FlowCall

/*
 * 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.config;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import javax.faces.context.FacesContext;

import org.apache.myfaces.orchestra.lib.OrchestraException;

/**
 * Contains static metadata information about a possible call to a flow.
 */
public class FlowCall implements Serializable
{
    // For serialization. IMPORTANT; update this when changing the
    // binary format of this class (eg adding fields).
    private static final long serialVersionUID = 1L;

    private String outcome;
    private String viewId;
    private String service;

    private List<FlowParamSend> params = new ArrayList<FlowParamSend>(4);
    private List<FlowReturnAccept> returns = new ArrayList<FlowReturnAccept>(4);

    private FlowOnCommit onCommit;

    /**
     * Constructor.
     */
    public FlowCall()
    {
    }

    /**
     * Check that all the properties of this object have valid values, ie
     * whether the configuration specified by the user is valid.
     * <p>
     * Throws an OrchestraException if a mandatory parameter is missing.
     * <p>
     * The outcome property is mandatory; it is always necessary to specify
     * what navigation outcome will trigger this flow call.
     * <p>
     * The service property is mandatory; it is always necessary to specify
     * what logical service (function) this callable flow implements.
     * <p>
     * There must be at least one input parameter passed to the called flow.
     * There are so few sensible flows that take no input parameters at all
     * that is is just not supported; it almost certainly means the user has
     * made a configuration error.
     * <p>
     * There must be at least one output parameter from this flow. A
     * sensible flow that returns no values to its caller is so rare that
     * this is just not supported; it almost certainly means the user has
     * made a configuration error.
     */
    public void validate()
    {
        if (outcome == null)
        {
            throw new OrchestraException("outcome is null");
        }

        // viewId is optional

        if (service == null)
        {
            throw new OrchestraException("service is null");
        }

        if (params.isEmpty())
        {
            throw new OrchestraException("params is empty");
        }

        if (returns.isEmpty())
        {
            throw new OrchestraException("returns is empty");
        }

        for(FlowParamSend p : params)
        {
            p.validate();
        }

        for(FlowReturnAccept p : returns)
        {
            p.validate();
        }
    }

     /**
      * Process all the configured "input param" expressions, fetching the data
      * from the calling environment into a temporary map.
      * <p>
      * The data in this map is then expected to be imported into beans belonging
      * to the called flow
      */
    public Map<String, Object> readSendParams(FacesContext facesContext)
    {
        Map<String, Object> data = new HashMap<String, Object>();
        for(FlowParamSend param : params)
        {
            String paramName = param.getName();
            Object paramValue = param.getSrcValue(facesContext);
            data.put(paramName, paramValue);
        }
        return data;
    }

    /**
     * Process all the configured "return" expressions, fetching the data
     * from a map and writing it into beans associated with the calling page.
     * <p>
     * The map is expected to have been populated by executing the
     * "return param" expressions of the called flow.
     */
    public void writeAcceptParams(FacesContext facesContext, Map<String, Object> data)
    {
        for(FlowReturnAccept param : returns)
        {
            String paramName = param.getName();
            Object newValue = data.get(paramName);
            param.setDstValue(facesContext, newValue);
        }
    }

    /**
     * Return the JSF navigation outcome which will trigger this flowCall.
     */
    public String getOutcome()
    {
        return outcome;
    }

    /** For use only during object initialization. */
    public void setOutcome(String outcome)
    {
        this.outcome = outcome;
    }

    /**
     * Return the viewId to navigate to when this flowCall is triggered.
     * <p>
     * Optional; when null then the normal JSF navigation rules apply.
     * <p>
     * This can be useful when the JSF command-component that triggers the call is a view "fragment" that
     * is included into many pages, eg via jsp:include or facelets templating. In this case, specifying
     * a separate navigation-case for each view that includes the fragment is unreasonable. One option
     * is to specify the navigation case as a global rule, but it also can be reasonable to hard-wire it
     * in the "included" page.
     * <p>
     * For other cases
     */
    public String getViewId()
    {
        return viewId;
    }

    /** For use only during object initialization. */
    public void setViewId(String viewId)
    {
        this.viewId = viewId;
    }

    /**
     * Return the logical function that this flow implements.
     * <p>
     * This is a free-form text string, but it is recommended that the contents
     * look like a fully-qualified java interface name. A called flow is really
     * like invoking a service implementation object via a "service interface"
     * that has only one method.
     */
    public String getService()
    {
        return service;
    }

    /** For use only during object initialization. */
    public void setService(String service)
    {
        this.service = service;
    }

    /**
     * Return list of FlowParamSend objects which defines what values the flow
     * caller passes to the called flow when this FlowCall is triggered.
     */
    public List<FlowParamSend> getParams()
    {
        return params;
    }

    /** For use only during object initialization. */
    public void addParam(FlowParamSend param)
    {
        this.params.add(param);
    }

    /**
     * Return list of FlowReturnAccept objects which defines what values the called
     * flow is expected to return on commit, and where they should be stored
     * within the caller's environment.
     */
    public List<FlowReturnAccept> getReturns()
    {
        return returns;
    }

    /** For use only during object initialization. */
    public void addReturn(FlowReturnAccept returnParam)
    {
        this.returns.add(returnParam);
    }

    /**
     * Return an object that wraps an EL expression which should be executed
     * within the caller environment on successful commit of a called flow.
     * <p>
     * This gives the caller a chance to process the returned values before
     * it is re-rendered.
     */
    public FlowOnCommit getOnCommit()
    {
        return onCommit;
    }

    /** For use only during object initialization. */
    public void setOnCommit(FlowOnCommit onCommit)
    {
        this.onCommit = onCommit;
    }

    /**
     * Custom string format to improve log messages.
     */
    public String toString()
    {
        return "flowCall: outcome=" + outcome + ",service=" + service;
    }
}