Before I discuss the different solutions and their benefits/disadvantages, let me describe the basic scenario I am talking about:

“I have/want to be able to receive messages in a number of different message formats and transform them into a common format in order to invoke a backend service.”

In terms of handling this in Oracle Service Bus there are a number of possible solutions:

Solution 1 – A separate proxy service for each message type

Solution 2 – A single proxy service containing if/then logic to determine the appropriate transform to apply for each message type

Solution 3 – A single proxy service which selects the appropriate transform to perform by inspecting the message type and determining the correct transform to apply at runtime (as described in Dynamic transformations in Oracle Service Bus 10gR3)

Before we consider why you would choose one over the other, lets make some assumptions:

- We have N different message types

- Each message type needs to be transformed into the same common data format

- We are invoking a single common business service

- We already have a message definition (WSDL, XML Schema or MFL) for the common data format

Now, on to the comparison:

In conclusion, I recommend choosing:

Solution 1 – If you have lots of message type dependent logic; need to ensure messages are valid and don’t mind the maintenance overhead

Solution 2 – If you have a few message types; don’t mind modifying the proxy service to add a new message type and don’t want the overhead of managing multiple proxy services

Solution 3 – If you have lots of different message types that change regularly and you don’t want to have to make proxy service changes to add a new message type

I’m keen to hear your thoughts/experiences/comments.

In Part 3 I explained one method for sending a binary attachment, but this relied on your proxy service being a messaging service which had an input message type of binary – fine if the only variable in your outbound email is the binary attachment, but limited if you want a number of components (e.g. subject, to address, etc. ) to be variable.

So, lets create a proxy service of messaging type which has an input message type of XML defined by the following XML schema:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.oracle.com/Email" xmlns:tns="http://www.oracle.com/Email" elementFormDefault="qualified">

    <element name="Email" type="tns:EmailType"></element>
    <complexType name="EmailType">
        <sequence>
            <element name="to" type="string" minOccurs="0" />
            <element name="subject" type="string" minOccurs="0" />
            <element name="body" type="string" minOccurs="1" />
            <element name="attachment" type="tns:AttachmentType" minOccurs="1" />
        </sequence>
    </complexType>

    <complexType name="AttachmentType">
        <sequence>
            <element name="name" type="string" minOccurs="1" />
            <element name="type" type="string" minOccurs="1" />
            <element name="content" type="base64Binary" minOccurs="1" />
        </sequence>
    </complexType>
</schema>

i.e. we can specify the to, subject and body fields of the email, plus the attachment name, type and content.

Hopefully you won’t be surprised to see the basic structure of the proxy service message flow is very similar to that described in Part 3:

Note the key differences are the addition of a Java callout (this decodes the incoming base64Binary content) and the Transport Header and Replace actions swapping places (this is only to ensure we only replace the payload of the message, once we have extracted all the pieces we are interested in).

The Java callout should look something like (note you may need to click on the images below to see the complete image):

This is basically invoking a Java method called decode, in the class BinaryConversion, in the package com.oracle, in the Jar file called binary.jar which will decode the incoming attachment content data. This is not built in functionality in Oracle Service Bus and so you will need to create this class file and Jar file yourself and add it in to your Oracle Service Bus project. The decode method should look like:

public static byte[] decode(String base64binary)
            throws IOException
    {
        BASE64Decoder decoder = new BASE64Decoder();
        return decoder.decodeBuffer(base64binary);
    }

The Insert action properties are basically the same as in Part 3, but with some of the hardcoded information replaced with XPath queries retrieving the information from the incoming message payload. Note the Content-Type must be a valid Internet Media type (MIME type), e.g. for a PDF file it should be application/pdf.

The Transport Header action properties simply specify the values of the to and subject fields:

And finally, the Replace action simply sets the body of the email to be as defined in the input message:

Note: In order to test this proxy service you will need a base64 encoded version of your attachment available. This can be obtained by using one of the many online tools such as the one available here which allows you to select your file and then convert it to base64 (simply copy and paste the text from the top window into the attachment content field in your test input data).

An example test might look something like:

<ema:Email xmlns:ema="http://www.oracle.com/Email">
    <ema:to>joe.bloggs@oracle.com</ema:to>
    <ema:subject>Email from OSB with binary attachment</ema:subject>
    <ema:body>This is the email body</ema:body>
    <ema:attachment>
        <ema:name>HelloWorld.pdf</ema:name>
        <ema:type>application/pdf</ema:type>
        <ema:content>JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURl

………(extra characters removed for brevity)……….

          CjE0MzQ5CiUlRU9GCg==</ema:content>
    </ema:attachment>
</ema:Email>

This should send an email to joe.bloggs@oracle.com, with the subject “Email from OSB with binary attachment”, with an email body “This is the email body” and a binary attachment HelloWorld.pdf containing whatever information it contained originally (in my case simply the text HelloWorld!).

Hopefully this helps answer all the questions on sending emails with attachments from Oracle Service Bus – at least for now :)

Use camel case for service names

Service names are often used by tooling to generate associated artifacts, e.g. JMS queues or endpoint URIs, or on platforms where spaces or special characters are not permitted so I highly recommend using camel case (e.g. EachWordStartsWithACapitalLetter) to name your services as this removes the need for these characters while retaining the readability.

Don’t reveal implementation details in the service name

This not only has the potential to lead to confusion if you decide to change the implementation of the service, but is also a security risk as it gives the service consumer an insight into how the service may be implemented which they may be able to exploit.

Don’t include protocol information in the service name

This is generally unnecessary as the service advertises itself at a particular endpoint which clearly defines the protocol to be used.

Don’t include the word service in the service name

Would you add the word Class to every Java class you define? I’m guessing not. So why add the word service, its unnecessary.

Don’t include a version in the service name

Including the version number in the name of the service can also be a recipe for disaster. What happens when you decide to change the service? If the change is major and includes modifying the interface, then you will probably be happy to rename the service and inform all your service consumers of the new service endpoint. However, if the change is minor, do you really want to have to inform all your service consumers of this? If not, the same service name may actually refer to multiple versions of the service – very confusing!

Make sure the name of the service is something sensible

Sounds obvious enough, but I’m sure many of us have seen services called ABCService before! Naming a service like this is a bad idea for 2 reasons. Firstly, no-one is going to have any idea what the service does and so they are not going to reuse it (one of the key benefits of SOA). Secondly, if something goes wrong naming your services sensibly can aid problem diagnosis as you may be able to identify the problem area by just the name itself.

I have to admit, I like Thomas Erl’s suggestion of using utility-centric (e.g. Notify), task-centric (GetProfile) and entity-centric (Customer) names – read more about this in the Service Labelling section of his article on Standardizing Service Endpoints.

Remember services can have operations

This is not true for all services, but many types of service, e.g. web services, can include operations which can be used to group together related functions. I’d argue it makes more sense to have a single Customer service with operations such as get, add, remove, update rather than 4 services called GetCustomer, AddCustomer, RemoveCustomer and UpdateCustomer.

Operation names don’t need to include the service context or parameters

I regularly see operation names along the lines of getCustomerByCustomerID. Now if this is an operation on the Customer service taking in an ID parameter and returning a Customer then I’d argue calling the operation get is sufficient.

By no means is this a definitive list nor do I suggest you have to follow these conventions in your organisation, however I feel it’s a good starting point. I’d be interested to hear your thoughts on the ideas above and other naming conventions in use in your organisation.

