Use the JAX-WS asynchronous response listener

JAX-WS includes an asynchronous response listener, which is used within the Thin Client for JAX-WS and application client environments to receive responses for requests that are invoked asynchronously.

JAX-WS provides support for invoking web services using an asynchronous client invocation by using either a callback or polling model. Both the callback model and the polling model are available on the Dispatch client and the dynamic proxy client. When the JAX-WS client uses an asynchronous client invocation, the responses are received by the asynchronous response listener. To learn how to use the asynchronous client invocation model, read about invoking JAX-WS web services asynchronously.

The asynchronous response listener is used within a Web services client to handle incoming asynchronous responses. Use the listener in Thin Client for JAX-WS environments and application client environments. By default, the listener opens a random port to listen for asynchronous responses or we can optionally configure a specific port for the listener to use. The listener starts automatically in the JAX-WS run time when the JAX-WS client is configured to expect an asynchronous response.

There are two versions of the asynchronous response listener. The unsecure version of the asynchronous response listener supports the HTTP protocol, and the secure version of the asynchronous response listener supports the HTTPS protocol. The correct asynchronous response listener is automatically started based on the particular transport used by the JAX-WS client. To ensure that the correct SSL handshaking occurs between the asynchronous response listener and the application server, configure the SSL properties using the SSL transport policy or the Java system properties.

For web services clients running in the application server environment, use the asynchronous response servlet for receiving asynchronous responses.

1. Determine if we want the JAX-WS client to use the HTTP or HTTPS transport mechanism.

2. Configure the asynchronous response listener for unsecure communication using HTTP.

   We can configure the HTTP port for the asynchronous response listener as a Java system property or as a custom property within the transport policy. Properties defined in the policy set binding files override any Java system property that might have been defined.

   1. Define the com.ibm.websphere.webservices.http.listenerPort property as a Java system property. If this property is set as a Java system property, then all asynchronous response listeners within that Java Virtual Machine (JVM) are affected.

   2. Define the com.ibm.websphere.webservices.http.listenerPort property within the HTTPTransport transport policy set bindings files. If this property is set as a custom property within a transport policy set binding, then only the services for which the policy set has been configured are affected.

3. Configure the asynchronous response listener for secure communication using HTTPS.

   We can configure the HTTPS port for the asynchronous response listener as a Java system property or as a custom property within the transport policy.

   1. Define the com.ibm.websphere.webservices.https.listenerPort property as a Java system property. If this property is set as a Java system property, thenall asynchronous response listeners within that JVM are affected.

   2. Define the com.ibm.websphere.webservices.https.listenerPort property within the SSLTransport transport policy set bindings files. If this property is set as a custom property within a transport policy set binding, then only the services for which the policy set has been configured are affected.

Results

Your JAX-WS web services client is configured to use the asynchronous response listener to receive incoming asynchronous responses.

Example

The following examples demonstrate how to enable the asynchronous response listener when defining the custom port of 9999:

• Use the following Java command to configure the custom HTTP port for the asynchronous response listener in a thin client environment:
  - java.exe -Dcom.ibm.websphere.webservices.http.listenerPort=9999 com.ibm.websphere.my_program

• Use the following launchClient command to configure the custom HTTP port for the asynchronous response listener in an application client container:
  - launchClient.bat MyClient.ear -CCDcom.ibm.websphere.webservices.http.listenerPort=9999

• The following is an excerpt from an HTTPTransport policy binding.xml file that includes the asynchronous response listener properties:

  </wsp:Policy>
     </wsp:ExactlyOne>
   </wsp:All>
      <wshttp:outAsyncResponseProxy>
       <wshttp:connectInfo host="" port=""></wshttp:connectInfo>
                     <wshttp:basicAuth userid="" password=""></wshttp:basicAuth>
      </wshttp:outAsyncResponseProxy>
      <wshttp:properties>
    <wshttp:customProperty name="com.ibm.websphere.webservices.http.listenerPort" value="9999" />
     </wshttp:properties>
   </wsp:All>
     </wsp:ExactlyOne>
  </wsp:Policy>

What to do next

Run the JAX-WS client with the specified asynchronous response listener options.

Related tasks

Use HTTP to transport web services

Use the JAX-WS asynchronous response servlet

Use HTTP to transport web services requests for JAX-WS applications

Invoking JAX-WS web services asynchronously

Running an unmanaged web services JAX-WS client