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.