org.apache.myfaces.orchestra.conversation
Class Conversation

java.lang.Object
  extended by org.apache.myfaces.orchestra.conversation.Conversation

public class Conversation
extends java.lang.Object

A Conversation is a container for a set of beans.

Optionally, a PersistenceContext can also be associated with a conversation.

There are various ways how to get access to a Conversation instance:

Conversation instances are typically created when an EL expression references a bean whose definition indicates that it is in a conversation scope.

Conversation instances are typically destroyed:


Constructor Summary
Conversation(ConversationContext conversationContext, java.lang.String name, ConversationFactory factory)
           
 
Method Summary
 void addAspect(ConversationAspect aspect)
          Add an Aspect to this conversation.
protected  void checkValid()
          Assert the conversation is valid.
protected  void destroy()
          Destroy the conversation.
(package private)  void enterConversation()
          Increase one to the "conversation active" counter.
 ConversationAspect getAspect(java.lang.Class conversationAspectClass)
          Get the aspect corresponding to the given class.
(package private)  ConversationAspects getAspects()
           
 java.lang.Object getAttribute(java.lang.String name)
          Get a specific attribute, ie a named managed bean.
static Conversation getCurrentInstance()
          Get the current conversation.
(package private) static CurrentConversationInfo getCurrentInstanceInfo()
          Returns the info about the current conversation
 ConversationFactory getFactory()
          Return the factory that created this conversation.
 long getLastAccess()
          The system time in millis when this conversation has been accessed last
 java.lang.String getName()
          Return the name of this conversation.
 boolean hasAttribute(java.lang.String name)
          Check if this conversation holds a specific attribute (ie has a specific named managed bean instance).
 void invalidate()
          Invalidate (end) the conversation.
 Conversation invalidateAndRestart()
          Invalidate/End and restart the conversation.
 boolean isInvalid()
          Return true if the conversation is invalid, ie should not be used.
(package private)  boolean isQueueInvalid()
          Return true if the conversation has been queued to be invalidated.
(package private)  void leaveConversation()
          decrease one from the "conversation active" counter
 java.lang.Object removeAttribute(java.lang.String name)
          Remove a bean from the conversation.
 void setAttribute(java.lang.String name, java.lang.Object bean)
          Add the given bean to the conversation scope.
(package private) static void setCurrentInstance(CurrentConversationInfo conversation)
          Sets info about the current conversation instance.
protected  void touch()
          Mark this conversation as having been used at the current time.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Conversation

public Conversation(ConversationContext conversationContext,
                    java.lang.String name,
                    ConversationFactory factory)
Method Detail

touch

protected void touch()
Mark this conversation as having been used at the current time.

Conversations can have "timeouts" associated with them, so that when a user stops a conversation and goes off to work on some other part of the webapp then the conversation's memory can eventually be reclaimed.

Whenever user code causes this conversation object to be looked up and returned, this "touch" method is invoked to indicate that the conversation is in use. Direct conversation lookups by user code can occur, but the most common access is expected to be via an EL expression which a lookup of a bean that is declared as being in conversation scope. The bean lookup causes the corresponding conversation to be looked up, which triggers this method.


getLastAccess

public long getLastAccess()
The system time in millis when this conversation has been accessed last


setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object bean)
Add the given bean to the conversation scope.

This will fire a ConversationBindingEvent on the bean parameter object if the bean implements the ConversationBindingListener interface

Note that any object can be stored into the conversation; it is not limited to managed beans declared in a configuration file. This feature is not expected to be heavily used however; most attributes of a conversation are expected to be externally-declared "managed beans".


checkValid

protected void checkValid()
Assert the conversation is valid. Throws IllegalStateException if this conversation has been destroyed; see method setInvalid.


getName

public java.lang.String getName()
Return the name of this conversation.

A conversation name is unique within a conversation context.


getFactory

public ConversationFactory getFactory()
Return the factory that created this conversation.

Note that this factory will have set the initial aspects of this factory, which configure such things as the lifetime (flash, manual, etc) and conversation timeout properties.


invalidate

public void invalidate()
Invalidate (end) the conversation.

If the conversation is currently active (ie the current call stack contains an object that belongs to this conversation) then the conversation will just queue the object for later destruction. Calls to methods like ConversationManager.getConversation(...) may still return this object, and it will continue to function as a normal instance.

Only when the conversation is no longer active will the conversation (and the beans it contains) actually be marked as invalid ("destroyed"). Once the conversation has been destroyed, the ConversationManager will discard all references to it, meaning it will no longer be accessable via lookups like ConversationManager.getConversation(). If something does still have a reference to a destroyed conversation, then invoking almost any method on that object will throw an IllegalStateException. In particular, adding a bean to the conversation (invoking addAttribute) is not allowed.


invalidateAndRestart

public Conversation invalidateAndRestart()
Invalidate/End and restart the conversation.

This conversation object is immediately "destroyed" (see comments for method invalidate), and a new instance is registered with the conversation manager using the same name. The new instance is returned from this method.

Any code holding a reference to the old conversation instance will receive an IllegalStateException when calling almost any method on that instance.


isInvalid

public boolean isInvalid()
Return true if the conversation is invalid, ie should not be used.


isQueueInvalid

boolean isQueueInvalid()
Return true if the conversation has been queued to be invalidated.


destroy

protected void destroy()
Destroy the conversation.


hasAttribute

public boolean hasAttribute(java.lang.String name)
Check if this conversation holds a specific attribute (ie has a specific named managed bean instance).


getAttribute

public java.lang.Object getAttribute(java.lang.String name)
Get a specific attribute, ie a named managed bean.


removeAttribute

public java.lang.Object removeAttribute(java.lang.String name)
Remove a bean from the conversation.

This will fire a ConversationBindingEvent if the bean implements the ConversationBindingListener interface.


getCurrentInstance

public static Conversation getCurrentInstance()
Get the current conversation.

Returns:
The conversation object associated with the nearest object in the call-stack that is configured to be in a conversation. Null is returned when no object in the call-stack is in a conversation.

setCurrentInstance

static void setCurrentInstance(CurrentConversationInfo conversation)
Sets info about the current conversation instance.

This method is only expected to be called by CurrentConversationAdvice.invoke, which ensures that the current instance is reset to null as soon as no bean in the call-stack is within a conversation.


getCurrentInstanceInfo

static CurrentConversationInfo getCurrentInstanceInfo()
Returns the info about the current conversation


enterConversation

void enterConversation()
Increase one to the "conversation active" counter. This is called when a method is invoked on a bean that is within this conversation. When the method returns, leaveConversation is invoked. The result is that the count is greater than zero whenever there is a bean belonging to this conversation on the callstack.


leaveConversation

void leaveConversation()
decrease one from the "conversation active" counter


getAspects

ConversationAspects getAspects()

getAspect

public ConversationAspect getAspect(java.lang.Class conversationAspectClass)
Get the aspect corresponding to the given class.

Returns:
null if such an aspect has not been attached to this conversation

addAspect

public void addAspect(ConversationAspect aspect)
Add an Aspect to this conversation. See class ConversationAspects for further details.



Copyright 2007 The Apache Software Foundation. All Rights Reserved.