Act-1465: documented services in user guide. This introduces the service API...

Act-1465: documented services in user guide. This introduces the service API sooner in the user guide such that new users can get started better.

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

userguide/src/en/chapters/ch04-API.xml

@@ -5,7 +5,7 @@
   <title>The Activiti API</title>
 
   <section id="apiEngine">
-    <title>Engine API</title>
+    <title>The Process Engine API and services</title>
     <para>The engine API is the most common way of interacting with
     Activiti. The central starting point is the <literal>ProcessEngine</literal>,
     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();</programlisting>
-    <para>The names of the services are quite self-explanatory.
-    For detailed information on the services and the engine API, see <ulink url="../javadocs/index.html">the javadocs</ulink>. 
-    </para>
-    
+
     <para><literal>ProcessEngines.getDefaultProcessEngine()</literal> 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 <literal>ProcessEngines.init()</literal> 
@@ -41,6 +38,119 @@ FormService formService = processEngine.getFormService();</programlisting>
     the Spring application context is created and then the process engine is obtained from that application context. 
     </para>
 
+    <para>
+        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.
+    </para>
+
+    <para>
+        The <emphasis role="bold">RepositoryService</emphasis> is probably the first service needed when working with the 
+        Activiti engine. This service offers operations for managing and manipulating <literal>deployments</literal> and 
+        <literal>process definitions</literal>. 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 <literal>deployment</literal> 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 <literal>RepositoryService</literal> allows to <literal>deploy</literal> 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. 
+    </para>
+    
+    <para>
+        Furthermore, this service allows to 
+        <itemizedlist>
+            <listitem><para>
+                query on deployments and process definitions known to the engine.
+            </para></listitem>
+            <listitem><para>
+                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.
+            </para></listitem>
+            <listitem><para>
+                Retrieve various resources such as files contained within the deployment or process diagrams that
+                were auto generated by the engine.
+            </para></listitem>
+            <listitem><para>
+                Retrieve a pojo version of the process definition which can be used to introspect the process using 
+                Java rather than xml.
+            </para></listitem>
+        </itemizedlist>
+    </para>
+    
+    <para>
+        Wile the <literal>RepositoryService</literal> is rather about static information (ie. data that doesn't change, or at least not a lot),
+        the <emphasis role="bold">RuntimeService</emphasis> is quite the opposite. It deals with starting new process instances of process definitions.
+        As said above, a <literal>process definition</literal> 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 <literal>RuntimeService</literal> also is the service which is used to retrieve and store
+        <literal>process variables</literal>. 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 <literal>Runtimeservice</literal> also allows to query on process instances and executions. Executions are a representation
+        of the <literal>'token'</literal> concept of BPMN 2.0. Basically an execution is a pointer pointing to where the process instance 
+        currently is.
+        Lastly, the <literal>RuntimeService</literal> 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 <literal>wait states</literal> and this service contains
+        various operations to 'signal' the instance that the external trigger is received and the process instance can be continues. 
+    </para>
+    
+    <para>
+        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 <emphasis role="bold">TaskService</emphasis>, such as
+        <itemizedlist>
+            <listitem><para>
+                Querying tasks assigned to users or groups
+            </para></listitem>
+            <listitem><para>
+                Creating new <emphasis>standalone</emphasis> tasks. This are tasks that are not related to a process instances.
+            </para></listitem>
+            <listitem><para>
+                Manipulating to which user a task is assigned or which users are in some way involved with the task.
+            </para></listitem>
+            <listitem><para>
+                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.
+            </para></listitem>
+        </itemizedlist>
+    </para>
+    
+    <para>
+        The <emphasis>IdentityService</emphasis> 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.
+    </para>
+    
+    <para>
+        The <emphasis role="bold">FormService</emphasis> is an optional service. Meaning that Activiti can perfectly be used without it, 
+        without sacrificing any functionality. This service introduces the concept of a <emphasis>start form</emphasis> and a <emphasis>task form</emphasis>.
+        A <emphasis>start form</emphasis> is a form that is shown to the user before the process instance is started, while a <emphasis>task form</emphasis>
+        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.
+    </para>
+    
+    <para>
+        The <emphasis role="bold">HistoryService</emphasis> 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.
+    </para>
+    
+    <para>
+        The <emphasis role="bold">ManagementService</emphasis> 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.
+    </para>
+
+    <para>
+    For more detailed information on the service operations and the engine API, see <ulink url="../javadocs/index.html">the javadocs</ulink>. 
+    </para>
+    
   </section>
 
   <section>