public abstract class FlowHandler
extends java.lang.Object
FlowHandler is the main entry
point that enables the runtime to interact with the faces flows
feature. NavigationHandler
uses this
class when it needs to make navigational decisions related to flows.
The faces flow feature entirely depends on the ClientWindow
feature and also on CDI.
Defining Flows
The implementation must support defining faces flows using the
<flow-definition>
element as specified in the
Application Configuration Resources XML Schema Definition, or by
using the FlowBuilder
API.
Additional means of defining flows may be provided by decorating the
FlowHandlerFactory
.
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 theClientWindow
. Because Flow instances are immutable, yet the flow stack is per-user, implementations must make allowance for flow scoped data (managed beans declared to beFlowScoped
and data stored in theMap
returned bygetCurrentFlowScope()
) to be fully re-entrant. For example, consider an application with two flows, A and B, each with a singleFlowScoped
beanMyBeanA
andMyBeanB
, respectively. Entry into flow A causesMyBeanA
to become active. Calling from A into B causesMyBeanB
to become active. Calling back into A causes a new instance ofMyBeanA
to become active, rather than reactivating the earlier instance ofMyBeanA
.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 Jakarta Server Faces VDL View that has been in the specification since the beginning.
Switch
This is a list of Jakarta Expression Language 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 totrue
, 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.
Edges in the graph are defined by the existing Jakarta Server Faces navigation rule system.
Flows and Model Objects
Managed beans annotated with the CDI annotation
FlowScoped
are created lazily, when referenced, after a user agent's entry into the named scope, and must be made available for garbage collection when the user agent leaves the flow.The
flowScope
Jakarta Expression Language implicit object is also available to store values in the "current" slope. Values stored in this scope must be made available for garbage collection when the user agent leaves the flow.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
FLOW_ID_REQUEST_PARAM_NAME
Components that are rendered by |
static java.lang.String |
NULL_FLOW
Components that are rendered by |
static java.lang.String |
TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME
Components that are rendered by |
Constructor and Description |
---|
FlowHandler() |
Modifier and Type | Method and Description |
---|---|
abstract void |
addFlow(FacesContext context,
Flow toAdd)
Add the argument |
abstract void |
clientWindowTransition(FacesContext context)
Allow for flow transitions in the
case of components rendered by the renderers from
component-family |
Flow |
getCurrentFlow()
Convenience overload that calls |
abstract Flow |
getCurrentFlow(FacesContext context)
Return the currently active |
abstract java.util.Map<java.lang.Object,java.lang.Object> |
getCurrentFlowScope()
Return the |
abstract Flow |
getFlow(FacesContext context,
java.lang.String definingDocumentId,
java.lang.String id)
Return the |
abstract java.lang.String |
getLastDisplayedViewId(FacesContext context)
Return the last displayed viewId for the
current flow, as returned by |
abstract boolean |
isActive(FacesContext context,
java.lang.String definingDocument,
java.lang.String id)
Return |
abstract void |
popReturnMode(FacesContext context)
Enable the correct handling of navigation when processing a return node. |
abstract void |
pushReturnMode(FacesContext context)
Enable the correct handling of navigation when processing a return node. |
abstract void |
transition(FacesContext context,
Flow sourceFlow,
Flow targetFlow,
FlowCallNode outboundCallNode,
java.lang.String toViewId)
Perform a transition in the flow
graph for the current user's |
public static final java.lang.String FLOW_ID_REQUEST_PARAM_NAME
Components that are rendered by Renderers
of component-family javax.faces.OutcomeTarget
must use this
constant as the parameter name for a parameter representing the flow id
of the flow that this component will cause to be entered.
public static final java.lang.String TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME
Components that are rendered by Renderers
of component-family javax.faces.OutcomeTarget
must use this
constant as the parameter name for a parameter representing the defining document id
of the flow that this component will cause to be entered.
public static final java.lang.String NULL_FLOW
Components that are rendered by Renderers
of component-family javax.faces.OutcomeTarget
must use this
constant as the value of the parameter named by TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME
when returning from a flow (without entering another flow) using such a component.
public abstract java.util.Map<java.lang.Object,java.lang.Object> getCurrentFlowScope()
Return the Map
that backs
the #{flowScope}
Jakarta Expression Language implicit object or null
if no flow is currently active.
Map
for this flow scope.public abstract Flow getFlow(FacesContext context, java.lang.String definingDocumentId, java.lang.String id)
Return the Flow
whose id
is equivalent to the argument id
, within the scope of
the argument definingDocument
.
context
- the FacesContext
for the current request.definingDocumentId
- 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
.Flow
for the argument identifiers.java.lang.NullPointerException
- if any of the parameters are null
public abstract void addFlow(FacesContext context, Flow toAdd)
Add the argument Flow
to the
collection of Flow
s known to the current
application. The implementation must be thread safe.
context
- the FacesContext
for the current request.toAdd
- the Flow
to add.java.lang.NullPointerException
- if any of the parameters are null
java.lang.IllegalStateException
- if there is already a flow with the
same id
as the argument Flow
within the scope of
the definingDocument
.java.lang.IllegalArgumentException
- if the id
of the flow to
add is null
or the empty string.java.lang.IllegalArgumentException
- if the definingDocumentId
of the toAdd
is null
.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.
If pushReturnMode(javax.faces.context.FacesContext)
had been called with true
as the
argument before invoking this method, return the preceding flow on
the stack instead of the actual current flow, or null
if there
is no preceding flow. Otherwise, return the current flow.
context
- the FacesContext
for the current request.Flow
or null
if no flow is activejava.lang.NullPointerException
- if any of the parameters are null
public Flow getCurrentFlow()
Convenience overload that calls FacesContext.getCurrentInstance()
and then calls through to getCurrentFlow(javax.faces.context.FacesContext)
.
Flow
or null
if no flow is activepublic abstract java.lang.String getLastDisplayedViewId(FacesContext context)
Return the last displayed viewId for the
current flow, as returned by getCurrentFlow(javax.faces.context.FacesContext)
,
or null
if there is no current flow.
context
- the FacesContext
for the current request.java.lang.NullPointerException
- if context
is null
public abstract void pushReturnMode(FacesContext context)
Enable the correct handling of navigation
when processing a return node. The default NavigationHandler
specification requires calling this method before processing
the navigation rules for the flow return, and calling popReturnMode(javax.faces.context.FacesContext)
,
from a finally
block, immediately afterward.
context
- the FacesContext
for the current request.java.lang.NullPointerException
- if context
is null
.public abstract void popReturnMode(FacesContext context)
Enable the correct handling of navigation
when processing a return node. The default NavigationHandler
specification requires calling this method from a finally
block,
immediately attempting to process the navigation rules in the context
of a flow return.
context
- the FacesContext
for the current request.java.lang.NullPointerException
- if context
is null
.public abstract void transition(FacesContext context, Flow sourceFlow, Flow targetFlow, FlowCallNode outboundCallNode, java.lang.String toViewId)
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
. Otherwise, if the outboundCallNode
argument is non-null
save aside the outbound parameters.
For discussion evaluatedParams is a data
structure that stores the evaluated values of any outbound
parameters. It is necessary to evaluate these values before
popping any flow scopes because the values may refer to scoped
instances that need to be passed to the target flow, but will not
be available once the new scope is activated. Save aside the
outbound parameters using the following algorithm.
If the
outboundParameters
property ofoutboundCallNode
is non-null
and not empty, and theinboundParameters
property of the target flow is non-null
and not empty, for each entry in the outbound parameters whose name matches an entry in the inbound parameters, evaluate the value of the parameter, and put the evaluated value into evaluatedParams under the corresponding name. Otherwise, consider evaluatedParams to be empty.
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 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. If evaluatedParams is not empty, for
each entry, find the corresponding parameter in the target flow's
inbound parameters and call its setValue
method, passing
the value from evaluatedParams.
context
- the FacesContext
for the current request.sourceFlow
- the current Flow
, or null
if
there is no source flow.targetFlow
- the destination Flow
, or null
if there is no destination flow.outboundCallNode
- the flow call node causing this
transition, or null
if this transition is not caused by a
flow call.toViewId
- the viewId of the view being displayed as a result of
this transition. This parameter makes it possible to implement getLastDisplayedViewId(javax.faces.context.FacesContext)
.java.lang.NullPointerException
- if context
or toViewId
is null
.public abstract void clientWindowTransition(FacesContext context)
Allow for flow transitions in the
case of components rendered by the renderers from
component-family javax.faces.OutcomeTarget
. These
transitions must happen at the front of the request processing
lifecycle due to the HTTP GET based nature of such components.
Therefore, this method is called from the restore view phase of
the lifecycle.
Let flowId be the value in the request parameter map
for the parameter whose name is given by the value of FLOW_ID_REQUEST_PARAM_NAME
. Let toFlowDocumentId be
the value in the request parameter map for the paramater whose
name is given by the value of TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME
. If
toFlowDocumentId is null
, take no action
and return. Otherwise, let sourceFlow be the return
from getCurrentFlow(javax.faces.context.FacesContext)
. A
null
value indicates there is no current flow, which
will be the case if this navigation is trying to enter a flow. If
flowId is not null
and
toFlowDocumentId is not equal to the
value of NULL_FLOW
, let targetFlow be the
result of calling getFlow(javax.faces.context.FacesContext, java.lang.String,
java.lang.String)
, passing toFlowDocumentId and
flowId as the last two arguments, respectively. If the
result is non-null
, let flowCallNode be the
return from calling Flow.getFlowCall(javax.faces.flow.Flow)
on the
sourceFlow, passing targetFlow as the argument.
Otherwise, targetFlow and flowCallNode must
remain null
, indicating that this is a flow
return. Call FacesContext.getViewRoot()
and let toViewId
be the the return from calling UIViewRoot.getViewId()
on it.
Call, transition(javax.faces.context.FacesContext, javax.faces.flow.Flow, javax.faces.flow.Flow, javax.faces.flow.FlowCallNode, java.lang.String)
, passing the arguments gathered in
the preceding algorithm.
context
- the FacesContext
for the current request.java.lang.NullPointerException
- if context
is null
.public abstract boolean isActive(FacesContext context, java.lang.String definingDocument, java.lang.String id)
Return true
if and only if
the flow referenced by the argument definingDocument
and
id
is currently active.
context
- the FacesContext
for the current request.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
.java.lang.NullPointerException
- if any of the parameters are null