[jboss-svn-commits] JBL Code SVN: r34261 - labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Jul 28 11:17:26 EDT 2010
Author: KrisVerlaenen
Date: 2010-07-28 11:17:25 -0400 (Wed, 28 Jul 2010)
New Revision: 34261
Modified:
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/EventListener.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/NodeInstance.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/NodeInstanceContainer.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessContext.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessInstance.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessRuntime.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/StatefulProcessSession.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItem.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItemHandler.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItemManager.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkflowProcessInstance.java
Log:
- added javadocs for Drools Flow in drools-api
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/EventListener.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/EventListener.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/EventListener.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -16,14 +16,26 @@
package org.drools.runtime.process;
+/**
+ * An interface that represents an element that is listening
+ * for specific types of events.
+ */
public interface EventListener {
- void signalEvent(String type,
+ /**
+ * Signals that an event has occurred. The type parameter defines
+ * which type of event and the event parameter can contain additional information
+ * related to the event.
+ *
+ * @param type the type of event
+ * @param event the data associated with this event
+ */
+ void signalEvent(String type,
Object event);
/**
* Returns the event types this event listener is interested in.
- * May return null if the event types are unknown.
+ * May return <code>null</code> if the event types are unknown.
*/
String[] getEventTypes();
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/NodeInstance.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/NodeInstance.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/NodeInstance.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -16,16 +16,61 @@
package org.drools.runtime.process;
+/**
+ * A node instance represents the execution of one specific node
+ * in a process instance. Whenever a node is reached during the
+ * execution of a process instance, a node instance will be created.
+ * A node instance contains all the runtime state related to the
+ * execution of that node.
+ * Multiple node instances for the same node can coexist in the same
+ * process instance (if that node is to be executed multiple times
+ * in that process instance).
+ *
+ * A node instance is uniquely identified (within its node instance
+ * container!) by an id.
+ *
+ * Node instances can be nested, meaning that a node instance can
+ * be created as part of another node instance.
+ */
public interface NodeInstance {
+ /**
+ * The id of the node instance. This is unique within the
+ * node instance container this node instance lives in.
+ *
+ * @return the id of the node instance
+ */
long getId();
+ /**
+ * The id of the node this node instance refers to. The node
+ * represents the definition that this node instance was based
+ * on.
+ *
+ * @return the id of the node this node instance refers to
+ */
long getNodeId();
+ /**
+ * The name of the node this node instance refers to.
+ * @return the name of the node this node instance refers to
+ */
String getNodeName();
+ /**
+ * The process instance that this node instance is executing in.
+ * @return the process instance that this node instance is executing in
+ */
WorkflowProcessInstance getProcessInstance();
+ /**
+ * The node instance container that this node instance is part of.
+ * If the node was defined in the top-level process scope, this is
+ * the same as the process instance. If not, it is the node instance
+ * container this node instance is executing in.
+ *
+ * @return the process instance that this node instance is executing in
+ */
NodeInstanceContainer getNodeInstanceContainer();
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/NodeInstanceContainer.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/NodeInstanceContainer.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/NodeInstanceContainer.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -18,10 +18,27 @@
import java.util.Collection;
+/**
+ * A node instance container is a container that can contain
+ * (zero or more) node instances.
+ */
public interface NodeInstanceContainer {
+ /**
+ * Returns all node instances that are currently active
+ * within this container.
+ *
+ * @return the list of node instances currently active
+ */
Collection<NodeInstance> getNodeInstances();
+ /**
+ * Returns the node instance with the given id, or <code>null</code>
+ * if the node instance cannot be found.
+ *
+ * @param nodeInstanceId
+ * @return the node instance with the given id
+ */
NodeInstance getNodeInstance(long nodeInstanceId);
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessContext.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessContext.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessContext.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -18,14 +18,56 @@
import org.drools.runtime.KnowledgeContext;
-public interface ProcessContext extends KnowledgeContext {
+/**
+ * Represents the context when executing a process.
+ */
+public interface ProcessContext extends KnowledgeContext {
+ /**
+ * Returns the process instance that is currently being
+ * executed in this context.
+ *
+ * @return the process instance that is currently being
+ * executed in this context
+ */
ProcessInstance getProcessInstance();
+ /**
+ * Returns the node instance that is currently being
+ * executed in this context, or <code>null</node> if no
+ * node instance is currently being executed.
+ *
+ * @return the node instance that is currently being
+ * executed in this context
+ */
NodeInstance getNodeInstance();
+ /**
+ * Returns the value of the variable with the given name.
+ * Based on the current node instance, it will try to resolve
+ * the given variable, taking nested variable scopes into
+ * account. Returns <code>null</code> if the variable could
+ * not be found.
+ *
+ * @param variableName the name of the variable
+ * @return the value of the variable
+ */
Object getVariable(String variableName);
+ /**
+ * Sets the value of the variable with the given name.
+ * Based on the current node instance, it will try to resolve
+ * the given variable, taking nested variable scopes into
+ * account.
+ *
+ * If the variable cannot be resolved, it will set the value as
+ * a process-level variable. It is however recommended to only
+ * use this with caution, as it is always recommended to define
+ * the variables that are used inside a process.
+ *
+ * @param variableName the name of the variable
+ * @param value the value of the variable
+ */
void setVariable(String variableName,
Object value);
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessInstance.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessInstance.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessInstance.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -16,6 +16,27 @@
package org.drools.runtime.process;
+/**
+ * A process instance represents one specific instance of a process
+ * that is currently executing. Whenever a process is started, a
+ * process instance is created that represents that specific instance
+ * that was started. It contains all runtime information related to
+ * that instance. Multiple process instances of the same process
+ * can be executed simultaneously.
+ *
+ * For example, consider a process definition that describes how to
+ * process a purchase order. Whenever a new purchase order comes in,
+ * a new process instance will be created for that purchase order.
+ * Multiple process instances (one for each purchase order) can coexist.
+ *
+ * A process instance is uniquely identified by an id.
+ *
+ * This class can be extended to represent one specific type of process,
+ * e.g. <code>WorkflowProcessInstance</code> when using a <code>WorkflowProcess</code>
+ * where the process logic is expressed as a flow chart.
+ *
+ * @see org.drools.runtime.process.WorkflowProcessInstance
+ */
public interface ProcessInstance
extends
EventListener {
@@ -26,15 +47,28 @@
int STATE_ABORTED = 3;
int STATE_SUSPENDED = 4;
+ /**
+ * The id of the process definition that is related to this process instance.
+ * @return the id of the process definition that is related to this process instance
+ */
String getProcessId();
+ /**
+ * The unique id of this process instance.
+ * @return the unique id of this process instance
+ */
long getId();
+ /**
+ * The name of the process definition that is related to this process instance.
+ * @return the name of the process definition that is related to this process instance
+ */
String getProcessName();
+ /**
+ * The state of the process instance.
+ * @return the state of the process instance
+ */
int getState();
-
- void signalEvent(String type,
- Object event);
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessRuntime.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessRuntime.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/ProcessRuntime.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -19,26 +19,104 @@
import java.util.Collection;
import java.util.Map;
+/**
+ * The <code>ProcessRuntime</code> is a super-interface for all <code>StatefulKnowledgeSession</code>s.
+ *
+ * @see org.drools.runtime.StatefulKnowledgeSession
+ */
public interface ProcessRuntime {
+ /**
+ * Start a new process instance. The process (definition) that should
+ * be used is referenced by the given process id.
+ *
+ * @param processId The id of the process that should be started
+ * @return the <code>ProcessInstance</code> that represents the instance of the process that was started
+ */
ProcessInstance startProcess(String processId);
+ /**
+ * Start a new process instance. The process (definition) that should
+ * be used is referenced by the given process id. Parameters can be passed
+ * to the process instance (as name-value pairs), and these will be set
+ * as variables of the process instance.
+ *
+ * @param processId the id of the process that should be started
+ * @param parameters the process variables that should be set when starting the process instance
+ * @return the <code>ProcessInstance</code> that represents the instance of the process that was started
+ */
ProcessInstance startProcess(String processId,
Map<String, Object> parameters);
+ /**
+ * Signals the engine that an event has occurred. The type parameter defines
+ * which type of event and the event parameter can contain additional information
+ * related to the event. All process instances that are listening to this type
+ * of (external) event will be notified. For performance reasons, this type of event
+ * signaling should only be used if one process instance should be able to notify
+ * other process instances. For internal event within one process instance, use the
+ * signalEvent method that also include the processInstanceId of the process instance
+ * in question.
+ *
+ * @param type the type of event
+ * @param event the data associated with this event
+ */
void signalEvent(String type,
Object event);
+ /**
+ * Signals the process instance that an event has occurred. The type parameter defines
+ * which type of event and the event parameter can contain additional information
+ * related to the event. All node instances inside the given process instance that
+ * are listening to this type of (internal) event will be notified. Note that the event
+ * will only be processed inside the given process instance. All other process instances
+ * waiting for this type of event will not be notified.
+ *
+ * @param type the type of event
+ * @param event the data associated with this event
+ * @param processInstanceId the id of the process instance that should be signaled
+ */
void signalEvent(String type,
Object event,
long processInstanceId);
+ /**
+ * Returns a collection of currently active process instances. Note that only process
+ * instances that are currently loaded and active inside the engine will be returned.
+ * When using persistence, it is likely not all running process instances will be loaded
+ * as their state will be stored persistently. It is recommended not to use this
+ * method to collect information about the state of your process instances but to use
+ * a history log for that purpose.
+ *
+ * @return a collection of process instances currently active in the session
+ */
Collection<ProcessInstance> getProcessInstances();
- ProcessInstance getProcessInstance(long id);
-
- void abortProcessInstance(long id);
+ /**
+ * Returns the process instance with the given id. Note that only active process instances
+ * will be returned. If a process instance has been completed already, this method will return
+ * <code>null</code>.
+ *
+ * @param id the id of the process instance
+ * @return the process instance with the given id or <code>null</code> if it cannot be found
+ */
+ ProcessInstance getProcessInstance(long processInstanceId);
+ /**
+ * Aborts the process instance with the given id. If the process instance has been completed
+ * (or aborted), or the process instance cannot be found, this method will throw an
+ * <code>IllegalArgumentException</code>.
+ *
+ * @param id the id of the process instance
+ */
+ void abortProcessInstance(long processInstanceId);
+
+ /**
+ * Returns the <code>WorkItemManager</code> related to this session. This can be used to
+ * register new <code>WorkItemHandler</code>s or to complete (or abort) <code>WorkItem</code>s.
+ *
+ * @return the <code>WorkItemManager</code> related to this session
+ */
WorkItemManager getWorkItemManager();
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/StatefulProcessSession.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/StatefulProcessSession.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/StatefulProcessSession.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -16,6 +16,12 @@
package org.drools.runtime.process;
+/**
+ * There are currently no process related methods that are used with the external StatefulKnowledgeSession class. So this
+ * interface is just a marker at the moment, but may find more uses in the future as requirements are discovered.
+ *
+ * @see org.drools.runtime.StatefulKnowledgeSession
+ */
public interface StatefulProcessSession {
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItem.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItem.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItem.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -18,6 +18,29 @@
import java.util.Map;
+/**
+ * Represents one unit of work that needs to be executed. It contains
+ * all the information that it necessary to execute this unit of work
+ * as parameters, and (possibly) results related to its execution.
+ *
+ * WorkItems represent a unit of work in an abstract, high-level and
+ * implementation-independent manner. They are created by the engine
+ * whenever an external task needs to be performed. The engine will
+ * delegate the work item to the appropriate <code>WorkItemHandler</code>
+ * for execution. Whenever a work item is completed (or whenever the work
+ * item cannot be executed and should be aborted), the work item manager
+ * should be notified.
+ *
+ * For example, a work item could be created whenever an email needs to
+ * be sent. This work item would have a name that represents the type of
+ * work that needs to be executed (e.g. "Email") and parameters related to
+ * its execution (e.g. "From" = "me at mail.com", "To" = ..., "Body" = ..., ...).
+ * Result parameters can contain results related to the execution of this
+ * work item (e.g. "Success" = true).
+ *
+ * @see org.drools.runtime.process.WorkItemHandler
+ * @see org.drools.runtime.process.WorkItemManager
+ */
public interface WorkItem {
int PENDING = 0;
@@ -25,20 +48,69 @@
int COMPLETED = 2;
int ABORTED = 3;
+ /**
+ * The unique id of this work item
+ * @return the id of this work item
+ */
long getId();
+ /**
+ * The name of the work item. This represents the type
+ * of work that should be executed.
+ * @return the name of the work item
+ */
String getName();
+ /**
+ * The state of the work item.
+ * @return the state of the work item
+ */
int getState();
+ /**
+ * Returns the value of the parameter with the given name. Parameters
+ * can be used to pass information necessary for the execution of this
+ * work item. Returns <code>null</code> if the parameter cannot be found.
+ *
+ * @param name the name of the parameter
+ * @return the value of the parameter
+ */
Object getParameter(String name);
+ /**
+ * Returns the map of parameters of this work item. Parameters
+ * can be used to pass information necessary for the execution
+ * of this work item.
+ *
+ * @return the map of parameters of this work item
+ */
Map<String, Object> getParameters();
+ /**
+ * Returns the value of the result parameter with the given name. Result parameters
+ * can be used to pass information related the result of the execution of this
+ * work item. Returns <code>null</code> if the result cannot be found.
+ *
+ * @param name the name of the result parameter
+ * @return the value of the result parameter
+ */
Object getResult(String name);
+ /**
+ * Returns the map of result parameters of this work item. Result parameters
+ * can be used to pass information related the result of the execution of this
+ * work item.
+ *
+ * @return the map of results of this work item
+ */
Map<String, Object> getResults();
+ /**
+ * The id of the process instance that requested the execution of this
+ * work item
+ *
+ * @return the id of the related process instance
+ */
long getProcessInstanceId();
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItemHandler.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItemHandler.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItemHandler.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -16,11 +16,46 @@
package org.drools.runtime.process;
+/**
+ * A work item handler is responsible for executing work items
+ * of a specific type. They represent the glue code between an
+ * abstract, high-level work item that is used inside the process
+ * and the implementation of this work item. Work item handlers
+ * should be registered with the <code>WorkItemManager</code> for
+ * each type of work that can be executed in the engine.
+ *
+ * A work item handler is responsible for executing a work item whenever
+ * the work item manager delegates one to it. It should also notify
+ * the work item manager when the work item has been completed.
+ *
+ * It is also possible that a work item handler is requested to abort
+ * an existing work item (that is still executing) because it is no longer
+ * necessary. This might for example be because the process instance
+ * (or a part of the process instance) that is was executing in is being
+ * aborted. The work item handler should then try to abort this work item
+ * (if possible) and if necessary clean up runtime state related to its
+ * execution.
+ *
+ * For example, a work item handler that is responsible for executing
+ * email work items will retrieve the necessary information from the
+ * work item (from, to, body, etc.) and invoke the mail server. Afterwards,
+ * it will notify the <code>WorkItemManager</code> that the work item was completed.
+ */
public interface WorkItemHandler {
+ /**
+ * The given work item should be executed.
+ * @param workItem the work item that should be executed
+ * @param manager the manager that requested the work item to be executed
+ */
void executeWorkItem(WorkItem workItem,
WorkItemManager manager);
+ /**
+ * The given work item should be aborted.
+ * @param workItem the work item that should be aborted
+ * @param manager the manager that requested the work item to be aborted
+ */
void abortWorkItem(WorkItem workItem,
WorkItemManager manager);
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItemManager.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItemManager.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkItemManager.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -18,13 +18,40 @@
import java.util.Map;
+/**
+ * A work item manager is responsible for finding the right
+ * work item handler when a work item should be executed and
+ * should be notified when this work item has been completed
+ * (or aborted).
+ */
public interface WorkItemManager {
+ /**
+ * Notifies the work item manager that the work item with the given
+ * id has been completed. Results related to the execution of this
+ * work item can be passed.
+ *
+ * @param id the id of the work item that has been completed
+ * @param results the results related to this work item, or <code>null</code> if there are no results
+ */
void completeWorkItem(long id,
Map<String, Object> results);
+ /**
+ * Notifies the work item manager that the work item with the given
+ * id could not be executed and should be aborted.
+ *
+ * @param id the id of the work item that should be aborted
+ */
void abortWorkItem(long id);
+ /**
+ * Register the given handler for all work items of the given
+ * type of work
+ *
+ * @param workItemName the type of work this work item handler can execute
+ * @param handler the handler for executing work items
+ */
void registerWorkItemHandler(String workItemName,
WorkItemHandler handler);
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkflowProcessInstance.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkflowProcessInstance.java 2010-07-28 15:14:40 UTC (rev 34260)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/runtime/process/WorkflowProcessInstance.java 2010-07-28 15:17:25 UTC (rev 34261)
@@ -16,11 +16,28 @@
package org.drools.runtime.process;
+/**
+ * A workflow process instance represents one specific instance of a
+ * workflow process that is currently executing. It is an extension
+ * of a <code>ProcessInstance</code> and contains all runtime state
+ * related to the execution of workflow processes.
+ *
+ * @see org.drools.runtime.process.ProcessInstance
+ */
public interface WorkflowProcessInstance
extends
ProcessInstance,
NodeInstanceContainer {
-
+
+ /**
+ * Returns the value of the variable with the given name. Note
+ * that only variables in the process-level scope will be searched.
+ * Returns <code>null</code> if the value of the variable is null
+ * or if the variable cannot be found.
+ *
+ * @param name the name of the variable
+ * @return the value of the variable, or <code>null</code> if it cannot be found
+ */
Object getVariable(String name);
}
\ No newline at end of file
More information about the jboss-svn-commits
mailing list