Transport header properties best practices

We can set the REQUEST_TRANSPORT_PROPERTIES property and RESPONSE_TRANSPORT_PROPERTIES property on a JAX-RPC client Stub, a Call instance, or a Java API for XML-Based Web services (JAX-WS) BindingProvider's RequestContext instance to enable a web services client to send or retrieve transport headers.

Use these best practices to enable a Web services client to send or retrieve transport headers.bprac

REQUEST_TRANSPORT_PROPERTIES best practices

Some transport headers such as the HTTP Cookie header and the Cookie2 header contain multiple embedded values. For headers that contain multiple values, the header value must be written in the following way:

• Each name=value pair embedded within the header value must be separated by a semi-colon (;).
• Each name and its value must be separated by an equal (=) sign.

The following is an example of how the header value must be written:

name1=value1;name2=value2;name3=value3

The values contained in the user's Map might be parsed before being added to the outgoing request if the outgoing request already contains a header identifier that matches one in the Map. For certain transport headers that contain multiple embedded values, the header values in the Map are parsed into individual name=value components. A semi-colon (;) separates the components, for example, name1=value1;name2=value2. Each name=value is appended to the outgoing header unless:

• The outgoing request header contains a name value.

  In this case, the name=value from the Map is silently ignored, preventing a client from overwriting or modifying values for the name value that are already set in the outgoing request header by either the server or the web services engine.

• The user's header value contains multiple name values.

  When the user's header value contains multiple name values, the first occurrence of the name value is used and the others are silently ignored. For example, if the user's header value contains name1=value1;name2=value2;name1=value3, where there are two occurrences of name1, the first value, name1=value1, is used. The other value, name1=value3, is silently ignored.

RESPONSE_TRANSPORT_PROPERTIES best practices

Only the Map keys are used; the Map values are ignored. The values are filled in this Map by retrieving the transport headers, which correspond to the Map keys from the incoming response message. An empty Map causes all of the transport headers and the associated values to be retrieved from the incoming response message.

HTTP headers that are processed under special consideration

The following are HTTP headers that are given special consideration when sending and retrieving HTTP responses and requests.

The values in these headers can be set in a variety of ways. For example, some header values are sent based on settings in a deployment descriptor or binding file. In these cases, the value set through REQUEST_TRANSPORT_PROPERTIES overrides the values set any other way.

Header	Send request	Retrieve response
Transfer-encoding	The transfer-encoding header is ignored for HTTP 1.0. When using HTTP 1.1, the transfer-encoding header is set to chunked if the value is chunked.	There is no special processing.
Connection	The connection header is ignored for HTTP 1.0. When using HTTP 1.1, the following values are set: The connection header is set to "close" if the value is set to "close". The connection header is set to "keep-alive" if the value is set to "keep-alive". All other value settings are ignored.	There is no special processing.
Expect	The expect header is ignored for HTTP 1.0. When using HTTP 1.1, the following values are set: The connection header is set to "100-continue" if the value is set to "100-continue". All other value settings are ignored.	There is no special processing.
Host	Ignored	There is no special processing.
Content-type	Ignored	There is no special processing.
SOAPAction	Ignored	There is no special processing.
Content-length	Ignored	There is no special processing.
Cookie The following is a String constant: com.ibm.websphere.webservices.Constants.HTTP_HEADER_COOKIE	The value is sent on the header if it is structured correctly. See the information for Header value format and Map values.	There is no special processing.
Cookie2 The following is a String constant: com.ibm.websphere.webservices.Constants.HTTP_HEADER_COOKIE2	See the information in the "Cookie" entry.	There is no special processing.
Set-cookie The following is a String constant: com.ibm.websphere.webservices.Constants.HTTP_HEADER_SET_COOKIE	There is no special processing.	If the property MAINTAIN_SESSION is set to true, the entire value is saved into SessionContext.CONTEXT_PROPERTY and is sent on subsequent requests in the Cookie header. See the Cookie entry in this table for more information.
Set-cookie2 The following is a String constant: com.ibm.websphere.webservices.Constants.HTTP_HEADER_SET_COOKIE2	There is no special processing.	If the property MAINTAIN_SESSION is set to true, the entire value is saved into SessionContext.CONTEXT_PROPERTY and is sent on subsequent requests in the Cookie header. See the Cookie entry in this table for more information.

Example client code

The following is an example of how we can code a web services client to send and retrieve transport header values:

public class MyApplicationClass {
    // Inject an instance of the service's port-type.
    @WebServiceRef(EchoService.class)
    private EchoPortType port;

    // This method will invoke the web service operation and send and receive transport headers.
    public void invokeService() {

        // Set up the Map that will contain the request headers.
        Map<String, Object>requestHeaders = new HashMap<String, Object>();
        requestHeaders.put("Cookie", "ClientAuthenticationToken=FFEEBBCC");
        requestHeaders.put("MyHeaderFlag", new Boolean(true));

        // Set the Map as a property on the RequestContext.
        BindingProvider bp = (BindingProvider) port;
        bp.getRequestContext().put(com.ibm.websphere.webservices.Constants.REQUEST_TRANSPORT_PROPERTIES, requestHeaders);

        // Set up the Map to retrieve transport headers from the response message.
        Map<String, Object>responseHeaders = new HashMap<String, Object>();
        responseHeaders.put("Set-Cookie", null);
        responseHeaders.put("MyHeaderFlag, null);

        // Invoke the web services operation.
        String result = port.echoString("Hello, world!");

        // Retrieve the headers from the response.
        String cookieValue = responseHeaders.get("Set-Cookie");
        String headerFlag = responseHeaders.get("MyHeaderFlag");
    }
}

Sending transport headers with JAX-WS

Retrieving transport headers with JAX-WS

Implement extensions to JAX-WS web services clients

Sending transport headers with JAX-RPC

Retrieving transport headers with JAX-RPC

Implement extensions to JAX-RPC web services clients