Links: Table of Contents | Single HTML | Single PDF

Chapter 11. WS-MakeConnection support

Table of Contents

11.1. Introduction to WS-MakeConnection
11.2. Configuring Web Service Endpoint
11.2.1. Configuration via an WS-Policy expression
11.2.2. Configuration via a Java annotation
11.3. Configuring Web Service Client

11.1. Introduction to WS-MakeConnection

The WS-MakeConnection specification defines a protocol that allows messages to be transferred between WS-MakeConnection-aware nodes by using a transport-specific back-channel. The protocol itself is described in a transport-independent manner. This allows it to be implemented using different network technologies. To support interoperable Web services, a SOAP binding is defined within WS-MakeConnection specification.

The WS-MakeConnection mechanism for the transfer of messages between two endpoints is useful in situations when the sending endpoint is unable to initiate a new connection to the receiving endpoint. Such situation may typically occur when a connection from a non-adressable client is broken before a response to client's request has been delivered. Rather than discarding the old response, replaying the whole request/response message exchange and generating a new response, which may be computationally or otherwise resource intensive, WS-MakeConnection provides a way how to uniquely identify non-addressable endpoints, and a mechanism by which undelivered messages destined for those endpoints can be delivered.

As all of the WS-* technologies, WS-MakeConnection mechanism is extensible allowing additional functionality, such as security, to be tightly integrated. WS-MakeConnection specification integrates with and complements the WS-ReliableMessaging, WS-Security, WS-Policy, and other Web services specifications.

11.2. Configuring Web Service Endpoint

11.2.1. Configuration via an WS-Policy expression

As all other WS-* features, WS-MakeConnection can be enabled using a WS-Policy assertion. Unfortunately, unlike many other WS-* features, NetBeans IDE in it's current version 6.8 don't provide a nice GUI-based support for enabling/disabling WS-MakeConnection feature on an endpoint. This means that in order to enable WS-MakeConnection, you need to manually put the assertion into your endpoint's WSIT config file. Here are the steps:

  1. Open the existing WSIT config file for the endpoint.

    • If no config file has been created for the endpoint yet, you can create an empty one with a little help from NetBeans IDE by selecting and unselecting any feature in the QoS dialog or the "Design" tab of the web service endpoint.

  2. Add the WS-MakeConnection assertion namespace definition into the root XML element of the WSIT config file:

    Example 11.1. 

    xmlns:wsmc="http://docs.oasis-open.org/ws-rx/wsmc/200702"


  3. Create new WS-Policy expression in the config file:

    Example 11.2. 

    <wsp:Policy wsu:Id="McTestEchoPortBindingPolicy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsam:Addressing wsp:Optional="false"/>
                <wsmc:MCSupported />
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>


  4. Attach newly created WS-Policy expression to the endpoint binding using WS-Policy reference:

    Example 11.3. 

    <binding name="McTestEchoPortBinding" type="tns:McTestEcho">
        <wsp:PolicyReference URI="#McTestEchoPortBindingPolicy"/>
    
        ...
    
    </binding>


  5. Build and run the service. Service will now have WS-MakeConnection support enabled.

11.2.2. Configuration via a Java annotation

In addition to using WS-Policy expression as discussed in Configuration via an WS-Policy expression, you may as well configure WS-MakeConnection support using a @MakeConnectionSupported Java annotation provided by Metro. Please note, that this annotation is meant to annotate whole classes only. The resulting Java code for a sample web service would look like this:

Example 11.4. Example of WS-MakeConnection enabled service class using @MakeConnectionSupported Java annotation

package com.sun.metro.mc.service;

import com.sun.xml.ws.rx.mc.MakeConnectionSupported;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebService;

@WebService()
@MakeConnectionSupported
public class McTestEcho {

    /**
     * Web service operation
     */
    @WebMethod(operationName = "echo")
    public String echo(@WebParam(name = "message")
    final String message) {
        return "Received: " + message;
    }

}

11.3. Configuring Web Service Client

Once the WS endpoint is properly configured in Metro to support WS-MakeConnection protocol messages, it advertises this ability in it's WSDL descriptor. In case you are developing a client for such an endpoint (which advertises WS-MakeConnection support in its WSDL), all the necessary configuration happens autmatically and you don't need to take any additional steps to enable WS-MakeConnection support on the client side.

There are however other web service frameworks that sometimes fail to advertise their advanced capabilities. In case of such an endpoint, which doesn't have the <wsmc:MCSupported /> assertion specified in its WSDL descriptor but you know that it DOES support WS-MakeConnection, you can use the JAX-WS's WS Feature mechanism to explicitly enable WS-MakeConnection support on your client proxy by passing a com.sun.xml.ws.rx.mc.MakeConnectionSupportedFeature instance as a parameter into a port getter method:

Example 11.5. 

McTestEcho port = null;
try {
    McTestEchoService service = new McTestEchoService();
    port = service.getMcTestEchoPort(
        new com.sun.xml.ws.rx.mc.MakeConnectionSupportedFeature());

    String message = "Test";

    String result = port.echo(message);

    System.out.println("Result = "+result);
} catch (Exception ex) {
    ex.printStackTrace();
} finally {
    if (port != null) {
        try {
            ((java.io.Closeable) port).close();
        } catch (java.io.IOException ex) {
            ex.printStackTrace();
        }
    }
}

Please note once again that passing the com.sun.xml.ws.rx.mc.MakeConnectionSupportedFeature explicitly is required ONLY if the endpoint fails to advertise its support for WS-MakeConnection feature via the <wsmc:MCSupported /> WS-Policy assertion.