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.
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.
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.
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 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.
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.