Contents


Integrating IBM Integration Bus with WebSphere Service Registry and Repository

Part 5: Performing SLA checks at runtime and registry 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.

When a service is offered for reuse within an organization, the provider of the service typically provides a number of artifacts that consumers of the service can use to implement client applications or services. These artifacts usually include one or more WSDL or XML schema documents. While these artifacts provide the information required by the developers of a service consumer, they do not provide any information regarding the non-functional, or quality of service (QoS), characteristics that the service consumer can expect from the service.

The Governance Enablement Profile (GEP) provided with WSRR is a complete WSRR configuration profile that contains all of the business models, life cycles, ontologies, and governance policies that you need to quickly get up and running with SOA governance. It enables a service provider to capture the QoS characteristics for a service using Service Level Definitions (SLDs). It also enables the agreements that exist between service providers and service consumers to be represented using Service Level Agreements (SLAs).

This article describes a sample message flow that enforces SLAs defined in WSRR at runtime, to ensure that the service consumer is authorised to invoke the target service.

SLA Check Business Scenario

The sample flow that is described within this article focuses on the SLA checking scenario that was described in Part 1: Scenarios and configuration, as follows:

  • Business Problem

    You have a number of services deployed in your SOA and they are all registered in WSRR. You have not, however, registered the consumers of those services in WSRR. As a consequence you do not know which service consumers might be invoking each service at any given point in time. You want to ensure that all of the service consumers in your SOA are registered in WSRR and that only consumers who are authorized to invoke a target service are allowed to do so.

  • Solution

    WSRR allows you to register the service consumers in your SOA, as well as service providers. It also enables the agreements, or contracts, that exist between service providers and service consumers to be represented using Service Level Agreements (SLAs). A message flow can retrieve this information from WSRR dynamically at runtime and use it to determine whether a service consumer is authorized to invoke a target service. If the service consumer is authorized to invoke the target service it can forward the request on to the agreed endpoint. If the service consumer is not authorized to invoke the target service a suitable error can be returned.

  • Benefits

    This approach allows you to control which service consumers are invoking the actual back end services, enabling you to enforce a level of runtime governance in your SOA. An added benefit is that, after the service consumers and providers are registered in WSRR, you can visualize these relationships in the Service Registry Dashboard user interface and use it to assess the impact of any changes that you are planning to make to your service.

Modeling Service Providers

The business models contained within the GEP define all of the object types that you need to represent service providers, service consumers, and the agreements between them. The core types that are used to model service providers and service consumers are described in the following table.

Main object types in the Governance Enablement Profile (GEP)
Object TypeDescription
Organization iconOrganizationIn any governance process, there must be ownership. The organization object embodies this ownership. Every other object must be owned by an organization, either directly or indirectly.
Business Capability iconBusiness CapabilityA business capability object expresses a business view of a capability that is required within your enterprise. The object describes the business needs and concerns, but not the implementation. The capability can be viewed from a generalized business perspective. Several types of business capability are possible. For example, a capability might be used with other capabilities to build a wider capability. In this case, the capability is considered and represented as a business service. Business service, business application, and business process are specific types of business capability.
Capability Version iconCapability VersionA capability version is the realization of a business capability. The capability version indicates how the business capability is provided, for example, whether it is a web service, whether it requires messaging, and so on. Aspects of the implementation, such as web service definitions or SCA modules, are referenced from the capability version. In the same way that business capabilities have specific types, so do capability versions. For example, capabilities that are built from other capabilities, or are used to build other capabilities, can be considered as service versions. Service versions, application versions, and process versions are all specific types of capability version. One of the key aspects of capability version objects is that they have version numbers. There might be numerous versions of a capability version that realize the same business capability.
Service Level Definition iconService Level DefinitionThe SLD describes non-functional, or quality-of-service, characteristics of a capability. These include characteristics such as how many hours a day the capability is available, or the types of security needed for interactions with the capability. Consider a capability version deployed onto a number of different servers, servicing different types of customer, or different geographies. Each server might not be able to provide the same qualities of service and require unique SLDs. However, each consumer interacts with the capability in the same way.
Service Level Agreement iconService Level AgreementIf a Capability version is offered for reuse in your enterprise, the SLA must be created to describe the details of the agreement between the consumer and provider. The SLA is usually a subset of the qualities of service offered by the SLD of the providing capability version. For example, the SLD might state that the service is available Monday through Friday, but the SLA might define that the service is only required on Wednesday.
Service Endpoint iconService EndpointWhen a capability version is deployed on a runtime system, it has one or more network-addressable endpoints. These endpoints are represented by service endpoints. Service endpoint objects inform the consumer of the service where the service is available on the network.
Policy Attachment iconPolicy AttachmentPolicies specify the requirements that must be met so that a service can be consumed by a client. For example, a Web service may require that all messages are digitally signed and encrypted, or that it is only available at certain times; or that it can only handle a certain number of messages. The Policy Object includes the Policy Document, the Policy Expression, and the Policy Attachment.

The example shown in depicts a service provider. It illustrates how the WSRR objects relate to one another. A MathServiceBusiness Service is owned by the IT DepartmentOrganization. This business service has a real implementation in the form of the MathService (1.0)Service Version, which has been deployed into three geographical locations. Each geographical location hosts the service on a different server and so there is a different Service Level Definition for each installation. Each SLD can offer a distinct set of Service Endpoints for the service.

Modeling Service Providers
Modeling Service Providers
Modeling Service Providers

Service Level Definitions

As mentioned previously, a service provider uses a SLD to capture the QoS characteristics for a service. More specifically, each SLD captures the QoS characteristics for a set of endpoints for the service. If a service can be invoked using different endpoints, and these endpoints exhibit different qualities of service, the service provider should be define separate SLDs to reference the relevant endpoints.

The GEP also defines the Extended Service Level Definition type. The Extended SLD type defines additional QoS properties that can specified for a service such as Average Response Time and Maximum Messages Per Day. It provides an example of how you can extend the default SLD type in the model to include QoS properties that are relevant to you.

The Available Endpoints Relationship

The Available Endpoints relationship is used to associate the SLD for a service with the set of endpoints that can be used to invoke the service. If multiple endpoints are associated with a SLD this indicates that the non-functional characteristics defined on the SLD apply to each of the endpoints. shows the available endpoints relationships in red. When attempting to retrieve the targets of the available endpoints relationship programmatically, you need to refer to it using the name gep63_availableEndpoints.

Available Endpoints Relationship
Available Endpoints Relationship
Available Endpoints Relationship

Modeling Service Consumers

A service consumer is modeled in exactly the same way in WSRR as a service provider. This is due to the fact that, in a large number of cases, a service provider will also be a consumer of other services in your SOA. However, some important properties and relationships play a central role in the service consumption relationship at both design time and runtime. These are discussed in the following sections.

The Consumer Identifier Property

The consumer identifier property is used to uniquely identify the service consumer in any interaction that it has with another service provider. A service consumer should include its consumer identifier in any service requests it sends when invoking other services. The following example shows a service request from the Calculator Application to the Math Service. The consumer identifier for the Calculator Application is contained in the consumerID element contained in the SOAP header.

Example Math Service Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                     xmlns:math="http://math.pot.ibm.com">
  <soapenv:Header>
    <math:MathHeader>
      <consumerID>CalculatorApplication</consumerID>
      <contextID>CTX_1</contextID>
    </math:MathHeader>
   </soapenv:Header>
   <soapenv:Body>
      <math:add>
         <augend>1</augend>
         <addend>1</addend>
      </math:add>
   </soapenv:Body>
</soapenv:Envelope>

The consumer identifier can be used by various components in your SOA environment to determine whether the service consumer is authorized to invoke the target service. The proposed solution to the Business Problem described previously is to make use of a message flow in IBM Integration Bus to perform this check. The message flow needs to query WSRR to locate the Capability Version with the specified consumer identifier. The message flow will need to refer to the consumer identifier using its programmatic property name of gep63_consumerIdentifier.

The Service Level Agreements Relationship

The Service Level Agreements relationship is used to associate the service consumer with the SLAs that it has with other service providers. Because a service consumer might consume various other services, this relationship can have multiple targets. A service consumer can also have multiple SLAs with the same service provider. For example, using the scenario shown in the following figure, a consumer of the MathService service might have a separate SLA for each installation of the target service in the different geographical locations.

