Chris Tomkins' Blog

Roger wrote a blog post recently about my post entitled “Dynamic transformations in Oracle Service Bus 10gR3“ which got me thinking about the different ways you can handle the transformation of multiple message types in Oracle Service Bus and the things you should consider before selecting one approach over another.

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.

When I started writing this sequence of articles on sending email from Oracle Service Bus I only expected to write 2 parts but following a number of requests asking how to send emails with attachments I wrote Part 3. Now, following a number of people having problems sending email with binary attachments, I’m writing Part 4 – hopefully this will be the last one!

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 :)

Customers frequently ask me “What naming conventions should I use for my services?” The problem is there isn’t really a right or wrong answer. However, let me share a few of my thoughts based on my customer experience which I hope you’ll find useful:

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.

One of the new features in Oracle Service Bus 10gR3, and one commonly requested by customers, is the ability to choose the transformation to apply to a message based on runtime information - also known as dynamic transformations.

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.

Last Friday (24th October) saw the release of Oracle Service Bus 10g Release 3 (download here and read the documentation here) on the Oracle Technical Network (OTN) - the first release of the product formerly known as AquaLogic Service Bus, since the Oracle acquisition of BEA.

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.

To those of you who used to read my Dev2Dev blog whilst I was working for BEA, welcome back and for those of you who are finding this blog for the first time, welcome.

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!

Note: This post was first published before Oracle merged with BEA when the Oracle Service Bus product was known as AquaLogic Service Bus, hence the occasional reference to BEA and AquaLogic Service Bus.

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.

Note: This post was first published before Oracle merged with BEA when the Oracle Service Bus product was known as AquaLogic Service Bus, hence the occasional reference to BEA and AquaLogic Service Bus.

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.

Note: This post was first published before Oracle merged with BEA when the Oracle Service Bus product was known as AquaLogic Service Bus, hence the occasional reference to BEA and AquaLogic Service Bus.

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.