All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.faces.flow.FlowHandler Maven / Gradle / Ivy

Go to download

This is the master POM file for Sun's Implementation of the JSF 2.1 Specification.

There is a newer version: 2.2.20
Show newest version
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 * 
 * Copyright (c) 1997-2012 Oracle and/or its affiliates. All rights reserved.
 * 
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 * 
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 * 
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 * 
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 * 
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.

 */
package javax.faces.flow;

import java.util.Map;
import javax.faces.context.FacesContext;

/**
 * 

FlowHandler is the main * entry point that enables the runtime to interact with the faces flows * feature. {@link * javax.faces.application.NavigationHandler} uses this * class when it needs to make navigational decisions related to flows. * The faces flow feature entirely depends on the {@link * javax.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 * {@link javax.faces.flow.builder.FlowBuilder} API. Additional means * of defining flows may be provided by decorating the {@link * 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 {@link javax.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 {@code 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 {@code true} is used to define the id of the next * node to which control must be passed. If none of the expressions * evaluates to {@code 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 * {@link 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 */ public abstract class FlowHandler { /** *

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 */ public static final String FLOW_ID_REQUEST_PARAM_NAME = "jffi"; /** *

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 */ public static final String TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME = "jftfdi"; /** *

Components that are rendered by Renderers * of component-family javax.faces.OutcomeTarget must use this * constant as the value of the parameter named by {@link #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 = "javax.faces.flow.NullFlow"; /** *

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

* * @since 2.2 */ public abstract Map getCurrentFlowScope(); /** *

Return the {@link Flow} whose {@code * id} is equivalent to the argument {@code id}, within the scope of * the argument {@code definingDocument}.

* @param context the {@code FacesContext} for the current request. * @param definingDocumentId An application unique identifier * for the document in which the returned flow is defined. * @param id the id of a {@link Flow}, unique within the * scope of the {@code definingDocument}. * @throws NullPointerException if any of the parameters are {@code null} * * @since 2.2 */ public abstract Flow getFlow(FacesContext context, String definingDocumentId, String id); /** *

Add the argument {@link Flow} to the * collection of {@code Flow}s known to the current * application. The implementation must be thread safe.

* @param context the {@code FacesContext} for the current request. * @param toAdd the {@code Flow} to add. * @throws NullPointerException if any of the parameters are {@code null} * * @throws IllegalStateException if there is already a flow with the * same {@code id} as the argument {@code Flow} within the scope of * the {@code definingDocument}. * @throws IllegalArgumentException if the {@code id} of the flow to * add is {@code null} or the empty string. * @throws IllegalArgumentException if the {@code * definingDocumentId} of the {@code toAdd} is {@code null}. * @since 2.2 */ public abstract void addFlow(FacesContext context, Flow toAdd); /** *

Return the currently active {@link * Flow} for the argument {@code FacesContext}, or {@code null} if * no flow is active. A {@code Flow} must always be associated with * exactly one {@link javax.faces.lifecycle.ClientWindow}, but a * {@code ClientWindow} may have multiple {@code Flow}s.

* *
* *

If {@link #pushReturnMode} had been called with {@code true} as the * argument before invoking this method, return the preceding flow on * the stack instead of the actual current flow, or {@code null} if there * is no preceding flow. Otherwise, return the current flow.

* *
* * @param context the {@code FacesContext} for the current request. * * @throws NullPointerException if any of the parameters are {@code null} * * @since 2.2 */ public abstract Flow getCurrentFlow(FacesContext context); /** *

Convenience overload that calls {@link FacesContext#getCurrentInstance()} * and then calls through to {@link #getCurrentFlow(javax.faces.context.FacesContext)}.

* * @since 2.2 */ public Flow getCurrentFlow() { return getCurrentFlow(FacesContext.getCurrentInstance()); } /** *

Return the last displayed viewId for the * current flow, as returned by {@link #getCurrentFlow(javax.faces.context.FacesContext)}, * or {@code null} if there is no current flow.

* * @param context the {@code FacesContext} for the current request. * * @throws NullPointerException if {@code context} is {@code null} * * @since 2.2 */ public abstract String getLastDisplayedViewId(FacesContext context); /** *

Enable the correct handling of navigation * when processing a return node. The default {@link javax.faces.application.NavigationHandler} * specification requires calling this method before processing * the navigation rules for the flow return, and calling {@link #popReturnMode}, * from a {@code finally} block, immediately afterward.

* * @param context the {@code FacesContext} for the current request. * @throws NullPointerException if {@code context} is {@code null}. * * @since 2.2 */ public abstract void pushReturnMode(FacesContext context); /** *

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

* * @param context the {@code FacesContext} for the current request. * @throws NullPointerException if {@code context} is {@code null}. * * @since 2.2 */ public abstract void popReturnMode(FacesContext context); /** *

Perform a transition in the flow * graph for the current user's {@link * javax.faces.lifecycle.ClientWindow}. Obtain references to the * {@code Flow} instances corresponding to the {@code origin} and * {@code destination} arguments. If the {@code origin Flow} is * equal to the {@code destination Flow}, take no action and return * {@code null}. Otherwise, if the {@code outboundCallNode} * argument is non-{@code 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 {@code outboundParameters} property of {@code * outboundCallNode} is non-{@code null} and not empty, and the * {@code inboundParameters} property of the target flow is * non-{@code 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 {@code destination Flow} is a sub-flow of the {@code * origin Flow} push the {@code destination Flow} onto the flow data * structure and return {@code the destination Flow}. Otherwise, pop * the current {@code Flow} from the flow data structure. If the * {@code destination Flow} is non-{@code null}, make the {@code * 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 {@code setValue} method, passing * the value from evaluatedParams.

* *
* * @param context the {@code FacesContext} for the current request. * @param sourceFlow the current {@code Flow}, or {@code null} if * there is no source flow. * * @param targetFlow the destination {@code Flow}, or {@code null} * if there is no destination flow. * * @param outboundCallNode the flow call node causing this * transition, or {@code null} if this transition is not caused by a * flow call. * * @param toViewId the viewId of the view being displayed as a result of * this transition. This parameter makes it possible to implement {@link #getLastDisplayedViewId}. * * @throws NullPointerException if {@code context} or {@code toViewId} is {@code null}. * * @since 2.2 */ public abstract void transition(FacesContext context, Flow sourceFlow, Flow targetFlow, FlowCallNode outboundCallNode, String toViewId); /** *

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 {@link * #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 {@link * #TO_FLOW_DOCUMENT_ID_REQUEST_PARAM_NAME}. If * toFlowDocumentId is null, take no action * and return. Otherwise, let sourceFlow be the return * from {@link #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 {@link #NULL_FLOW}, let targetFlow be the * result of calling {@link * #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 {@link 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 {@link FacesContext#getViewRoot()} and let toViewId * be the the return from calling {@link javax.faces.component.UIViewRoot#getViewId} * on it.

*

Call, {@link #transition}, passing the arguments gathered in * the preceding algorithm.

* *
* @since 2.2 * * @param context the {@code FacesContext} for the current request. * @throws NullPointerException if {@code context} is {@code null}. */ public abstract void clientWindowTransition(FacesContext context); /** *

Return {@code true} if and only if * the flow referenced by the argument {@code definingDocument} and * {@code id} is currently active.

* @param context the {@code FacesContext} for the current request. * @param definingDocument An application unique identifier * for the document in which the returned flow is defined. * @param id the id of a {@link Flow}, unique within the * scope of the {@code definingDocument}. * @throws NullPointerException if any of the parameters are {@code null} * * @since 2.2 */ public abstract boolean isActive(FacesContext context, String definingDocument, String id); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy