Retrieving HTTP transport headers

This task explains how to enable an existing Web services client to retrieve values from HTTP transport headers. By modifying your client code to retrieve transport headers, one can retrieve information from HTTP headers from incoming responses.

 

Before you begin

You need a Web services client that one can enable to retrieve HTTP transport headers.

Retrieving transport headers is supported by Web services clients only and over the HTTP transport only. The Web services client must call the Java API for XML-based RPC (JAX-RPC) APIs directly and not through any intermediary layers, such as a gateway-like function. Sending and retrieving HTTP transport headers on the Web services server-side is done through non-Web services APIs.

 

Overview

The client must set a property on the Stub in order to retrieve values from the HTTP transport headers. Once the property is set, values are read from HTTP responses for the subsequent method invocations against that Stub until the associated property is set to null or the Stub is discarded. To retrieve values from the HTTP transport headers on inbound responses, modify the client code as follows:

 

Procedure

  1. Create a java.util.HashMap that will contain the HTTP header identifiers values to retrieve.

  2. Add an entry to the HashMap for each header that you want the client to retrieve a value from.

    1. Set the HashMap entry key to a string that exactly matches the HTTP header identifier. The header identifier can be one defined for HTTP, such as Cookie, or it can be user-defined, such as MyHTTPHeader. Certain header identifiers are processed in a special manner, but no other checks are made to confirm the header identifier value. To learn more about the header identifiers that have special consideration, see HTTP transport header properties best practices. Common header identifier string constants, such as HTTP_HEADER_SET_COOKIE can be found in the com.ibm.websphere.webservices.Constants class. The HashMap entry value does not need to be set; it is ignored. An empty HashMap (one that is non-null, but does not contain keys) causes values from all headers in the HTTP response to be received.

  3. Set the HashMap entry on the Stub 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 you set the RESPONSE_TRANSPORT_PROPERTIES property to null, the header does not retrieve from the response headers. To learn more about the properties used, see HTTP transport header properties.

  4. Issue remote method calls against the Stub. The values from the HTTP response headers indicated in the HashMap are copied into a new instance of a HashMap for each method invocation.

    You might experience API usage errors that result in a JAXRPCException. The following items are checked for during invocation and cause an exception to be thrown if there is an error:

    • The property value that is set on the Stub is either null or a HashMap.

    • All the HashMap keys are not non-null and an instance of a String.

  5. Retrieve the new HashMap instance that contains the HTTP header identifiers and the associated values from the Stub using the com.ibm.websphere.webservices.Constants.RESPONSE_TRANSPORT_PROPERTIES property.

 

Result

You have a Web service that is able to receive HTTP transport headers.

 

See Also


Extensions to the JAX-RPC and Web Services for J2EE programming models
HTTP transport header properties best practices