In the sample data that is provided with the articles in this series, Version 1.0. of the Calculator Application has a SLA with each versions of the Math Service, as shown in the following figure. The service level agreements relationships are shown in red. When processing the WSRR query results, the message flow will need to examine the SLAs of the service consumer. To locate the targets of the service level agreements relationship, it will need to refer to the service level agreements relationship using its programmatic name of gep63_consumes.

Calculator Application SLAs
Calculator Application SLAs
Calculator Application SLAs

Service Level Agreements

When a service consumer wishes to consume a service, they must come to an agreement with the service provider regarding how much of the service's overall capacity they are allowed to consume. When using WSRR, this information is encapsulated in a SLA. SLAs are contracts that formally and quantifiably define the qualities of service agreed between the service provider and the service consumer.

In terms of the core GEP types that were described previously, the SLA sits between the consuming capability version and the SLD of the service provider:

Service Consumption
Service Consumption
Service Consumption

When the details of the agreement between a service provider and a service consumer are captured in an SLA, you can use this information to aid the decision-making process in your SOA, both at design time and runtime. An example of how this information can be used at design time is the Service Consumption Visualizer widget that is available in the Service Registry Dashboard user interface provided with WSRR. This widget lets you visualize:

  1. All of the consumers of a specific service.
  2. All of the services that a specific service is consuming.
  3. The agreements that exist between service providers and service consumers.

This information can be used at design time when you are planning to make changes to an existing service. It helps you to identify all of the other services that might be impacted by the planned changes. The following figure shows how this information is displayed in the Service Consumption Visualizer widget.

Service Consumption Visualizer
Service Consumption Visualizer
Service Consumption Visualizer

The Context Identifier Property

The context identifier property is used to uniquely identify a SLA in WSRR. In situations where a service consumer has multiple SLAs, the context identifier can be used to identify the specific SLA that applies to a given service request. A service consumer should include the relevant context identifier in any service requests it sends to a specific target service. The example service request from the Calculator Application to the Math Service, shown in , shows the context identifier for the relevant SLA in the contextID element contained in the SOAP header.

To locate the SLA that applies to the current service request, the message flow will need to compare the context identifier specified in the input message with the context identifier on each SLA for the relevant service consumer. It will need to refer to the context identifier property on the SLA using its programmatic name of gep63_contextIdentifier.

The Agreed Endpoints Relationship

The Agreed Endpoints relationship is used to associate the SLA with a SLD for the service being consumed. It is central to the service consumption relationship because it links the set of objects that represent the service consumer to the set of objects that represent the service provider. It is called the agreed endpoints relationship because the SLD that is pointed to specifies the set of endpoints that can be invoked by the service consumer as part of the consumption agreement.

shows the agreed endpoints relationships in red. To determine the agreed endpoint to route the service request to, the message flow will need to locate the SLD that is pointed to by the relevant SLA. It will need to refer to the agreed endpoints relationship using its programmatic name of gep63_agreedEndpoints.

Agreed Endpoints Relationship
Agreed Endpoints Relationship
Agreed Endpoints Relationship

SLA Lifecycle

The SLA lifecycle in the GEP is used to govern a SLA from its initial identification, through to being activated, and, eventually, terminated when it is no longer required. There is an active/inactive loop, which allows it to be turned on or off as required. By making it active or inactive, a run time can determine whether a particular consumer is allowed to invoke a particular endpoint by checking whether the relevant SLA is in the correct state.

SLA Lifecycle
SLA Lifecycle
SLA Lifecycle

To ensure that the relevant SLA is active, the message flow will need to check that it is classified correctly. The OWL URI for the SLAActive state in the SLA lifecycle is http://www.ibm.com/xmlns/prod/serviceregistry/lifecycle/v6r3/LifecycleDefinition#SLAActive. This state, along with the other states that are defined on the SLA lifecycle, is described in the following table:

