You
can enable a Java API
for XML-Based Web Services (JAX-WS) web services client to retrieve
values from transport headers. For a request that uses HTTP, the transport
headers are retrieved from HTTP headers found in the HTTP response
message. For a request that uses Java Message
Service (JMS), the transport headers are retrieved from the JMS message
properties found on the JMS response message.
Before you begin
You need a JAX-WS
web services client that you can enable
to retrieve transport headers.
Retrieving transport headers is supported
only by Web services clients, and is supported for the HTTP and JMS
transports. The web services client must call the JAX-WS APIs directly
and not through any intermediary layers, such as a gateway function.
About this task
When using the JAX-WS programming model, the client must
set a property on the BindingProvider's RequestContext object
to retrieve values from the transport headers. After you set the property,
values are read from responses for the subsequent method invocations
against that BindingProvider object until the associated property
is set to null or the BindingProvider object is discarded.
To
retrieve values from the transport headers on inbound responses, modify
the client code as follows:
Procedure
- Create
a java.util.Map object that will hold the transport
headers retrieved from the response message. To retrieve
all the transport headers from a response message, leave this Map
empty.
- (Optional) Add an entry to the Map
for each header that
you want to retrieve from the incoming response message.
- Set the Map entry key to a string that exactly matches
the transport header identifier. You can specify the header
identifier with a reserved header name, such as Cookie in the case
of HTTP, or the header identifier can be user-defined, such as MyTransportHeader.
Certain header identifiers are processed in a unique manner, but no
other checks are made to confirm the header identifier value. To learn
more about the HTTP header identifiers that have unique consideration,
read about transport header properties best practices. You can find
common header identifier string constants, such as HTTP_HEADER_SET_COOKIE
in the com.ibm.websphere.webservices.Constants class. The Map entry
value is ignored and does not need to be set. An empty Map, for example,
one that is non-null, but does not contain any keys, causes all the
transport headers in the response to be retrieved.
- Set the Map object on the BindingProvider's
RequestContext
using the com.ibm.websphere.webservices.Constants.RESPONSE_TRANSPORT_PROPERTIES
property. When the Map is set, the RESPONSE_TRANSPORT_PROPERTIES
property is used in subsequent invocations to retrieve the headers
from the responses. If you set the property to null,
no headers are retrieved from the response. To learn more about these
properties, see the transport header properties documentation.
- Invoke remote method calls against the BindingProvider
instance. The values from the specified transport headers
are retrieved from the response message and placed in the Map.
If
the property is not set correctly, you might experience API usage
errors that result in a WebServiceException error. The following requirements
must be met, or the process fails:
- The Constants.RESPONSE_TRANSPORT_PROPERTIES
property value that
is set on the BindingProvider's RequestContext instance must
be either null or an instance of java.util.Map.
- All the Map keys must be of the java.lang.String data type, and
the keys must not be null.
- The Map may be empty, which means
that it contains no entries
at all. In this case, all the transport headers will be retrieved
from the response message.
Results
You
have a JAX-WS web service that can receive transport
headers from incoming response messages.
Example
Here
is a short programming example that illustrates how
response transport headers are retrieved by a JAX-WS Web services
client application:
public class MyApplicationClass {
// Inject an instance of the service's port-type.
@WebServiceRef(EchoService.class)
private EchoPortType port;
// This method will invoke the web service operation and retrieve transport headers on the request.
public void invokeService() {
// Set up the Map to retrieive our response headers.
Map<String, Object> responseHeaders = new HashMap<String, Object>;
responseHeaders.put(“MyHeader1”, null);
responseHeaders.put(“MyHeader2”, null);
responseHeaders.put(“MyHeader3”, null);
// Set the Map as a property on the RequestContext.
BindingProvider bp = (BindingProvider) port;
bp.getRequestContext().put(com.ibm.websphere.webservices.Constants.RESPONSE_TRANSPORT_PROPERTIES, responseHeaders);
// Invoke the web services operation.
String result = port.echoString(“Hello, world!”);
// Now retrieve our response headers.
Object header1 = responseHeaders.get(“MyHeader1”);
Object header2 = responseHeaders.get(“MyHeader2”);
Object header3 = responseHeaders.get(“MyHeader3”);
}
}