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.