WebSphere WebSphere Enterprise Service Bus, Version 6.0.2 Operating Systems:

Endpoint Lookup mediation primitive

Use the Endpoint Lookup mediation primitive to dynamically route messages to appropriate service endpoints. The Endpoint Lookup searches for service information in a WebSphere Service Registry and Repository (WSRR).

Introduction

The Endpoint Lookup mediation primitive lets you retrieve service endpoint information from a WSRR registry that can be local or remote. The service endpoint information can relate directly to Web services or to Service Component Architecture (SCA) module exports.
Note: Mediation modules are types of SCA modules

In order to use the Endpoint Lookup mediation primitive you might need to add service endpoint information to your WSRR registry. If you want to extract service endpoint information about Web services, then your WSRR registry must contain the appropriate WSDL documents or SCA modules that contain exports using Web service bindings. If you want to extract service endpoint information about exports that use the default SCA binding, then your WSRR registry must contain the appropriate SCA modules.

The Endpoint Lookup mediation primitive lets you retrieve service endpoint information that relates to the following:
  • Web services using SOAP/HTTP.
  • Web services using SOAP/JMS.
  • Mediation module exports with Web service bindings, using SOAP/HTTP.
  • Mediation module exports with Web service bindings, using SOAP/JMS.
  • Mediation module exports with the default SCA binding.

When the Endpoint Lookup mediation primitive receives a message it sends a search query to the registry. The search query is constructed using the Endpoint Lookup properties that you specify and the query might return nothing, or might return one or more service endpoints. You can choose whether to be informed of all endpoints that match your query, or just one endpoint that matches your query.

The Endpoint Lookup mediation primitive has one input terminal and three output terminals. The input terminal is wired to accept a message and the output terminals are wired to propagate a message. One of the output terminals is for failure output. If an exception occurs during the processing of the input message, then the fail terminal propagates the original message, together with any exception information. If service endpoints are retrieved from the registry then the out terminal propagates the original Service Message Object (SMO) modified by the service endpoint information. If no services are retrieved from the registry then the noMatch terminal propagates an unmodified message.

Note:
In order for the runtime to implement dynamic routing on a request, you must set the Use dynamic endpoint property, in the callout node. Optionally, you can specify a default endpoint that the runtime uses if it cannot find a dynamic endpoint. You specify a default endpoint by wiring an import that has the default service selected.

Details

If you specify an endpoint Match Policy of One, and your registry query returns matches, then the dynamic callout address in the SMO header is updated with one service address and the SMO context is updated with registry information relating to that service.

If you specify an endpoint Match Policy of All, and your registry query returns matches, then the SMO context is updated with registry information relating to all services returned by the registry. The dynamic callout address in the SMO header is not updated. Therefore, you need to post-process the SMO to select a service endpoint.

The SMO context contains a primitiveContext element that is used for storing state information. The Endpoint Lookup mediation primitive uses an element within the primitiveContext, called EndpointLookupContext, to store the results of WSRR queries. A number of service endpoints can be stored within the SMO context. If you specify a Match Policy of One then the Endpoint Lookup mediation primitive updates the SMO header at /headers/SMOHeader/Target/address. If you specify a Match Policy of All then you must wire the Endpoint Lookup mediation primitive to another mediation primitive that decides which endpoint to use, and moves endpoint information from the SMO context to /headers/SMOHeader/Target/address.

The Endpoint Lookup mediation primitive uses the Endpoint Reference structure defined by the WS-Addressing specification http://schemas.xmlsoap.org/ws/2004/08/addressing.

Usage

You can use the Endpoint Lookup mediation primitive to dynamically route messages based upon customer classification. For example, you might want messages for customers of type A routed to URL X, and messages for customers of type B routed to URL Y. If you set up your registry to key URLs against customer types, then you can dynamically route customer requests according to customer type.

You can use the Endpoint Lookup mediation primitive, together with other mediation primitives, to add security to dynamic routing. For example, you could use the Endpoint Lookup, Message Filter and XSLT mediation primitives to check whether an endpoint was external or internal, and remove any internal information from public messages. To do this you might wire the matching output terminal of the Endpoint Lookup mediation primitive to the input terminal of the Message Filter mediation primitive. You could then use the Message Filter mediation primitive to check whether the URL was internal or external, and route external messages to the XSLT mediation primitive: wire one of the Message Filter output terminals to the XSLT mediation primitive. Lastly, you could use the XSLT mediation primitive to remove private information from messages.

Properties

Registry Name
Identifies the WSRR definition to be used by Endpoint Lookup mediation primitive. A WSRR definition is created using the server administrative console and provides connection information for a WSRR instance. At least one WSRR definition needs to exist on the server that your mediation module is installed to. If the Registry Name is absent then the default WSRR definition is used.
Match Policy
If the registry has more than one service matching your query, then Match Policy determines how many service endpoints should be added to the message. Specify One to add only one match, and specify All to add all matches. If you choose a Match Policy of One then the Endpoint Lookup mediation primitive selects the first service returned from the registry. If you choose a Match Policy of All then, typically, you would wire the match output terminal of the Endpoint Lookup to another mediation primitive. This is because if multiple endpoints are returned, the SMO context is updated but the dynamic callout address in the SMO header is not updated. Therefore, you need to post-process the SMO to select a service endpoint.
PortType Name
Search the registry for services that implement a particular portType, the name of which is specified by PortType Name.
PortType Namespace
Search the registry for services that implement a particular portType, the namespace of which is specified by PortType Namespace. The PortType Namespace can be specified in any valid namespace format. For example, URI or URN.
PortType Version
Search the registry for services that implement a particular portType, the version of which is specified by PortType Version.
User Properties
Search the registry for services that are annotated with user defined properties.
Name
The name of the user defined property.
Type
The type of the user defined property. If the type is String then what you specify as the Value is used as a literal, in the search query. If the type is XPath then what you specify as the Value must be an XPath expression. The XPath expression must resolve to a unique leaf node in the inbound SMO. The value of the leaf node is used in the search query.
Value
The value of the user defined property. This can be either a literal value or an XPath expression, depending upon the Type property.
Classification
Search for objects that match a particular classification. The WSRR classifies objects using the ontology classification system (OWL), in which each classifier is a class and has a URI. OWL implements a simple hierarchical system. For example, a bank account could start with the following details:
  • Account
    • Identifier
    • Name
      • First name
      • Second name
    • Address
      • First line of address
      • Second line of address
Specifying a classification of Address matches any object classified as Address, First line of address or Second line of address.
Table 1. Endpoint Lookup mediation primitive properties
Property Valid Values Default
Registry Name String The default registry
Match Policy String: One or All. One
PortType Name String  
PortType Namespace String  
PortType Version String  
User Properties Name String  
Type String or XPath  
Value Dependent on Type  
Classification List of URIs  

Considerations

Consider the following when using the Endpoint Lookup mediation primitive:

SOAP/HTTP example

The URI format in the case of an export with a Web service binding, is as follows:
http://<host>:<port>/<moduleName>/sca/<exportName>
The URI format in the general Web service case, (when a Web service is not implemented by an export with a Web service binding), is as follows:
 http://<host>:<port>/<service>
Consider the following example WSDL.
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="SOAP_HTTPExport_BigEchoHttp_Service" targetNamespace="http://big.com/Binding3" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:Port_0="http://big.com" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:this="http://big.com/Binding3" xmlns="http://schemas.xmlsoap.org/wsdl/">
  <wsdl:import namespace="http://big.com" location="BigEcho.wsdl"/>
  <wsdl:binding name="SOAP_HTTPExport_BigEchoHttpBinding" type="Port_0:BigEcho">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="echo">
      <soap:operation/>
      <wsdl:input name="echoRequest">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="echoResponse">
        <soap:body use="literal"/>
      </wsdl:output>
      <wsdl:fault name="BadBoyException">
        <soap:fault name="BadBoyException" use="literal"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="SOAP_HTTPExport_BigEchoHttpService">
    <wsdl:port name="SOAP_HTTPExport_BigEchoHttpPort" binding="this:SOAP_HTTPExport_BigEchoHttpBinding">
      <soap:address location="http://testhost:9080/RegistryWeb/sca/SOAP_HTTPExport"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

The port declaration contains a soap:address location of http://testhost:9080/RegistryWeb/sca/SOAP_HTTPExport. This indicates that it is an export with a Web service binding. To enable dynamic routing, update the /headers/SMOHeader/Target/address field in the message with the location value in the soap:address element.

SOAP/JMS example

The URI format in the case of an export with a Web service binding, is as follows:
jms:/queue?destination=jms/WSjmsExport&connectionFactory=jms/WSjmsExportQCF&targetService=WSjmsExport_ServiceBJmsPort
The URI format in the general Web service case, (when a Web service is not implemented by an export with a Web service binding), is as follows:
 jms:/queue?destination=<destName>&connectionFactory=<factory>&targetservice=<service>
Consider the following example WSDL.
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="SOAP_JMSExport_BigEchoJms_Service" targetNamespace="http://big.com/Binding4" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:Port_0="http://big.com" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:this="http://big.com/Binding4" xmlns="http://schemas.xmlsoap.org/wsdl/">
  <wsdl:import namespace="http://big.com" location="BigEcho.wsdl"/>
  <wsdl:binding name="SOAP_JMSExport_BigEchoJmsBinding" type="Port_0:BigEcho">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/jms"/>
    <wsdl:operation name="echo">
      <soap:operation/>
      <wsdl:input name="echoRequest">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="echoResponse">
        <soap:body use="literal"/>
      </wsdl:output>
      <wsdl:fault name="BadBoyException">
        <soap:fault name="BadBoyException" use="literal"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="SOAP_JMSExport_BigEchoJmsService">
    <wsdl:port name="SOAP_JMSExport_BigEchoJmsPort" binding="this:SOAP_JMSExport_BigEchoJmsBinding">
      <soap:address location="jms:/queue?destination=jms/SOAP_JMSExport&;connectionFactory=jms/SOAP_JMSExportQCF&;targetService=SOAP_JMSExport_BigEchoJmsPort"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

SCA default binding example

The URI format in the case of an export with the default SCA binding, is as follows:
sca://<moduleName>/<exportName>

For services that use the SCA binding, the URI is never physically present in the resources that define that service.

If using an Endpoint Lookup mediation primitive to retrieve endpoint information about services using the SCA binding from a service registry, the Endpoint Lookup will derive this URI from the information returned by the registry.

Consider the following example SCDL.
<?xml version="1.0" encoding="UTF-8"?>
<scdl:export xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://big.com" xmlns:scdl="http://www.ibm.com/xmlns/prod/websphere/scdl/6.0.0" xmlns:wsdl="http://www.ibm.com/xmlns/prod/websphere/scdl/wsdl/6.0.0" displayName="SCAExport" name="SCAExport">
  <interfaces>
    <interface xsi:type="wsdl:WSDLPortType" portType="ns1:BigEcho">
      <method name="echo"/>
    </interface>
  </interfaces>
</scdl:export

Reference topic

Terms of Use | Rate this page

Timestamp iconLast updated: 29 Oct 2006
http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.wbit.help.medprim602.doc\ref\rwesb_EndpointLookupmediationprimitive.html

(C) Copyright IBM Corporation 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)