# Managing Conversation Lifetime

WebLogic Server maintains the aspects of a conversation that regulate its life span, including how old it is and how long it has been idle. You can write code to control and respond to these aspects at run time using methods and callbacks exposed by the JwsContext interface.

The life span you want for your conversation depends on the specific actions your service performs. For example, you can extend the maximum age or idle time (or both) when you anticipate that certain processes will take a long time to complete. You can finish a conversation immediately if you know the conversation should terminate. Or you can write code that executes when a conversation is about to end, so you can clean up after your service, release acquired resources, or notify the client that the conversation is about to end.

Using the JwsContext interface, you can manage a conversation's life span by:

- Controlling how long a conversation may remain idle
- Limiting a conversation's duration
- Finishing a conversation
- Doing something when a conversation finishes

Each of these aspects of managing the life span of a conversation is described in greater detail in the sections that follow.

## 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 web service's conversation automatically ends. The length of time you specify depends on what you need your conversation to accomplish. For example, you can temporarily increase the maximum idle time if your code makes an asynchronous follow-up request to a client and you suspect that it will take longer than the maximum idle time to respond. Once the client does respond, your code can update the maximum idle time back to a shorter duration.

You can control the maximum idle time in two ways: you first set the initial idle time at design time, and you can then change the maximum idle time at run time.

Note: The timer keeping track of idle time is only reset by interactions with a client. The idle timer is not reset when your web service receives a callback from another web service or Java control (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 a callback handler.

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

To set the initial maximum idle time in Design View, first click the service area. Next, use the Property Editor window to set the max-idle-time attribute, which is part of the conversation-lifetime property.

By default, the value of this attribute is 0, which means that the conversation may remain idle indefinitely. In general, you want to estimate a reasonable amount of time for your service to remain idle, then give this attribute the value you choose. 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!).

WebLogic Workshop annotates your service class with a Javadoc annotation when you change the default value of the max-idle-time attribute. So if you do not change the default value the annotation does not appear in your source code. Once the annotation is added, it resembles the following, which sets the value to 2 minutes:

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

The value specified in this attribute represents 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 can change the initial value by editing the Javadoc annotation either in your source code or in the Property Editor; changes in one are automatically reflected in the other.

For reference information about the @jws:conversation annotation, see @jws:conversation-lifetime Annotation.

### 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(): Resets the idle timer. 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 web services or Java 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 the Duration of a Conversation

A conversation's maximum age is the maximum time a conversation instance will exist before it is finished by WebLogic Server.

You can set the maximum age at design time, and you can change the maximum age during run time. This can be useful, for example, if it appears that the combined actions taken by your service to return a response to the client will take longer than originally expected.

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

To set the initial maximum age in Design View, click the service area, then use the Property Editor window to set the conversation-lifetime max-age attribute.

By default, the value of this attribute is 1 day, meaning that the conversation automatically finishes 24 hours 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 annotates your service class with a Javadoc annotation resembling the following example, which sets the value to 7 days.

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

The value specified in this attribute is 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 can change the initial value by editing the Javadoc annotation either in your source code or through the Properties window; changes in one are automatically reflected in the other. Also, note that WebLogic Workshop does not add the Javadoc annotation to your source code until you change the default value of max-age in the Properties window.

For reference information about the @jws:conversation-lifetime annotation, see @jws:conversation-lifetime Annotation.

### 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 can 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 accumulated 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 to allow WebLogic Server to remove it from memory. All data that is part of its persistent state is removed. The following list describes the four ways in which a conversation can finish:

- On completion of a web service method annotated with finish or one that invokes a client callback marked finish.
- When the conversation's maximum idle time is exceeded.
- When the conversation's maximum age is exceeded.
- When your code calls the JwsContext interface's finishConversation method.

Note that a conversation never ends during a method invocation. The conversation terminates immediately after the current method or callback invocation completes.

### Defining What Happens When a Conversation Finishes

You can write code that executes when a conversation finishes, regardless of how the conversation meets its end. To do this, you implement a handler for JwsContext's onFinish callback handler. You can add this handler to any web service that supports conversations.

When a conversation ends, your callback handler receives a boolean value that indicates whether or not 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 or if it has remained idle longer than the value set in the conversation-lifetime property max-idle-time attribute.

The onFinish callback handler will receive a value of false if the conversation ended because your code called the JwsContext.finishConversation method or via execution of an method or callback whose conversation phase attribute is set to finish.

To Add Code to Handle the End of a Conversation

1. Declare a variable for com.bea.control.JwsContext:

       /** @common:context */
       com.bea.control.JwsContext context;

2. Using the variable name, add a callback handler for the onFinish callback exposed by the JwsContext interface.

   Your callback handler declaration should resemble the following example, where the variable is context:

       public void context_onFinish(boolean expired)
       {
       }

3. 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.";
           }
           context.getLogger("myWebService").debug(finishStatus);

       }

Related Topics

Life of a Conversation

Implementing Conversations

JwsContext Interface

@jws:conversation-lifetime Annotation