/*
|
* JBoss, Home of Professional Open Source
|
* Copyright 2005, JBoss Inc., and individual contributors as indicated
|
* by the @authors tag. See the copyright.txt in the distribution for a
|
* full listing of individual contributors.
|
*
|
* This is free software; you can redistribute it and/or modify it
|
* under the terms of the GNU Lesser General Public License as
|
* published by the Free Software Foundation; either version 2.1 of
|
* the License, or (at your option) any later version.
|
*
|
* This software is distributed in the hope that it will be useful,
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
* Lesser General Public License for more details.
|
*
|
* You should have received a copy of the GNU Lesser General Public
|
* License along with this software; if not, write to the Free
|
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
|
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
|
*/
|
package org.jbpm.api;
|
|
import java.io.Serializable;
|
import java.util.Collection;
|
import java.util.Map;
|
import java.util.Set;
|
|
import org.jbpm.api.model.OpenExecution;
|
|
/** a runtime path of execution.
|
*
|
* <h3 id="state">State of an execution</h3>
|
*
|
* <p>The state of an execution is either active or locked. An active execution is either
|
* executing or waiting for an external trigger. If an execution is not in {@link #STATE_ACTIVE_ROOT}
|
* or {@link #STATE_ACTIVE_CONCURRENT} then it is locked. A locked execution is read only.
|
* </p>
|
*
|
* <p>When a new execution is created, it is in {@link #STATE_ACTIVE_ROOT}.
|
* {@link #STATE_ACTIVE_ROOT Some STATE_* constants} are provided that represent the
|
* most commonly used locked states. But the state '...' in the picture indicates
|
* thsat any tring can be provided as the state in the lock method.
|
* </p>
|
*
|
* <p>If an execution is locked, methods that change the execution will throw
|
* a {@link JbpmException} and the message will reference the actual locking state.
|
* {@link OpenExecution#setVariable(String, Object) updating variables},
|
* {@link OpenExecution#setPriority(int) updating priority} are not considered to change an
|
* execution.
|
* </p>
|
*
|
* <p>Make sure that comparisons between {@link #getState()} and the
|
* {@link #STATE_ACTIVE_ROOT STATE_* constants} are
|
* done with .equals and not with '==' because if executions are
|
* loaded from persistent storage, a new string is created instead
|
* of the constants.
|
* </p>
|
*
|
* <h3>Comments</h3>
|
*
|
* @author Tom Baeyens
|
*/
|
public interface Execution extends Serializable {
|
|
/** between creation of a new process instance and the start of that
|
* process instance. Typically this is only a very short period that is
|
* not observable thourgh the service interfaces. */
|
String STATE_CREATED = "created";
|
|
/** single (non-concurrent) path of execution that is an active indicator
|
* of the current position in the diagram. jBPM can be executing automatic
|
* activities or some external entity might be responsible for continuing the
|
* execution (wait state for jBPM). An active execution is always
|
* a leaf in the execution tree.
|
* This is the normal state of an execution and the initial state
|
* when creating a new execution. Make sure that comparisons are
|
* done with .equals and not with '==' because if executions are
|
* loaded from persistent storage, a new string is created instead
|
* of the constants. */
|
String STATE_ACTIVE_ROOT = "active-root";
|
|
/** concurrent path of execution that is an active indicator
|
* of the current position in the diagram. The parent of an active
|
* concurrent execution is always an inactive concurrent root. jBPM can
|
* be executing automatic
|
* activities or some external entity might be responsible for continuing the
|
* execution (wait state for jBPM).
|
* Make sure that comparisons are
|
* done with .equals and not with '==' because if executions are
|
* loaded from persistent storage, a new string is created instead
|
* of the constants. */
|
String STATE_ACTIVE_CONCURRENT = "active-concurrent";
|
|
/** parent of concurrent child executions.
|
* When an execution has concurrent child executions, it implies that
|
* this execution can't be active. For example, at a fork, the parent
|
* execution can wait inactively in the fork being till all the
|
* child executions are joined. Only leaves of the
|
* execution tree can be active. Make sure that comparisons are
|
* done with .equals and not with '==' because if executions are
|
* loaded from persistent storage, a new string is created instead
|
* of the constants. */
|
String STATE_INACTIVE_CONCURRENT_ROOT = "inactive-concurrent-root";
|
|
/** parent of a scoped execution. This execution is inactive,
|
* but points to the parent scope like e.g. a group.
|
* This execution has exactly 1 child execution. That indicates
|
* the state inside of the scope.
|
* Make sure that comparisons are
|
* done with .equals and not with '==' because if executions are
|
* loaded from persistent storage, a new string is created instead
|
* of the constants. */
|
String STATE_INACTIVE_SCOPE = "inactive-scope";
|
|
/** concurrent execution that is inactively waiting in a join
|
* until other concurrent executions arrive.
|
* Make sure that comparisons are
|
* done with .equals and not with '==' because if executions are
|
* loaded from persistent storage, a new string is created instead
|
* of the constants. */
|
String STATE_INACTIVE_JOIN = "inactive-join";
|
|
/** indicates that this execution is temporary suspended. Human tasks of
|
* a suspended execution
|
* shouldn't show up in people's task list and timers of suspended
|
* executions shouldn't fire and the execution is locked. Make sure that comparisons are
|
* done with .equals and not with '==' because if executions are
|
* loaded from persistent storage, a new string is created instead
|
* of the constants. */
|
String STATE_SUSPENDED = "suspended";
|
|
/** indicates that this execution is doing an asynchronous continuation. */
|
String STATE_ASYNC = "async";
|
|
/** this execution has ended. Make sure that comparisons are
|
* done with .equals and not with '==' because if executions are
|
* loaded from persistent storage, a new string is created instead
|
* of the constants. */
|
String STATE_ENDED = "ended";
|
|
/** the externally given name or id of this execution. The id of a main
|
* path of execution is null. Can be used to differentiate concurrent
|
* paths of execution e.g. the shipping and billing paths. */
|
String getName();
|
|
/** the optional user provided business key that is unique within one
|
* process definition. This could be for instance the order number.
|
* It's a user defined identifier for one execution within the scope of
|
* a single process definition. */
|
String getKey();
|
|
/** a globally unique identifier for this execution that is used as a reference in the service methods. */
|
String getId();
|
|
/** the <a href="#state">state</a> of this execution. */
|
String getState();
|
|
/**
|
* Returns whether this execution is a process instance.
|
* Note that we cannot use 'isProcessInstance', since this
|
* would clash with 'getProcessInstance()' when using expressions.
|
* (see JBPM-2494)
|
* */
|
boolean getIsProcessInstance();
|
|
/** is this execution ended */
|
boolean isEnded();
|
|
/** is this execution suspended ? */
|
boolean isSuspended();
|
|
/** indicates low priorities with negative values and high priorities
|
* with positive values. The default priority is 0, which means
|
* NORMAL. Other recognized named priorities are HIGHEST (2), HIGH (1),
|
* LOW (-1) and LOWEST (-2). For the rest, the user can set any other
|
* priority integer value, but then, the UI will have to display it as
|
* an integer and not the named value.*/
|
int getPriority();
|
|
// execution hierarchy access ///////////////////////////////////////////////
|
|
/** the main path of execution in the <a href="package-summary.html#basicexecutionstructure">execution
|
* structure</a>. Null will be returned in case this execution itself is the
|
* main execution path. */
|
Execution getProcessInstance();
|
|
/** the parent execution in the <a href="package-summary.html#basicexecutionstructure">execution
|
* structure</a>. Null will be returned in case this execution itself is the
|
* main execution path. */
|
Execution getParent();
|
|
/** the child executions in the <a href="package-summary.html#basicexecutionstructure">execution
|
* structure</a>. Can be null and can be an empty collection. */
|
Collection<? extends Execution> getExecutions();
|
|
/** maps child execution names to execution objects. In case multiple executions
|
* have the same name, the first one is taken. Can be null or can be an empty
|
* map. The first execution without a name is also included with null as the key.
|
*/
|
Map<String, Execution> getExecutionsMap();
|
|
/** the child execution for the given name or null in case such execution doesn't exist. */
|
Execution getExecution(String name);
|
|
/** indicates if this execution has a child execution with the given executionName */
|
boolean hasExecution(String executionName);
|
|
/** search for an execution that is active and in the given activityName.
|
* Returns null in case there is no such execution.
|
* @see #findActiveActivityNames() */
|
Execution findActiveExecutionIn(String activityName);
|
|
/** get the set of all activities that are active.
|
* Returns an empty set in case there are no activities active.
|
* @see #findActiveExecutionIn(String) */
|
Set<String> findActiveActivityNames();
|
|
/** is the given activity active.
|
* This execution and its child executions are searched. If this is a
|
* process instance, this means that the whole process instance is searched. */
|
boolean isActive(String activityName);
|
|
/** id of the process definition used for this execution */
|
String getProcessDefinitionId();
|
}
|
