David Maddison - Accessing Workshop Conversational WebServices

For WebService clients, invocing methods on a stateless service is pretty straight forward, however conversational services require a much more complex interaction.

The Conversational Phases

Webservices are turned into Conversational services by marking certain methods with the conversation-phase annotation. Just to recap, the following image shows a WebService with methods marked as start, continue and finish.

The ConversationID

With standard Servlets HTTP sesion state is recorded on the server and accessed via the client providing a session token. The same method is used with conversational WebServices however the session token is called the conversationID.

The major difference between a session token and a conversationID is that it's the responsibility of the client to generate the ConversationID. The converationID can be any combination of numbers and letters.

The Conversational SOAP Headers

The ConversationID can be thought of as 'meta data' about the current method invocation in that it's not actually part of the invocation but rather provides context information to the WebService runtime. For this reason the ConversationID is passed in a Conversational Header, transmitted in the SOAP Envelope Header

There are two different types of conversational header formats used when accessing WebServices:

Real World Example

The following examples were collected using using TCPMonitor and show how the above headers look in real world calls.

The WSDL

WebService clients discover the existance and shape of the headers through the services WSDL document. The following is the Header schema extracted from a Conversational services WSDL document:

The Callback header specified above is use to pass the conversationID back to the calling client during a callback method invocation.

WSDL Extensions

If you create a WebService control from a Converstional WebService WSDL document, the control is able to determine the conversational phase of each method.

To support this, special transition extensions are embedded in the document. The following gives an example of methods marked with these "cw:transition" extensions

Accessing from a Weblogic WebService Client

When using the standard Weblogic Webservice client library, there is no requirement to add these conversational headers. This is because the client library is able to read the WSDL extensions and attach the appropriate headers to the call. The converationID is also generated by the client libraries and then reused when continue methods are called.

There are times however when you wish to explicitly specify the conversationID that you wish to use in the invocations. In order to do this, you much use an undocumented API and add the conversationID to the WebService context.

The following code shows an interaction with a Conversational Service with the conversationID being explictly set.


package bea.example;





import bea.example.convservice.client.TestConversational_Impl;


import bea.example.convservice.client.TestConversationalSoap;


import bea.example.convservice.client.TestConversational;





// Weblogic Extensions


import weblogic.webservice.context.WebServiceContext;


import weblogic.webservice.context.WebServiceHeader;


import weblogic.webservice.WLMessageContext;





public class ConvClient {





  public static void main(String args[]) throws Exception {





      // Get a copy of the service proxy


      TestConversational service = new TestConversational_Impl();


      TestConversationalSoap client = service.getTestConversationalSoap();





      // Set the conversationID


      WebServiceContext ctx = service.context();


      ctx.getSession().setAttribute(WLMessageContext.CONVERSATION_PROP,"12345678922");





      // Call the start method


      System.out.println(client.startMethod("David Maddison"));





      // Call the continue method


      System.out.println("Continue Reply=" + client.continueMethod());





      // And Clean up


      System.out.println("Finish Reply=" + client.finishMethod());


  }


}

For completeness, the following is the WebService to which the above client would communicate:


public class TestConversational implements com.bea.jws.WebService


{ 


    static final long serialVersionUID = 1L;





    String _name;





    /**


     * @common:operation


     * @jws:conversation phase="start"


     */


    public String StartMethod(String name)


    {


        _name = name;


        


        return "Hello From Start Method";


    }





    /**


     * @common:operation


     * @jws:conversation phase="continue"


     */


    public String ContinueMethod()


    {


        return _name;


    }





    /**


     * @common:operation


     * @jws:conversation phase="finish"


     */


    public String FinishMethod()


    {


        return "Conversation Ending!";


    }


}