It’s also worth noting, these naming conventions only apply to the service interface and this alone is unlikely to be sufficient to define your service fully. You should also consider defining one, or more, service contracts (typically human readable documents) which describe:

- What your service does

- Behaviour characteristics

- Any security requirements

- Performance characteristics

- Quality of service

- Usage charge

These documents should then be stored alongside your service interface definition in your enterprise repository.

Some time ago I wrote a two-part blog post describing how you could use Oracle Service Bus to send email and thought I’d covered just about everything people wanted to know about email. However, over the last few weeks several people have asked how to send email with attachments from Oracle Service Bus, something I didn’t cover in those blog posts, and so this is effectively Part 3.

If you didn’t read my earlier blog posts on sending email (Part 1 and Part 2), I suggest you read them now, as I will be referring to them in the remainder of this post.

Developing a service to send an email with an attachment from Oracle Service Bus is not much different from what I have described so far. In general, you will have an email business service which is responsible for actually sending the email (Part 1), and a proxy service, which routes to this email business service, responsible for defining the actual content of the email and attachment(s) (Part 2). The basic structure of the proxy service message flow for sending an email with an attachment will look something like:

We have a single Route node containing a Routing action configured to send messages to our email business service. As in Part 2, the Request Action flow of the Routing action contains the same Replace action (to set the body of the email message) and a Transport Header action (to set the subject of the email message). The key difference here is the addition of the Insert action which describes the attachment we are going to send:

As you can see in the image above, we are setting the first child element of the attachments context variable to be the XML expression in the yellow box. This expression is the key to sending an attachment, so lets look at it in more detail:

<con:attachment xmlns:con=”http://www.bea.com/wli/sb/context”>….</con:attachment>

This is the wrapper element required for any attachment.

<con:Content-Type>text/plain</con:Content-Type>

This element defines the Internet media type (aka MIME type) of the attachment – in this case a simple text file attachment.

<con:Content-Disposition>attachment; filename=”Simple.txt”</con:Content-Disposition>

This element specifies how the attachment should be handled by the recipient – in this case as an attachment (as opposed to being inline) with a filename of Simple.txt.

<con:body>I am the attachment contents</con:body>

This element represents the actual contents of the attachment.

But I don’t want the filename and/or contents to be hardcoded?

Then simply replace the static values with XPath expressions which will evaluate to the filename and/or contents of your attachment, for example:

<con:attachment xmlns:con="http://www.bea.com/wli/sb/context">
  <con:Content-Type>text/plain</con:Content-Type>
  <con:Content-Disposition>attachment; filename="{$body/email/attachment/filename/text()}"</con:Content-Disposition>
  <con:body>{$body/email/attachment/contents/text()}</con:body>
</con:attachment>

Note the use of the curly braces to ensure this is evaluated as an XPath expression and not just text.

What if my attachment isn’t text?

If your attachment is a binary attachment, such as a PDF, Microsoft Office Document or image, your Insert action properties will be exactly the same, apart from the XML expression which will be slightly different. For example, lets imagine we want to send an attachment called Simple.pdf, our expression will look something like:

<con:attachment xmlns:con="http://www.bea.com/wli/sb/context">
  <con:Content-Type>application/pdf</con:Content-Type>
  <con:Content-Transfer-Encoding>base64</con:Content-Transfer-Encoding>
  <con:Content-Disposition>attachment; filename="Simple.pdf"</con:Content-Disposition>
  <con:body>{$body/ctx:binary-content}</con:body>
</con:attachment>

Note the differences from our earlier example:

- The Internet media type (the Content-Type element) is now the one for a PDF file: application/pdf (for other types of attachment refer to the list of Internet media types here to see what this value should be set to)

- We have added a Content-Transfer-Encoding element which describes how the attachment is encoded (normally in Oracle Service Bus this will be base64).

- The body element (remember this is of the attachment) refers to the binary content within the body of the original message.

But how would I get binary content in the body of the message in the first place?

The simplest way is to make sure your proxy service is a messaging service, using the file transport, expecting an input message of type binary (e.g. a binary file placed in a folder). Oracle Service Bus would read in this file and create a reference to the binary file contained within the ctx:binary-content element within the body. Alternatively, your proxy service may be reading in email which contains binary attachments already.

You can read more about how binary content is handled in Oracle Service Bus here in the documentation.

How can I send multiple attachments?

Simply add another Insert action to insert another attachment to the attachments variable. Unless you are worried about the order of the attachments (only likely for inline attachments) then the only piece that will be different is the content of the XML expression.

So, in summary I have shown how to:

- Build a proxy service to send an email with an attachment from Oracle Service Bus

- Configure the Insert action to:

- Send a text or binary attachment

- Dynamically set the filename and contents of the attachments

- Send an email with multiple attachments

If you have anymore questions about how to use the email capabilities of Oracle Service Bus, then let me know by commenting.

In the previous version of Oracle Service Bus you could only specify the transformation to be performed on the message at design time which may have resulted in:

- Multiple proxy services performing the same mediation logic, but applying different transformations

- A proxy service message flow containing a for loop with a number of cases each performing a different transformation

These scenarios can easily be handled when the number of transformations is small and/or doesn't change regularly but both scenarios involve modifying or creating a proxy service just to add a new transformation. Dynamic transformations allow you to define a proxy service which can handle new transformations being added at a later date.

Let's look at how we might implement a typical scenario where a proxy service accepts multiple versions of a message and applies an appropriate transformation based on the version of the message (determined by the namespace of the root element) in order to convert the message into a common format.

First create a new Oracle Service Bus project called DynamicTransformation (File>New>Oracle Service Bus Project, enter a name of DynamicTransformation and click Finish)

Then create a new schema file called Customer.xsd (File>New>Other>XML Schema) and define the common format with the target namespace http://www.oracle.com/Customer and the following structure:

Now define a CustomerApplication business service which accepts messages in this format (File>New>Business Service, enter a name of CustomerApplication and click Finish)

Now in the main editor pane, select the General tab for this service and make sure it is defined as a Messaging Service.

Now move to the Messaging tab, set the Request Type to XML and click the Browse button to select the Customer element from Customer.xsd as the message format definition:

Now move to the Transport tab:

- Select the protocol as JMS

- Click Add to accept the default URL or modify it to point to a valid JMS endpoint

(NB. You will need to ensure the connection factory and queue specified in this JMS endpoint exist. If you accept the default, and are running on the default port of 7001 you should only need to create a JMS queue with a JNDI name of CustomerApplicationRequest on the WebLogic Server instance underpinning your Service Bus instance as the connection factory is created for you).

Now move to the JMS Transport tab:

- Select the Message Type as Text and leave the other values as their defaults.

Now test this business service is working as expected by right clicking on it in the Project Explorer and selecting Run As. When the Select Tasks dialog box appears, just click Finish. This should launch the Test Console.

Enter some sample data (the Test Console should have generated the structure for you) and then click Execute.

This should succeed but without a response (this is a one way service and the message has been placed on the CustomerApplicationRequest queue). Navigate to the CustomerApplicationJMS queue and check it contains your message:

Next create a new schema file called CustomerV1.xsd and define the CustomerV1 format to be in the http://www.oracle.com/CustomerV1 target namespace and have the following structure:

