javax.faces.flow

## Class FlowHandler

- java.lang.Object
- - 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. `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.

  Since:
    2.2

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static 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.
    `static 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.
    `static 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.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FlowHandler()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `addFlow(FacesContext context, Flow toAdd)` Add the argument `Flow` to the collection of `Flow`s known to the current application.
    `abstract void` | `clientWindowTransition(FacesContext context)` Allow for flow transitions in the case of components rendered by the renderers from component-family `javax.faces.OutcomeTarget`.
    `Flow` | `getCurrentFlow()` Convenience overload that calls `FacesContext.getCurrentInstance()` and then calls through to `getCurrentFlow(javax.faces.context.FacesContext)`.
    `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 `#{flowScope}` EL implicit object or `null` if no flow is currently active.
    `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`.
    `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.
    `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.
    `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 `ClientWindow`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### FLOW_ID_REQUEST_PARAM_NAME

          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.

      Since:
        2.2
      See Also:
        Constant Field Values

    - #### TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME

          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.

      Since:
        2.2
      See Also:
        Constant Field Values

    - #### NULL_FLOW

          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.

      Since:
        2.2
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### FlowHandler

          public FlowHandler()

  - ### Method Detail

    - #### getCurrentFlowScope

          public abstract Map<Object,Object> getCurrentFlowScope()

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

      Since:
        2.2

    - #### getFlow

          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` - 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`.
      Throws:
        `NullPointerException` - if any of the parameters are `null`
      Since:
        2.2

    - #### addFlow

          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` - the `FacesContext` for the current request.
        `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`.
        `IllegalArgumentException` - if the `id` of the flow to add is `null` or the empty string.
        `IllegalArgumentException` - if the `definingDocumentId` of the `toAdd` is `null`.
      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 `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.

      Parameters:
        `context` - the `FacesContext` for the current request.
      Throws:
        `NullPointerException` - if any of the parameters are `null`
      Since:
        2.2

    - #### getCurrentFlow

          public Flow getCurrentFlow()

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

      Since:
        2.2

    - #### getLastDisplayedViewId

          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.

      Parameters:
        `context` - the `FacesContext` for the current request.
      Throws:
        `NullPointerException` - if `context` is `null`
      Since:
        2.2

    - #### pushReturnMode

          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.

      Parameters:
        `context` - the `FacesContext` for the current request.
      Throws:
        `NullPointerException` - if `context` is `null`.
      Since:
        2.2

    - #### popReturnMode

          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.

      Parameters:
        `context` - the `FacesContext` for the current request.
      Throws:
        `NullPointerException` - if `context` is `null`.
      Since:
        2.2

    - #### transition

          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.

      Parameters:
        `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)`.
      Throws:
        `NullPointerException` - if `context` or `toViewId` is `null`.
      Since:
        2.2

    - #### clientWindowTransition

          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.

      Parameters:
        `context` - the `FacesContext` for the current request.
      Throws:
        `NullPointerException` - if `context` is `null`.
      Since:
        2.2

    - #### isActive

          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` - 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`.
      Throws:
        `NullPointerException` - if any of the parameters are `null`
      Since:
        2.2

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.