You can enable an existing 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. B
Retrieving transport headers is supported only by Web
services clients, and only 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. Sending and retrieving transport
headers on the Web services server is done through non-Web services APIs.
About this task
When using the JAX-WS programming model, the client must set a
property on the BindingProvider 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.
Procedure
- Create a java.util.HashMap object that contains the names of the
transport headers to be retrieved from incoming response messages.
- Add an entry to the HashMap for each header that you want to retrieve
a value from every incoming response message.
- Set the HashMap entry key to a string that exactly matches the
transport header identifier. You can define 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 HashMap entry value is ignored and does not need to
be set. An empty HashMap, 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 HashMap entry on the BindingProvider instance using the
com.ibm.websphere.webservices.Constants.RESPONSE_TRANSPORT_PROPERTIES property.
When the HashMap 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.
- Issue remote method calls against the BindingProvider instance.
The values from the specified transport headers are retrieved from the
response message and placed in the HashMap.
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 property value that is set on the BindingProvider instance must be
either null or an instance of a HashMap.
- All the HashMap keys must be a string data type, and the keys must not
be null.
Results
You have a JAX-WS Web service that can receive transport headers
from incoming response messages.