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. You can also enable a JAX-WS Web
services endpoint to send application-defined information along with
the Web services response message 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.
Avoid trouble: This
step only applies if you are running on Version 7.0.0.13 or earlier
gotcha
- Add an entry to the HashMap object for each transport header
that you want the client to send.
Avoid trouble: This step only applies if you are running on Version
7.0.0.13 or earlier
gotcha
- 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.
Avoid trouble: This step
only applies if you are running on Version 7.0.0.13 or earlier
gotcha
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.
Avoid trouble: This step only applies
if you are running on Version 7.0.0.13 or earlier
gotcha
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.
- Create a java.util.Map object that
contains the transport headers.
- Add an entry to the Map object for
each transport header that you want the client to send.
- Set the Map 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 Map entry value to the value of the transport
header. The type of this value can be one of the following
data types:
- java.lang.String
- java.lang.Integer
- java.lang.Short
- java.lang.Long
- java.lang.Float
- java.lang.Double
- java.lang.Byte
- java.lang.Boolean
Note: When using transport headers with HTTP,
all non-String header values are converted to java.lang.String before
being set on the HTTP message.
- Set the Map object on the BindingProvider's
RequestContext using the com.ibm.websphere.webservices.Constants.REQUEST_TRANSPORT_PROPERTIES
property. When the REQUEST_TRANSPORT_PROPERTIES property
value is set, that Map 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 transport properties
are sent 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 Map 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 Constants.REQUEST_TRANSPORT_PROPERTIES 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 Constants.REQUEST_TRANSPORT_PROPERTIES property value that
is set on the BindingProvider's RequestContext must be a java.util.Map
object or null.
- Each key in the Map must be a java.util.String data type.
- Each value in the Map must be one of the following data types:
- java.lang.String
- java.lang.Integer
- java.lang.Short
- java.lang.Long
- java.lang.Float
- java.lang.Double
- java.lang.Byte
- java.lang.Boolean
Results
You have a JAX-WS Web services client that is configured
to send transport headers.