Retrieving transport headers with JAX-WS

You can enable an existing Java API for XML-Based Web Services (JAX-WS) 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.

Before you begin

You need a JAX-WS Web services client that you can enable to retrieve transport headers.

Retrieving 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-WS 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.

About this task

When using the JAX-WS programming model, the client must set a property on the BindingProvider object to retrieve values from the transport headers. After you set the property, values are read from responses for the subsequent method invocations against that BindingProvider object until the associated property is set to null or the BindingProvider object is discarded.

Complete the following actions modify the client code to retrieve values from the transport headers on inbound responses.

Procedure

  1. Create a java.util.HashMap object that contains the names of the transport headers to be retrieved from incoming response messages.
    Avoid trouble Avoid trouble: This step only applies if you are running on Version 7.0.0.13 or earliergotcha
  2. Add an entry to the HashMap for each header that you want to retrieve a value from every incoming response message.
    Avoid trouble [Fix Pack 15 or later] Avoid trouble: This step only applies if you are running on Version 7.0.0.13 or earliergotcha
    1. Set the HashMap entry key to a string that exactly matches the transport header identifier. You 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. You 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 BindingProvider instance using the com.ibm.websphere.webservices.Constants.RESPONSE_TRANSPORT_PROPERTIES property.
    Avoid trouble Avoid trouble: This step only applies if you are running on Version 7.0.0.13 or earliergotcha

    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 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 BindingProvider instance.
    Avoid trouble Avoid trouble: This step only applies if you are running on Version 7.0.0.13 or earliergotcha

    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 WebServiceException error. The following requirements must be met, or the process fails:
    • The property value that is set on the BindingProvider instance 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.
  5. [Fix Pack 15 or later] Create a java.util.Map object that will hold the transport headers retrieved from the response message. To retrieve all the transport headers from a response message, leave this Map empty.
  6. [Fix Pack 15 or later] (Optional) Add an entry to the Map for each header that you want to retrieve from the incoming response message.
    1. Set the Map entry key to a string that exactly matches the transport header identifier. You can specify 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. You can find common header identifier string constants, such as HTTP_HEADER_SET_COOKIE in the com.ibm.websphere.webservices.Constants class. The Map entry value is ignored and does not need to be set. An empty Map, for example, one that is non-null, but does not contain any keys, causes all the transport headers in the response to be retrieved.
  7. [Fix Pack 15 or later] Set the Map object on the BindingProvider's RequestContext using the com.ibm.websphere.webservices.Constants.RESPONSE_TRANSPORT_PROPERTIES property. When the Map is set, the RESPONSE_TRANSPORT_PROPERTIES property is used in subsequent invocations to retrieve the headers from the responses. If you set the property to null, no headers are retrieved from the response. To learn more about these properties, see the transport header properties documentation.
  8. [Fix Pack 15 or later] Invoke remote method calls against the BindingProvider instance. The values from the specified transport headers are retrieved from the response message and placed in the Map.
    If the property is not set correctly, you might experience API usage errors that result in a WebServiceException error. The following requirements must be met, or the process fails:
    • The Constants.RESPONSE_TRANSPORT_PROPERTIES property value that is set on the BindingProvider's RequestContext instance must be either null or an instance of java.util.Map.
    • All the Map keys must be of the java.lang.String data type, and the keys must not be null.
    • The Map may be empty, which means that it contains no entries at all. In this case, all the transport headers will be retrieved from the response message.

Results

You have a JAX-WS Web service that can receive transport headers from incoming response messages.




In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Jun 11, 2013 8:40:09 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v701sca&product=was-nd-mp&topic=twbs_retrievecookiejaxws
File name: twbs_retrievecookiejaxws.html