javax.faces.flow
Class FlowHandler

java.lang.Object
  extended by javax.faces.flow.FlowHandler

public abstract class FlowHandler
extends Object

FlowHandler is the main entry point that enables the runtime to interact with the Faces Flows feature. FlowHandler is used by the ConfigurableNavigationHandler when it needs to make navigational decisions related to flows. The implementation must support two means of defining Faces Flows: 1. metadata within VDL pages and 2. metadata in the Application Configuration Resources. Additional means of defining flows may be provided by decorating the FlowHandlerFactory.

Regardless of the means of defining a flow, the runtime must scan for and discover flows at application startup time, as well as support the capability to add flows dynamically during the application's lifetime. In the case of dynamically added flows, the runtime is not required to persist the flow definition for such flows, but may do so. The faces flow feature entirely depends on the ClientWindow feature, which itself requires explicit enabling. Please see the specification for ClientWindow for the requirements for enabling this feature.

Startup Time Requirements

During startup, flow definitions must be discoverd and inspected and each such flow made known to the runtime with a call to addFlow(javax.faces.context.FacesContext, java.lang.Object, javax.faces.flow.Flow). The inspection must proceed in the following order.

If the runtime discovers a conflict between a flow defined in a VDL view and one defined in the Application Configuration Resources, the entry in the Application Configuration Resources takes precedence. This is consistent with the behavior regarding annotations and XML as specified in the section "Requirements for scanning of classes for annotations" of the spec prose document.

Defining Flows

The runtime must support the set of XML elements described in the "Faces Flows" facelet taglibrary as a means of defining the Faces Flows for an application instance. See the API Overview for a link to the Facelet Taglibrarydocs, including the Faces Flows taglibrary. When used within VDL views, the elements must reside within the view's <f:metadata> section, and must be namespaced properly as with any other Facelet Taglibrary. When used in the Application Configuration Resources, the elements may appear as defined in the Application Configuration Resources schema.

Managing Flows

The singleton instance of this class must be thread safe, and therefore must not store any per-user state. Flows are, however, traversed in a per-user manner, and must be associated with the current ClientWindow. Furthermore, Flows may be nested. These requirements strongly suggest managing the flows with a stack-like runtime data structure, stored in a per-user fashion and associated with the ClientWindow.

The Flow Graph

Prior versions of the specification defined a flow graph but the only kind of node in the graph was a VDL view. The Faces Flow feature currently defines the following node types.

This UML diagram shows the relationship of the flow node types to the FlowHandler. Non-implemented classes are shaded in gray.

Since:
2.2

Constructor Summary
FlowHandler()
           
 
Method Summary
abstract  void addFlow(FacesContext context, Object definingDocument, Flow toAdd)
          

Add the argument Flow to the collection of Flows known to the current application.

abstract  Flow getCurrentFlow(FacesContext context)
          

Return the currently active Flow for the argument FacesContext, or null if no flow is active.

abstract  Map<Object,Object> getCurrentFlowScope()
          

Return the Map that backs the #{facesFlowScope} EL implicit object or null if no flow is currently active.

abstract  Flow getFlow(FacesContext context, Object definingDocument, String id)
          

Return the Flow whose id is equivalent to the argument id, within the scope of the argument definingDocument.

abstract  boolean isActive(FacesContext context, Object definingDocument, String id)
          

Return true if and only if the flow referenced by the argument definingDocument and id is currently active.

abstract  Flow transition(FacesContext context, UIComponent origin, UIComponent destination)
          

Perform a transition in the flow graph for the current user's ClientWindow.

 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FlowHandler

public FlowHandler()
Method Detail

getCurrentFlowScope

public abstract Map<Object,Object> getCurrentFlowScope()

Return the Map that backs the #{facesFlowScope} EL implicit object or null if no flow is currently active.

Since:
2.2

getFlow

public abstract Flow getFlow(FacesContext context,
                             Object definingDocument,
                             String id)

Return the Flow whose id is equivalent to the argument id, within the scope of the argument definingDocument.

Parameters:
definingDocument - An application unique identifier for the document in which the returned flow is defined.
id - the id of a Flow, unique within the scope of the definingDocument.
Throws:
NullPointerException - if any of the parameters are null
Since:
2.2

addFlow

public abstract void addFlow(FacesContext context,
                             Object definingDocument,
                             Flow toAdd)

Add the argument Flow to the collection of Flows known to the current application.

Parameters:
definingDocument - An application unique identifier for the document in which the argument flow is defined.
toAdd - the Flow to add.
Throws:
NullPointerException - if any of the parameters are null
IllegalStateException - if there is already a flow with the same id as the argument Flow within the scope of the definingDocument.
Since:
2.2

getCurrentFlow

public abstract Flow getCurrentFlow(FacesContext context)

Return the currently active Flow for the argument FacesContext, or null if no flow is active. A Flow must always be associated with exactly one ClientWindow, but a ClientWindow may have multiple Flows.

Parameters:
context - the FacesContext for the current request.
Since:
2.2

transition

public abstract Flow transition(FacesContext context,
                                UIComponent origin,
                                UIComponent destination)

Perform a transition in the flow graph for the current user's ClientWindow. Obtain references to the Flow instances corresponding to the origin and destination arguments. If the origin Flow is equal to the destination Flow, take no action and return null. If the destination Flow is a sub-flow of the origin Flow push the destination Flow onto the flow data structure and return the destination Flow. Otherwise, pop the current {code Flow} from the flow data structure. If the destination Flow is non-null, make the destination Flow the current flow, pushing it onto the data structure.

Since:
2.2

isActive

public abstract boolean isActive(FacesContext context,
                                 Object definingDocument,
                                 String id)

Return true if and only if the flow referenced by the argument definingDocument and id is currently active.

Parameters:
definingDocument - An application unique identifier for the document in which the returned flow is defined.
id - the id of a Flow, unique within the scope of the definingDocument.
Since:
2.2


Copyright 2002-2010 Oracle America Inc, Inc. All Rights Reserved.