Web Services Addressing (WS-Addressing) aids interoperability
between web services by defining a standard way to address web services
and provide addressing information in messages. This task describes
the steps that are required to create a JAX-WS web service that is
accessed using a WS-Addressing endpoint reference. The task also describes
the extra steps that are required to use stateful resources as part
of the web service.
Before you begin
The steps that are described in this task apply to servers
and clients that run on WebSphere® Application Server.
About this task
Complete this task if you are creating a JAX-WS web service
that uses the WS-Addressing specification. This task uses the JAX-WS
WS-Addressing APIs to create the required endpoint reference. Alternatively,
you can create endpoint references by using the IBM proprietary WS-Addressing
API, and convert them into JAX-WS API objects for use with the rest
of the application.
Procedure
- Provide a web service interface that returns an endpoint
reference to the target service.
The interface must
return an endpoint reference, which it can do by using a factory operation
or a separate factory service. The target service can front a resource
instance, for example a shopping cart.
- Implement the web service created in the previous step.
For the WS-Addressing portion of the implementation, complete the
following steps:
- Optional: Include annotations to specify
WS-Addressing behavior. See Web Services Addressing annotations for more details.
- Optional: If your interface involves a web
service that fronts a resource instance, create or look up the resource
instance.
- Optional: If you are using a resource instance,
obtain the identifier of the resource. The resource identifier
is application dependent and might be generated during the creation
of the resource instance.
Attention: Do not put sensitive
information in the resource identifier, because the identifier is
propagated in the SOAP message.
- Create an endpoint reference that references the web
service by following the instructions in Creating endpoint references by using the JAX-WS Web Services Addressing API. If you are
using a resource instance, pass in the resource identifier as a parameter.
- Return the endpoint reference.
- If your web service uses resource instances, extend the
implementation to match incoming messages to the appropriate resource
instances. Because you associated the resource identifier
with the endpoint reference that you created earlier, any incoming
messages targeted at that endpoint reference contain the resource
identifier information as a reference parameter in the SOAP header
of the message. Because the resource identifier is passed in the SOAP
header, you do not have to expose it on the web service interface.
When WebSphere Application Server receives
the message, it puts this information into the message context on
the thread. Extend the implementation to undertake the following actions:
- Obtain the resource instance identifier from the message
context.
- If you are using the 2005/08 WS-Addressing namespace, use the
REFERENCE_PARAMETERS property of the MessageContext class.
- If you are using the 2004/08 WS-Addressing namespace, you must
use the IBM WS-Addressing API, specifically the EndpointReferenceManager.getReferenceParameterFrom
MessageContext(QName resource_id) method.
Use the following method for the 2005/08 namespace:...
List resourceIDList = (List)getContext().getMessageContext().get(MessageContext.REFERENCE_PARAMETERS);
...
Use the following method for the 2004/08 namespace:...
String resource_identifier =
EndpointReferenceManager.getReferenceParameterFromMessageContext(PRINTER_ID_PARAM_QNAME);
...
- Forward the message to the appropriate resource instance.
- Optional: Configure a proxy client to communicate
with the service.
- Use the wsimport or xjc tool to generate the artifacts
required by the client.
Note: If you want to use the 2004/08
WS-Addressing specification, specify the provided binding file, app_server_root/util/SubmissionEndpointReference.xjb,
as the -b parameter of the tool. This parameter tells the tool to
generate endpoint reference objects by using the SubmissionEndpointReference
class that is part of the IBM implementation of the standard JAX-WS
API. If you do not specify this bindings file, the resulting endpoint
reference objects will not work with the standard JAX-WS API.
- In the client code, create an instance of the service
class.
- Obtain a proxy object from the service class. There
are several ways to use the JAX-WS API to obtain proxy objects. For
example, there are several getPort methods on the Service class and
one on the EndpointReference class. For more information, refer to
the API documentation.
- Optional: Use the Addressing or SubmissionAddressing
feature to enable WS-Addressing support. For example, create
a proxy by using a getPort method that accepts web service features
as a parameter. If you prefer, you can enable WS-Addressing support
by using another method, such as policy sets. For more information
see Enabling Web Services Addressing support for JAX-WS applications.
- Use the proxy object to invoke the service method that
returns the endpoint reference.
The following sample code shows a client invoking a web
service to add two numbers together. The web service issues a ticket
(the resource identifier) to the client, and requires the client to
use this ticket when invoking the web service.
The client creates
two proxies. The first proxy obtains the ticket as an endpoint reference
from the service. The second proxy uses the AddressingFeature class
to enable WS-Addressing for the 2005/08 specification, and invokes
the service to add the two numbers together.
...
CalculatorService service = new CalculatorService();
// Create the first proxy
Calculator port1 = service.getCalculatorServicePort();
// Obtain the ticket as an endpoint reference from the service
W3CEndpointReference epr = port1.getTicket();
// Create the second proxy, using an addressing feature to enable WS-Addressing
Calculator port2 = epr.getPort(Calculator.class, new AddressingFeature());
// Invoke the service to add the numbers
int answer = port2.add(value0, value1);
System.out.println("The answer is: " + answer);
...
Note: If the metadata of the endpoint reference
conflicts with the information already associated with the outbound
message, for example if the proxy object is configured to represent
a different interface, a javax.xml.ws.WebServiceException exception
is thrown on attempts to invoke the endpoint.
If
you want to set message-addressing properties, such as a reply to
endpoint, you must use the IBM proprietary WS-Addressing SPI and the
BindingProvider class, as described in Specifying and acquiring message-addressing properties by using the IBM proprietary Web Services Addressing SPIs.
- Optional: Configure a Dispatch client to communicate
with the service. You can configure a client in different
ways; the following steps describe one example.
- Create an instance of the service.
- Add a port to the service object.
- Create an instance of the Dispatch class, passing in
the endpoint reference.
- Create a Dispatch object. Use the Service.createDispatch
method with the following parameters:
There are several variations of the Service.createDispatch method;
see the API documentation for more details.
- Compose the client request message.
- Invoke the service endpoint with the Dispatch client.
The following code shows an example fragment of a Dispatch
client that enables 2004/08 WS-Addressing....
CalculatorService service = new CalculatorService();
Dispatch(<SOAPMessage> dispatch = service.createDispatch(
endpointReference,
SOAPMessage.class,
Service.Mode.MESSAGE,
new SubmissionAddressingFeature(true));
...