SLA lifecycle
TransitionTarget StateDescription
(Initial state)SLA identifiedThis state is entered as soon as a consumer, represented by a capability version, requests a dependency on a service version or other capability version that offers the service level definition (SLD) that they require.
Request SLASLA requestedThe agreed endpoints relationship target has been selected together with details of the required SLA properties and policies. The provider of the selected SLD must approve the request, reject it or ask for it to be revised.
Approve SLA requestSLA inactiveThe development team that want to consume the service can continue their development based on the consumption of this specific SLA, but they do not yet have authorization to access any endpoints.
Revise SLA requestSLA identifiedAs part of the negotiation of a SLA, the service provider requests a rework of the details of the SLA by the service consumer. This is done by moving the SLA back into the identified state, ready for a resubmission.
Activate SLASLA activeAll the approved endpoints associated with the SLD, that are online, can be invoked using the terms of the SLA. There might be situations where the SLA is deactivated, in which case the SLA enters the SLA inactive state and any further interactions are blocked until it is reactivated.
Deactivate SLASLA inactiveFor operational issues, the SLA is temporarily suspended by moving it back to the inactive state. After you remove the operational issues, you can reactivate the SLA.
Terminate SLASLA terminatedNo interactions from this SLA are permitted.

Message Flow Description

The SLA check message flow (as shown in the following figure) uses the consumer identifier specified in the service request to retrieve the metadata for the service consumer from WSRR. It uses this metadata to determine whether the specified service consumer is authorized to invoke the target service. If the service consumer is authorized to invoke the target service it forwards the request on to the agreed endpoint. If the service consumer is not authorized to invoke the target service it returns a suitable error. The sections that follow describe each of the nodes in this message flow in detail, along with any settings or code used to perform the SLA checking.

The SLA Check Message Flow
The SLA Check Message Flow
The SLA Check Message Flow

Service Request node

The flow starts with the Service Request SOAP Input node. The important point to note about this node is that it 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 the following figure. You can see that the MathServerServiceDummyEndpoint.wsdl file is specified in the WSDL file name field. The other basic properties for the node are automatically filled in after the WSDL file is 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/slacheck1. 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 SLA check flow using the out terminal.

Exposed WSDL Interface
Exposed WSDL Interface
Exposed WSDL Interface

Extract SOAP Headers node

The Extract SOAP Headers node is an instance of a Java Compute node. As the name suggests, this node processes the service requests that are passed to it by the Service Request node, extracting the consumer identifier and context identifier properties from the SOAP header. It then checks whether the values extracted are valid. The following code shows these tasks being performed.

Extracting the consumer identifier and context identifier
MbMessage inMessage = inAssembly.getMessage();
MbElement rootElement = inMessage.getRootElement();

MbElement consumerIdElement =
    rootElement.getFirstElementByPath("/SOAP/Header/MathHeader/consumerID");

MbElement contextIdElement =
    rootElement.getFirstElementByPath("/SOAP/Header/MathHeader/contextID");
    
if (  consumerIdElement != null && consumerIdElement.getValue() != null
   && contextIdElement != null &&contextIdElement.getValue() != null)
   {
        ...
}

If either of the identifiers specified in the service request is not valid, the Extract SOAP Headers node generates a SOAP fault and 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. This check is important and is performed at the very beginning of the message flow because the flow needs to be able to identify both the service consumer and the relevant SLA that applies to the service request.

After this initial check is passed, the Extract SOAP Headers node inserts the relevant fields into the local environment tree to programmatically override the properties on the Registry Lookup node. The code shown in configures the Registry Lookup node to retrieve objects that have a gep63_consumerIdentifier property that matches the consumer identifier specified in the SOAP header. In the GEP, the gep63_consumerIdentifier property is unique to the Capability Version abstract type and its sub-types, so the Registry Lookup node will only return objects of this type. The node then passes the message to the out terminal, which is wired to the Registry Lookup node.

Java code overriding Registry Lookup node variables
MbMessage environment = new MbMessage(inAssembly.getLocalEnvironment());
MbElement environmentRoot = environment.getRootElement();

environmentRoot.evaluateXPath(
    "?ServiceRegistryLookupProperties/?UserProperties/?gep63_consumerIdentifier[
    set-value('" + consumerIdElement.getValue() + "')]");

As discussed in Part 2: WSRR nodes in IBM Integration Bus, to deploy a flow containing the Registry Lookup node, a value must be specified for one of the Name, Namespace or Version properties on the node when defining the message flow. In this case, a dummy value for Name was used, and that value must be programmatically cleared at runtime before the node is used. The code in the Extract SOAP Headers node does this by using the code shown in the following example.

Programmatically clearing the name property
environmentRoot.evaluateXPath("?ServiceRegistryLookupProperties/?Name[set-value('')]");

Registry Lookup node

The behaviour of the Registry Lookup node is determined by the entries that were programmatically created in the local environment tree by the previous node. As explained previously, one or more Capability Version objects will be returned whose consumer identifier matches the value extracted from the service request. The node inserts representations of all the matching objects into the ServiceRegistry entry in the local environment tree and then passes the message to the out terminal.

The Match Policy for the node is set to All, even though a consumer identifier is supposed to uniquely identify a single service consumer registered in WSRR. Specifying a Match Policy of All allows the SLA check flow to verify that this is the case.

It is important to note that the Depth Policy is set to Return matched plus all related entities. (Depth = -1). With this Depth Policy specified, the Registry Lookup node will retrieve a representation of all of the Capability Version objects with a matching consumer identifier and all of the objects that they relate to downstream. This includes their SLAs, any SLDs pointed to by these SLAs and any endpoints pointed to by the SLDs. Because all of this information is returned as the result of a single query against WSRR, this allows the SLA check message flow to verify that the service consumer is authorized to invoke the target service and route the request to the relevant endpoint without needing to retrieve additional metadata from WSRR.

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

SLA Check node

The SLA Check node is another instance of a Java Compute node and it is the node where the majority of the work takes place in this message flow. This node processes the results of the query performed by the previous Registry Lookup node, using the metadata returned to check whether a valid SLA exists between the service consumer and the service provider.

As mentioned previously, the results of the query will contain representations of all of the Capability Version objects with a matching consumer identifier. Because a consumer identifier is supposed to uniquely identify a single service consumer registered in WSRR, the first check that the SLA Check node performs is to verify that only a single Capability Version was returned. If more than one Capability Version with a matching consumer identifier was returned, the node generates a SOAP fault and 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. The code in the following example shows these tasks being performed.

Checking that a single service consumer was returned
MbElement rootElement = inAssembly.getLocalEnvironment().getRootElement();
MbElement serviceRegistry = rootElement.getFirstElementByPath("/ServiceRegistry");

List<MbElement> consumingVersions =
    (List <MbElement>)serviceRegistry.evaluateXPath("Entity");

if (consumingVersions != null && consumingVersions.size() == 1) {
    MbElement consumer = consumingVersions.get(0);
        ...
} else {        
    outAssembly = MessageUtils.createSOAPFault(inAssembly
                , "ERROR_SLA_003"
                , "Multiple CapabilityVersions found with the specified consumer id."
                , "The consumer id specified does not resolve to a unique"
                  + " CapabilityVersion in WSRR."
                );
    outputTerminal = getOutputTerminal("failure");
}

The next task that the SLA Check node needs to perform is to locate the SLA for the service consumer that has a context identifier that matches the one specified in the service request. Several steps are involved with this task:

  1. The SLA Check node needs to retrieve all of the targets of the gep63_consumes relationship for the service consumer. The targets will be instances of SLAs that are defined for the service consumer and, as discussed in , there may be more than one.
  2. The SLA Check node then checks the list of SLAs to ensure that it is not empty.
  3. If there is at least one SLA, the SLA Check node then retrieves the context identifier from the original service request and uses it to locate the SLA with a matching gep63_contextIdentifer, verifying that it was able to locate it.

The code in the following example shows these tasks being performed. The blocks of code for each else statement generate a SOAP fault with a suitable error message and passes the message to the failure terminal. The code for these blocks has been omitted for brevity.

Locating the specified SLA
List<MbElement> slas = (List<MbElement>)consumer.evaluateXPath(
    "userDefinedRelationships[@name='gep63_consumes']/targetEntities/Entity"); 

if (slas != null && !slas.isEmpty()) {
    String contextId = getContextId(inMessage);
    if (contextId != null) {
        MbElement sla = getSLAByContextId(slas, contextId);
        if (sla != null) {
            ...
        } else {
            ...
        }
    } else {
        ...
    }
} else {
    ...
}

