You can enable an existing Java API for XML-based RPC (JAX-RPC) 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 Web services client that you can enable to retrieve transport
headers.
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-RPC 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-RPC programming model, the client must set
a property on the Stub or Call object in order to retrieve values from the
transport headers. After you set the property, values are read from responses
for the subsequent method invocations against that Stub or Call instance until
the associated property is set to null or the Stub or Call
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 Stub or Call object 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 Stub or Call object.
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 JAXRPCException error.
The following requirements must be met, or the process fails:
- The property value that is set on the Stub or Call object 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-RPC Web service that can receive transport headers
from incoming response messages.