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

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 AquaLogic 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 AquaLogic Service Bus v3.0 - 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 AquaLogic Service Bus v3.0.

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 AquaLogic 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 (AquaLogic Service Bus v3.0 is built on this version of WebLogic Server) and click the Next button.

- Optional: Modify the Server name to be AquaLogic 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 AquaLogic 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 an AquaLogic Service Bus Project and AquaLogic 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.

- 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 (thanks nugs) - 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.

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

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

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

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

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

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

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

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

Click Next.

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

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

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

Click Save.

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

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

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

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

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

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