You can enable an existing Java™ API for XML-Based Web Services (JAX-WS)
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-WS 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-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 send values in transport headers.
After you set the property, the values are set in all the requests for subsequent
remote method invocations against the BindingProvider object until the associated
property is set to null or the BindingProvider object is
discarded.
To send values in the transport headers on outbound requests,
modify the client code.
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 BindingProvider instance 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 BindingProvider instance.
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 WebServiceException error. The following requirements
must be met, or the process fails:
- The property value that is set on the BindingProvider instance 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-WS Web services client that is configured to send
transport headers.