Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.myfaces.orchestra.conversation
Class Conversation

    java.lang.Object
      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:

- `getCurrentInstance()` if you are calling from a conversation-scoped bean, or something that is called from such a bean.
- `ConversationManager.getConversation(String)`
- by implementing the `ConversationAware` or `ConversationBindingListener` interface in a bean.

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

A conversation instance is typically destroyed:

- At the end of a request when it are marked as access-scoped but no bean in the conversation scope was accessed during the just-completed request.
- Via an ox:endConversation component
- Via an action method calling Conversation.invalidate()
- Due to a conversation timeout, ie when no object in the conversation has been accessed for N minutes. See ConversationManagedSessionListener, ConversationTimeoutableAspect, and ConversationManager.checkTimeouts.

Constructor Summary
`Conversation(ConversationContext conversationContext, java.lang.String name, ConversationFactory factory)`

Method Summary
`void` | `addAspect(ConversationAspect aspect)` Add an Aspect to this conversation.
`java.lang.Object` | `bind(java.lang.Object instance)` Return a proxy object that "binds" the specified instance to this conversation.
`protected void` | `checkValid()` Assert the conversation is valid.
`protected void` | `destroy()` Destroy the conversation.
`ConversationAspect` | `getAspect(java.lang.Class conversationAspectClass)` Get the aspect corresponding to the given class.
`java.lang.Object` | `getAttribute(java.lang.String name)` Get a specific attribute, ie a named managed bean.
`protected java.util.Map` | `getBeans()` Get direct access to the beans map.
`static Conversation` | `getCurrentInstance()` Get 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.
`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.
`protected void` | `setBeans(java.util.Map beans)` Replace the current beans map.
`void` | `setBinder(ConversationBinder binder)` Define the (optional) binder used by this instance in method bind(Object).
`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

### setBinder

    public void setBinder(ConversationBinder binder)

  Define the (optional) binder used by this instance in method bind(Object).

  Expected to be called by code that creates instances of this type immediately after the constructor is invoked. See bind(Object) for more details.

  Since:
    1.3

### 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 (access, 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.

  Returns:
    the new conversation

### isInvalid

    public boolean isInvalid()

  Return true if the conversation is invalid, ie should not be used.

### destroy

    protected void destroy()

  Destroy the conversation.
  - inform all beans implementing the `ConversationBindingListener` about the conversation end
  - free all beans

  After return from this method, this conversation object's invalid flag is set and the map of beans associated with this conversation is empty. In addition, the parent context no longer holds a reference to this 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.
    If there is no object in the call-stack the system will lookup the single conversation bound to the conversationContext.
    If not found, null will be returned.

### 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.

### getBeans

    protected java.util.Map getBeans()

  Get direct access to the beans map.

  This method is only intended for use by subclasses that manipulate the beans map in unusual ways. In general, it is better to use the setAttribute/removeAttribute methods rather than accessing beans via this map. Adding/removing entries in this map will not trigger the usual callbacks on the bean objects themselves.

  Since:
    1.2

### setBeans

    protected void setBeans(java.util.Map beans)

  Replace the current beans map.

  Since:
    1.2
  See Also:
    `getBeans()`

### bind

    public java.lang.Object bind(java.lang.Object instance)

  Return a proxy object that "binds" the specified instance to this conversation.

  Whenever a method is executed on the proxy, this conversation is "entered" before the method is invoked on the actual instance, as if the specified instance were a bean that was defined in the dependency-injection framework as belonging to this conversation.

  The specified bean is NOT added to the set of beans belonging to the conversation, ie its lifecycle is still independent of the conversation.

  The returned proxy is bound to a specific Conversation instance, so it should not be stored for a long time; if the conversation is "invalidated" the proxy will continue to reference the original conversation instance meaning that invoking the proxy would use the "stale" conversation rather than a new instance. It also means that memory allocated to the conversation will not be recycled, although this is not too serious as the invalidated conversation will be empty of beans. This limitation on the lifetime of the returned proxy is not an issue for many of the uses of this method; in particular, when wrapping objects returned by property getters for the use of EL expressions this is fine as the proxy is only used during the scope of the EL expression execution. If a proxy is used after the conversation it is bound to has been invalidated then an IllegalStateException will be thrown.

  This method is useful when a conversation-scoped object creates an object instance via new() or via calling some other library, and then wants all operations on that object to run within its own conversation. In particular, when a backing-bean returns a persistent object that has been loaded via a DAO class, it is often desirable for all methods on the persistent object to run within the backing-bean's persistence context, ie within the same persistence context set up which existed when the DAO class loaded the instance. For example, a JSF EL expression may retrieve a persistent object from a backing bean then navigate through its properties; walking lazy relations in this way will fail unless calls to methods of the persistent object cause the correct persistence-context to be set up.

  This method is theoretically an optional operation; the orchestra adapter layer for some specific dependency-injection frameworks might choose not to support this, in which case an UnsupportedOperationException will be thrown. The default Orchestra-Spring integration certainly does support it.

  It initially seems reasonable for Orchestra to also provide a variant of this method that returns a "scoped proxy" object that looks up the most recent version of the conversation by name and then runs the bound object in the context of that conversation instance. This would mean that a proxy would never throw an IllegalStateException due to its conversation having been invalidated. However this is not actually very useful. The primary use for this method is expected to be wrapping of persistent objects returned by JPA, Hibernate or similar. In this case the point is to access the object using the conversation's "persistence context"; a new conversation will have a new persistence context instance, not the one the object needs.

  Since:
    1.3

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 The Apache Software Foundation. All Rights Reserved.