Sending transport headers with JAX-RPC

We can enable an existing JAX-RPC Web services client to send application-defined information along with your Web services requests using transport headers.

You need a JAX-RPC web services client that we 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.

When using JAX-RPC, the client must set a property on the Stub or Call object to send values in transport headers. After we 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:

Tasks

1. Create a java.util.HashMap object containing the transport header identifiers.

2. Add an entry to the HashMap object for each transport header that we want the client to send.

   1. Set the HashMap entry key to a string that exactly matches the transport header identifier. We 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. We can find common header identifier string constants, such as HTTP_HEADER_SET_COOKIE in the com.ibm.websphere.webservices.Constants class.

   2. Set the HashMap entry value to a string containing the value of the transport header.

3. 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.
4. 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, we 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.

We have a JAX-RPC web services client configured to send transport headers.

Implement extensions to JAX-RPC web services clients

Retrieving transport headers with JAX-RPC

Transport header properties best practices