Managing Conversation Lifetime

For a service participating in a conversation, aspects of the conversation — including how old it is and how long it has been idle — are maintained by WebLogic Server. Using methods and callbacks exposed by the JwsContext interface, you can write code to control and respond to these aspects at run time.

This can be useful when you want to provide logic that changes the values controlling conversation lifetime according to specific actions your service performs. For example, you might extend maximum age or idle time (or both) when you anticipate that certain processes will take a long time to complete; you might also finish a conversation immediately.

You can also write code that executes when a conversation is about to end, giving you an opportunity to clean up after your service, releasing acquired resources or notifying the client that the conversation is about to end.

When you create a new web service (JWS file) your source code automatically includes the following:

    /** @jws:context */
    weblogic.jws.control.JwsContext context;

The @jws:context Javadoc tag specifies that a context should be created within which to manage state and correlate calls for the web service. The declaration of a JwsContext variable is provided so that you can write code calling methods and handling callbacks exposed by the JwsContext interface.

Note: With the JwsContext variable in your code, you will be able to view a list of the interface's methods and callbacks in the WebLogic Workshop Structure Pane.

Using this JwsContext variable, you can manage conversation lifetime by:

- Controlling how long a conversation may remain idle

- Limiting a conversation's duration

- Finishing a conversation

- Doing something when a conversation finishes

# Controlling How Long a Conversation Can Remain Idle

Maximum idle time is the amount of time that can go by between incoming messages before your service's conversation automatically ends and WebLogic Server removes it from memory.

You can write code to change the maximum amount of time for which a conversation may remain idle before it automatically finishes. You might write code to change the maximum idle time if you want to allow more time for a client to complete some process. For example, you might temporarily increase the maximum idle time if your code makes an asynchronous follow-up request to that client and you suspect that it will take longer than the maximum idle time to respond; when the client does respond, your code can update the maximum idle time back to a shorter duration.

Note: The timer keeping track of idle time is only reset by interactions with a client. For example, it is not reset when your service receives a callback from another web service (in other words, from entities on the right side of your service in Design View). To reset the idle timer in such circumstances, you can call the resetIdleTime method of the JwsContext interface in your callback handler.

## Setting the Initial Maximum Idle Time Value at Design Time

You can set the initial maximum idle time in Design View by clicking the service area, then using the Properties pane to set the conversation-lifetime max-idle-time attribute.

By default, the value of this attribute is "0", meaning that the conversation may remain idle indefinitely. In general, it is a good practice to estimate a reasonable amount of time for your service to remain idle, then set this attribute to some other value. Allowing a conversation to remain idle for a long period of time can absorb system resources, particularly as new conversation contexts are created for new calls to the service (each with indefinite idle timeout values!).

When you change the max-idle-time attribute, WebLogic Workshop will annotate your service class with a Javadoc tag resembling the following (this example sets the value to "2 minutes").

    /**
     * @jws:conversation-lifetime max-idle-time="2 minutes"
     */

The value specified in this attribute will be the starting value for maximum idle time when a new conversation with this service starts. Thereafter, you can update the value through your service's code.

Note: You may change the initial value by editing the Javadoc tag in your source code or through the Properties pane; changes in one will be automatically reflected in the other. Also, note that WebLogic Workshop will not add the Javadoc tag to your source code until you use the Properties pane to change the default value of "0".

For reference information about the @jws:conversation tag, see @jws:conversation-lifetime Tag.

## Changing the Maximum Idle Time Value at Run Time

To manage the maximum idle time at run time, you can use the following JwsContext methods:

- void setMaxIdleTime(long seconds) — Sets a new value to the specified number of seconds.

- void setMaxIdleTime(String duration) — Sets a new value using a string expressing the idle time duration (such as "2 minutes," "5 days," and so on).

- long getMaxIdleTime() — Returns the current maximum idle time as a number of seconds.

- void resetIdleTime() — Sets the maximum idle time back to its initial value. This may be useful when the conversation involves some activity besides receiving messages from the client, but this activity is still considered "non-idle." This could include interacting with other services through controls.

- long getCurrentIdleTime() — Returns the number of seconds the conversation has been idle.

In the following example involving a database query, maximum idle time is set to allow at least five minutes for the database query to return.

    public void getEmployeeContactInfo(String employeeID)
    {
        context.setMaxIdleTime("5 minutes");
        Employee m_contactInfo =
            employeeDataControl.getContactInformation(employeeID);
    }

# Limiting a Conversation's Duration

A conversation's maximum age is the interval between the time the conversation starts and the time it finishes, before it is finished by WebLogic Server and removed from memory.

You can write code to change the maximum age. This can be useful if, for example, it appears that the combined actions taken by your service to return a response to the client will take longer that originally expected.

