Table of Contents
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.
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:
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.
Add the WS-MakeConnection assertion namespace definition into the root XML element of the WSIT config file:
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>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>Build and run the service. Service will now have WS-MakeConnection support enabled.
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;
}
}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.