EE4J Web API 10.0.0 · jakarta.faces.flow.FlowHandler

FlowHandler is the main entry point that enables the runtime to interact with the faces flows feature. jakarta.faces.application.NavigationHandler uses this class when it needs to make navigational decisions related to flows. The faces flow feature entirely depends on the jakarta.faces.lifecycle.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 jakarta.faces.flow.builder.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 jakarta.faces.lifecycle.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. Because Flow instances are immutable, yet the flow stack is per-user, implementations must make allowance for flow scoped data (managed beans declared to be FlowScoped and data stored in the Map returned by getCurrentFlowScope) to be fully re-entrant. For example, consider an application with two flows, A and B, each with a single FlowScoped bean MyBeanA and MyBeanB, respectively. Entry into flow A causes MyBeanA to become active. Calling from A into B causes MyBeanB to become active. Calling back into A causes a new instance of MyBeanA to become active, rather than reactivating the earlier instance of MyBeanA.

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

Field Summary

Modifier and Type	Field and Description
public static final String	FLOW_ID_REQUEST_PARAM_NAME Components that are rendered by `Renderers` of component-family `jakarta.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	NULL_FLOW Components that are rendered by `Renderers` of component-family `jakarta.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 static final String	TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME Components that are rendered by `Renderers` of component-family `jakarta.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.

Constructor Summary

Access	Constructor and Description
public	FlowHandler()

Method Summary

Modifier and Type	Method and Description
public abstract void	addFlow(FacesContext the `FacesContext` for the current request. context, Flow the `Flow` to add. toAdd) Add the argument `Flow` to the collection of `Flow`s known to the current application.
public abstract void	clientWindowTransition(FacesContext the `FacesContext` for the current request. context) Allow for flow transitions in the case of components rendered by the renderers from component-family `jakarta.faces.OutcomeTarget`.
public abstract Flow	Returns: the current `Flow` or `null` if no flow is active getCurrentFlow(FacesContext the `FacesContext` for the current request. context) Return the currently active `Flow` for the argument `FacesContext`, or `null` if no flow is active.
public Flow	Returns: the current `Flow` or `null` if no flow is active getCurrentFlow() Convenience overload that calls `FacesContext#getCurrentInstance()` and then calls through to `getCurrentFlow(jakarta.faces.context.FacesContext)`.
public abstract Map<Object, Object>	Returns: the `Map` for this flow scope. getCurrentFlowScope() Return the `Map` that backs the `#{flowScope}` Jakarta Expression Language implicit object or `null` if no flow is currently active.
public abstract Flow	Returns: the `Flow` for the argument identifiers. getFlow(FacesContext the `FacesContext` for the current request. context, String An application unique identifier for the document in which the returned flow is defined. definingDocumentId, String the id of a `Flow`, unique within the scope of the `definingDocument`. id) Return the `Flow` whose `id` is equivalent to the argument `id`, within the scope of the argument `definingDocument`.
public abstract String	Returns: the last displayed viewId. getLastDisplayedViewId(FacesContext the `FacesContext` for the current request. context) Return the last displayed viewId for the current flow, as returned by `getCurrentFlow(jakarta.faces.context.FacesContext)`, or `null` if there is no current flow.
public abstract boolean	Returns: true if and only if the referenced flow is active isActive(FacesContext the `FacesContext` for the current request. context, String An application unique identifier for the document in which the returned flow is defined. definingDocument, String the id of a `Flow`, unique within the scope of the `definingDocument`. id) Return `true` if and only if the flow referenced by the argument `definingDocument` and `id` is currently active.
public abstract void	popReturnMode(FacesContext the `FacesContext` for the current request. context) Enable the correct handling of navigation when processing a return node.
public abstract void	pushReturnMode(FacesContext the `FacesContext` for the current request. context) Enable the correct handling of navigation when processing a return node.
public abstract void	transition(FacesContext the `FacesContext` for the current request. context, Flow the current `Flow`, or `null` if there is no source flow. sourceFlow, Flow the destination `Flow`, or `null` if there is no destination flow. targetFlow, FlowCallNode the flow call node causing this transition, or `null` if this transition is not caused by a flow call. outboundCallNode, String the viewId of the view being displayed as a result of this transition. This parameter makes it possible to implement `getLastDisplayedViewId`. toViewId) Perform a transition in the flow graph for the current user's `jakarta.faces.lifecycle.ClientWindow`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

FLOW_ID_REQUEST_PARAM_NAME back to summary

