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,
your WSRR registry must contain either 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, 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.
- SCA module exports with Web service bindings, using SOAP/HTTP.
- SCA module exports with Web service bindings, using SOAP/JMS.
- SCA 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 it 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
(
in), two output terminals (
out and
noMatch), and a fail terminal (
fail). The
in terminal is wired
to accept a message and the other terminals are wired to propagate
a message. If an exception occurs during the processing of the input
message, the
fail terminal propagates the input
message, together with any exception information. If service endpoints
are retrieved from the registry, the
out terminal
propagates the original service message object (SMO) modified by the
service endpoint information. If no services are retrieved from the
registry, the
noMatch terminal propagates an
unmodified message.
Note: In order for the run time to implement dynamic
routing on a request, you must set the Use dynamic endpoint
if set in the message header property in the callout node
or Service Invoke mediation primitive. You can specify a default endpoint
that the run time uses if it cannot find a dynamic endpoint. You specify
a default endpoint by wiring an import that has the default service
selected.
Details
The Endpoint Lookup mediation primitive
uses the Endpoint Reference structure defined by the WS-Addressing
specification. For more information, see: http://schemas.xmlsoap.org/ws/2004/08/addressing.
Updates made to the SMO by the Endpoint Lookup mediation
primitive are dependant on the success of the registry query (matches
are found during the registry query) and the match policy.
The Endpoint Lookup mediation primitive can make updates to both
the SMO context (the
primitiveContext element) and
to SMO headers:
- /headers/SMOHeader/Target/address.
- Can contain the address of a service to invoke dynamically (the
dynamic callout address).
- /context/primitiveContext/EndpointLookupContext.
- Can contain the results of the WSRR query.
- /headers/SMOHeader/AlternateTarget
If the Endpoint Lookup mediation primitive updates the SMO
with one or more endpoint addresses, it will also update the SMO so
that each endpoint address has an associated bindingType. The bindingType set by the Endpoint Lookup mediation
primitive can be either WebService or SCA.
Match policy
The match policy (specified
using the
Match Policy property) can be one of
the following:
- Return first matching endpoint and set routing target.
- If the registry query returns matches, the following occurs:
- The dynamic callout address, in the SMO header, is updated with
one service address from the results returned.
- The SMO context is updated with registry information relating
to the address in the dynamic callout address.
- The alternate targets list, in the SMO header, is cleared.
- Return all matching endpoints.
- If the registry query returns matches, the following occurs:
- 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 cleared.
- The alternate targets list, in the SMO header, is cleared.
- You must post-process the SMO to select a service endpoint for
dynamic invocation.
- Return all matching endpoints and set alternate routing
targets.
- If the registry query returns matches, the following occurs:
- The dynamic callout address, in the SMO header, is set with the
first match.
- The alternate targets list, in the SMO header, is updated with
the remaining matches.
- All services found are also placed into the primitive context.
- Return endpoint matching latest compatible service version.
- If the registry query returns matches, the following occurs:
- The dynamic callout address, in the SMO header, is updated with
one service address from the results returned.
- The SMO context is updated with registry information relating
to the address in the dynamic callout address.
- The alternate targets list, in the SMO header, is cleared
If no match is found during a registry query, regardless
of the match policy, the noMatch output terminal
is fired and the original input SMO is propagated.
The following
table summarizes the effect of the match policy on the SMO elements:
Table 1. Effect of match policy on SMO Match Policy |
First |
All |
All and Alternates |
Latest compatible |
Output terminal |
out |
noMatch |
out |
noMatch |
out |
noMatch |
out |
noMatch |
Target |
update |
no action |
clear |
no action |
update |
no action |
update |
no action |
Primitive context |
update |
no action |
update |
no action |
update |
no action |
update |
no action |
Alternate targets |
clear |
no action |
clear |
no action |
update |
no action |
clear |
no action |
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.
- Use the Message Filter mediation primitive to check whether the
URL was internal or external, and route external messages to the XSLT
mediation primitive (by wiring one of the Message Filter output terminals
to the XSLT mediation primitive).
- Use the XSLT mediation primitive to remove private information
from messages.
Properties
- Registry Name
- Identifies the WSRR definition to be used by the 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 SCA 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,
the Match Policy determines how many service
endpoints should be added to the message. It also determines whether
the matching should select exact matches or the latest compatible
service versions.
- Name
- Search the registry for services that implement a particular portType,
the name of which is specified by the Name property.
- Namespace
- Search the registry for services that implement a particular portType,
the namespace of which is specified by the Namespace property. The Namespace can be specified in
any valid namespace format, for example, URI or URN.
- Version
- The Version property can be used in one
of two ways. If you are using portTypes, this field holds the version
of the portType. However, if you are using versioned SCA modules,
this field holds the version of the SCA module.
If you are using
portTypes, the registry is searched for services that implement a
particular portType.
If you are using versioned SCA modules,
to do service-version-aware lookups, you must select a Match
Policy of Return endpoint matching latest compatible
service version. In addition, you must set the Version property to be the version of the SCA module,
and set the Module and Export properties. For versioned SCA modules, the format of the Version property is: V.R.M, where V is an integer version
number, R is an integer release number, and M is an integer modification
number. The version supplied can include one or more wildcard (*)
characters. For example, a Version property of 1.0.* will find the endpoint of the service that has
a version set to 1, a release set to 0, and the greatest modification
number. For further information, see: Matching latest compatible
service versions.
- Module
- The SCA module name. Only used when the Match Policy property is set to Return endpoint matching latest compatible
service version. Search the registry for SCA modules with
a name that matches the specified Module name.
Must be used in conjunction with the Export property.
- Export
- The SCA export name. Only used when the Match Policy property is set to Return endpoint matching latest compatible
service version. Search the registry for SCA exports with
a name that matches the specified Export name.
Must be used in conjunction with the Module property.
- User Properties
- Search the registry for services that are annotated with user-defined properties.
Note: - If you want to extract endpoint information about exports that
use the default SCA binding then, in WSRR, you must specify any user
properties on the SCA Export objects that you want to retrieve. Make
sure that you put user properties on the SCA Exports and not on the
SCA Export documents.
- If you want to extract endpoint information about Web services
then, in WSRR, you must specify any user properties on the appropriate
WSDL Port objects. The WSDL Port objects must implement a port type
that you describe using the Endpoint Lookup properties relating to
portType.
- 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.
Note: - If you want to extract endpoint information about exports that
use the default SCA binding then, in WSRR, you must specify any classifications
on the SCA Export objects that you want to retrieve. Make sure that
you put classifications on the SCA Exports and not on the SCA Export
documents.
- If you want to extract endpoint information about Web services
then, in WSRR, you must specify any classifications on the appropriate
WSDL Port objects. The WSDL Port objects must implement a port type
that you describe using the Endpoint Lookup properties relating to
portType.
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
- 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 2. Endpoint Lookup mediation primitive
propertiesProperty |
Valid Values |
Default |
Registry Name |
String |
The default registry |
Match Policy |
String: Return all matching endpoints, Return first matching endpoint and set routing target, or Return all matching endpoints and set alternate routing
targets or Return endpoint matching latest
compatible service version. |
Return first matching endpoint
and set routing target |
Name |
String |
|
Namespace |
String |
|
Version |
String |
|
Module |
String |
|
Export |
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:
- If the Use dynamic endpoint if set in the message header property is not set in the callout node, the run time does not use
the dynamic endpoint in /headers/SMOHeader/Target/address. In this case, the run time uses the default endpoint if there is
one, or throws an error.
- It is valid to specify only the Match Policy property. In this case, the default registry is queried for all
applicable services.
- All portType, Classification or User Properties specified for an Endpoint Lookup mediation
primitive result in a query that combines all of these properties
using a logical AND.
- If you want to use Classification URIs that
include white space characters, the correct URL encoding should be
used. For example, a single character space should be represented
as %20.
- White space characters provided in any of the Endpoint Lookup
mediation primitive properties are treated as literal characters.
They are not removed by the Endpoint Lookup mediation primitive when
querying the registry. For example, if you specify a Classification property and the expected results are not returned from a query,
ensure there is no white space before or after the Classification URI.
- If you use the Return endpoint matching latest compatible
service version Match Policy, the Module and Export properties must
be supplied and only SCA export objects are queried in the registry.
- If you want to retrieve endpoints from WSDL that has SOAP 1.2
bindings, the WSRR definition must use the Version 6.2 Web service
interface URL, which is generally: http://<server>:<port>/WSRR6_2/services/WSRRCoreSDOPort. However, if you call the Version 6.2 URL from a client generated
for a previous version of WSRR, the client might fail if it cannot
correctly process the data that is returned.
Matching latest compatible service versions
If you have created versioned SCA modules, and have loaded these
SCA modules into WSRR, you might want to use the latest compatible
version of the service provider that is available.
To find
the latest compatible version of the provider service, use the Return endpoint matching latest compatible service version Match Policy. In this case, the mediation primitive
queries the registry for all SCA exports with the supplied properties.
The format of the Version property is: V.R.M,
where V is an integer version number, R is an integer release number
and M is an integer modification number. You must specify the version.
However, you do not have to specify the release or modification; alternatively,
you can specify the wildcard (*) character.
The mediation primitive
chooses the latest compatible matching service, by comparing the versions
of the services returned by WSRR with the
Version property, following these rules:
- If the Version modification (3rd digit) is declared
- Exact match at version (1st digit) and release (2nd digit), and
a modification (3rd digit) that is equal to or greater than the declared
value.
- If the Version modification (3rd digit) is not declared, or is
a wild card (*), but the Version release (2nd digit) is declared
- Exact match at version (1st digit) and release (2nd digit), and
the greatest modification (3rd digit) in the release.
- If the Version modification (3rd digit) and the Version release
(2nd digit) are not declared, or are wild cards (*)
- Exact match at version (1st digit), and the greatest release (2nd
digit) and greatest modification (3rd digit) in the release.
For example, if WSRR returns a list of services
with the following version numbers:
1.0.0 |
1.0.1 |
1.0.2 |
1.0.3 |
1.1.0 |
1.1.3 |
1.1.4 |
1.3.0 |
1.3.1 |
1.3.4 |
2.0.0 |
2.1.0 |
The following supplied
Version property values will match as follows:
Version property setting |
Latest Compatible Match |
1.0.1 |
1.0.3 |
1.0.4 |
NO MATCH |
1.0 or 1.0.* |
1.0.3 |
1.2 or 1.2.* |
NO MATCH |
1 or 1.* |
1.3.4 |
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>