participantexpression.java

一个工作流设计及定义的系统,可以直接与数据库结合进行系统工作流程的定义及应用.

/*
 * Copyright (c) 2005, John Mettraux, OpenWFE.org
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions are met:
 * 
 * . Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.  
 * 
 * . Redistributions in binary form must reproduce the above copyright notice, 
 *   this list of conditions and the following disclaimer in the documentation 
 *   and/or other materials provided with the distribution.
 * 
 * . Neither the name of the "OpenWFE" nor the names of its contributors may be
 *   used to endorse or promote products derived from this software without
 *   specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * $Id: ParticipantExpression.java,v 1.37 2005/07/19 16:24:35 jmettraux Exp $
 */

//
// ParticipantExpression.java
//
// [e-mail]
//
// generated with 
// jtmpl 1.0.04 20.11.2001 John Mettraux ([e-mail])
//

package openwfe.org.engine.expressions;

import openwfe.org.Utils;
import openwfe.org.ApplicationContext;
import openwfe.org.time.Time;
import openwfe.org.engine.Definitions;
import openwfe.org.engine.expool.ExpressionPool;
import openwfe.org.engine.history.History;
import openwfe.org.engine.workitem.Attribute;
import openwfe.org.engine.workitem.CancelItem;
import openwfe.org.engine.workitem.HistoryItem;
import openwfe.org.engine.workitem.InFlowWorkItem;
import openwfe.org.engine.dispatch.DispatchingException;
import openwfe.org.engine.expressions.state.FrozenState;
import openwfe.org.engine.participants.Filter;
import openwfe.org.engine.participants.Participant;
import openwfe.org.engine.participants.ParticipantMap;


/**
 * A leaf (terminal) expression : a reference to a participant.
 * <p>This expression now includes the 'dyna-participant' functionality</p>
 *
 * <p><font size=2>CVS Info :
 * <br>$Author: jmettraux $
 * <br>$Date: 2005/07/19 16:24:35 $
 * <br>$Id: ParticipantExpression.java,v 1.37 2005/07/19 16:24:35 jmettraux Exp $ </font>
 *
 * @author [e-mail]
 */
public class ParticipantExpression

    extends ZeroChildExpression

    implements ExpressionWithTimeOut