## Setting the Initial Maximum Age Value at Design Time

You can set the initial maximum age in Design View by clicking the service area, then using the Properties pane to set the conversation-lifetime max-age attribute.

By default, the value of this attribute is "1 day", meaning that the conversation will automatically finish one day after it starts. In general, it is a good practice to estimate a reasonable amount of time for your service to remain active, then set this attribute to that value. Allowing a conversation to remain active for a long period of time can absorb system resources, particularly as new conversation contexts are created for new calls to the service.

When you change the max-age attribute, WebLogic Workshop will annotate your service class with a Javadoc tag resembling the following (this example sets the value to "7 days").

    /**
     * @jws:conversation-lifetime max-age="7 days"
     */

The value specified in this attribute will be the starting value for the maximum age when a new conversation with this service starts. Thereafter, you can update the value through your service's code.

Note: You may change the initial value by editing the Javadoc tag in your source code or through the Properties pane; changes in one will be automatically reflected in the other. Also, note that WebLogic Workshop will not add the Javadoc tag to your source code until you change the default value of max-age in the Properties pane.

For reference information about the @jws:conversation-lifetime tag, see @jws:conversation-lifetime Tag.

## Changing the Maximum Age Value at Run Time

To manage a conversation's maximum age at run time, you can use the following JwsContext methods:

- void setMaxAge(String duration) — Sets a new value using a string expressing the maximum age duration (such as "3 hours," "2 days," and so on).

- void setMaxAge(java.util.Date date) — Sets a new value to the specified number of seconds.

- long getMaxAge() — Returns the maximum age of the conversation number in seconds.

- long getCurrentAge() — Returns the number of seconds since the conversation began.

The following simple example illustrates how you might set the maximum age to a duration intended to allow time for a client to gather more information related to their request and return. Extending the conversation's life allows the service's context (along with any persistent state accrued so far) to remain active until the client returns.

    public void needMoreInfo(String neededInfoDescription)
    {
        context.setMaxAge("2 days");
        callback.onRequestMoreInfo(neededInfoDescription);
    }

# Finishing a Conversation

The end of a conversation marks the conversation context for removal from memory by WebLogic Server. This means that data that is part of its persistent state will be removed. A conversation may finish in any of the following ways:

- On completion of a service method annotated with "finish" or one that invokes a client callback marked ”finish”.

- The conversation's maximum idle time is exceeded.

- The conversation's maximum age is exceeded.

- Your code calls the JwsContext interface's finishConversation method.

Note that in all but the last case, the conversation may not in fact end immediately. Even though it is marked for destruction, it may still be some time before WebLogic Server actually removes the conversation context.

Calling the finishConversation method, on the other hand, provokes the end of the conversation (and subsequent clean-up by WebLogic Server) upon return of the method or callback in which finishConversation was called. You may find it useful to directly end a conversation in response to client requests, changes in state, or other events. When you want to ensure a timely end to the conversation, call the finishConversation method.

## Doing Something When a Conversation Finishes

You can write code that will execute when a conversation finishes, regardless of how the conversation meets its end. To do this, you add code to the JwsContext_onFinish callback handler. You can add this handler to any service that supports conversations.

When a conversation ends your callback handler receives boolean value indicating whether the conversation ended by expiring. A conversation expires if it lasts longer than the value set in the service's conversation-lifetime property max-age attribute. It also expires if your service has remained idle longer than the value set in the conversation-lifetime property max-idle-time attribute.

On the other hand, your handler will receive a value of false if the conversation ended because your code called the JwsContext.finishConversation method. A false value also indicates that the conversation ended through execution of an item (such as a method or callback) whose conversation property phase attribute is set to finish.

# To Add Code to Handle the End of a Conversation

1. Locate the variable declared as weblogic.jws.control.JwsContext.
   When you add support for a conversation, WebLogic Workshop automatically adds to your code a variable you can use to manage conversation lifetime. This variable will look something like the following:

    /** @jws:context */
    weblogic.jws.control.JwsContext context;

2. Using the variable name provided (here, this is context) add a callback handler for the onFinish callback exposed by the JwsContext interface.
   Your callback handler declaration should look something like the following:

    public void context_onFinish(boolean expired)
    {
    }

3. Between the braces, add the code you would like to have execute when the conversation finishes.
   For example, if for debugging purposes you wanted to write a message to the console to indicate how the conversation had ended, you might implement the handler in the following way:

    public void context_onFinish(boolean expired)
    {
        String finishStatus = "";
        if(expired){
            finishStatus = "Conversation expired.";
        }
        else{
            finishStatus = "Conversation finished normally.";      }
        System.out.println(finishStatus);
        }

Related Topics

Life of a Conversation

Defining Conversation Scope

JwsContext Interface

@jws:conversation-lifetime Tag