# Implementing Conversations

Conversations maintain a web service's state-related data and correlate communications between the web service, its clients, and other resources. You should implement conversations in any web service design that is asynchronous or involves multiple communications with a client or Java control in connection with a single request.

This topic describes the components of a conversation and explains how to build web services that support conversations. It introduces the phase attribute and provides guidelines for implementing conversational callbacks and methods.

## Understanding Conversation Context

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.

When a conversation starts, WebLogic Server does the following:

- Creates a context through which to maintain the scope of the conversation and associates it with a conversation ID.
- Starts an internal timer to measure idle time.
- Starts an internal timer to measure the conversation's age.

When WebLogic Server performs all of these tasks, it creates a context for the conversation. Each piece of information—including the conversation ID, persistent data, idle time and age—is part of the conversation's context.

The conversation ID is a particularly useful item in the conversation’s context. It attaches to each communication, which helps each of the resources, web services, and clients involved in the conversation identify which communications belong to which conversation. To learn more about conversation IDs, see Overview: Conversations.

## Designing a Web Service to Use Conversations

As you build services that support conversations, you should keep in mind a few characteristics of conversations. First, WebLogic Server automatically handles correlation between two web services that support conversations. In other words, if your web service supports conversations and calls the conversational methods of another web service that supports conversations, WebLogic Server manages the conversation, including the conversation ID, automatically.

However, the scope of conversation context is limited to the service itself. You cannot assume that the state of another web service is being persisted simply because your service calls one of its methods during the course of a conversation. The other web service is responsible for its own state maintenance.

Also keep in mind that a web service's 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. This excludes internal methods of your service, which are not operations and so can not be conversational.

## Applying the Conversation Phase Attribute

When you apply a conversation phase attribute to a method or callback, you identify it as having a role in conversations. In Design View, you can apply the attribute using the Properties Editor when a method is selected. When you set the conversation phase property, a corresponding annotation like the one shown here is added to your web service's source code immediately preceding the method or callback declaration:

    @jws:conversation phase="start"

The possible values for the conversation phase attribute are start, continue, finish, and none. The following sections describe these values.

### The start Value

You can apply the start value to methods only. It specifies that a call to the method starts a new conversation. Each call creates a new conversation context and an accompanying unique conversation ID, saves the service's state, and starts its idle and age timer.

### The continue Value

You can apply the continue value to methods and callbacks. It specifies that a call to this method or callback is part of a conversation in progress. WebLogic Server attempts to use the incoming conversation ID to correlate each call to an existing conversation. Each call to a continue method saves the service's state and resets 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 operation. This includes methods that are clearly intended to be called subsequent to the conversation's start and before its finish as well as requests for responses with additional information, requests for progress or status, and so on.

### The finish Value

You can apply the finish value to methods and callbacks. It specifies that a call to this method or callback finishes an existing conversation. A call to a finish method or callback marks the conversation for destruction by WebLogic Server. At some point after a finish method returns successfully, all data associated with the conversation's context is removed.

It is also possible to finish a conversation by calling the JwsContext interface finishConversation method. For more information, see Managing Conversation Lifetime.

### The none Value

You can apply the none value to methods and callbacks. It specifies that a call to this method or callback has no meaning in the context of the conversation. none is the default value for the conversation phase attribute.

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

## Implementing Conversational Methods and Callbacks

In practice, adding support for conversations is simply a matter of annotating methods and callbacks with the conversation phase attribute, as described above. Even so, as you write code for methods and callback handlers that will be annotated for use in conversations, you might want to keep the following issues in mind.

### Handle Exceptions

Be sure to handle exceptions thrown from conversational methods and callback handlers. An unhandled exception thrown from a conversational method or callback handler cancels any update of state from that method or handler. In other words, state data will not be serialized. So 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 @common:operation annotation) or callback handler.

Depending on your web 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.

### Keep Methods and Callbacks Short-Lived

Keep conversational methods and callbacks short-lived. Only one method or callback may be executing within a conversation at a given time. This is a benefit in that it means you needn't worry about a new call interfering with one that is already being processed. But because new calls are 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. Use buffering where appropriate to prevent subsequent clients from being blocked while the web service is busy.

### Ensure Support for Serialization

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.

### Stay Within the Code of a Conversation

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.

Related Topics

JwsContext Interface

@jws:conversation Annotation

@jws:message-buffer Annotation