And one called CustomerV2.xsd defining our CustomerV2 format to be in the http://www.oracle.com/CustomerV2 target namespace and have the following structure:

Next, lets create our transformations: Version1.xq (which converts from CustomerV1 format to the common Customer format):

And Version2.xq (which converts from Customer V2 format to the common Customer format):

NB. It is important the target namespaces and transformation filenames are named as described as this is how the correct transformation is selected.

So now we have our transformations and formats defined, the final step is to create our Customer proxy service (File>New>Proxy Service, enter name Customer and click Finish) which will actually perform the dynamic transformation.

In the General tab, select the Service Type to be Messaging Service.

In the Messaging tab, select the Request Type to be XML but don't specify a format (this is because this service can accept both V1 and V2 message formats).

In the Transport tab, select the Protocol to be JMS and accept the default endpoint (the queue and connection factory pointed at by this JMS endpoint will be created for you).

In the Message Flow tab create a message flow like the following which routes to the CustomerApplication business service:

The Assign action extracts the version number (the last digit) from the namespace URI for the Customer element and stores it in the version variable:

NB. The XPath expression here gets the namespace URI of the Customer element (fn:namespace-uri), converts it into a string (fn:string) and then extracts the version number from the end of the string (fn:substring-after).

The Replace action replaces the entire contents of the body with the result of performing the XQuery transformation, the name of which is determined, in this case, by concatenating the static string DynamicTransformation/Version with the value stored in the version variable:

In order to create the Expression line you need to have clicked in the Expression field and completed the XQuery editor as follows:

The Bind Variables field defines the variable passed to the transformation. To create this simply enter the name Customer in the Add Custom Variable field and clicked Add. The XPath expression here evaluates to the Customer element within the body, irrespective of namespace.

After completing this, save everything and then launch the Test Console on the Customer proxy service (right click on it and select Run As).

Enter a CustomerV1 format message into the payload field (you can generate a sample one of these by right clicking on CustomerV1.xsd in Workshop and selecting Generate XML).

Then click Execute.

The invocation should succeed without a response - the V1 message should have been transformed to the common Customer format, the CustomerApplication business service invoked and a common Customer format message placed on the CustomerApplicationRequest JMS queue. Check the JMS queue to see this is the case.

Then try the same, but replace the payload with a CustomerV2 format message. This should also succeed without a response - the V2 message having been also transformed to the common Customer format and placed on the CustomerApplicationRequest JMS queue. Again, check the JMS queue to see that this is the case.

That's it. You've just implemented your first dynamic transformation with Oracle Service Bus - congratulations!

NB. A few words of caution when adopting an approach like the one described above. Since your proxy service now has a weakly defined service contract rather than a strongly defined one you will need to describe to your service consumers the message structure(s) your service supports (probably via documentation) and also ensure you have some error handling to deal with unsupported message formats.

Click here for the Oracle Service Bus configuration jar, which includes the Customer proxy service, the CustomerApplication business service, the Customer XML schemas, the transformations and the sample messages.

So what's new, apart from the version numbering :)

Oracle branding

The product and documentation have now been re-branded to reflect the new name, Oracle Service Bus. NB. There are a few parts where the product's BEA heritage sneaks through, such as choosing a BEA home directory, etc. but you can expect these to disappear in future releases.

Re-based on Oracle WebLogic Server 10gR3

Oracle Service Bus is still built on WebLogic Server but the version incorporated has moved up to WebLogic Server 10gR3 - the first version of WebLogic Server since the BEA merger. This will be the version on which we aim to standardise all the relevant ex-BEA and Oracle products.

There are a whole raft of new features in this version of WebLogic Server but one which warrants specific mention here is the .NET JMS client which allows .NET applications to natively invoke JMS proxy services hosted on the Oracle Service Bus - something a number of customers had been asking for.

Action metrics

Earlier versions of Oracle Service Bus have allowed you to gather service and pipeline metrics using Oracle Service Bus, i.e. the number of messages, average response time etc. but you can now drill down to the Action level as well. This is incredibly useful for identifying performance hot-spots in your proxy message flow (actions taking a long time to complete) - prime examples are service callouts, Java callouts and transformations. Visit the Monitoring Oracle Service Bus at Runtime section of the documentation for more information.

Message tracing

When you use the Test Console to test proxy and business services hosted on Oracle Service Bus you can see the message being traced through the message flow in the lower section. This is useful for development but not typically something that is used in production. However, operational people may want/need to enable message level tracing temporarily (at a particular level of detail) in order to help diagnose a problem. They can now do this using the new message tracing capabilities exposed in the Oracle Service Bus console. Find out more here.

Visual Debugging

If, during development, you have often wanted to know what the values of the context variables are at a specific point in the proxy service message flow, then visual debugging is the feature you've been waiting for.  Simply right click on any action in the message flow, and choose Toggle Breakpoint.  Start the server in Debug mode and then right click on your proxy service and choose Debug As to launch the Test Console. Now when you execute your test, the Debug perspective will be launched showing you where you are in the message flow and the values of the variables at this point. Find out more here.

XOP/MTOM support

Message Transmission Optimisation Mechanism (MTOM) and XML-Binary Optimised Packaging (XOP) help boost the performance of web services transferring binary data by enabling the data to be passed through in a compact format (this article explains the 2 standards in a bit more detail). By simply ticking a check box you can enable your proxy service to receive messages in XOP/MTOM format (find out more here), or enable messages sent from Oracle Service Bus to a business service to be in this format (find out more here).

Dynamic transformations

In earlier versions of Oracle Service Bus when you performed an XQuery transformation you had to specify the name of the transformation file at runtime. This limitation was fine for most use cases however numerous customers want to be able to choose which transformation to perform on a message (typically the payload) based on the value of a field (typically in the header). This new feature allows you to dynamically specify the name of the XQuery transformation to be performed based on a value evaluated at runtime.

Oracle BPEL Process Manager transport

In the past, if you had developed business processes in BPEL Process Manager and were looking to expose them via Oracle Service Bus (a good practice as it promotes loose coupling between the client and the business process itself) then you would have had to expose the business process as a web service or JMS service and then connect to them from Oracle Service bus using the standard SOAP/HTTP transport or JMS transport. This approach is fine but adds an extra, unnecessary, performance overhead. With the new version, there is a new native BPEL Process Manager transport enabling you to connect directly from Oracle Service Bus to BPEL Process Manager through a high performance connection.

Improved REST support

Representational State Transfer (better known as REST) is an architectural style which makes uses a combination of HTTP URLs and HTTP verbs to provide a simple, lightweight, service interface. In Oracle Service Bus we now provide full support for exposing your proxy services as REST services and communicating with REST business services. Within a proxy service message flow you can now get easy access to a number of key pieces of information via the inbound and outbound context variables: the HTTP verb (transport/request/http:http-method); the HTTP query string (transport/request/http:query-string) and the relative URI (transport/request/http:relative-URI). When invoking a business service, you can now specify any one of the standard HTTP verbs: POST, PUT, HEAD, GET, DELETE or even specify your own custom verbs if you so wish. Find out more in the HTTP transport section.

As well as the Oracle re-branding, one of the new improvements in the IDE is the addition of a Resource Summary which gives you a summary of the resources in your Oracle Service Bus configuration in the same way as the Resources view does through the Oracle Service Bus console. This is a particularly useful view if you have multiple projects deployed on a single Oracle Service Bus instance.

