Implementing Conversations

This topic provides information about building web services that support conversations. Conversations are part of a technology through which you can ensure that WebLogic Server maintains your service's state-related data and correlates communications between your service, clients, and resources such as other services.

You should consider supporting conversations in any service design that is asynchronous or involves multiple communications with a client in connection with a single request. Services that support conversations are treated differently by WebLogic Server. When a client calls a service operation that is annotated to start a conversation, WebLogic Server creates a conversation context through which to correlate calls to and from the service and to persist its state-related data.

# Understanding Conversation Context

Context is the key to the benefit provided by conversations. Conceptually speaking, multiple related calls to or from a single web service are part of the same context by virtue of being related to the same initial request. With WebLogic Workshop, you can easily build services that support this conceptual reality by using conversations.

When a conversation starts, WebLogic Server does the following:

- Creates a context through which to maintain the scope of the conversation.

- Generates a conversation ID with which to identify the context.

- Saves the service's state, including any data stored in serializable member variables.

- Starts an internal timer to measure idle time.

- Starts an internal timer to measure the conversation's age.

Each piece of information — the conversation ID, persistent data, idle time and age — are part of the conversation's context. In particular, the conversation ID is passed back to the client in the XML message through which web services communicate. A conversation ID is also passed in calls to resources. With each subsequent conversational call to the web service, the conversation ID is used to associate the call with the correct conversation context — in other words, the correct instance of the service, along with whatever state it may currently hold.

## Notes About Conversation Context

As you build services that support conversations, there are a few characteristics of conversations you should keep in mind:

- The scope of conversation context is limited to the service itself.
  For example, you cannot assume that the state of another service is being persisted simply because your service calls one of its methods during the course of a conversation. The other service must be responsible for its own state maintenance, with or without conversations.

- Correlation between two services that support conversations is handled automatically by WebLogic Server.
  In other words, if your service supports conversations and calls the conversational methods of another service that supports conversations, WebLogic Server will correlate the two separate contexts automatically.

- Unless you know otherwise, it is not a good practice to assume that conversations will be correctly correlated between your service and one that appears not to support conversations.

- Service state is only updated on the successful completion of methods or callback handlers that are marked with the conversation phase attributes "start," "continue" or "finish."

Note that this excludes internal methods of your service (which are not operations and so can not be conversational) and methods exposed by other web services.

# Implementing Conversational Methods and Callbacks

In practice, adding support for conversations is typically a matter of annotating methods and callbacks with the conversation phase attribute (discussed in the following section). Even so, as you write code for methods and callback handlers that will be annotated for use in conversations, you may want to keep the following suggestions in mind.

- Be sure to handle exceptions thrown from conversational methods and callback handlers.
  An unhandled exception thrown from a conversational method or callback handler will cancel any update of state from that method or handler (in other words, state data will not be serialized). As you plan exception handling for conversational methods and callback handlers, you should consider what an appropriate response to the exception is. The JwsContext interface provides an onException callback handler that is invoked whenever an exception is thrown from an operation (a method marked with the @jws:operation tag) or callback handler. Depending on your service's design, your code in the onException handler might:

- Log the error in an application log.

- Notify the client of the failure.

- Finish the conversation.

- Conversational methods and callbacks should be short-lived.
  Only one method or callback may be executing within a conversation at a given time. On one hand, this is a benefit in that it means you needn't worry about a new call interfering with one that is already being processed. On the other hand, because new calls will be blocked until the current one finishes executing, you should try to implement each method or callback so that it executes in a short amount of time.

- Ensure serialization support for variables that will hold state-related data.
  In Java, serialization is a technology that makes it possible to write information about an object instance to disk. This requirement can in most cases be met with no extra effort. For more information, see Supporting Serialization.

- Do not save state from within code that is not part of a conversation.
  If your service must save state, you should always try to do so by writing to member variables from within a method that starts or continues a conversation.

# Applying the Conversation Phase Attribute

Applying a conversation phase attribute to a method or callback identifies it as having a role in conversations. In Design View, you can apply the attribute using the Properties pane. When you set the conversation phase property, a corresponding tag like the one below is added to your service's source code immediately preceding the method or callback declaration:

    @jws:conversation phase="start"

Possible values for the conversation phase attribute are as follows:

- start — May be applied to methods only. Specifies that a call to the method starts a new conversation. Each call will create a new conversation context and an accompanying unique conversation ID, save the service's state, and start its idle and age timer.

- continue — May be applied to methods and callbacks. Specifies that a call to this method or callback is part of a conversation in progress. WebLogic Server will attempt to use the incoming conversation ID to correlate each call to an existing conversation. Each call to a "continue" method will save the service's state and reset its idle timer.
  Set the phase attribute to "continue" for any method or callback that is likely to be used for communication with a client in connection with an ongoing request — methods that are clearly intended to be called subsequent to the conversation's start and before its finish. These include requests for or responses with additional information, requests for progress or status, and so on.

- finish — May be applied to methods and callbacks. Specifies that a call to this method or callback finishes an existing conversation. A call will mark the conversation for destruction by WebLogic Server. At some point after a finish method returns successfully, all data associated with the conversation's context will be removed.
  It is also possible to finish a conversation by calling the JwsContext interface finishConversation method. For more information, see Managing Conversation Lifetime.

- none — May be applied to methods and callbacks. Specifies that a call to this method or callback has no meaning in the context of the conversation.

For more information adding support for conversations with the conversation phase attribute, see How Do I: Add Support for Conversations?

Note: It is possible to create a conversational web service that supports a deadlock condition. If the web service has at least one non-buffered incoming method with conversational phase set to "continue" or "finish" and has at least one non-buffered outgoing callback, it is possible that the callback will be initiated at the same time as a client calls one of the incoming methods. This situation will result in deadlock, causing one or both of the transactions to time out and be rolled back. If you experience this problem, make either all incoming methods or all outgoing callbacks message-buffered. For more about message buffering, see Asynchronous Methods.

## Notes About Setting Conversation Phase

Unless you know how a given control is implemented, it is not a good practice to apply the conversation phase attribute to methods and callbacks exposed by controls.

In other words, you should ordinarily not change the conversation phase attribute for items that appear on the right side of the design view. When you import the control (CTRL) file corresponding to a resource such as another service, its image in Design View will indicate how and whether it supports conversations. Because the control is merely a proxy for the resource itself, "changing" its conversation support may result in unpredictable behavior.

Related Topics

JwsContext Interface

@jws:conversation Tag