diff --git a/modules/activiti-engine/src/main/java/org/activiti/engine/RuntimeService.java b/modules/activiti-engine/src/main/java/org/activiti/engine/RuntimeService.java
index 51e7b1d5e8910c52584b159d3f4d7eae8a730f22..e210edab7a445f74af3cde0ae3248a3baaca21bf 100644
--- a/modules/activiti-engine/src/main/java/org/activiti/engine/RuntimeService.java
+++ b/modules/activiti-engine/src/main/java/org/activiti/engine/RuntimeService.java
@@ -16,8 +16,6 @@ import java.util.Collection;
import java.util.List;
import java.util.Map;
-import org.activiti.engine.repository.Deployment;
-import org.activiti.engine.repository.ProcessDefinition;
import org.activiti.engine.runtime.Execution;
import org.activiti.engine.runtime.ExecutionQuery;
import org.activiti.engine.runtime.NativeExecutionQuery;
@@ -26,8 +24,7 @@ import org.activiti.engine.runtime.ProcessInstance;
import org.activiti.engine.runtime.ProcessInstanceQuery;
-/** Service which provides access to {@link Deployment}s,
- * {@link ProcessDefinition}s and {@link ProcessInstance}s.
+/**
*
* @author Tom Baeyens
* @author Joram Barrez
diff --git a/userguide/src/en/chapters/ch04-API.xml b/userguide/src/en/chapters/ch04-API.xml
index c111a74b5e5d4f5c8dd33046b7b4992f6d055e80..9fd9b05ce5410534187495b5682f5bf54486beaa 100644
--- a/userguide/src/en/chapters/ch04-API.xml
+++ b/userguide/src/en/chapters/ch04-API.xml
@@ -5,7 +5,7 @@
The Activiti API
- Engine API
+ The Process Engine API and services
The engine API is the most common way of interacting with
Activiti. The central starting point is the ProcessEngine,
which can be created in several ways as described in the
@@ -25,10 +25,7 @@ ManagementService managementService = processEngine.getManagementService();
IdentityService identityService = processEngine.getIdentityService();
HistoryService historyService = processEngine.getHistoryService();
FormService formService = processEngine.getFormService();
- The names of the services are quite self-explanatory.
- For detailed information on the services and the engine API, see the javadocs.
-
-
+
ProcessEngines.getDefaultProcessEngine() will initialize and build a process
engine the first time it is called and afterwards always return the same process engine.
Proper creation and closing of all process engines can be done with ProcessEngines.init()
@@ -41,6 +38,119 @@ FormService formService = processEngine.getFormService();
the Spring application context is created and then the process engine is obtained from that application context.
+
+ All services are stateless. This means that you can easily run Activiti on multiple nodes in a cluster, each going to the same database,
+ without having to worry about which machine actually executed previous calls. Any call to any service
+ is idempotent regardless of where it is executed.
+
+
+
+ The RepositoryService is probably the first service needed when working with the
+ Activiti engine. This service offers operations for managing and manipulating deployments and
+ process definitions. Without going into much detail here, a process definition is a Java counterpart
+ of BPMN 2.0 process. It is a representation of the structure and behaviour of each of the steps of a process.
+ A deployment is the unit of packaging within the Activiti engine. A deployment can contain
+ multiple BPMN 2.0 xml files and any other resource. The choice of what is included in one deployment is
+ up to the developer. It can range from a single process BPMN 2.0 xml file to a whole package of processes
+ and relevant resources (for example the deployment 'hr-processes' could contain everything related to hr processes).
+ The RepositoryService allows to deploy such packages. Deploying a deployment
+ means it is uploaded to the engine, where all processes are inspected and parsed before being stored in the database.
+ From that point on, the deployment is known to the system and any process included in the deployment can
+ now be started.
+
+
+
+ Furthermore, this service allows to
+
+
+ query on deployments and process definitions known to the engine.
+
+
+ Suspend and activate deployments as a whole or specific process definitions.
+ Suspending means no further operations can be done on them, while activation is the opposite operation.
+
+
+ Retrieve various resources such as files contained within the deployment or process diagrams that
+ were auto generated by the engine.
+
+
+ Retrieve a pojo version of the process definition which can be used to introspect the process using
+ Java rather than xml.
+
+
+
+
+
+ Wile the RepositoryService is rather about static information (ie. data that doesn't change, or at least not a lot),
+ the RuntimeService is quite the opposite. It deals with starting new process instances of process definitions.
+ As said above, a process definition defines the structure and behaviour of the different steps in a process.
+ A process instance is one execution of such a process definition. For each process definition there typically are many
+ instances running at the same time. The RuntimeService also is the service which is used to retrieve and store
+ process variables. This is data which is specific to the given process instance and can be used by various
+ constructs in the process (eg. an exclusive gateway often uses process variables to determine which path is chosen to continue the process).
+ The Runtimeservice also allows to query on process instances and executions. Executions are a representation
+ of the 'token' concept of BPMN 2.0. Basically an execution is a pointer pointing to where the process instance
+ currently is.
+ Lastly, the RuntimeService is used whenever a process instance is waiting for an external trigger and the process
+ needs to be continued. A process instance can have various wait states and this service contains
+ various operations to 'signal' the instance that the external trigger is received and the process instance can be continues.
+
+
+
+ Task that need to be performed by actual human users of the system are core to a BPM engine such as Activiti.
+ Everything around tasks is grouped in the TaskService, such as
+
+
+ Querying tasks assigned to users or groups
+
+
+ Creating new standalone tasks. This are tasks that are not related to a process instances.
+
+
+ Manipulating to which user a task is assigned or which users are in some way involved with the task.
+
+
+ Claiming and completing task. Claiming means that someone decided to be the assigee for the task, meaninung
+ that this user will complete the task. Completing means 'doing the work of the tasks'. Typically this is
+ filling in a form of sorts.
+
+
+
+
+
+ The IdentityService is pretty simple. It allows the management (creation, update, deletion, querying, ...)
+ of groups and users. It is important to understand that Activiti actually doesn't do any checking on users at runtime.
+ For example, a task could be assigned to any user, but the engine does not verify if that user is known to the system.
+ This is because the Activiti engine can also used in conjunction with services such as ldap, active directory, etc.
+
+
+
+ The FormService is an optional service. Meaning that Activiti can perfectly be used without it,
+ without sacrificing any functionality. This service introduces the concept of a start form and a task form.
+ A start form is a form that is shown to the user before the process instance is started, while a task form
+ is the form that is displayed when a user wants to complete a form. Activiti allows to define these forms in the BPMN 2.0 process
+ definition. This service exposes this data in an easy way to work with. But again, this is optional as forms don't need to be embedded
+ in the process definition.
+
+
+
+ The HistoryService exposes all historical data gathered by the Activiti engine. When executing processes,
+ a lot of data can be kept by the engine (this is configurable) such as process instance start times, who did which tasks, how long it took to
+ complete the tasks, which path was followed in each process instance, etc. This service exposes mainly query capabilities to
+ access this data.
+
+
+
+ The ManagementService is typically not needed when coding custom application using Activiti.
+ It allows to retrieve information about the database tables and table metadata. Furthermore, it exposes query capabilities and
+ management operations for jobs. Jobs are used in Activiti for various things such as timers, asynchronous continuations,
+ delayed suspension/activation, etc. Later on, these topics will be discussed in more detail.
+
+
+
+ For more detailed information on the service operations and the engine API, see the javadocs.
+
+