org.springframework.conversation
Interface Conversation

All Known Subinterfaces:
MutableConversation
All Known Implementing Classes:
DefaultConversation

public interface Conversation

The interface for a conversation object being managed by the ConversationManager and created, stored and removed by the ConversationRepository.
The conversation object is most likely never used directly but rather indirectly through the ConversationScope. It supports fine grained access to the conversation container for storing and retrieving attributes, access the conversation hierarchy or manage the timeout behavior of the conversation.

Since:
3.1
Author:
Micha Kiener

Method Summary
 Object getAttribute(String name)
          Returns the value attached to the given name, if any previously registered, null otherwise.
Returns the attribute stored with the given name within this conversation or any within the path through its parent to the top level root conversation.
 List<? extends Conversation> getChildren()
          Returns a list of child conversations, if any, an empty list otherwise, must never return null.
 long getCreationTime()
          Returns the timestamp in milliseconds this conversation has been created.
 String getId()
          Returns the id of this conversation which must be unique within the scope it is used to identify the conversation object.
 long getLastAccessedTime()
          Returns the timestamp in milliseconds this conversation was last accessed (usually through a getAttribute(String), setAttribute(String, Object) or removeAttribute(String) access).
 Conversation getParent()
          Returns the parent conversation, if this is a nested conversation, null otherwise.
 Conversation getRoot()
          Returns the top level root conversation, if this is a nested conversation or this conversation, if it is the top level root conversation.
 int getTimeout()
          Returns the timeout of this conversation object in seconds.
 boolean isIsolated()
          Returns true, if this is a nested, isolated conversation so that it does not inherit the state from its parent but rather has its own state.
 boolean isNested()
          Returns true, if this is a nested conversation and hence getParent() will returns a non-null value.
 Object removeAttribute(String name)
          Removes the value in the current conversation having the given name and returns it, if found and removed, null otherwise.
Removes the attribute from this specific conversation, does not remove it, if found within its parent.
 Object setAttribute(String name, Object value)
          Stores the given value in this conversation using the specified name.
 void setTimeout(int timeout)
          Set the timeout of this conversation hierarchy in seconds.
 

Method Detail

getId

String getId()
Returns the id of this conversation which must be unique within the scope it is used to identify the conversation object. The id is set by the ConversationRepository and most likely be used by the ConversationResolver in order to manage the current conversation.

Returns:
the id of this conversation

setAttribute

Object setAttribute(String name,
                    Object value)
Stores the given value in this conversation using the specified name. If this state already contains a value attached to the given name, it is returned, null otherwise.
This method stores the attribute within this conversation so it will be available through this and all nested conversations.

Parameters:
name - the name of the value to be stored in this conversation
value - the value to be stored
Returns:
the old value attached to the same name, if any, null otherwise

getAttribute

Object getAttribute(String name)
Returns the value attached to the given name, if any previously registered, null otherwise.
Returns the attribute stored with the given name within this conversation or any within the path through its parent to the top level root conversation. If this is a nested, isolated conversation, attributes are only being resolved within this conversation, not from its parent.

Parameters:
name - the name of the value to be retrieved
Returns:
the value, if available in the current state, null otherwise

removeAttribute

Object removeAttribute(String name)
Removes the value in the current conversation having the given name and returns it, if found and removed, null otherwise.
Removes the attribute from this specific conversation, does not remove it, if found within its parent.

Parameters:
name - the name of the value to be removed from this conversation
Returns:
the removed value, if found, null otherwise

getRoot

Conversation getRoot()
Returns the top level root conversation, if this is a nested conversation or this conversation, if it is the top level root conversation. This method never returns null.

Returns:
the root conversation (top level conversation)

getParent

Conversation getParent()
Returns the parent conversation, if this is a nested conversation, null otherwise.

Returns:
the parent conversation, if any, null otherwise

getChildren

List<? extends Conversation> getChildren()
Returns a list of child conversations, if any, an empty list otherwise, must never return null.

Returns:
a list of child conversations (may be empty, never null)

isNested

boolean isNested()
Returns true, if this is a nested conversation and hence getParent() will returns a non-null value.

Returns:
true, if this is a nested conversation, false otherwise

isIsolated

boolean isIsolated()
Returns true, if this is a nested, isolated conversation so that it does not inherit the state from its parent but rather has its own state. See ConversationType.ISOLATED for more details.

Returns:
true, if this is a nested, isolated conversation

getCreationTime

long getCreationTime()
Returns the timestamp in milliseconds this conversation has been created.

Returns:
the creation timestamp in millis

getLastAccessedTime

long getLastAccessedTime()
Returns the timestamp in milliseconds this conversation was last accessed (usually through a getAttribute(String), setAttribute(String, Object) or removeAttribute(String) access).

Returns:
the system time in milliseconds for the last access of this conversation

getTimeout

int getTimeout()
Returns the timeout of this conversation object in seconds. A value of 0 stands for no timeout. The timeout is usually managed on the root conversation object and will be returned regardless of the hierarchy of this conversation.

Returns:
the timeout in seconds if any, 0 otherwise

setTimeout

void setTimeout(int timeout)
Set the timeout of this conversation hierarchy in seconds. A value of 0 stands for no timeout. Regardless of the hierarchy of this conversation, a timeout is always set on the top root conversation and is valid for all conversations within the same hierarchy.

Parameters:
timeout - the timeout in seconds to set, 0 for no timeout