Split-Join Enhancements

In the last version of Oracle Service Bus we introduced the Split-Join capability to allow you to break an incoming message up into a number of parts and perform mediation logic on them in parallel. Within these parallel flows we have now added the ability to perform Java callouts for custom validation, transformation, logging, etc. We have also added the ability to log data at a specified severity to the server log file and the ability to invoke one Split-Join from another Split-Join using a high performance mechanism. Read more here.

Interoperability with Oracle Web Services Manager

Oracle Service Bus allows you to apply security policies to service hosted on the bus, whereas Oracle Web Services Manager allows you to apply security policies to services wherever they are hosted. This release sees support for Oracle Web Services Manager and Oracle Service Bus working in conjunction. The common use cases see Oracle Web Services Manager acting as a gateway for either perimeter security, or identity propagation and acting as a client performing message protection or authentication. These use cases are described in the Securing Oracle Service Bus with Oracle Web Services Manager chapter of the Security topic.

Streaming attachments

In earlier versions we had support for streaming the payload of a message, but now we have added support for streaming attachments to disk. This allows you to process messages with large attachments efficiently. Find out more here.

JCA Adapter Framework

Addition of the JCA adapter framework is an important, but currently invisible to the user, addition to the product. This will allow us to support the same JCA adapters as in BPEL Process Manager. Over the next few months we are looking to certify a few key ones of these against Oracle Service Bus:

- Database
- Oracle AQ
- Oracle E-Business Suite
- Siebel
- JD Edwards
- PeopleSoft
- SAP

And eventually we will move towards supporting the same set as in BPEL Process Manager - incredibly useful additions to the product.

Congratulations to the development team and project management team on getting this completed in less than 4 month since the Oracle-BEA acquisition. Expect to see some more detailed posts on some of these aspects in the coming months.

Before I begin posting to this new blog I thought it would be a good idea to introduce myself - at least a bit more than the picture and brief job description you can see to the right :)

My name is Chris Tomkins and I am now a Sales Consultant in the Oracle Fusion Middleware team, focusing on the SOA Suite set of products, in particular Oracle Service Bus (based on the product formally known as AquaLogic Service Bus). Before the Oracle acquisition of BEA I spent 8 months working as a Senior Systems Engineer in Pre-Sales as a technology specialist on the AquaLogic Service Bus product and before that 8 years at IBM working in a number of development and testing roles before spending my last 3 years working on WebSphere ESB in a number of roles culminating in leading the Customer SWAT team.

