org.springframework.conversation
Interface ConversationManager

All Known Implementing Classes:
DefaultConversationManager

public interface ConversationManager

A conversation manager is used to manage conversations, most of all, the current conversation. It is used by the advice behind the conversation annotations BeginConversation and EndConversation in order to start and end conversations.

A conversation manager uses a ConversationRepository to create, store and remove conversation objects and a ConversationResolver to set and remove the current conversation id.

A conversation manager might be used manually in order to start and end conversations manually.

Conversations are a good way to scope beans and attributes depending on business logic boundary rather than a technical boundary of a scope like session, request etc. Usually a conversation boundary is defined by the starting point of a use case and ended accordingly or in other words a conversation defines the boundary for a unit of work.

A conversation is either implicitly started upon the first request of a conversation scoped bean or it is explicitly started by using the conversation manager manually or by placing the begin conversation on a method.
The same applies for ending conversations as they are either implicitly ended by starting a new one or if the timeout of a conversation is reached or they are ended explicitly by placing the end conversation annotation or using the conversation manager manually.

Conversations might have child conversations which are either nested and hence will inherit the state of their parent or they are isolated by having its own state and hence being independent from its parent.

Extending the conversation management
The conversation management ships with different out-of-the box implementations but is easy to extend. To extend the storage mechanism of conversations, the ConversationRepository and maybe the DefaultConversation have to be extended or overwritten to support the desired behavior.
To change the behavior where the current conversation is stored, either overwrite the ConversationResolver or make sure the current conversation id is being resolved, stored and removed within the default ThreadLocalConversationResolver.

Since:
3.1
Author:
Micha Kiener

Method Summary
 Conversation beginConversation(ConversationType conversationType)
          Creates a new conversation according the given conversationType and makes it the current active conversation.
 void endCurrentConversation(boolean root)
          Ends the current conversation, if any.
 Conversation getCurrentConversation()
          Returns the current conversation and creates a new one, if there is currently no active conversation yet.
 Conversation getCurrentConversation(boolean createNewIfNotExisting)
          Returns the current conversation, if existing or creates a new one, if currently no active conversation available and createIfNotExisting is specified as true.
 

Method Detail

getCurrentConversation

Conversation getCurrentConversation()
Returns the current conversation and creates a new one, if there is currently no active conversation yet. Internally, the manager will use the ConversationResolver to resolve the current conversation id and the ConversationRepository to load the conversation object being returned.

Returns:
the current conversation, never null, will create a new conversation, if no one existing

getCurrentConversation

Conversation getCurrentConversation(boolean createNewIfNotExisting)
Returns the current conversation, if existing or creates a new one, if currently no active conversation available and createIfNotExisting is specified as true.

Parameters:
createNewIfNotExisting - true, if a new conversation should be created, if there is currently no active conversation in place, false to return null, if no current conversation active
Returns:
the current conversation or null, if no current conversation available and createIfNotExisting is set as false

beginConversation

Conversation beginConversation(ConversationType conversationType)
Creates a new conversation according the given conversationType and makes it the current active conversation. See ConversationType for more detailed information about the different conversation creation types available.
If ConversationType.NEW is specified, the current conversation will automatically be ended

Parameters:
conversationType - the type used to start a new conversation
Returns:
the newly created conversation

endCurrentConversation

void endCurrentConversation(boolean root)
Ends the current conversation, if any. If root is true, the whole conversation hierarchy is ended and there will no current conversation be active afterwards. If root is false, the current conversation is ended and if it is a nested one, its parent is made the current conversation.

Parameters:
root - true to end the whole current conversation hierarchy or false to just end the current conversation