Retrieve transport headers with JAX-RPC

We can enable an existing 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.

You need a web services client that we can enable to retrieve transport headers.

Retrieve 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 in order to retrieve values from the transport headers. After setting 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.

1. Create a java.util.HashMap object containing the names of the transport headers to be retrieved from incoming response messages.

2. Add an entry to the HashMap for each header to retrieve a value from every incoming response message.

   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 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. We 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.

3. 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 we set the property to null, no headers are retrieved from the response. To learn more about these properties, see the transport header properties documentation.

4. 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 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.

Related tasks

Sending transport headers with JAX-RPC

Implement extensions to JAX-RPC web services clients

Transport header properties best practices