Transport header 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.

The following is an example of how you 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”);
    }
}