Contents


Integrating IBM Integration Bus with WebSphere Service Registry and Repository

Part 3: Endpoint lookup scenarios

Comments

Content series:

This content is part # of # in the series: Integrating IBM Integration Bus with WebSphere Service Registry and Repository

Stay tuned for additional content in this series.

This content is part of the series:Integrating IBM Integration Bus with WebSphere Service Registry and Repository

Stay tuned for additional content in this series.

It is generally accepted that you should never allow direct access to a service provider in a SOA environment. Instead, you should deploy a new virtual service to the Enterprise Service Bus (ESB) which acts as a proxy to the real back end service. Introducing a controlled point of access to the back end service provides several benefits. In its most basic form it achieves loose coupling between the service consumer and the service provider, allowing you to relocate the back end service or modify its interface without necessarily impacting the service consumer. This pattern is commonly referred to as a simple service proxy. It also enables you to introduce service management functionality, for example error handling and alerting, logging, security configuration, traffic management, service charging and performance measurement. These are extensions to the simple service proxy pattern.

This article describes three sample message flows. The first is an implementation of the simple service proxy pattern that dynamically retrieves the endpoint for the real back end service from WSRR at run time. The second extends this pattern to allow for selection between different provider endpoints. The final pattern is another extension that allows service requests to be routed to alternative endpoints in the event of failures when invoking the endpoint originally selected.

Service Location business scenario

The first sample flow that is described focuses on the service location scenario that was described in Part 1: Scenarios and configuration, as follows:

  • Business problem

    Message flows that act as proxies for other services, or invoke other services at runtime, need to know the location, or endpoints, of these services. The location of the services could be hard coded into each message flow but this makes them vulnerable to changes in your environment. For example, if the location of any of the services that are invoked changes, the affected message flows will need to be updated with the new locations and redeployed. It might also be necessary to modify the location of the services that are invoked by each message flow as they move through various environments during the development process.

  • Solution

    The locations of the invoked services can be registered in WSRR and retrieved dynamically by the message flows at runtime. If the location of a service changes for some reason, it is a simple task to update the endpoint that is registered in WSRR so that any affected message flows can route requests to the service at its new location.

  • Benefits

    This approach reduces the impact of changes that are made to the location of services, both in terms of impact to the message flows and in terms of system management.

    It also allows for substitution of one service provider for another without the service consumer being aware of the change or without needing to alter the architecture to support the substitution.

Service Location message flow

The service location message flow (as shown in ) uses the Endpoint Lookup node to retrieve the endpoint for the target service from WSRR at run time. It is the simplest message flow that is described in this series because it does not require any additional programming to perform its task.

The Basic Endpoint Lookup message flow
Basic Endpoint Lookup message flow
Basic Endpoint Lookup message flow

Service Request node

The flow starts with the Service Request SOAP Input node. This node is configured to expose the interface for the Math Service. This is specified on the Basic tab of the Properties editor for the node, as shown in . You can see that the MathServerServiceDummyEndpoint.wsdl has been specified in the WSDL file name field. As its name suggests, this WSDL document defines a dummy endpoint for the service, ensuring that the only way service requests can be successfully routed to the target service is to retrieve the endpoint from WSRR.

The other basic properties for the node are automatically filled in once the WSDL file has been selected. When configured to expose a specific WSDL interface, the SOAP Input node will validate any service requests that it receives to ensure that they comply with the definition of the service contained in the WSDL. This node is also configured to use the HTTP transport with a URL suffix of /MathServer/Services/MathServer/eplookup1. This is the value that consumers will need to use when invoking the service exposed by this flow. The Service Request node is connected to the next node in the service location flow using the out terminal.

Exposed WSDL Interface
Exposed WSDL Interface
Exposed WSDL Interface

Endpoint Lookup node

The Endpoint Lookup node queries WSRR to retrieve the endpoint for version 1.0 of the Math Service. The properties that are used to query WSRR are specified as follows:

Endpoint Lookup node properties
Property nameValue
PortType NameMathServerPortType
PortType Namespacehttp://math.pot.ibm.com
PortType Version1.0
Classificationhttp://www.ibm.com/xmlns/prod/serviceregistry/lifecycle/v6r3/LifecycleDefinition#Online
Match PolicyOne

A Match Policy of One has been specified on the node, which enables the node to be wired directly to a SOAP Request node, in this case the Forward Request node.

Endpoint Lookup node
Endpoint Lookup node

If the query performed by the Endpoint Lookup node returns no results, the node passes the message to the NoMatch terminal. This terminal is wired to the No Match Faultnode.

Forward Request and SOAP Reply nodes

The Forward Request node is responsible for calling the target service. You must specify a value for the Web Service URL property when defining the flow, even though this will be programmatically overwritten at run time by the Endpoint Lookup node. As a result, a dummy value of http://tempuri.org/MathServer/services/MathServer has been specified for this property. The Operation mode for the node must be set to Invoke a generic web service, which is specified on the Basic tab of the Properties editor for the node. The Forward Request node is wired directly to the SOAP Reply node using both the out and failure terminals.

Forward Request and SOAP Reply nodes
Forward Request and SOAP Reply nodes

The SOAP Reply node, as its name suggests, simply passes a SOAP response back to the service consumer. In a successful pass through the flow, the response returned will be the response from the actual target service. If the Endpoint Lookup node was unable to find an online endpoint in WSRR, the response will be a SOAP fault that was generated by the No Match Fault node.

No Match Fault node

If the query performed by the Endpoint Lookup node does not return any results, it does not automatically generate a SOAP fault. To do this, the NoMatch terminal for this node is wired to the No Match Fault Java Compute node. This node programmatically generates a SOAP fault which is returned to the service consumer using the SOAP Reply node.

Testing the Service Location message flow

The steps that follow describe how to use the Calculator application to verify tat the service location message flow is working correctly.

  1. Make sure that your IBM Integration Bus execution group is running, with the EndpointLookup_Basic flow deployed and started.
  2. Start the calculator application, as described in Running the Calculator Application in Part 1.
  3. Specify suitable hostname and port number values for the server that is running IBM Integration Bus. For example, if you are running IBM Integration Bus on the same machine as the Calculator application and are using the default port these values would be localhost and 7800.
  4. Modify the path for the service, setting its value to /MathServer/services/MathServer/eplookup1. This is the endpoint for the EndpointLookup_Basic flow.
  5. Specify some values and a suitable operator (+, -, /, *) in the drop-down, then press the = button.
  6. The Calculator application will send a service request to the service location message flow, which will route it to the Math Service. The response is then returned to the Calculator application, which displays it. The Calculator application should look similar to this:
    The calculator application, set up to use the service location message flow
    The calculator application, set up to use the service location message flow
    The calculator application, set up to use the service location message flow

If you receive an error from the application, check the following:

  1. You have performed all of the configuration steps described in series, Part 1: Scenarios and configuration.
  2. You have specified the correct hostname.
  3. You have specified the correct port number.
  4. You have specified the correct path for the flow.

Service Selection business scenario

The service selection scenario is an extension to the service location scenario. It was described in Part 1: Scenarios and Configuration, as follows:

  • Business problem

    An interface for a Stock Quote service has been defined, but three implementations have been deployed. One implementation returns up-to-date stock quotes and should only be used by Gold customers. Another implementation returns quotes that are 5 minutes old and should only be used by Silver customers. The final implementation returns quotes that are 20 minutes old and should only be used by Bronze customers. Consumers of the stock quote service want to be able to invoke it using a single endpoint.

  • Solution

    The endpoints of the all three services can be registered in WSRR and additional metadata can be associated with each endpoint. For example, in the scenario described above, you might define a custom ontology in WSRR that allows you to classify each endpoint as Gold, Silver or Bronze. When the endpoints are retrieved by a message flow at runtime, the metadata is also returned to IBM Integration Bus. This metadata can then be used by the message flow to decide which endpoint the request should be routed to, probably in conjunction with some information available on the original request or contextual information available in the ESB.

  • Benefits

    This approach enables you to select between multiple service providers at runtime based on metadata about those providers. The routing decision could be influenced by information that is available in the original request, which is sometimes referred to as content based routing. Alternatively, the decision could be entirely based on the metadata about the target endpoints. For example, a monitoring component in your environment could be pushing performance metrics into WSRR and the message flow could decide to route the request to the endpoint with the lowest average response time.

Service Selection message flow

The service selection message flow (as shown in ) uses the Endpoint Lookup node to retrieve all of the online endpoints for the target service from WSRR at run time. It then selects one of the endpoints and forwards the service request onto it.

As you can see from , the service selection message flow is very similar to the service location message flow. As a result, only those aspects of the implementation that differ from the service location message flow are described in the sections that follow.

The Service Selection message flow
The Service Selection message flow
The Service Selection message flow

Service Request node

The Service Request SOAP Input node for the service selection message flow is configured to use the HTTP transport with a URL suffix of /MathServer/Services/MathServer/eplookup2. This is the value that consumers will need to use when invoking the service exposed by this flow.

Endpoint Lookup node differences

The configuration of the Endpoint Lookup node in this flow is almost identical to that of the service location message flow. The only difference is that the Match Policy configured on the node is All. This is an important difference because it means that the node will not automatically set values for the Destination.HTTP.RequestURL and Destination.SOAP.Request.Transport.WebServiceURL elements in the local environment tree. This must be done programmatically by a compute node later in the message flow if the request is to be forwarded on to a SOAP Request or HTTP Request. This is exactly what has been done in the service selection message flow, with the out terminal of the Endpoint Lookup node wired to the Endpoint Selector Java compute node.

Endpoint Selector node

The Endpoint Selector node is an instance of a Java Compute node. As its name suggests, this node processes the results of the query performed by the Endpoint Lookup node, selecting the endpoint to forward the service request to. The service selection message flow has already performed a level of selection by only retrieving endpoints for the Math Service that are classified as Online in WSRR. This was configured as a Classification property on the Endpoint Lookup node itself.

Endpoint Selector node
Endpoint Selector node

As discussed above in Service Selection business scenario, you could select the endpoint based on the metadata associated with the object. Typically, you inspect the classifications on the endpoint to select the appropriate one. However, this is left as an exercise for you, and the service selection message flow simply chooses one of the returned endpoints at runtime.

The first step in this process is to retrieve the list of online endpoints that were retrieved from WSRR by the Endpoint Lookup node. These were placed into the local environment tree in the ServiceRegistry entry. The code in shows how to retrieve the list of endpoint addresses from this location:

Retrieving the list of endpoint addresses
MbElement rootElement = inAssembly.getLocalEnvironment().getRootElement();
MbElement serviceRegistry = rootElement.getFirstElementByPath("/ServiceRegistry");
List<MbElement> addresses = 
    (List <MbElement>)serviceRegistry.evaluateXPath("ITService/Endpoint/Address");

The next step is to randomly select one of the endpoint addresses from the list, assuming that there is more than one endpoint. The code in shows how to do this. It is worth noting that there must be at least one address available. If the Endpoint Lookup node had not retrieved any results from WSRR then the message would have been routed through the NoMatch terminal, bypassing the Endpoint Selector node.

Randomly selecting the endpoint address
int index = 0;
if (addresses.size() > 1) {
    Random random = new Random();
    index = random.nextInt(addresses.size());
}
String addressUrl = (String)addresses.get(index).getValue();

Once an endpoint address has been selected, the Endpoint Selector node needs to forward the service request onto the target service. To do this, the service selection message flow makes use of a SOAP Request node called Forward Request. To programmatically override the Web Service URL that has been configured on the Forward Request node, the Endpoint Selector node needs to insert the endpoint address into the Destination.SOAP.Request.Transport.HTTP.WebServiceURL field of the local environment tree. shows the code required to perform this task. The Endpoint Selector node then passes the message to the out terminal, which is wired to the Forward Request node.

Placing the address into the local environment tree
MbMessage environment = new MbMessage(inAssembly.getLocalEnvironment());
MbElement environmentRoot = environment.getRootElement();

environmentRoot.evaluateXPath("?Destination/?SOAP/?Request/?Transport/?"
    + "HTTP/?WebServiceURL[set-value('" + addressUrl + "')]");
   
environmentRoot.evaluateXPath("?Destination/?HTTP/?RequestURL[set-value('"
    + addressUrl + "')]");
                
outAssembly = new MbMessageAssembly( inAssembly
                                   , environment
                                   , inAssembly.getExceptionList()
                                   , inAssembly.getMessage()
                                   );

Testing the Service Selection message flow

The steps that follow describe how to use the Calculator application to verify that the service selection message flow is working correctly.

Making the second endpoint online

In the test data that is provided with the articles in this series, version 1.0 of the Math Service actually has two endpoints registered in WSRR, as shown in .

Math Service v1.0 Endpoints
Math Service v1.0 Endpoints
Math Service v1.0 Endpoints

You will notice that one of the endpoints is actually a dummy endpoint, with a URL of http://dummy.endpoint:7800/MathServer2/services/MathServer. This endpoint is currently classified as Offline and, therefore, was not returned when testing the service location message flow above. To demonstrate that the service selection message flow is working correctly, you need to change the state of this endpoint to online. The steps that follow describe how to do this.

  1. In a Web browser, log on to the Service Registry Dashboard for your WSRR instance.
  2. Change to the SOA Governance view and then select the Overview page.
  3. Select SLA - CalculatorApplication 1.0 to MathService 1.0 in the Collection widget, as shown below:
    The SOA Governance View
    The SOA Governance View
    The SOA Governance View
  4. You will be taken to the Browse page, which will display the details of the SLA - CalculatorApplication 1.0 to MathService 1.0 service level agreement in the Detail widget. This is a representation of the consumption agreement between the Calculator application and the Math Service in WSRR. In this widget, under Agreed Endpoints, select SLD - MathService v1.0.
  5. The Detail widget will be updated to display the details of the SLD - MathService v1.0 SLD. In the Detail widget, under Available Endpoints select http://dummy.endpoint:7800/MathServer2/services/MathServer (1.0).
  6. The Detail widget will be updated to display the details of the http://dummy.endpoint:7800/MathServer2/services/MathServer ‪(1.0) endpoint. Select Action => Approve For Use, as shown below:
    Approve For Use
    Approve For Use
    Approve For Use
  7. Click OK once the operation has completed. The endpoint now has a governance state of Online.

Testing the message flow

  1. Make sure that your IBM Integration Bus execution group is running, with the EndpointLookup_EndpointSelection flow deployed and started.
  2. Start the calculator application, as described in Running the Calculator Application in Part 1.
  3. Specify suitable hostname and port number values for the server that is running IBM Integration Bus. For example, if you are running IBM Integration Bus on the same machine as the Calculator application and are using the default port these values would be localhost and 7800.
  4. Modify the path for the service, setting its value to /MathServer/services/MathServer/eplookup2. This is the endpoint for the EndpointLookup_EndpointSelection flow.
  5. Specify some values and a suitable operator (+, -, /, *) in the drop-down, then press the = button several times.
  6. Some of the calls to the Math Service will work and the result will be displayed. Some of the calls with fail, with the Calculator application displaying the message Error: Unable to invoke math service, as shown below. This is expected because the endpoint that has just been switched online in WSRR is a dummy endpoint. You should see the error approximately 50% of the time.
    The calculator application, set up to use the service selection message flow
    The calculator application, set up to use the service selection message flow
    The calculator application, set up to use the service selection message flow

If you receive an error from the application, check the following:

  1. You have performed all of the configuration steps described in Part 1: Scenarios and Configuration.
  2. You have specified the correct hostname.
  3. You have specified the correct port number.
  4. You have specified the correct path for the flow.

Alternate Service Provider business scenario

The alternate service provider is an extension to the service selection scenario,and it was described in Part 1, as follows:

  • Business problem

    Multiple endpoints are available for a target service, but an error occurs when attempting to invoke the selected endpoint. Consumers of the service only know the endpoint of the message flow that is proxying the service. They expect the ESB to be able to handle routing requests around problem endpoints transparently.

  • Solution

    All of the endpoints for the target service can be registered in WSRR and retrieved by the message flow in a single query. If an error occurs when attempting to invoke the target service on the selected endpoint, the message flow can simply select one of the other endpoints for the service and retry. The message flow can continue this process until the request is successful or all of the service endpoints have been tried.

  • Benefits

    This approach enables you to build a level of fault tolerance into your ESB by allowing the ESB to transparently route service requests around problem endpoints. You might decide to allow message flows to try all of the available endpoints for a service or, alternatively, you might decide to limit the number of endpoints that are attempted before returning an error to the service consumer. Obviously, any fault tolerance built into the ESB must be designed to work in conjunction with other high availability mechanisms in use in your environment.

Alternate Service Provider message flow

The alternate service provider message flow (as shown in ) uses the Endpoint Lookup node to retrieve all of the online endpoints for the target service from WSRR at run time. It then selects the first endpoint from the list and attempts to forward the service request to it. If an error occurs when attempting to invoke the target service using the first endpoint that was selected, the message flow attempts the next endpoint in the list. If there are no endpoints left to try, it returns an error.

As you can see from , the alternate service provider message flow is very similar to the service selection message flow. As a result, only those aspects of the implementation that differ from the service selection message flow are described in the sections that follow.

The Alternate Endpoint Selector message flow
The Alternate Endpoint Selector message flow
The Alternate Endpoint Selector message flow

Service Request node

The Service Request SOAP Input node for the alternate service provider message flow is configured to use the HTTP transport with a URL suffix of /MathServer/Services/MathServer/eplookup3. This is the value that consumers will need to use when invoking the service exposed by this flow.

Alternate Endpoint Selector node

The Alternate Endpoint Selector node is an instance of a Java Compute node. It processes the results of the query performed by the Endpoint Lookup node in a subtly different way to the Endpoint Selector node in the service selection message flow.

Alternate Endpoint Selector node
Alternate Endpoint Selector node

The first task that the node performs is to retrieve the list of online endpoints that were retrieved from WSRR by the Endpoint Lookup node. It then extracts the actual address of each endpoint and places these into a list. This is shown in .

Retrieving the list of endpoint addresses
MbElement rootElement = inAssembly.getLocalEnvironment().getRootElement();
MbElement serviceRegistry = rootElement.getFirstElementByPath("/ServiceRegistry");

List<MbElement> addresses = 
    (List <MbElement>)serviceRegistry.evaluateXPath("ITService/Endpoint/Address");
    
List<String> addressUrls = new ArrayList<String>();
for (MbElement address : addresses) {
    addressUrls.add((String)address.getValue());
}

The next step is to check to see if an endpoint has already been selected in a previous pass through the node. If this is the case, the address of the previously selected endpoint will be stored in the Destination.SOAP.Request.Transport.WebServiceURL element in the local environment tree. In this situation, the Alternate Endpoint Selector node can locate the previously selected endpoint in the list of addresses and then simply select the next address in the list, checking to make to sure that it has not reached the end of the list. shows how to do this. If all of the addresses have been tried, a SOAP fault is generated and the node passes the message to the failure terminal. This terminal is wired directly to the SOAP Reply node, which passes the SOAP fault back to the client.

Selecting the endpoint address
String webServiceUrl = null;

MbElement webServiceUrlElement = rootElement.getFirstElementByPath(
    "/Destination/SOAP/Request/Transport/HTTP/WebServiceURL");