private MbElement getSLAByContextId(List<MbElement> slas, String contextId)
    throws MbException {
        
    MbElement matchingSla = null;
    for (MbElement sla : slas) {
        if ((Boolean)sla.evaluateXPath(
            "userDefinedProperties[@name='gep63_contextIdentifier']/attribute::value ='"
            + contextId + "'")) {
            
            matchingSla = sla;
            break;
        }
    }
        
    return matchingSla;
}

Having located the relevant SLA for the service request, the next check performed by the SLA Check node is to verify that the SLA is active. When a lifecycle is applied to an object in WSRR, WSRR adds the OWL URI for the current lifecycle state to the list of classifications on the object. Therefore, to check whether an object is in a given state, you simply need to see if it is classified with relevant OWL URI for that state. The code in the following example shows these tasks being performed. If the SLA is not in the active state a SOAP fault is generated with a suitable error message and this is passed to the failure terminal.

Checking that the SLA is active
protected static final String OWL_URL_SLA_ACTIVE = 
    "http://www.ibm.com/xmlns/prod/serviceregistry/lifecycle/v6r3/LifecycleDefinition#"
    + "SLAActive";

if (isActive(sla)) {
} else {
    ...
}

private boolean isActive(MbElement sla) throws MbException {
    return (Boolean)sla.evaluateXPath("classificationURIs='" + OWL_URL_SLA_ACTIVE + "'");
}

Having established that the SLA is active, the next task is to retrieve the list of endpoints that the service consumer is authorized to use when invoking the service. As described previously, to navigate from the SLA to the list of agreed endpoints, you need to traverse two relationships, as follows:

  1. The Agreed Endpoints relationship that associates a SLA with the SLD of the service being consumed. Recall that the programmatic name of this relationship is gep63_agreedEndpoints.
  2. The Available Endpoints relationship that associates a SLD for a service provider with the set of endpoints that can be used to invoke the service. Recall that the programmatic name of this relationship is gep63_availableEndpoints.

Fortunately, because all of this information is retrieved from WSRR, you can traverse both of these relationships by using a single XPath expression. The following example shows the code required to navigate these relationships. If no endpoints are returned a SOAP fault is generated with a suitable error message and this is passed to the failure terminal.

Retrieving the available endpoints
List<MbElement> availableEndpoints = (List<MbElement>)sla.evaluateXPath(
    "userDefinedRelationships[@name='gep63_agreedEndpoints']/targetEntities/Entity/"
    + "userDefinedRelationships[@name='gep63_availableEndpoints']/targetEntities/Entity");
    
if (availableEndpoints != null && !availableEndpoints.isEmpty()) {
    ...
} else {
    ...
}

The next task to perform is to select the first endpoint from the list that is in the online state. Again, this is achieved by checking whether an endpoint is classified with the relevant OWL URI for this state. shows the code required to select the first online endpoint. If none of the available endpoints are currently in the online state in WSRR, a SOAP fault is generated with a suitable error message and this is passed to the failure terminal.

Selecting an online endpoint
protected static final String OWL_URL_ONLINE =
    "http://www.ibm.com/xmlns/prod/serviceregistry/lifecycle/v6r3/LifecycleDefinition#"
    + "Online";

String addressUrl = selectEndpoint(availableEndpoints, inAssembly);
if (addressUrl != null) {
    ...
} else {
    ...
}

protected boolean isOnline(MbElement endpoint) throws MbException {
    return (Boolean)endpoint.evaluateXPath("classificationURIs='" + OWL_URL_ONLINE + "'");
}
    
public String selectEndpoint(List<MbElement> availableEndpoints, MbMessageAssembly 
inAssembly) throws MbException {
        
    String addressUrl = null;
        
    for (MbElement availableEndpoint : availableEndpoints) {
        if (isOnline(availableEndpoint)) {
            addressUrl = (String)availableEndpoint.evaluateXPath(
                "string(userDefinedRelationships[@name='sm63_soapAddress']"
                + "/targetEntities/Entity/attribute::location)");
            break;
        }
    }
        
    return addressUrl;
}

The SLA Check message flow has now verified that there is an active SLA in place between the service consumer and the service provider, and that there is at least one online endpoint registered in WSRR for the target service. The message flow is now in a position to forward the service request onto the target service. To do this, the SLA check 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 SLA Check 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 SLA Check node then passes the message to the out terminal, which is wired to the Forward Request node.

