expressionpool.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: ExpressionPool.java,v 1.18 2005/05/17 16:40:23 jmettraux Exp $
 */

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

package openwfe.org.engine.expool;

import openwfe.org.Service;
import openwfe.org.time.Time;
import openwfe.org.engine.workitem.InFlowWorkItem;
import openwfe.org.engine.expressions.FlowExpression;
import openwfe.org.engine.expressions.ApplyException;
import openwfe.org.engine.expressions.ReplyException;
import openwfe.org.engine.expressions.FlowExpressionId;


/**
 * The set of methods an ExpressionPool must provide.
 *
 * <p><font size=2>CVS Info :
 * <br>$Author: jmettraux $
 * <br>$Date: 2005/05/17 16:40:23 $
 * <br>$Id: ExpressionPool.java,v 1.18 2005/05/17 16:40:23 jmettraux Exp $ </font>
 *
 * @author [e-mail]
 */
public interface ExpressionPool

    //extends Controllable

{


    //
    // CONSTANTS

    /**
     * This is the name of a global 'application/engine' setting.
     */
    public final static String DEFAULT_EXPRESSION_TIMEOUT
        = "defaultExpressionTimeout";

    /**
     * The default value for an expression timeout (7 days).
     */
    public final static long DEFAULT_EXPRESSION_TIMEOUT_VALUE
        = Time.parseTimeString("7d"); // 7 days before timeout occurs

    /**
     * with this key name, you can set the purge frequency of this
     * service in the configuration file
     */
    public final static String PURGE_FREQUENCY
        = "purgeFrequency";

    /**
     * when 'purgeFrequency' is not set, the purge daemon will be launched
     * every 4 hours
     */
    public final static String DEFAULT_PURGE_FREQUENCY
        = "4h"; // 4 hours

    /**
     * Key name for setting how frequently the 'when' expressions should
     * be checked (DEPRECATED in favor of 'timerFrequency').
     */
    public final static String WHEN_FREQUENCY
        = "whenFrequency";

    /**
     * Key name for setting how frequently the 'when' expressions should
     * be checked
     */
    public final static String TIMER_FREQUENCY
        = "timerFrequency";

    /**
     * The default value for checking 'timer' expressions
     */
    public final static String DEFAULT_TIMER_FREQUENCY
        = "1m"; // 3 minutes


    //
    // METHODS

    /**
     * Usually called by WorkflowInstanceBuilders to add a freshly created
     * expression to the pool.
     */
    public void add (FlowExpression fe)
        throws PoolException;

    /**
     * Stores the flow expression (as it may have changed).
     */
    public void update (FlowExpression fe)
        throws PoolException;

    /**
     * Retrieves an expression from the pool.
     * If the expression cannot be retrieved from the pool, null will be
     * returned.
     */
    public FlowExpression fetch (FlowExpressionId fei);

    /**
     * Returns the Ur-Expression : an expression unique to the engine, its 
     * only task (as of 1.5.1) is to hold variables global to all workflow
     * instances.
     */
    public FlowExpression fetchUrExpression ();

    /**
     * given an id, returns the root expression of the flow
     */
    public FlowExpression fetchRootOfFlow (FlowExpressionId fei);

    /**
     * Applies an expression. 
     * This method is usually called by expressions on their subexpressions or
     * by a launchListener on a rootExpression of a workflow just instantiated.
     */
    public void apply (FlowExpressionId fei, InFlowWorkItem wi)
        throws ApplyException;

    /**
     * A shortcut to 
     * apply (flowExpressionId, inFlowWorkItem)
     */
    public void apply (FlowExpression fe, InFlowWorkItem wi)
        throws ApplyException;

    /**
     * This method replies to the father of the expression passed as parameter
     * then releases this expression.
     */
    public void replyToParent (FlowExpression fe, InFlowWorkItem wi)
        throws ReplyException;

    /* *
     * Applies the next expression and releses the calling expression (fe).
     * This method is used by FlatSequenceExpression, its chained children
     * may thus apply each other.
     * /
    public void applyNext (FlowExpression fe, InFlowWorkItem wi)
        throws ApplyException;
     */

    /**
     * Replies to an expression.
     * This method should only be called by listeners
     */
    public void reply (FlowExpressionId fei, InFlowWorkItem wi)
        throws ReplyException;

    /**
     * Releases a flow expression.
     * This method is called by the replyToFather method, as the
     * expression tree gets diminished.
     */
    public void removeExpression (FlowExpression fe);

    /**
     * Releases a flow expression indicated by its id.
     */
    public void removeExpression (FlowExpressionId fei);

    /* *
     * Removes a whole workflow branch. The branch is referenced by its
     * 'root' child, it's like a global cancel.
     * /
    public void releaseBranch (FlowExpressionId fei);
     */

    /**
     * Will return true if there is still a FlowExpression stored for the
     * given FlowExpressionId.
     * Might get useful for a UI that has to determine if a workitem belongs
     * to an active or a dead branch of a workflow instance.
     */
    public boolean isExpressionActive (FlowExpressionId fei);

    /**
     * (child cancel) Cancels an expression (simply calls its cancel method and 
     * removes it from the pool).
     * Will return a workitem if the cancelled expression was handling one.
     */
    public InFlowWorkItem childCancel (FlowExpressionId fei)
        throws ApplyException;

    /**
     * (root cancel) Cancels a whole branch, starting with its top expression
     * fei.
     */
    public void cancel (FlowExpressionId fei);

    /**
     * Forgets an expression (it stays in the pool, but its reference to its
     * parent expression is replaced by a 'gone-parent' tag, so that its
     * execution continues but its results will get forgotten (never reaching
     * the parent flow)).
     */
    public void forget (FlowExpressionId fei);

    /**
     * Retrieves a given class of expressions. If the parameter is set to
     * null, will return all the expressions.
     */
    public java.util.Iterator contentIterator (Class assignClass);


    //
    // 'next' and 'previous' stuff

    /**
     * Sets the 'next' field of the 'subject' expression.
     */
    public void setNext 
        (FlowExpressionId subject, FlowExpressionId next)
    throws 
        PoolException;

    /**
     * Sets the 'previous' field of the 'subject' expression.
     */
    public void setPrevious 
        (FlowExpressionId subject, FlowExpressionId previous)
    throws 
        PoolException;


    //
    // CONTROL METHODS

    /**
     * Returns a list of 'controllable' expressions.
     */
    public java.util.List listExpressions ();

    /**
     * Unfreezes an expression.
     */
    public void unfreezeExpression (FlowExpressionId freezableExpressionId)
        throws PoolException;

    /**
     * Freezes a flow : freezes all of its freezable expressions.
     */
    public void freezeFlow (String workflowInstanceId)
        throws PoolException;

    /**
     * Freezes an expression.
     */
    public void freezeExpression (FlowExpressionId freezableExpressionId)
        throws PoolException;


    //
    // VARIABLE METHODS

    public Object lookupVariable
        (FlowExpression requester, String variableName);

    /**
     * Sets a variable.
     * If the variableName is prefixed, this method will take care of 
     * storing the variable in the appropriate [upper] expression.
     */
    public void setVariable
        (FlowExpression requester, String variableName, Object value);

    /**
     * Sets a variable in the parent of the requester expression (${x}).
     */
    public void setVariableInParent
        (FlowExpression requester, String variableName, Object value);

}