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, you can retrieve information from HTTP headers
from incoming responses.
Before you begin
You need a Web services client that you 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.
Why and when to perform this task
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:
Steps for this task
- Create a java.util.HashMap that will contain the HTTP header identifiers
values to retrieve.
- Add an entry to the HashMap for each header that you want the client
to retrieve a value from.
- 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.
- 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.
- 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.
- 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.