Programmatically specifying the web service URL
MbMessage environment = new MbMessage(inAssembly.getLocalEnvironment());
MbElement environmentRoot = environment.getRootElement();

environmentRoot.evaluateXPath(
    "?Destination/?SOAP/?Request/?Transport/?HTTP/?WebServiceURL[set-value('"
    + addressUrl + "')]");

Forward Request and SOAP Reply nodes

The Forward Request node is responsible for calling the target service, in this case Version 1.0 of the Math Service. You must specify a value for the Web Service URL property on this node when defining the flow, even though this will be programmatically overwritten at runtime by the SLA Check node. As a result, a dummy value of http://tempuri.org/MathServer/services/MathServer has been specified for this property. Another important point to note is that the Operation mode for the node must be set to Invoke a generic web service. This is specified on the Basic tab of the Properties editor for the node. It enables the flow to proxy requests for any of the operations defined on the Math Service rather than being forced to proxy an individual operation. The Forward Request node is wired directly to the SOAP Reply node using all its terminals; out, fault and failure.

"SOAP Request and SOAP Reply nodes
SOAP Request and SOAP Reply nodes

The SOAP Reply node 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 an error occurs, the response will be a SOAP fault that was generated by one of the Java Compute nodes in the flow, or by the target service itself.

No Match Fault node

When an error occurs in either of the Extract SOAP Headers or SLA Check Java Compute nodes, the nodes programmatically generate an appropriate SOAP fault and pass this to their failure terminals. These are wired directly to the SOAP Reply node. However, when the query performed by the Registry Lookup node does not return any results, it does not automatically generate a SOAP fault. To do this, the NoMatch terminal for the Registry Lookup node is wired to the No Match Fault Java Compute node. This node programmatically generates a SOAP fault that is returned to the service consumer using the SOAP Reply node.

Testing the Message Flow

These steps describe how to use the Calculator application to verify that the SLA Check flow is working correctly.

Basic Test

  1. Make sure that your IBM Integration Bus execution group is running, with the RegistryLookup_SLACheck flow deployed and started.
  2. Start the calculator application, as described in Running the Calculator Application in Part 1.
  3. Enter the hostname and port number values for the server that is running IIB. 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/slacheck1. This is the endpoint for the RegistryLookup_SLACheck flow.
  5. Set the Consumer ID to CalculatorApplication. This is the consumer identifier that has been specified on the Application Version in WSRR that represents the Calculator application.
  6. Set the Context ID to CTX_1. This is the context identifier that has been specified on the SLA that represents the consumption agreement between the Calculator application and the Math Service.
  7. Enter the calculation you wish to perform using the number fields and the operator drop-down menu. The Calculator application should look similar to this when you have entered all of the information:
    The Calculator Application set up to use the SLA check message flow
    The Calculator Application set up to use the SLA check message flow
    The Calculator Application set up to use the SLA check message flow
  8. Click = (the equals button). The Calculator application will send a service request to the SLA check message flow, which will route the request to the actual Math Service. The result is ultimately returned to the Calculator application and is then displayed.

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

  1. You have performed all of the configuration steps in Part 1: Scenarios and configuration.
  2. You have specified the correct path for the flow (/MathServer/services/MathServer/slacheck1).
  3. You have specified the correct consumer identifier (CalculatorApplication).
  4. You have specified the correct context identifier (CTX_1).

Advanced Tests

To verify that the checks performed by the message flow are working correctly, you need to modify the state of the relevant objects in WSRR and then test the effect on the behaviour of the flow. The sections that follow describe the how to perform these tests.

Deactivating and reactivating the SLA

  1. Start the Calculator application and perform a calculation to check that the message flow is working correctly.
  2. In a Web browser, log on to the Service Registry Dashboard for your WSRR instance.
  3. Change to the SOA Governance view and then select the Overview page.
  4. Select SLA - CalculatorApplication 1.0 to MathService 1.0 in the Collection widget:
    The SOA Governance View
    The SOA Governance View
    The SOA Governance View
  5. 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. Select Action => Deactivate SLA:
    Deactivating the SLA
    Deactivating the SLA
    Deactivating the SLA
  6. When the operation has completed an Operation Successful dialog will be displayed. Click OK. The governance state of the SLA has changed to SLA Inactive.
  7. Go to the Calculator application, and try to perform another calculation. The message Error: Unable to invoke math service. is displayed at the bottom of the application.
  8. Back in the Service Registry Dashboard, reactivate the SLA by selecting Action => Activate SLA. After the operation is completed, click OK. The SLA now has a governance state of SLA Active.
  9. Go to the Calculator application, and try to perform another calculation. This time the operation succeeds.