FLOW_ID_REQUEST_PARAM_NAME	back to summary
public static final String FLOW_ID_REQUEST_PARAM_NAME Components that are rendered by `Renderers` of component-family `jakarta.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. Since 2.2

public static final String FLOW_ID_REQUEST_PARAM_NAME

Components that are rendered by Renderers of component-family jakarta.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.

Since: 2.2

NULL_FLOW back to summary

NULL_FLOW	back to summary
public static final String NULL_FLOW Components that are rendered by `Renderers` of component-family `jakarta.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. Since 2.2

public static final String NULL_FLOW

Components that are rendered by Renderers of component-family jakarta.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.

Since: 2.2

TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME back to summary

TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME	back to summary
public static final String TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME Components that are rendered by `Renderers` of component-family `jakarta.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. Since 2.2

public static final String TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME

Components that are rendered by Renderers of component-family jakarta.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.

Since: 2.2

Constructor Detail

FlowHandler	back to summary
public FlowHandler()

Method Detail

addFlow back to summary

addFlow	back to summary
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. Parameters context:FacesContext the `FacesContext` for the current request. toAdd:Flow the `Flow` to add. Exceptions 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. if the `definingDocumentId` of the `toAdd` is `null`. Since 2.2

public abstract void addFlow(FacesContext context, Flow toAdd)

Add the argument Flow to the collection of Flows known to the current application. The implementation must be thread safe.

Parameters

context:FacesContext: the FacesContext for the current request.
toAdd:Flow: the Flow to add.

Exceptions

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.
if the definingDocumentId of the toAdd is null.

Since

2.2

clientWindowTransition back to summary

clientWindowTransition	back to summary
public abstract void clientWindowTransition(FacesContext context) Allow for flow transitions in the case of components rendered by the renderers from component-family `jakarta.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(jakarta.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(jakarta.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` 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 `jakarta.faces.component.UIViewRoot#getViewId` on it. Call, `transition`, passing the arguments gathered in the preceding algorithm. Parameters context:FacesContext the `FacesContext` for the current request. Exceptions NullPointerException: if `context` is `null`. Since 2.2

public abstract void clientWindowTransition(FacesContext context)

Allow for flow transitions in the case of components rendered by the renderers from component-family jakarta.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(jakarta.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(jakarta.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 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 jakarta.faces.component.UIViewRoot#getViewId on it.

Call, transition, passing the arguments gathered in the preceding algorithm.

Parameters

context:FacesContext: the FacesContext for the current request.

Exceptions

NullPointerException:: if context is null.

Since

2.2

getCurrentFlow back to summary

getCurrentFlow	back to summary
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 `jakarta.faces.lifecycle.ClientWindow`, but a `ClientWindow` may have multiple `Flow`s. If `pushReturnMode` 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. Parameters context:FacesContext the `FacesContext` for the current request. Returns:Flow the current `Flow` or `null` if no flow is active Exceptions NullPointerException: if any of the parameters are `null` Since 2.2

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 jakarta.faces.lifecycle.ClientWindow, but a ClientWindow may have multiple Flows.

If pushReturnMode 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.

Parameters

context:FacesContext: the FacesContext for the current request.

Returns:Flow

the current Flow or null if no flow is active

Exceptions

NullPointerException:: if any of the parameters are null

Since

2.2

getCurrentFlow back to summary

getCurrentFlow	back to summary
public Flow getCurrentFlow() Convenience overload that calls `FacesContext#getCurrentInstance()` and then calls through to `getCurrentFlow(jakarta.faces.context.FacesContext)`. Returns:Flow the current `Flow` or `null` if no flow is active Since 2.2

public Flow getCurrentFlow()

Convenience overload that calls FacesContext#getCurrentInstance() and then calls through to getCurrentFlow(jakarta.faces.context.FacesContext).

Returns:Flow: the current Flow or null if no flow is active
Since: 2.2

getCurrentFlowScope back to summary

getCurrentFlowScope	back to summary
public abstract Map<Object, Object> getCurrentFlowScope() Return the `Map` that backs the `#{flowScope}` Jakarta Expression Language implicit object or `null` if no flow is currently active. Returns:Map<Object, Object> the `Map` for this flow scope. Since 2.2

public abstract Map<Object, Object> getCurrentFlowScope()

Return the Map that backs the #{flowScope} Jakarta Expression Language implicit object or null if no flow is currently active.

Returns:Map<Object, Object>: the Map for this flow scope.
Since: 2.2

getFlow back to summary

getFlow	back to summary
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`. Parameters context:FacesContext the `FacesContext` for the current request. definingDocumentId:String An application unique identifier for the document in which the returned flow is defined. id:String the id of a `Flow`, unique within the scope of the `definingDocument`. Returns:Flow the `Flow` for the argument identifiers. Exceptions NullPointerException: if any of the parameters are `null` Since 2.2

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.

Parameters

context:FacesContext: the FacesContext for the current request.
definingDocumentId:String: An application unique identifier for the document in which the returned flow is defined.
id:String: the id of a Flow, unique within the scope of the definingDocument.

Returns:Flow

the Flow for the argument identifiers.

Exceptions

NullPointerException:: if any of the parameters are null

Since

2.2

getLastDisplayedViewId back to summary

getLastDisplayedViewId	back to summary
public abstract String getLastDisplayedViewId(FacesContext context) Return the last displayed viewId for the current flow, as returned by `getCurrentFlow(jakarta.faces.context.FacesContext)`, or `null` if there is no current flow. Parameters context:FacesContext the `FacesContext` for the current request. Returns:String the last displayed viewId. Exceptions NullPointerException: if `context` is `null` Since 2.2

public abstract String getLastDisplayedViewId(FacesContext context)

Return the last displayed viewId for the current flow, as returned by getCurrentFlow(jakarta.faces.context.FacesContext), or null if there is no current flow.

Parameters

context:FacesContext: the FacesContext for the current request.

Returns:String

the last displayed viewId.

Exceptions

NullPointerException:: if context is null

Since

2.2

isActive back to summary

isActive	back to summary
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. Parameters context:FacesContext the `FacesContext` for the current request. definingDocument:String An application unique identifier for the document in which the returned flow is defined. id:String the id of a `Flow`, unique within the scope of the `definingDocument`. Returns:boolean true if and only if the referenced flow is active Exceptions NullPointerException: if any of the parameters are `null` Since 2.2

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.

Parameters

context:FacesContext: the FacesContext for the current request.
definingDocument:String: An application unique identifier for the document in which the returned flow is defined.
id:String: the id of a Flow, unique within the scope of the definingDocument.

Returns:boolean

true if and only if the referenced flow is active

Exceptions

NullPointerException:: if any of the parameters are null

Since

2.2

popReturnMode back to summary

popReturnMode	back to summary
public abstract void popReturnMode(FacesContext context) Enable the correct handling of navigation when processing a return node. The default `jakarta.faces.application.NavigationHandler` specification requires calling this method from a `finally` block, immediately attempting to process the navigation rules in the context of a flow return. Parameters context:FacesContext the `FacesContext` for the current request. Exceptions NullPointerException: if `context` is `null`. Since 2.2

public abstract void popReturnMode(FacesContext context)

Enable the correct handling of navigation when processing a return node. The default jakarta.faces.application.NavigationHandler specification requires calling this method from a finally block, immediately attempting to process the navigation rules in the context of a flow return.

Parameters

context:FacesContext: the FacesContext for the current request.

Exceptions

NullPointerException:: if context is null.

Since

2.2

pushReturnMode back to summary

pushReturnMode	back to summary
public abstract void pushReturnMode(FacesContext context) Enable the correct handling of navigation when processing a return node. The default `jakarta.faces.application.NavigationHandler` specification requires calling this method before processing the navigation rules for the flow return, and calling `popReturnMode`, from a `finally` block, immediately afterward. Parameters context:FacesContext the `FacesContext` for the current request. Exceptions NullPointerException: if `context` is `null`. Since 2.2

public abstract void pushReturnMode(FacesContext context)

Enable the correct handling of navigation when processing a return node. The default jakarta.faces.application.NavigationHandler specification requires calling this method before processing the navigation rules for the flow return, and calling popReturnMode, from a finally block, immediately afterward.

Parameters

context:FacesContext: the FacesContext for the current request.

Exceptions

NullPointerException:: if context is null.

Since

2.2

transition back to summary

transition	back to summary
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 `jakarta.faces.lifecycle.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. Parameters context:FacesContext the `FacesContext` for the current request. sourceFlow:Flow the current `Flow`, or `null` if there is no source flow. targetFlow:Flow the destination `Flow`, or `null` if there is no destination flow. outboundCallNode:FlowCallNode the flow call node causing this transition, or `null` if this transition is not caused by a flow call. toViewId:String the viewId of the view being displayed as a result of this transition. This parameter makes it possible to implement `getLastDisplayedViewId`. Exceptions NullPointerException: if `context` or `toViewId` is `null`. Since 2.2

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 jakarta.faces.lifecycle.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.

Parameters

context:FacesContext: the FacesContext for the current request.
sourceFlow:Flow: the current Flow, or null if there is no source flow.
targetFlow:Flow: the destination Flow, or null if there is no destination flow.
outboundCallNode:FlowCallNode: the flow call node causing this transition, or null if this transition is not caused by a flow call.
toViewId:String: the viewId of the view being displayed as a result of this transition. This parameter makes it possible to implement getLastDisplayedViewId.

Exceptions

NullPointerException:: if context or toViewId is null.

Since

2.2

public abstract Class FlowHandler

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail