|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.faces.flow.FlowHandler
public abstract class FlowHandler
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.
VDL files accessible to the application.
The Application Configuration Resources.
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.
View
This is the regular JSF VDL View that has been in the specification since the beginning.
Switch
This is a list of EL expressions. When control is passed to a
switch node, each expression in the list is evaluated and the first
one that returns true
is used to define the id of the next
node to which control must be passed. If none of the expressions
evaluates to true
, control passes to the specified default
id.
Return
This node type specifies an outcome that is returned to the calling flow.
Method Call
This node type allows invocation of arbitrary application logic at any point in the executiong of the flow. An outcome can be specified that will cause a navigation case to be navigated to after the method has been invoked.
Faces Flow Call
This node type allows one flow to call another flow. The calling flow remains active and is not exited until control returns from the called flow.
This UML diagram shows the relationship of the flow node types to
the FlowHandler
. Non-implemented classes are shaded in
gray.
Constructor Summary | |
---|---|
FlowHandler()
|
Method Summary | |
---|---|
abstract void |
addFlow(FacesContext context,
Object definingDocument,
Flow toAdd)
Add the argument |
abstract Flow |
getCurrentFlow(FacesContext context)
Return the currently active |
abstract Map<Object,Object> |
getCurrentFlowScope()
Return the |
abstract Flow |
getFlow(FacesContext context,
Object definingDocument,
String id)
Return the |
abstract boolean |
isActive(FacesContext context,
Object definingDocument,
String id)
Return |
abstract Flow |
transition(FacesContext context,
UIComponent origin,
UIComponent destination)
Perform a transition in the flow
graph for the current user's |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public FlowHandler()
Method Detail |
---|
public abstract Map<Object,Object> getCurrentFlowScope()
Return the Map
that backs
the #{facesFlowScope}
EL implicit object or null
if no flow is currently active.
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
.
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
.
NullPointerException
- if any of the parameters are null
public abstract void addFlow(FacesContext context, Object definingDocument, Flow toAdd)
Add the argument Flow
to the
collection of Flow
s known to the current
application.
definingDocument
- An application unique identifier
for the document in which the argument flow is defined.toAdd
- the Flow
to add.
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
.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 Flow
s.
context
- the FacesContext
for the current request.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.
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.
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
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |