How Do I: Control the Lifetime of a Web Service?

If several messages between your web service and a client are related to each other, they messages can be associated with one another by using conversations. To create a conversation, identify messages from the client as messages that start a conversation, continue a conversation, finish a conversation, or do not participate in a conversation at all.

Methods that start a conversation will create a unique identifier that is returned to the client.

Continue methods and callbacks will use this identifier to associate their message with the information that was saved from the start method. There can be as many continue methods necessary to accumulate the information you web service needs.

Once all of the processing is complete, finish methods will remove the unique identifier from the server’s conversation persistence cache.

To Set How a Method Participates in a Conversation

1. In Design View, click the method you identified as starting the conversation.

2. In the Properties pane, expand the conversation property.

3. On the phase property, from the drop-down list, select start.

4. Repeat steps 1 through 3 for each method that can start a conversation.

5. Click the method you identified as continuing the conversation.

6. In the Properties pane, expand the conversation property.

7. On the phase property, from the drop-down list, select continue.

8. Repeat from steps 5 through 7 for each method that can continue a conversation.

9. Click the method you identified as finishing the conversation.

10. In the Properties pane, expand the conversation property.

11. On the phase property, from the drop-down list, select finish.

12. Repeat steps 9 through 11 for each method that can finish a conversation.

A conversation can also be finished at run time by a call to the JwsContext interface's finishConversation() method. This interface was added to your web service when the service was created with a default variable name of context. To end a conversation from the server, add this line in the source view where you would like to end the conversation.

    context.finishConversation();

A conversation can also expire due to the max-age attribute of the conversation-lifetime property. The default duration for a conversation is one day.

Note that conversation termination never occurs during the execution of a web service method. Whether the conversation is finished due to the method being marked as a "finish" method; because JwsContext.finishConversation is called; or whether the conversation lifetime expires, the conversation does not actually finish until immediately after execution of any current method invocation.

To Change the Default Conversation Lifetime

1. In Design View, select your web service.

2. In the Properties pane, expand the conversation-lifetime property.

3. For the max-age attribute, enter the duration you would like to preserve a conversation.

You can also give a conversation a max-idle time, or how long should the server wait between messages.

To Change the max-idle-time Property

1. In the Properties pane, expand the conversation-lifetime property.

2. For the max-idle-time attribute, enter the longest allowed duration between messages. Use the default of 0 if you do not want to use the max-idle time.

If a conversation exists for a duration of more than the max-age, or there are not messages for longer than the max-idle-time, the conversation will be removed from the server’s cache.

Related Topics

Managing Conversation Lifetime

@jws:conversation-lifetime Tag

JwsContext.finishConversation() Method