FlowInfo

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.myfaces.orchestra.flow;

import java.util.Map;

import javax.faces.component.UIViewRoot;

import org.apache.myfaces.orchestra.flow.config.FlowAccept;
import org.apache.myfaces.orchestra.flow.config.FlowCall;

/**
 * Holds information about a specific call to a specific flow.
 * <p>
 * A new instance of this type is created for each call to a flow,
 * and is stored in the ConversationContext created for that flow.
 */
public class FlowInfo
{
    public static final int STATE_ACTIVE = 1;
    public static final int STATE_COMMITTED = 2;
    public static final int STATE_CANCELLED = 3;

    private int state = STATE_ACTIVE;
    private boolean isModalFlow;

    // caller info
    private String callerOutcome;
    private String callerViewId;
    private UIViewRoot callerViewRoot;
    private FlowCall flowCall;

    // values being passed from caller to callee
    private Map<String,Object> argsIn;

    // values being returned from callee to caller
    private Map<String,Object> argsOut;

    // Javascript to render when closing a flow that was run as
    // a modal dialog.
    private String onExitScript;

    // callee info
    private String flowViewId;
    private String flowPath;
    private FlowAccept flowAccept;

    /**
     * Constructor.
     * <p>
     * This creates just a partially-initialised FlowInfo object, as it defines only
     * information about the caller. It is expected that very soon after this is
     * created a call to setAcceptInfo will be made to add information about the
     * called flow.
     *
     * @param callerViewId contains the viewId of the view that started the call. This
     * value must not be null.
     *
     * @param callerViewRoot contains the view tree for the view that started the call.
     * This is optional; when not null then this view state will be restored on return
     * from the flow. In particular, this allows data entered by the user into input
     * components to be restored when the flow returns (assumes that the flow call is
     * triggered by an immediate command component). When this is null, then on return
     * to the caller a new view tree will be created. The viewRoot should normally not
     * be saved (this avoids wasting memory). It does need to be saved, however, when
     * the component triggering the flow has immediate=true and the caller wants
     * incomplete data to be preserved on return. It may also need to be preserved in
     * certain scenarios such as when code stores stateful data into the view tree (eg
     * when the t:saveState tag is used or when JSF2.0 view-scope beans are used).
     *
     * @param flowCall is the configuration object that describes the caller of a flow.
     *
     * @param argsIn is the set of parameter values being passed to the called flow. See
     * FlowCall.readSendParams().
     */
    public FlowInfo(
            String callerOutcome,
            String callerViewId,
            UIViewRoot callerViewRoot,
            FlowCall flowCall,
            Map<String, Object> argsIn)
    {
        this.callerOutcome = callerOutcome;
        this.callerViewId = callerViewId;
        this.callerViewRoot = callerViewRoot;
        this.flowCall = flowCall;
        this.argsIn = argsIn;

        // TODO: save the serialized view tree, not just a ref to the viewroot
        // TODO: determine whether to save the view tree or not (see comments on callerViewRoot property)
    }

    /**
     * Return the outcome string that triggered this flowcall.
     */
    public String getCallerOutcome()
    {
        return callerOutcome;
    }

    /**
     * Return the viewId of the page that initiated the call to a flow (never null).
     */
    public String getCallerViewId()
    {
        return callerViewId;
    }

    /**
     * Return the view root of the page that initiated the call to a flow (optional,
     * may be null).
     */
    public UIViewRoot getCallerViewRoot()
    {
        return callerViewRoot;
    }

    /**
     * Return metadata about the caller of the flow.
     */
    public FlowCall getFlowCall()
    {
        return flowCall;
    }

    /**
     * Get the (name,value) parameters that the caller is passing to the
     * called flow.
     * <p>
     * These objects are then "accepted" into the called flow when the flow
     * first starts. These objects are also used if the flow performs a
     * "restart"; note however that if any of these objects are mutable then
     * on restart the modified versions are passed to the called flow.
     */
    public Map<String,Object> getArgsIn()
    {
        return argsIn;
    }

    /**
     * Get the (name,value) parameters that the caller is returning to the
     * called flow.
     * <p>
     * These objects are then "accepted" into the calling flow when the
     * caller's view is restored. The return value is null until the
     * flow has committed.
     */
    public Map<String, Object> getArgsOut()
    {
        return argsOut;
    }

    /** Set to true to specify that the flow this object represents is "modal". */
    public void setModalFlow(boolean state)
    {
        this.isModalFlow = state;
    }

    /**
     * Returns true when this flow represents a modal flow.
     */
    public boolean isModalFlow()
    {
        return isModalFlow;
    }

    /**
     * Finish initialising this object by adding information about the called flow.
     * <p>
     * It is assumed that the FlowAccept has been checked for compatibility against
     * the FlowCall object.
     * <p>
     * @param entryViewId
     * @param flowPath
     * @param flowAccept
     */
    public void setAcceptInfo(String flowViewId, String flowPath, FlowAccept flowAccept)
    {
        this.flowViewId = flowViewId;
        this.flowPath = flowPath;
        this.flowAccept = flowAccept;
    }

    /**
     * Return the viewId of the entry page of the flow.
     */
    public String getFlowViewId()
    {
        return flowViewId;
    }

    /**
     * Return the path prefix which is expected to be present on the viewId of every
     * page that "belongs" to this flow.
     * <p>
     * A viewId which does not start with the flowPath is not part of the current flow,
     * and so immediately triggers cancellation of the flow.
     */
    public String getFlowPath()
    {
        return flowPath;
    }

    /**
     * Return metadata about the called flow.
     */
    public FlowAccept getFlowAccept()
    {
        return flowAccept;
    }

    public String getOnExitScript()
    {
        return onExitScript;
    }

    public void setOnExitScript(String script)
    {
        onExitScript = script;
    }


    public int getState()
    {
        return state;
    }

    public void commit(Map<String, Object> argsOut)
    {
        this.argsOut = argsOut;
        state = STATE_COMMITTED;
    }

    public void cancel()
    {
        state = STATE_CANCELLED;
    }

    public boolean isComplete()
    {
        return (state == STATE_CANCELLED || state == STATE_COMMITTED);
    }
}