[jbpm-commits] JBoss JBPM SVN: r5144 - jbpm4/trunk/modules/userguide/src/main/docbook/en/modules.

[do-not-reply at jboss.org]

Author: tom.baeyens at jboss.com
Date: 2009-06-29 06:12:05 -0400 (Mon, 29 Jun 2009)
New Revision: 5144

Modified:
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml
Log:
variables documented in the userguide

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml	2009-06-29 09:45:55 UTC (rev 5143)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml	2009-06-29 10:12:05 UTC (rev 5144)
@@ -1,7 +1,83 @@
 <chapter id="variables">
   <title>Variables</title>
   
-  <para>TODO  
+  <para>Process variables can be accessed from outside the process with methods from the <literal>ExecutionService</literal>:
   </para>
+  
+  <itemizedlist>
+    <listitem><literal>ProcessInstance startProcessInstanceById(String processDefinitionId, Map&lt;String, Object&gt; variables);</literal></listitem>
+    <listitem><literal>ProcessInstance startProcessInstanceById(String processDefinitionId, Map&lt;String, Object&gt; variables, String processInstanceKey);</literal></listitem>
+    <listitem><literal>ProcessInstance startProcessInstanceByKey(String processDefinitionKey, Map&lt;String, ?&gt; variables);</literal></listitem>
+    <listitem><literal>ProcessInstance startProcessInstanceByKey(String processDefinitionKey, Map&lt;String, ?&gt; variables, String processInstanceKey);</literal></listitem>
+    <listitem><literal>void setVariable(String executionId, String name, Object value);</literal></listitem>
+    <listitem><literal>void setVariables(String executionId, Map&lt;String, ?&gt; variables);</literal></listitem>
+    <listitem><literal>Object getVariable(String executionId, String variableName);</literal></listitem>
+    <listitem><literal>Set&lt;String&gt; getVariableNames(String executionId);</literal></listitem>
+    <listitem><literal>Map&lt;String, Object&gt; getVariables(String executionId, Set&lt;String&gt; variableNames);</literal></listitem>
+  </itemizedlist>
+  
+  <para>And from inside the process with methods from Execution interfaces passed to user code like 
+  <literal>ActivityExecution</literal> and <literal>EventListenerExecution</literal>:
+  </para>
 
+  <itemizedlist>
+    <listitem><literal>Object getVariable(String key);</literal></listitem>
+    <listitem><literal>void setVariables(Map&lt;String, ?&gt; variables);</literal></listitem>
+    <listitem><literal>boolean hasVariable(String key);</literal></listitem>
+    <listitem><literal>boolean removeVariable(String key);</literal></listitem>
+    <listitem><literal>void removeVariables();</literal></listitem>
+    <listitem><literal>boolean hasVariables();</literal></listitem>
+    <listitem><literal>Set&lt;String&gt; getVariableKeys();</literal></listitem>
+    <listitem><literal>Map&lt;String, Object&gt; getVariables();</literal></listitem>
+    <listitem><literal>void createVariable(String key, Object value);</literal></listitem>
+    <listitem><literal>void createVariable(String key, Object value, String typeName);</literal></listitem>
+  </itemizedlist>
+
+  <para>jBPM doesn't have a mechanism for detecting changes automatically to variable values.  So if you
+  get e.g. a serializable collection from the process variables and add an element, then you need to 
+  set the changed variable value explicitely for the changes to be saved to the DB.   
+  </para>
+  
+  <section>
+    <title>Variable scoping</title>
+    <para>By default variables are created in the top level process instance scope.  This means they are 
+    visible and accessible in all the paths of execution of the whole process instance.  Process variables are 
+    created dynamically.  Meaning that a variable is created the first time it is set 
+    through one of these methods.
+    </para>
+    <para>Each execution is a variable scope.  Variables declared in a nested execution level will 'see'
+    their own variables and variables declared in parent executions according to the normal scoping rules.
+    With the <literal>createVariable</literal> methods in the execution interfaces <literal>ActivityExecution</literal>
+    and <literal>EventListenerExecution</literal>, execution-local variables can be created. 
+    </para>
+	  <para>In one of the future releases, we might add variable declaration in the jPDL process language.
+	  </para>
+  </section>
+  
+  <section>
+    <title>Variable types</title>
+    <para>jBPM supports following Java types as process variables:</para>
+    <itemizedlist>
+      <listitem>java.lang.String</listitem>
+      <listitem>java.lang.Long</listitem>
+      <listitem>java.lang.Double</listitem>
+      <listitem>java.util.Date</listitem>
+      <listitem>java.lang.Boolean</listitem>
+      <listitem>java.lang.Character</listitem>
+      <listitem>java.lang.Byte</listitem>
+      <listitem>java.lang.Short</listitem>
+      <listitem>java.lang.Integer</listitem>
+      <listitem>java.lang.Float</listitem>
+      <listitem>byte[] (byte array)</listitem>
+      <listitem>char[] (char array)</listitem>
+      <listitem>hibernate entity with a long id</listitem>
+      <listitem>hibernate entity with a string id</listitem>
+      <listitem>serializable</listitem>
+    </itemizedlist>
+    <para>For persistence of these variable, the type of the variable is 
+    checked in the order of this list.  The first match will determine how 
+    the variable is stored.
+    </para>
+  </section>
+  
 </chapter>