You
can enable an existing Java API
for XML-based RPC (JAX-RPC) Web
services client to send application-defined information along with
your Web
services requests by using transport headers.
Before you begin
You need a JAX-RPC web services client that you
can enable to send
transport headers.
Sending 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 to send values in transport
headers.
After you set the property, the values are set in all the requests
for subsequent
remote method invocations against that Stub or Call object until the
associated
property is set to null or the Stub or Call object
is discarded.
To
send values in the transport headers on outbound requests, modify
the client
code as follows:
Procedure
- Create a java.util.HashMap
object that contains the transport header
identifiers.
- Add an entry to the HashMap object
for each transport header that
you want the client to send.
- 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 as to 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.
- Set the HashMap entry value
to a string that contains the value
of the transport header.
- Set
the HashMap entry on the Stub or Call object using the com.ibm.websphere.webservices.Constants.REQUEST_TRANSPORT_PROPERTIES property.
When the REQUEST_TRANSPORT_PROPERTIES property value
is set, that HashMap is used on subsequent invocations to set the
header values
in the outgoing requests. If the REQUEST_TRANSPORT_PROPERTIES property
value
is set to null, no HashMap is used on subsequent
invocations
to set header values in outgoing requests. To learn more about these
properties,
see the transport header properties documentation.
-
Issue remote method calls against the Stub or Call object.
The headers and the associated values from the HashMap are added
to
the outgoing request for each method invocation. If the invocation
uses HTTP,
then the transport headers are sent as HTTP headers within the HTTP
request.
If the invocation uses JMS, then the transport headers are sent as
JMS message
properties.
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 a HashMap
object or null.
- The HashMap must not be empty.
- Each key in the HashMap must be a String object.
- Each
value in the HashMap must be a String object.
Results
You have a JAX-RPC web services client that
is configured to send
transport headers.