{

    private final static org.apache.log4j.Logger log = org.apache.log4j.Logger
        .getLogger(ParticipantExpression.class.getName());

    //
    // CONSTANTS

    /**
     * The attribute 'ref' indicates to this expression which is the participant
     * that should receive the workitem.
     * See also 'default-ref', 'field-ref', 'variable-ref' and 'else-ref'.
     */
    public final static String REF 
        = "ref";

    /**
     * Use this attribute 'filter' to link this participant expression to a 
     * filter.
     */
    public final static String FILTER
        = "filter";


    private final static String HISTORY_TEXT
        = "ok";

    /**
     * In the flow definition, use this attribute of 'participant' to 
     * determine the value of the '__description__' field.
     */
    public final static String DESCRIPTION 
        = "description";

    /**
     * States the name of the field that will be added (and later removed) to 
     * the workitem if the description attribute is present.
     */
    public final static String DESCRIPTION_FIELD_NAME
        = "__description__";

    /**
     * use this parameter name to set the default participant who
     * will receive the workitem if no participant is indicated 
     * in the workitem
     */
    public final static String DEFAULT_REF 
        = "default-ref";

    /**
     * use this parameter name to tell the expression in which field of
     * the incoming workitem the target participant name will be found
     */
    public final static String FIELD_REF 
        = "field-ref";

    /**
     * use this param name to indicate to the engine in which variable it 
     * shall find the name of the participant to which it should dispatch the 
     * workitem.
     */
    public final static String VARIABLE_REF 
        = "variable-ref";

    /**
     * When 'field-ref' is not set, the target participant is to be found
     * in the '__next_participant__' field of the workitem. (And of course,
     * if it is not set, default-ref, will be consulted)
     */
    public final static String DEFAULT_FIELD_REF
        = "__next_participant__";

    /**
     * This 'else-ref' attribute accepts a comma separated list of successful
     * 'failover participant', ie participants that will receive the workitem
     * if delivery failed to the regularly referenced participant ('ref').
     * Each participant in this else list will get probed until dispatching
     * is successful.<br>
     * If none of them is available, the participant expression will get frozen.
     */
    public final static String ELSE_REF
        = "else-ref";

    //
    // FIELDS

    private Filter filter = null;

    /* *
     * If this participant has a filter, at dispatch time, the workitem
     * is stored in this field (and the expression state is stored again
     * in the expression pool via 'storeItself')
     */
    private InFlowWorkItem appliedWorkitem = null;

    /**
     * If this value is defined, each time this expression is applied a field
     * named '__description__' will be set in the workitem dispatched to the
     * participant. 
     * When the participant will reply, the field will be unset.
     */
    protected String description = null;

    /**
     * When setting the description field, this expression will
     * keep track of the old value and set back when the participant replies.
     */
    protected Attribute oldDescriptionValue = null;

    protected String dynaParticipantName = null;
        // it is determined once and only once, after it is
        // kept, even when the expression gets stored

    //
    // CONSTRUCTORS

    /*
    public ParticipantExpression ()
    {
        super();
    }
    */

    //
    // BEAN METHODS

    public Filter getFilter () { return this.filter; }
    public InFlowWorkItem getAppliedWorkitem () { return this.appliedWorkitem; }

    public void setFilter (Filter f) { this.filter = f; }
    public void setAppliedWorkitem (InFlowWorkItem wi) { this.appliedWorkitem = wi; }

    //
    // METHODS

    /**
     * Extracts the name of the participants who should receive the workitem
     * (it looks in the expression and if necessary in the workitem).
     */
    protected String getParticipantName (final InFlowWorkItem wi)
        throws ApplyException
    {
        if (this.dynaParticipantName != null)
            //
            // alreay determined
            //
            return this.dynaParticipantName;

        log.debug("getParticipantName() name has to be determined");

        //
        // determine key for looking up participant

        String defaultParticipantName = lookupAttribute(DEFAULT_REF, wi);
        String ref = lookupAttribute(REF, wi);
        String fieldRef = lookupAttribute(FIELD_REF, wi);
        String variableRef = lookupAttribute(VARIABLE_REF, wi);

        if (fieldRef == null && variableRef == null)
            fieldRef = DEFAULT_FIELD_REF;

        //
        // lookup name of 'real participant'

        Object participantName = null;

        if (ref != null)
            participantName = ref;
        else if (fieldRef != null && this.appliedWorkitem != null)
            participantName = this.appliedWorkitem.getAttribute(fieldRef);
        else if (variableRef != null)
            participantName = lookupVariable(variableRef);

        if (participantName == null) 
            this.dynaParticipantName = defaultParticipantName;
        else
            this.dynaParticipantName = participantName.toString();

        if (this.dynaParticipantName == null)
            this.dynaParticipantName = lookupAttribute(REF, wi);

        if (this.dynaParticipantName == null)
        {
            throw new ApplyException
                ("Could not determine dynamically or statically the target "+
                 "participant. Is '"+FIELD_REF+
                 "', '"+VARIABLE_REF+"' or '"+REF+
                 "' set in the flow definition ?");
        }

        log.debug
            ("getParticipantName() result : >"+this.dynaParticipantName+"<");

        return this.dynaParticipantName;
    }

    /**
     * Retrieves the participant associated with this participant
     */
    protected Participant lookupParticipant (final InFlowWorkItem wi)
        throws ApplyException
    {
        //log.debug("this.attributes = "+this.attributes);

        String participantName = getParticipantName(wi);

        //log.debug("this.applicationContext = "+this.applicationContext);

        final ParticipantMap pMap = Definitions.getParticipantMap(context());

        if (pMap == null)
        {
            throw new ApplyException
                ("Cannot find participantMap  service. "+
                 "Cannot retrieve any participant.");
        }

        final Participant result = pMap.get(participantName);

        if (result == null)
        {
            throw new ApplyException
                ("Participant '"+participantName+"' not found");
        }

        wi.setParticipantName(participantName);

        return result;
    }

    /**
     * Applies this expression, ie dispatches the workitem to the
     * participant according to the participant map 
     * (etc-engine/participants.xml)
     */
    public void apply (final InFlowWorkItem wi) 
        throws ApplyException
    {
        touchApplyTime();

        //
        // determine filter and description now

        if (this.getAttributes().keySet().contains(FILTER))
        {
            final String filterName = lookupAttribute(FILTER, wi);

            final FilterDefinitionExpression fde = 
                (FilterDefinitionExpression)this.lookupVariable(filterName);

            if (fde != null)
                this.filter = fde.buildFilter(wi);
            else
                log.warn("apply() did not find filter '"+filterName+"'");
        }

        this.description = lookupAttribute(DESCRIPTION, wi);

        //log.debug("apply() description is \""+this.description+"\"");

        // 
        // do the job...

        this.appliedWorkitem = (InFlowWorkItem)wi.clone();

        //
        // should we set a description field ?

        if (this.description != null)
        {
            this.oldDescriptionValue = wi
                .getAttribute(DESCRIPTION_FIELD_NAME);

            wi.getAttributes().puts(DESCRIPTION_FIELD_NAME, this.description);
        }

        //
        // apply filter if any

        InFlowWorkItem itemToDispatch = wi;

        if (this.filter != null)
            itemToDispatch = this.filter.constrain(wi);

        //
        // store itself in the expression to keep track of apply time and
        // other such fields
        
        storeItself();

        //
        // dispatch
        
        regularDispatch(itemToDispatch);
    }

    /**
     * Does the job of regular (not 'else-ref' based dispatching).
     */
    protected void dispatch 
        (final Participant participant, 
         final String participantName, 
         final InFlowWorkItem wi)
    throws 
        ApplyException, 
        DispatchingException
    {
        // identify participant name

        wi.setParticipantName(participantName);

        // dispatch

        participant.dispatch(wi);