Routing and Service Chaining with WSO2 ESB Part 1

Part 1 > Part 2 > Part 3 

This will be the first part of a series of posts on Routing and Service Chaining with WSO2 ESB and will cover the use case and high level architectural details. 

The use case is the transmission of a request to a geo service locator to obtain information on the nearest health care centers using the user's longitude and latitude values. 

The request will be received by a proxy service that is deployed in the ESB. The proxy service will send/receive the messages to/from 3 different services in order to obtain information on the health care centers.  

The following web services will be made use of for this purpose:

GeoService    HCFacilityLocatorService    HCInformationService

For this tutorial these three services will be deployed in the WSO2 Application Server. Let's take a look at what each of these services do. 

GeoService service will take the longitude and latitude values and will return a zipcode value.

HCFacilityLocatorService requires a zipcode value and will return the healthcare center code(s) for the given area (zipcode). 

HCInformationService requires the healthcare center code to return information about the healthcare center pertaining to the healthcare center code. 

What the user needs to do is send the location and get the nearest healthcare center information. There are 3 service calls involved. Hence the application can be written so that the user sends the request to a proxy service that will perform service orchestration. In simple words, the proxy service will first invoke GeoService with the longitude and latitude values and obtain the zipcode value. It will then invoke HCFacilityLocatorService with the zipcode value and obtain healthcare center codes. Finally, it will invoke the HCInformationService for each healthcare center code that will return the details of the healthcare center for each healthcare center code; details of each of the healthcare centers will be merged into one message and be sent to the user as a list. 

Configuring the WSO2 ESB

The mediation engine of WSO2 ESB is driven off a set of XML configuration files. The configuration files that drive the mediation engine are stored in the ESB_HOME/repository/conf/synapse-config directory. These configuration files are written using the Synapse configuration language which is a domain specific language based on XML.

It is recommended to use the graphical wizards and tools provided in the WSO2 ESB management console to setup the mediation configuration, thus avoiding having to write XML configurations manually. Understanding how the files are stored will allow you to use third party tools and scripts for configuration management activities.  In this series, I will be showing how to use the graphical interface to create xml configurations as well as make the xml files available for download. 

The mediation engine of the WSO2 ESB consists of Proxy services, Endpoints, Sequences and Startup jobs managed by the ESB. It also contains the interface to the Registry/Repository being used by the mediation engine. Items like sequences, endpoints and proxy services could be made to reference different configuration elements that are served through the Registry. 

For more information go to the Service Mediation WSO2 Enterprise Service Bus (ESB) Configuration page. 

Let's take a look at the components of the WSO2 ESB that will be used in order to carry out the above operations required to implement the use case above. For this scenario we have created 3 endpoints, 1 proxy service and 2 sequences. Let's take a look at what each of these components fulfill. 

Endpoints

An Endpoint defines an external service endpoint and any attributes or semantics that should be followed when communicating with that endpoint. An endpoint definition can be named for re-use, or defined in-line or anonymously within a configuration. Typically an endpoint would be based on a service Address or a WSDL. Additionally WSO2 ESB supports Failover and Load-balance endpoints - which are defined over a group of endpoints. Endpoints may be defined within the synapse-config configuration or within the Registry. The following endpoints are used for this scenario.                                                                                                                                               
GeoEP.xml    HCFacilityLocatorServiceEP.xml    HCInformationService.xml

Sequences

A sequence element is used to define a sequence of mediators that can be invoked later by name. A sequence is a sequential arrangement of mediators. Mediators are the simplest functional component and performs a predefined action on a given message. 

The sequences named "main" and "fault" are significant in a Synapse configuration. The "main" sequence handles any message that is accepted for 'Message Mediation', and the "fault" sequence is invoked if Synapse encounters a fault, and a custom fault handler is not specified for the sequence via its "onError" attribute. If the "main" or "fault" sequences are not defined locally or not found in the Registry, the Synapse ESB defines suitable defaults at initialization. The following sequences are used for this scenario.

hcfRequest.xml    hciRequest.xml

Proxy Services

A proxy service is a virtual service hosted in the ESB runtime. For a service client it appears to be a real Web Service which accepts service requests. The proxy service mediates any accepted requests and forwards them to a specified endpoint, most of the time to an actual Web Service. The responses coming back from the target endpoint are mediated back to the client which sent the original service request. Proxy services often make references to sequences, endpoints and local entries.

An 'inSequence' in a proxy service would decide how the message would be handled after the proxy service receives the message. The 'outSequence' defines how the response is handled before it is sent back to the client. Unlike sequences and endpoints which can be stored and loaded from the registry, proxy services cannot be loaded from the registry. However a proxy service can make references to sequences and endpoints stored in the registry. The following proxy service is used for this scenario.

HCCService.xml

Message Flow

In the above example the following takes place in the given order:

1. The request message is first received by the inSequence of the HCCService proxy service and mediation occurs.
2. The message is forwarded to the GeoService service via the GeoEP endpoint. 
3. The response (zip code) from GeoService is forwarded to hcfRequest sequence for mediation.
4. hcfRequest forwards the message to the HCFacilityLocatorService via the HCFacilityLocatorServiceEP endpoint. 
5. The response from HCFacilityLocatorService is forwarded to hciRequest sequence for mediation. 
6. hciRequest forwards the message to HCInformationService service via the HCInformationService endpoint. 
7. The message is received by the outSequence of the HCCService proxy service which performs the final mediation steps and sends the response to the consumer. 

Now that the technical overview of this use case has been discussed, we can move on to implementing the given configurations from scratch using the graphical interface of the WSO2 ESB. Await for a step by step guide and detailed explanations on implementation in Part 2.