Chris Tomkins' Blog

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.

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 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.

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 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.