public abstract class FlowHandler extends 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 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.
Edges in the graph are defined by the existing JSF navigation rule system.
Flows and Model Objects
Managed beans annotated with the CDI annotation
FlowScoped
must be instantiated upon 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
EL 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 String |
FLOW_ID_REQUEST_PARAM_NAME
Components that are rendered by |
static String |
NULL_FLOW
Components that are rendered by |
static 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 Map<Object,Object> |
getCurrentFlowScope()
Return the |
abstract Flow |
getFlow(FacesContext context,
String definingDocumentId,
String id)
Return the |
abstract String |
getLastDisplayedViewId(FacesContext context)
Return the last displayed viewId for the
current flow, as returned by |
abstract boolean |
isActive(FacesContext context,
String definingDocument,
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,
String toViewId)
Perform a transition in the flow
graph for the current user's |
public static final 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 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 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 Map<Object,Object> getCurrentFlowScope()
Return the Map
that backs
the #{flowScope}
EL implicit object or null
if no flow is currently active.
public abstract Flow getFlow(FacesContext context, String definingDocumentId, 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
.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.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
.IllegalArgumentException
- if the id
of the flow to
add is null
or the empty string.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.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)
.
public abstract 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.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.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.NullPointerException
- if context
is null
.public abstract void transition(FacesContext context, Flow sourceFlow, Flow targetFlow, FlowCallNode outboundCallNode, 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 of outboundCallNode
is non-null
and not empty, and the
inboundParameters
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)
.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.NullPointerException
- if context
is null
.public abstract boolean isActive(FacesContext context, String definingDocument, 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
.NullPointerException
- if any of the parameters are null
Copyright © 2017 JBoss by Red Hat. All rights reserved.