if (webServiceUrlElement != null) {
    webServiceUrl = (String)webServiceUrlElement.getValue();
}

int index = 0;
if (webServiceUrl != null && addressUrls.contains(webServiceUrl)) {
    index = addressUrls.indexOf(webServiceUrl) + 1;
}

if (index < addressUrls.size()) {
    String addressUrl = addressUrls.get(index);
    
    ...
    
} else {
    outAssembly =
        MessageUtils.createSOAPFault(inAssembly
                                    , "ERROR_EP_002"
                                    , "It is not possible to process the request."
                                    , "All of the available endpoints for the service "
                                    + "have been tried (" + addressUrls.size() + ") and "
                                    + "none of them succeeded."
                                    );
    outputTerminal = getOutputTerminal("failure");
}

Once an endpoint address has been selected, the Alternate Endpoint Selector node forwards the service request onto the target service. The code required to do this is the same as that used by the Endpoint Selector node, shown in above. The Alternate Endpoint Selector node then passes the message to the out terminal, which is wired to the Forward Request node.

Forward Request node

The only difference with the Forward Request node in the alternate service provider message flow is that its failure terminal is wired back to the In terminal of the Alternate Endpoint Selector node. This will cause the message flow to go back through the Alternate Endpoint Selector node and select the next endpoint in the list if it attempts to forward the request to the dummy endpoint. Of course, in a real world scenario, you might also want to select an alternate endpoint if a SOAP fault was returned when invoking the original endpoint. In this scenario, you would need to wire the Fault terminal for the Forward Request node back to the In terminal of the Alternate Endpoint Selector node.

Testing the Alternate Service Provider message flow

The steps that follow describe how to use the Calculator application to verify that the alternate service provider message flow is working correctly.

  1. Make sure that your IBM Integration Bus execution group is running, with the EndpointLookup_AlternateEndpoint message flow deployed and started.
  2. Start the calculator application, as described in Running the Calculator in Part 1.
  3. Specify suitable hostname and port number values for the server that is running IBM Integration Bus. For example, if you are running IBM Integration Bus on the same machine as the Calculator application and are using the default port these values would be localhost and 7800.
  4. Modify the path for the service, setting its value to /MathServer/services/MathServer/eplookup3. This is the endpoint for the EndpointLookup_AlternateEndpoint flow.
  5. Specify some values and a suitable operator (+, -, /, *) in the drop-down, then press the = button.
  6. The Calculator application will send a service request to the alternate service provider message flow, which will route it to the Math Service. If the dummy endpoint is selected first the message flow receives and an error and will transparently forward the request to the real endpoint for the service. The response is then returned to the Calculator application, which displays it.

If you receive an error from the application, check the following:

  1. You have performed all of the configuration steps described in Part 1.
  2. You have specified the correct hostname.
  3. You have specified the correct port number.
  4. You have specified the correct path for the flow.

Making the second endpoint offline

If you intend to work through the message flows that are described in the other articles in this series, it is important that you change the state of the dummy endpoint back to Offline at this point. To do this, follow the steps described in , but when you come to step 7, select Action => Revoke From Use.

Conclusion

This article described a number of messages flows that are all implementations of service virtualization patterns. These patterns can be used to help you achieve loose coupling between the service consumers and service providers in your SOA, enabling you to route requests to one or more provider endpoints and transparently handle errors without the service consumer being aware.

Acknowledgements

The author thanks the following people for all of their help with the development of the sample messages flows in this series:

  • John Hosie
  • Ben Thompson
  • Matt Golby-Kirk
  • Trevor Dolby
  • Andreas Martens
  • Graham Haxby
  • Andrew Coleman
  • John Reeve

The author also thanks the following people for their help with reviewing this article:

  • David Seager
  • Arnauld Desprets
  • Anna Maciejkowicz

Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=970092
ArticleTitle=Integrating IBM Integration Bus with WebSphere Service Registry and Repository: Part 3: Endpoint lookup scenarios
publish-date=04302014