# Conversing with Non-Workshop Clients

For services you build with WebLogic Workshop, adding support for conversations is easy. At design time, you simply set the conversation property's phase attribute for your service's methods and callbacks.

The SOAP messages that invoke conversational web service methods contain extra SOAP headers that include a conversation ID. If both the client and web service are build in WebLogic Workshop, the conversation SOAP headers are managed automatically. Web service clients built using other tools, however, must manually provide the necessary SOAP headers when invoking conversational WebLogic Workshop web service methods.

Note: If you are developing web services with Microsoft .NET (or need to interoperate with .NET services), you may be interested in the ConversationClient.asmx.cs sample. This file contains code for a conversational web service client written in C#. For more information, see .NET Client Sample.

The three SOAP headers related to conversations are:

- <StartHeader>: The client sends this header with the call to a method marked to "start" a conversation. The <StartHeader> contains <conversationID> and <callbackLocation> elements.
- <ContinueHeader>: The client sends this with any subsequent calls to the web service's methods. It contains the conversation ID the client used to start the conversation.
- <CallbackHeader>: The client receives this header when it receives a callback from the web service. The <CallbackHeader> includes the conversation ID the client used to start the conversation.

As you can see, one piece of information all of the headers carry is the conversation ID. The client proposes a conversation ID with any request to a start method. The same ID is then passed back and forth between the client and the web service for each subsequent exchange. This way, both know to which conversation each message is related.

## Conversation SOAP Headers

A client's first request, which begins a conversation, is always sent to a method marked to "start" the conversation. The SOAP message for this request must include the <StartHeader> header. In the message, this header looks like the following:

    <SOAP-ENV:Header>
        <StartHeader xmlns="http://www.openuri.org/2002/04/soap/conversation/">
            <conversationID>someUniqueIdentifier</conversationID>
            <callbackLocation>http://www.mydomain.com/myClient</callbackLocation>
        </StartHeader>
    </SOAP-ENV:Header>

The <StartHeader> element simply contains the header information. The XML namespace must be specified as it is shown here.

The <conversationID> element is technically optional. If it is omitted, WebLogic Server will invent one for use locally. However, the client will have no way of knowing what this conversation ID is if they don't send it. This means that they will be unable to correlate any responses received with the original request. For this reason, the client should only omit the conversation ID if they do not expect any further conversation with the web service. The value of the conversation ID is a string with a maximum length of 768 bytes. The conversation ID should be unique across all possible conversational clients of the target web service. To construct such an identifier, you may wish to combine data such as the process ID of the client, the current date and time and the host name or host IP address of the client.

The <callbackLocation> element, also optional, contains the URL to which callbacks should be sent. The client needs to send this only if it expects to handle callbacks from the web service. All callbacks intended for this client will be sent to the specified URL.

After the first request, the client either continues its side of the conversation by calling additional methods of the web service or receives callbacks from the web service. Each subsequent call to the web service must include the <ContinueHeader>. Note that this means even calls to web service methods marked to "finish" the conversation must include the <ContinueHeader>. The <ContinueHeader> looks like the following:

    <SOAP-ENV:Header>
        <ContinueHeader xmlns="http://www.openuri.org/2002/04/soap/conversation/">
            <conversationID>theUniqueIdentifierSentWithTheStartHeader</conversationID>
        </ContinueHeader>
    </SOAP-ENV:Header>

In order to correctly correlate this invocation, the <conversationID> used here must be the same as the ID sent with the <StartHeader>.

Finally, the client may be designed to handle callbacks from the web service. This means that the client software includes an operation capable of receiving the message sent by the WebLogic Workshop web service's callback. How this is implemented differs depending on the technology used to build the client. In general, though, the message sent with a callback contains the callback's parameter values.
The callback message also contains the <CallbackHeader>. The <CallbackHeader> also includes the conversation ID. It looks like the following:

    <SOAP-ENV:Header>
        <CallbackHeader xmlns="http://www.openuri.org/2002/04/soap/conversation/">
            <conversationID>theUniqueIdentifierSentWithTheStartHeader</conversationID>
        </CallbackHeader>
    </SOAP-ENV:Header>

Notice that there is no "finish" header. The conversation is over when the web service finishes it. This may be through execution of an operation (method or callback) marked with the conversation phase set to "finish". The web service can also call the finish method of the JwsContext interface (something it might do in the event of an exception). Using the WSDL file for the web service, the client knows which operations are designed to finish the conversation.

Once a conversation is finished, any further continue messages sent with that conversation ID will result in a SOAP fault.

## What to Look for in a Conversational Web Service's WSDL File

By looking at the WSDL file generated from a WebLogic Workshop service, a developer of a client of the web service can discover which of the service's operations start, continue or finish a conversation. They can also see which SOAP header each operation requires.

The following excerpt is from a WSDL generated from the Conversation.jws web service in the WebLogic Workshop samples project. In this example:

- The name of each operation (method and callback) is highlighted in bold.
- The phase attribute describing the operation's role in a conversation is highlighted in blue.
- The part attribute describing which header the service will receive (as an "input" header) and which it will send (as an "output" header) is highlighted in red.

By looking at this excerpt, you can see that:

- The startRequest operation starts the conversation and requires a <StartHeader>.
- The getRequestStatus operation continues the conversation and requires a <ContinueHeader>.
- The terminateRequest operation finishes the conversation and requires a <ContinueHeader>.
- The onResultReady operation finishes the conversation and sends a <CallbackHeader>.

      <binding name="ConversationSoap" type="s0:ConversationSoap">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
        <operation name="startRequest">
          <soap:operation soapAction="http://www.openuri.org/startRequest" style="document" />
            <cw:transition phase="start" />
          <input>
            <soap:body use="literal" />
            <soap:header wsdl:required="true" message="s0:StartHeader_literal" part="StartHeader" use="literal" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" />
          </input>
          <output>
            <soap:body use="literal" />
          </output>
        </operation>
        <operation name="getRequestStatus">
          <soap:operation soapAction="http://www.openuri.org/getRequestStatus" style="document" />
          <cw:transition phase="continue" />
          <input>
            <soap:body use="literal" />
            <soap:header wsdl:required="true" message="s0:ContinueHeader_literal" part="ContinueHeader" use="literal" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" />
          </input>
          <output>
            <soap:body use="literal" />
          </output>
        </operation>
        <operation name="terminateRequest">
          <soap:operation soapAction="http://www.openuri.org/terminateRequest" style="document" />
          <cw:transition phase="finish" />
          <input>
            <soap:body use="literal" />
            <soap:header wsdl:required="true" message="s0:ContinueHeader_literal" part="ContinueHeader" use="literal" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" />
          </input>
          <output>
            <soap:body use="literal" />
          </output>
        </operation>
        <operation name="onResultReady">
          <soap:operation soapAction="http://www.openuri.org/onResultReady" style="document" />
          <cw:transition phase="finish" />
          <input>
            <soap:body use="literal" />
          </input>
          <output>
            <soap:body use="literal" />
            <soap:header wsdl:required="true" message="s0:CallbackHeader_literal" part="CallbackHeader" use="literal" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" />
          </output>
        </operation>
      </binding>

Related Topics

Life of a Conversation

Overview: Conversations

How Do I: Add Support for Conversations?

How Do I: Tell Developers of Non-WebLogic Workshop Clients How to Participate in Conversations?