Taking the endpoints offline

  1. Start the Calculator application and perform a calculation to check that the message flow is working correctly.
  2. In a Web browser, log on to the Service Registry Dashboard for your WSRR instance.
  3. Change to the SOA Governance view and then select the Overview page.
  4. Select the MathService in the Approved Business Capabilities collection.
  5. You will taken to the Browse page, which will display the details of the MathService business service in the Detail widget. This is a business representation of the Math Service in WSRR. In this widget, under Versions , select MathService ‪(1.0).
  6. The Detail widget will be updated to display the details of the MathService (1.0) service version. This is a representation of an implementation of the Math Service in WSRR, specifically version 1.0. In the Detail widget, under Service Level Definitions select SLD - MathService v1.0.
  7. 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://localhost:7800/MathServer1/services/MathServer ‪(1.0). The port number for your endpoint may be different if your IBM Integration Bus instance is not using the default port to listen for HTTP requests.
  8. The Detail widget will be updated to display the details of the http://localhost:7800/MathServer1/services/MathServer ‪(1.0) endpoint. Select Action => Revoke from use.
  9. After the operation has completed, click OK. The endpoint now has a governance state of Offline. Both of the endpoints for the version 1.0 of the Math Service should now be Offline.
  10. Go to the Calculator application, and try to perform another calculation. The message Error: Unable to invoke math service. is displayed at the bottom of the application.
  11. Back in the Service Registry Dashboard, switch the http://localhost:7800/MathServer1/services/MathServer ‪(1.0) endpoint back online by selecting Action => Approve For Use. After the operation is completed, click OK. The endpoint now has a governance state of Online.
  12. Go to the Calculator application, and try to perform another calculation. This time the operation succeeds.

Conclusion

This article described an example message flow that enforces SLAs defined in WSRR at runtime. The message flow uses the Registry Lookup node to retrieve the metadata for the service consumer. It then uses this metadata to verify that the service consumer is authorized to invoke the target service by checking that it has an active SLA with the service provider and that the target service has at least one online endpoint registered in WSRR.

An alternative solution to this business problem is presented in Part 8: SLA checking using the HTTP Request node. That solution makes use of the HTTP Request node to execute the SLAEndpointLookup named query using the WSRR REST API. This named query verifies that the service consumer is authorized to invoke the target service by checking that it has an active SLA with the service provider. It then returns any online endpoints for the target service that are registered in WSRR.

The benefits of using the Registry Lookup node are:

  • It provides specific support for querying WSRR out-of-the-box in IBM Integration Bus and does not necessarily require any additional coding in a compute node before the node is invoked.
  • It makes use of the WSRR Cache in IBM Integration Bus automatically without the need for further coding.
  • All of the validation can be performed in the actual message flow based on the metadata that was retrieved. As a result, the message flow can be very precise about exactly why it is rejecting a request, returning a suitable error message in a SOAP fault.

Of course, using the Registry Lookup node has some drawbacks:

  • You do not have much control over the XPath expression that is generated by the node. As a result, it is not possible to generate XPath expressions that traverse multiple relationships and apply predicates at various stages in the query. This forces you either to perform a query against WSRR to a greater depth than you might like, or to perform multiple queries against WSRR in a single flow.
  • You are unable to control the type of query that is performed against WSRR. Both the Endpoint Lookup and Registry Lookup nodes in IBM Integration Bus perform Graph Queries against WSRR, which can potentially return a large amount of data and do not perform as well as Property Queries on the WSRR server.

Acknowledgements

The author would like to thank 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 would also like to thank 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=970296
ArticleTitle=Integrating IBM Integration Bus with WebSphere Service Registry and Repository: Part 5: Performing SLA checks at runtime and registry lookup scenarios
publish-date=04302014