In terms of this blog I plan to post how to solve common customer problems using the products in the SOA Suite, and some answers to commonly asked customer questions. My aim is to do this in such a way that someone with little experience of the products can make sense of them (I don't expect any of my readers to be product experts!). If you have a problem or question then don't hesitate to post it here and I'll try to do my best to answer it. Also, if you don't understand something in one of my posts, then just add a comment explaining your issue and I'll try to explain things more clearly - I really appreciate reader feedback.

If you are keen to know what the future product strategy and roadmap is following the Oracle and BEA merger, and didn't watch it live on 1st July, then I strongly advise you to take watch Thomas Kurian's webcast. The view from the blogosphere and from customers I've spoken to so far seems to be very positive and all of us in Oracle and really excited about the future.

Enjoy reading!

In the last post I demonstrated how to configure a business service in Oracle Service Bus to support load balancing across multiple service endpoints. What we didn't consider was what would happen if one of these endpoints was unavailable for some reason - perhaps due to a network or hardware failure, or just down for maintenance. If we leave things as they are then if a service request gets directed to a service endpoint which is currently offline, then this service request will fail. This is almost certainly not what we want to happen - we would prefer this service request to be redirected to an online service endpoint (if one is available) rather than the offline one. Luckily, Oracle Service Bus comes to the rescue with its new endpoint failover feature. This enables us to automatically mark an endpoint as offline, either temporarily or permanently, and hence ensure service requests are only sent to available online endpoints.

To apply this logic to our business service we need to make a couple of changes to our configuration.

The first step is to enable a retry on our business service so that if the endpoint we attempt to invoke is offline we try to invoke an alternative endpoint. To configure this we need to do the following:

- Open up the business service definition for LoadBalancedService

- Switch to the Transport tab

- Set the Retry Count field to 1

This is an improvement over our original configuration. Now, if a service request gets directed to an offline endpoint, service bus will recognise this as an error and try to send the service request to an alternate endpoint. However, if this alternate endpoint is also offline then the service request will fail at this stage, even though there could possibly be an online endpoint available. To handle this case as well, we need to enable the offline endpoint URI capability in Oracle Service Bus.

To do this:

- Right click on the server you have defined in the Servers view of Workspace Studio and choose Launch ALSB Administration Console

- Click on the Resource Browser tab in the left hand navigation

- Select the Business Services link

- Click on your LoadBalancedService business service

- Choose the Operational Settings tab

- Click Create in Change Center to start a new session so you can make a change

- Select the checkbox to enable Offline Endpoint URIs and set a retry interval of 10 seconds

- Click Update

- Click Activate in Change Center, enter a description of the change you have made and click Submit to apply your changes

That's all there is to it.

What we have done is configured our business service so that if a service request is sent to an endpoint which happens to be offline, service bus marks this endpoint offline and attempts to send the service request to an alternate endpoint (in accordance with the retry count).  Subsequent service requests will not be sent to the offline endpoint until the offline endpoint URI retry interval has elapsed, at which stage service bus will attempt to start sending service requests to the endpoint. If the endpoint is still offline the cycle will repeat, if it is online the service request will be sent to it.

Note: If you wish to mark an endpoint permanently offline, set the offline endpoint URI retry interval to be 0 hours, 0 mins and 0 seconds. In order to mark this endpoint online again, you will need to do this manually through the service bus console.

Note: If you are using the offline endpoint URI setting, you may well want to consider configuring an alert rule to notify you that an endpoint has gone offline so that you can address this. You can do this by following the instructions here.

To test this works, we need to perform the following tests:

- Using the Test Console, invoke the service twice - this should exercise both endpoints. To check this, simply go to the Operations section of the administration console, click on Service Health, then click on LoadBalancedService (if you do not see this in the list, you need to go back and enable monitoring on your business service) and finally on Endpoint URIs. You should see something like the following (provided you have waited for the monitoring aggregation interval):

- Now make the first endpoint unavailable (how you do this depends on the service you are calling and where it is hosted - for my example, I will just undeploy the application to simulate the endpoint being unavailable).

- Now, using the Test Console, invoke the service again - this request should be routed to the first endpoint as we are using the round-robin load balancing algorithm but since this endpoint is offline, we should see the service request redirected to the other endpoint. To prove this is the case, take a look at the Endpoint URIs monitoring screen again, which should now look something like:

- From this we can clearly see that service bus attempted to send the request to the EchoService endpoint and it failed (hence an Error Count of 1) because the endpoint was offline. We can also see that EchoService2 received this request as it is still online.

- Now re-enable the EchoService endpoint and invoke the business service again using the Test Console. If we look at the Endpoint URIs monitoring screen again, we should see that this service request has been directed to the now online again EchoService endpoint.

We now have a business service which load balances across a set of endpoints and handles the majority of communication related issues we may have with these endpoints. The great thing about this is that this business service can now be used across the rest of the service bus, in any proxy service, in exactly the same way as any other business service.

If you have a service you expect to receive heavy usage you may want to consider introducing multiple instances of the service (i.e. multiple service endpoints) and distributing service requests across them in order to share the workload - this is known as load balancing. Out of the box Oracle Service Bus supports a number of different load balancing algorithms:

Round robin - the first request goes to the first service endpoint, the second request to the second service endpoint and so on until all endpoints have been exercised and then the sequence repeats.

Random - each request gets distributed to any one of your service endpoints - over time you would expect each service endpoint to get a similar share of the load

Random weighted - each service endpoint is given a weighting and then service requests are distributed randomly amongst the service endpoints - over time you would expect service requests to be distributed to the service endpoints according to the weighting you have defined

Configuring a load balancing policy for multiple instances of a service in Oracle Service Bus is simple - all you need to do is create a single business service, choose a load balancing algorithm from the list above and define the service endpoints.

Lets walk through how to do this using the Workspace Studio IDE (If you've never used the Workspace Studio IDE before then check out my Oracle Service Bus - Getting started with Workspace Studio post before you start):

- Create an ALSB Project (File>New>ALSB Project) and give it a name - if you have an existing ALSB Configuration Project choose it from the list, if not leave the default setting and one will be created for you.

- Right click on the ALSB Project you have just created and choose New>Business Service

- Give your business service a name, and choose where you want to place your business service in terms of your project and folder structure - by default it will be in the root of the project you right clicked on:

- Then click Next

- Choose the type of service you are creating - for the purpose of this example, I'll choose a WSDL Web Service and select a simple Echo service I have created which simply returns the input message.

- Click Next

- It is on this page of the wizard you choose your load balancing algorithm and define the multiple endpoints you have. In this case I have chosen round-robin as the load balancing algorithm and defined 2 endpoints:

- For the purpose of this example, we do not need to perform anymore configuration of our business service so we can just click Finish to complete our business service. To perform more configuration of your business service, select Next.

- Now we've defined our business service we need to publish it to the server, which we do by right clicking on the server in the Servers view and selecting Publish. Note you will need to make sure your endpoints are available too - if you have developed these in Workspace Studio as well then simply right click on the server and choose to Add and Remove projects.

So now we've defined our load balanced business service and deployed it to the runtime - the next step is to test it, right?

Not quite - before we launch the Test Client to try this out lets enable monitoring so we can see our load balancing in action and make sure our requests are correctly being distributed between our service endpoints.

To do this, right click on the server in the Servers view and choose Launch ALSB Administration Console.

Once the ALSB Administration Console opens you need to perform the following steps:

- Click on Create in Change Center to start a new session

- Navigate (either via Resource Browser or Project Explorer) to the business service you have just created and click on it.

- Click on the Operational Settings tab and choose to Enable Monitoring.

- Choose an aggregation interval - this is the time over which monitoring statistics will be aggregated (to calculate things such as average response time) and hence the time you will need to wait to see your metrics in the console - for the purpose of this demo lets choose an aggregation interval of 1 minute.

- Click Update

- Click Activate in the Change Center to complete your session and apply your changes to the server

Now lets test the business service by clicking on the bug icon in the Actions column alongside your business service in the console (you can also launch the Test Client from Workspace Studio by right clicking on the business service and choosing Run As>Run on Server)

- Choose the operation you wish to invoke, enter some valid input data and click Execute. If your business service is a request/response service you should see a response returned.

- Click Back.

- Invoke the test a second time - this should mean that both endpoints are exercised since we have chosen the round-robin load balancing algorithm.

Now click on the Operations link in the left hand navigation of the ALSB Administrative Console. Click on the Service Health tab and you should see your business service listed along with some statistics:

Note: If you don't see your service listed, check you have enabled monitoring.

Note: If you see your service listed, but don't see any statistics then make sure you have waited for your aggregation interval period.

- Click on the word Online in the Endpoint URI Status column for your business service to drill down to see the metrics for the individual endpoints:

- In this case we chose a load balancing algorithm of round-robin, have 2 distinct service endpoints and have submitted 2 service requests so, as expected, we see each endpoint has serviced 1 message.

Note: If you have chosen a different load balancing algorithm such as random-weighted you will need to submit more requests and probably set a longer aggregation interval to see the number of requests accurately reflect the load balancing algorithm.

So, we have successfully configured, deployed and tested a load balanced business service (and this can be used in the same way as any other business service) - in the next part of this post I will explain how to configure load balancing to automatically handle unreliable service endpoints which may be either online or offline - this is a new feature of Oracle Service Bus v3.0.

One of the major changes in Oracle Service Bus v3.0 was to enable you to create service bus artifacts in Workspace Studio as well as the web-based console. This post explains how to get started with Workspace Studio including - how to add a server, how to create a service bus project, how to start creating service bus resources and how to deploy and test them.

Launching Workspace Studio

When you first launch Workspace Studio, the first dialog box you get presented with is the Workspace Launcher:

This is asking you where you want your workspace (the place where your Workspace Studio work will be stored) to be located on your file system. Once you have selected a location, click OK and Workspace Studio will finish launching.

Note: If you always want your work to be stored in this location, then tick the box to make this the default location (you can always change this setting from within Workspace Studio by going to Window>Preferences>General>Startup and Shutdown).

Once Workspace Studio has launched, you should see the Welcome screen:

This provides links to an overview of the product, samples, tutorials and other web based resources - if this is your first time using the product it is definitely worth spending some time on these.

Once you have finished looking at the links from the Welcome screen then click the Go to the Workspace button - you are now ready to start doing some work.

Defining your Oracle Service Bus server

Before we start creating actual service bus resources we need to define a local server instance which we can use to deploy our resources to. To do this, click on the Servers view tab in the lower half of the screen and then right click in this view and choose New>Server.

- Keep the default of BEA WebLogic Server v10.0 (Oracle Service Bus v3.0 is built on this version of WebLogic Server) and click the Next button.

- Optional: Modify the Server name to be Oracle Service Bus v3.0 @ localhost - I find this makes it easier to work out which server I am working with.

- Click the browse button to navigate to an existing Oracle Service Bus v3.0 domain or click the link to launch the Configuration Wizard to create a new one.

- Click Finish

You should now see the service bus server you created has been added to the Servers view and is currently in the Stopped state:

- To start the server, simply click on the green arrow or right click on the server and select Start.

Creating a Service Bus Project and Service Bus Configuration

Now we have a server, the next step is to create an ALSB Project which will contain our service bus resources. To do this, right click on the whitespace in the Project Explorer view on the left hand side, and choose New>ALSB Project:

Give the project a name and leave the <Default ALSB Configuration> option selected. By default the project contents will reside in a folder with the same name as the project, under the directory you selected for the workspace when you launched Workspace Studio, although you can select a different location if you wish.

Click Finish. When prompted as to whether you want to switch to the AquaLogic Service Bus perspective, tick the Remember my decision check box and click Yes.

You should see 2 projects have been created for you - an ALSB Project with the name you defined and an ALSB Configuration project called ALSB Configuration. You typically have one ALSB Configuration project per server instance and it handles access to the server, the automatic creation of sessions (to manage changes through Change Center) and is where cross project resources - such as SMTP server, JNDI provider and UDDI registry connections reside.

The ALSB Project you created is where resources such as business and proxy service definitions, XML Schema, XSLT and XQuery transformations etc. reside. For those of you familiar with earlier versions of service bus - this is analogous to a project in the project explorer view in the web based console.

Creating resources

To create resources simply right click on either the ALSB Configuration project (if you want to create a cross project resource) or on the ALSB Project (if you want to create a project resource - this is what you will be doing most often) and select New and then the type of resource you want to create. This will launch the appropriate wizard to help you create the resource. If you already have existing resources you can import these by choosing one of the import options. To demonstrate how to do this, here is a simple example where we import a WSDL file from a URL, create a business service from it and then create a proxy service from it:

- Right click on the ALSB project and select Import>Resources from URL and complete the necessary information to identify the WSDL we are interested in:

- Right click on the ALSB project and choose New>Business Service

- Accept the default location (i.e. in the root of this project) and give the business service a name:

- Click Next

- Choose the Service Type to be WSDL Web Service and browse to the WSDL you just imported, selecting the port you need (I have chosen the SOAP one for my example) and click Finish (note if you want to perform any more configuration of the business service click Next instead of Finish).

- To create the proxy service, right click on the ALSB Project and choose New>Proxy Service.

- Accept the default location (i.e. the root of this project) and give the proxy service a name:

- Choose to create this proxy from a business service and select the business service you have just created:

- Click Finish to accept all the defaults (if you need to customise any of the options for your proxy service, just click on Next instead of Finish)

This completes the construction of the service bus resources needed for this example - if you wish to further customise the business service or proxy service you can double click on them in the Project Explorer view and modify their properties via the various tabs (these correspond to the various panels you would see if you completed every panel in the creation wizard).

Deploying and Testing

Right click on the proxy service and choose Run As>Run on Server which will publish the resources to the server and also launch the test client.

Note: If you want to just publish the resources, you can do so by right clicking on your server and choosing publish or clicking the publish icon (next to the red square stop server icon).

- Check the "Set server as project default (do not ask again)" option so that you are not prompted with this screen for each subsequent publish.

- Click Finish (if you need to customise which applications are deployed to the server, click Next instead of Finish)

- You should now see the Test Client launch and be able to test your proxy service by entering sample data and clicking execute:

Note: If you would prefer to see the Test Client launched in your own web browser rather than in Workspace Studio, you can configure this by going to Window>Preferences>General>Web Browser.

Congratulations - you have just developed, deployed and tested your first proxy service from within the Workspace Studio IDE.

Note: To enable operational settings, SLAs etc. you will still need to use the web based console - this can easily be launched by right clicking on the server you created and choosing Launch ALSB Administration Console.

One of the main goals of Service Oriented Architecture is to promote reuse, not just of services but also of things like data type definitions - after all, once you've defined something once you don't typically want to have to do it again. One common web services practice however, actually prevents the reuse of data type definitions. In the remainder of this post I will describe the practice, how it prevents reuse and explain an improved practice which allows these data type definitions to be reused in other services.

Web services are described by a WSDL (Web Services Description Language) document, one of the the key elements of which is the types section, where the data type definitions for the request and response messages for your web service are described, in XML schema syntax. In the interest of simplicity these definitions are often placed inline, i.e. described within the WSDL file, which is fine for your web service but prevents these definitions from being reused elsewhere.

The alternative approach is to define your data types in a separate XML schema file and add a line into the WSDL document which imports this schema into the types section of the WSDL. This not only gives you better encapsulation - your data type definitions are described in one file and your web service in another - but also allows you to use these data type definitions in other services.

Lets work through a simple scenario to demonstrate why you might want to do this:

Imagine you have an existing SOAP/HTTP web service (we'll use the free CurrencyConverter service provided by WebServiceX) which you need to expose to a JMS messaging system. In order to keep things simple you decide to make the message definitions used by the JMS messaging system the same as those expected by the web service.

The steps you would follow are described below:

1 - Save a copy of the CurrencyConverter WSDL document to your machine and extract the types definitions from it into a separate schema. To do this, open the CurrencyConverter.wsdl file and copy and paste the contents of the <wsdl:types> element into a separate file called CurrencyConverterTypes.xsd.

2 - Next we need to ensure the namespaces are correct. Modify the first line of the CurrencyConverterTypes.xsd file to say:

<s:schema elementFormDefault="qualified" targetNamespace="http://www.webserviceX.NET/" xmlns:tns="http://www.webserviceX.NET/" xmlns:s="http://www.w3.org/2001/XMLSchema">

3 - Now modify the <wsdl:types> section of CurrencyConverter.wsdl to import CurrencyConverterTypes.xsd:

<wsdl:types>

          <s:schema>
                    <s:import namespace="http://www.webserviceX.NET/" schemaLocation="CurrencyConverterTypes.xsd" />
          </s:schema>

</wsdl:types>

We have now extracted the inline data type definitions from our WSDL. In the remainder of the steps we will create the business service representing our SOAP/HTTP web service and the JMS messaging proxy service which exposes this to the JMS messaging system.

4 - Add the modified CurrencyConverter.wsdl and CurrencyConverterTypes.xsd to a zip file called CurrencyConverter.zip (this is not essential but will make it easier to import them into Oracle Service Bus and also save us having to manually create a reference between the XML schema and the WSDL).

5 - Login to your AquaLogic Service Bus domain and create a new project (remember to click Create in Change Center if you haven't already created a new session).

6 - Navigate into this project using Project Explorer and import the zip file created in step 4 using the Zipped Resources option from the Create Resource drop down.

You will need to browse to the zip file on the system and click Open, then click Next and Import.

7 - In the same project, create a WSDL Web Service business service called CurrencyConverterBS from the imported WSDL (the basic steps can be found in my earlier blog post).

8 - In the same project, create a new proxy service called CurrencyConverterPS by selecting Proxy Service from the Create Resource drop down and selecting the Service Type to be Messaging Service. Click Next.

9 - Set the Request Message Type to be XML and click the adjacent Browse button.

10 - Select the CurrencyConversionTypes schema by clicking on it and then select the ConversionRate element (this is the data type definition for the request message) and click Submit.

11 - Repeat steps 9 and 10 for the Response Message Type ensuring you select the ConversionRateResponse element as the data type definition for the response message and click Next.

Note: If you had left the data type definitions inline in the original WSDL file, you would not have been able to select the request and response message type definitions as you have done in steps 9-11.

12 - Choose the protocol to be JMS and ensure the hostname part of the Endpoint URI points to your host (or localhost, if you have not specified a fully qualified domain name for your AquaLogic Service Bus domain). Copy the Endpoint URI as you will need it later and then click Next.

Note: The last part of the URI refers to the JNDI name of the JMS input queue of your proxy service.

13 - Paste the Endpoint URI you copied into the Response URI field and modify the last part of the URI to be CurrencyConverterPSResponse (the JNDI name of the response JMS queue). Click Last and then Save.

14 - Open up the Message Flow of the CurrencyConverterPS proxy service by click on the Message Flow icon .

15 - Click on the CurrencyConverterPS node and choose Add Route (give the route node a more sensible name and a description by left clicking on it and choosing Edit Name and Description).

16 - Click the route node and choose edit Route

17 - Click Add an Action and choose Communication>Routing.

18 - Set the Service attribute to be the CurrencyConverterBS business service.

19 - Select ConversionRate as the invoking Operation from the drop down.

20 - Click Save All.

22 - Activate your changes.

We now have a JMS messaging proxy service which fronts our SOAP/HTTP web service and uses the same data type definitions for the request and response messages. To test this, you can either use the test console by clicking on the bug icon (change the FromCurrency to GBP and the ToCurrency to USD as a good example) or by placing a message on the request queue as pointed to by the request endpoint URI (see step 12 above) ensuring your request message is in the right format. Note AquaLogic Service Bus has created the JMS resources required for your proxy service automatically so you will not need to create them yourself.

In summary, if you have data type definitions you expect to reuse in other services then you should aim to put them in external XML schemas rather than defining them inline in WSDL documents. If you have types that are specific to your web service and you don't envisage using them again, then it is fine to define them inline in the WSDL. If you wish, you can choose to have a mixture of both.

In my previous post I showed how easy it was to create a business service in Oracle Service Bus which could be used to send email. If you completed the steps and created this service in your own Oracle Service Bus environment you may have noticed a few limitations:

- It only ever sends email to one address

- The email sent doesn't have the subject field populated

As pointed out in a comment on my first post - one way of addressing the first limitation is to create a separate business service for each email address - not exactly a scalable approach if you have 3000 different email addresses to send email to! Thankfully there is a better way to address both limitations - the Transport Headers action which allows you to modify the transport specific headers of the outbound request and/or inbound response from within a proxy service. In our case, we are interested in setting the email transport specific headers in the outbound request.

In order to demonstrate this, lets make our existing email business service more useful by fronting it with a proxy service which sets the email subject, content and destination email address dynamically based on information in an incoming request of the form:

<email>

  <to>The destination email address</to>

  <subject>The subject of the email</subject>

  <content>The content of the email</content>

</email>

Lets start by creating a simple XML schema to represent our incoming request:

- In the service bus console, click Create in the Change Center to start a new session

- Navigate to the project you created your email business service in

- In the field Enter New Folder Name box type XML Schema and click Add Folder

- Click on the newly created XML Schema folder

- From the Create Resource drop down select XML Schema and complete the screen as follows:

Make sure you enter the XML schema which is:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/EmailRequest" xmlns:tns="http://www.example.org/EmailRequest" elementFormDefault="qualified">

    <element name="Email" type="tns:EmailType"></element>
    <complexType name="EmailType">
        <sequence>
            <element name="to" type="string"></element>
            <element name="subject" type="string"></element>
            <element name="content" type="string"></element>
        </sequence>
    </complexType>
</schema>

- Click Save

The next step is to create the proxy service which accepts an XML message conforming to the schema you have just created:

- Add a new folder to your project called Proxy Services and navigate to this folder

- From the Create Resource drop down choose to create a new Proxy Service

- Complete the first screen as follows:

- Click Next

- Select XML as the Request Message Type and select Browse

- Select the EmailRequest schema you have just created

- Select the Email element and click Submit

- Click Last as we do not need to modify any other settings for this service

- Check the summary screen looks like the one below:

Note: By clicking the Last button we have accepted the defaults and created an XML over HTTP service (although we could equally well have chosen to create a WSDL based service too).

- Click Save

The next step is to create the message flow for the proxy service:

- Click on the message flow icon in the Actions column and you should see a very simple message flow:

- Click on the EmailService node and select Add Route

- Click on the route node created and choose Edit Name and Description. Give the route node a sensible name and description and click Save

- Click on the route node again and select Edit Route

- Click on Add an Action and select Communication>Routing

- In the Route to action just created, click on Service, select the email business service you created previously, and click Submit

- Back in the Route to action add a request action by clicking on Add an Action under Request actions and select Communication>Transport Headers

- Click on Add Header

- From the drop down select email>Subject

- Set the Set Header to Expression to $body/ema:Email/ema:subject/text() (you can use the Variable Structures section on the left hand side to select the correct structure)

- Click on the document icon to the left of the Subject radio button and select Add Header

- Repeat the Add Header steps to set the To field to $body/ema:Email/ema:to/text()

Next we have to replace the main body of the message with just the content part to ensure our email contains the content rather than the original XML request sent to the proxy service:

- Click on the icon to the left of Set Transport Headers and select Add an Action>Message Processing>Replace

- Ignore the XPath field (by default it selects everything which is what we want in this case)

- In the variable field enter body

- Set the Expression field to be $body/ema:Email/ema:content/text()

- Ensure the Replace node contents radio button is selected

- The completed Route to part of the flow should look like:

- Click Save All

- Click Activate, enter a description and click Submit to enforce your changes.

The final step is to test our new proxy service. Click on the bug icon to launch the Test Console and modify the contents of the to, subject and content XML fields and click Execute. Check your email to make sure it has been sent and is formatted correctly.

In summary, in this post we have taken a simple email business service and fronted it with a proxy service. This has turned our limited email service into a much more flexible service which can easily be reused by other services. We have also showed how to expose a service using a different transport protocol (in this case we have exposed our email business service as an XML/HTTP proxy service) and ensured our service consumers are not tightly coupled to our email business service making it easier for us to make changes.

The first step is to create an SMTP Server configuration (it is the SMTP server that actually sends the email). To do this, you need to do the following:

- Click on the System Administration link in the left hand navigation in the service bus console

- Click on Create in the Change Center to create a new session in which you can make changes

- Click on Add and enter the details for your SMTP Server, e.g.

- Click Save.

Now we have an SMTP Server configuration we can use multiple times within Oracle Service Bus without entering this information again.

The next step is to create an email business service that uses this SMTP Server configuration:

- Click on the Project Explorer link in the left hand navigation

- Select (or create) the project and folder you want to create the email business service in

- From the Create Resource drop down select Business Service

- Enter a name and description for your business service and ensure you select the Service Type as Messaging Service:

- Click Next

- Select Text as the Request Message Type, leave the Response Message Type as none (sending email is a one-way service) and then click Next.

- On the next screen, select the Protocol as email and set the Endpoint URI to be mailto:<email address you want the service to send email to> and click Add:

- Click Next

- Select your SMTP Server from the drop down list of SMTP Servers available and configure the rest of the settings on this screen appropriately, e.g.

- Click Next, review the summary and then click Save.

- Click Activate to enforce these changes to Oracle Service Bus.

- Enter a description and click Submit.

You have now successfully created an email business service which you can use to send email from Oracle Service Bus. If you click on the bug icon in the Actions column alongside it, you can use the Test Console to prove this service does indeed send an email to the address you specified, with the settings you configured and the payload you specified in the Test Console.

In the second post of this set I will explain how a proxy service can make use of this email business service and some tips for customising the email sent.

In my previous post I talked about how to add a service to Oracle Service Bus. In this post I am going to explain the typical next step: how to take this business service and expose it as a new service.

"But why can't my service consumers connect directly to my business service, without the need for Oracle Service Bus?" I hear you say. The answer is - they could, however the result is a tightly coupled, point-to-point solution where any change to either the service consumer or business service will almost certainly require a change in the other - not very practical if you have a number of service consumers or you are not in control of both the service consumer(s) and business service.

Oracle Service Bus addresses this problem through the notion of a Proxy Service - a new service created on the bus which describes how your business service(s) are exposed to your service consumer(s). As well as providing loose coupling between the service consumer(s) and business service(s), proxy services are a good place to implement any mediation of service requests (and/or responses), such as validation, enrichment, transformation (of both data and protocol) and routing. Encapsulating this mediation logic within the proxy service allows it to be changed more easily than if it was part of the service consumer or business service and helps maximises the reusability of both service consumer and business service.

Now we understand the purpose and benefits of having a proxy service, lets continue with the example from my previous post and create a proxy service for our Currency Converter business service (feel free to follow similar steps for your own business service). In this proxy service we are going to expose a service with the same interface but with a different service (endpoint) address - a simple example but one which demonstrates the concepts and reflects a common business scenario.

The first step is to start a new session so we can make changes which we do by clicking New in Change Center.

Next, using Project Explorer we navigate to the project we created (Adding a service to Oracle Service Bus) and create a new folder called Proxy Services by entering Proxy Services in the Enter New Folder Name box and clicking Add Folder. You should now have a screen that looks like:

Move into the newly created directory by clicking on Proxy Services and select the Proxy Service option from the Create Resource drop down.

This is the page where we can name the proxy service, provide a description of it and most importantly describe what type of service it is - whether it is a web service, a messaging service, an XML service or a SOAP service without a concrete interface. Oracle Service Bus also provides a convenient option to create a proxy service based on an existing business service which will create a proxy service with the same interface as the business service. This is the option we are going to use here. Complete the screen as follows:

Note:  To complete the create from existing business service box just select the Browse button and select the business service - CurrencyConverterBS.

Click Next.

On the next screen you will be asked some more questions about your proxy service, such as which protocol should it use (in this case we choose http, the same as the business service), the endpoint URI (this is the service endpoint address we are going to modify) and whether you need access to the header information within the service request (in this case we don't). The completed screen should look like:

Note: Feel free to set the endpoint URI to something of your choice.

This is all we need to configure for our proxy service so just go ahead and click the Last button and check your summary looks something like:

Click Save.

So what has happened here? Oracle Service Bus has created a new service for us with the same interface and transport protocol as the original business service, but with a different endpoint address. It has also created a message flow which routes any requests sent to the new proxy service to the backend business service.

Open up the message flow for the newly created proxy service to see how this is done. Using Project Explorer, find the proxy service and then click on the message flow icon ( ) and you should see something like the simple message flow below:

The CurrencyConverterPS node handles the messages coming into and being emitted by the proxy service and the RouteTo_CurrencyConverterBS handles the routing to the existing business service.  Since this is a simple use case there is just a direct wire between them - in more advanced message flows you would see more complex logic here.

If you left click on the RouteTo_CurrencyConverterBS node and select Edit Route you should see the details of the route node. You can see that you have the ability to add extra actions here that occur on either the request or response, but for this simple example there is no need. Simply check the box to "Use inbound operation for outbound" which does exactly what it says on the tin - uses the inbound operation name as the outbound operation name invoked on the business service. It also forces the SOAPAction field to be set which happens to be required by this backend web service as it is implemented using .NET. Then click Save All to save your changes, and then Activate in the Change Center to enforce your changes to Oracle Service Bus. Make sure you enter a description and click Submit.

You can now test this new proxy service in the same way as my previous post, by clicking on the bug icon in the Actions column. Modify the fromCurrency to GBP and the toCurrency to USD and marvel at how many US dollars you can currently get to the British pound!

In this post, I've hopefully demonstrated how easy it is to expose a new service on the bus. Obviously this is a simple example, but it is a quite often used one and has demonstrated a number of the key concepts. In future posts, I will talk about some more advanced features of the product and provide some tips and also some solutions to some commonly faced problems.

A common first task for people who have installed Oracle Service Bus is to add an existing service to the bus - after all what is the point of a service bus without any services! In the remainder of this post I'll explain the basic process for doing this as it will give you a good introduction to a number of Oracle Service Bus concepts, which I am sure I will talk about in more detail in future posts.

First things first, you need to start the server by clicking on the Start Server for AquaLogic Service Bus Domain Windows shortcut under All Programs>BEA Products>User Projects>Name of your domain (on other platforms run the startWebLogic script from the corresponding directory on your filesystem).

Next you need to launch the service bus console which you can do by pointing your web browser at http://localhost:7001/sbconsole (note the server name and port may differ if you have changed the defaults during the install process):

In order to start making any changes to the service bus you need to use the Change Center to activate a session (a topic for another blog post I'm sure, but basically it allows you to make a set of changes, apply them when complete, and roll them back at a later date if you so wish). To do this, just click the Create button in the top left of the screen.

Next you need to create a project to group our resources together, so click on Project Explorer in the left hand navigation, enter a new project name where prompted, e.g. Adding a service to Oracle Service Bus, and click the Add Project button. You should end up with a screen that looks like:

Now you have a project, you can give it a meaningful description and can create a set of folders to organise the artifacts we are about to create. You can add the description by clicking the project you have just created and clicking on Edit Description, entering some text and then clicking Submit Description. To add the folders, enter the folder name where prompted and then click Add Folder. For now, create 2 folders called: WSDL and Business Services. You should end up with a screen that looks like:

At this point it is a good idea to complete the Change Center session as it means you can easily return to this point if you do something wrong at a later stage. To do this, click the green Activate button in Change Center and enter some descriptive text giving an overview of what you have done (this makes it easy to identify the changes later):

Then click Submit.

To continue to make changes you need to create another session, so do this now by clicking Create in the Change Center again.

Next, you need to import a WSDL, which describes your existing service, into the WSDL folder in your project. I have selected to import an existing WSDL for a free CurrencyConverter web service from WebServiceX which allows you to input two different currencies and find the conversion rate but you can choose any service you wish. To do this navigate to the WSDL folder via the Project Explorer, click on the Create Resource drop down box in the right hand section and select the Resources from URL option. Complete the screen that appears as follows:

Click Next, confirm the information is correct and then click Import.

Now you have the WSDL imported, it is time to create a business service - a representation of the service including both its interface and how to connect to it, which can then be re-used by other Oracle Service Bus services. To do this, use the Project Explorer to navigate to the Business Services folder you created earlier in the Adding a service to Oracle Service Bus project.

From the Create Resource drop down, choose to create a Business Service.

Enter a Service Name, e.g. CurrencyConverterBS and a description and then select the Service Type as a WSDL Web Service. Click the Browse button and select the CurrencyConverter WSDL and the CurrencyConverterSoap port (this service can be invoked in a number of different ways but we are going to choose SOAP this time) and click Submit. Your screen should now look like:

Note: in this case we have chosen a web service but we could just as easily have chosen another type of service at this point - the basic process is the same.

Click on Last and then, on the summary screen, click Save.

Complete the session by clicking Activate in Change Center, give it a description and click Submit - you have now added a business service to Oracle Service Bus.

The last step is to test the business service in order to check the actual service is accessible from the bus. Using the Project Explorer navigate back to the Business Services folder and click on the bug icon in the Actions column, next to the business service you created, to launch the Test Console which will allow you to define the input data to send to your service. In my case I want to use my business service to find out the currency conversion rate between British pounds (GBP) and US Dollars (USD) and so I modify the sample SOAP message to set the FromCurrency to GBP and the ToCurrency to USD. If you have chosen to use the same service as me then your Test Console should look like:

To execute the test, simply click on Execute and you should see the response from your business service:

Congratulations, you have now added your first service to Oracle Service Bus!