[jbpm-commits] JBoss JBPM SVN: r6405 - jbpm4/trunk/modules/userguide/src/main/docbook/en/modules.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Jun 11 14:05:08 EDT 2010
Author: swiderski.maciej
Date: 2010-06-11 14:05:08 -0400 (Fri, 11 Jun 2010)
New Revision: 6405
Modified:
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml
Log:
JBPM-2776: documentation for variable declaration and history support
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 2010-06-11 13:11:04 UTC (rev 6404)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml 2010-06-11 18:05:08 UTC (rev 6405)
@@ -114,4 +114,143 @@
</para>
</section>
+ <section>
+ <title>Declared variables</title>
+ <para>(Since jBPM 4.4)</para>
+ <para>
+ Variables can be declared directly in process definition (JPDL). These variables
+ will be created at process instance startup. There can be more than one variable definition.
+ </para>
+ <para>There are several possible ways for declaring variable:</para>
+ <itemizedlist>
+ <listitem>declare <literal>String</literal> variable initialized with static text
+ <programlisting>
+<variable name="declaredVar" type="string" init-expr="testing declared variable"/>
+ </programlisting>
+ </listitem>
+ <listitem>declare <literal>custom</literal> variable initialized with EL
+ <programlisting>
+<variable name="declaredVar" type="long" init-expr="#{anotherVar}"/>
+ </programlisting>
+ </listitem>
+ <listitem>declare <literal>custom</literal> variable initialized with serializable class
+ <programlisting>
+<variable name="declaredVar" type="serializable" >
+ <object class="org.jbpm.examples.variable.declared.HistoryVariable" />
+</variable>
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>As shown above variable values can be assigned in two ways: using attribute <literal>init-expr</literal> or
+ by nesting init descriptor (element <literal>object</literal>) within variable tags.
+ </para>
+ <para>
+ Note: Only one of value assignment can be used for a variable declaration.
+ </para>
+ <table><title>Attribute for <literal>variable</literal> element:</title>
+ <tgroup cols="5" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Attribute</entry>
+ <entry>Type</entry>
+ <entry>Default</entry>
+ <entry>Required?</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>name</literal></entry>
+ <entry>text</entry>
+ <entry></entry>
+ <entry><emphasis role="bold">required</emphasis></entry>
+ <entry>name of the variable</entry>
+ </row>
+ <row>
+ <entry><literal>type</literal></entry>
+ <entry>text</entry>
+ <entry></entry>
+ <entry><emphasis role="bold">required</emphasis></entry>
+ <entry>type of the variable, must refer to types defined in jbpm.variable.types.xml</entry>
+ </row>
+ <row>
+ <entry><literal>init-expr</literal></entry>
+ <entry>text (EL expression)</entry>
+ <entry></entry>
+ <entry><emphasis role="bold">optional</emphasis></entry>
+ <entry>value for the variable, this attribute or nested element must be given</entry>
+ </row>
+ <row>
+ <entry><literal>init-expr-type</literal></entry>
+ <entry>text</entry>
+ <entry>UEL</entry>
+ <entry><emphasis role="bold">optional</emphasis></entry>
+ <entry>defines language for expression evaluation</entry>
+ </row>
+ <row>
+ <entry><literal>history</literal></entry>
+ <entry>boolean</entry>
+ <entry>false</entry>
+ <entry><emphasis role="bold">optional</emphasis></entry>
+ <entry>indicates wheater variable should be stored in history or not - default false,
+ for more information about history see <xref linkend="variablehistory" /></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table><title>Nested element for <literal>variable</literal>:</title>
+ <tgroup cols="5" rowsep="1" colsep="1">
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Multiplicity</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>object</literal></entry>
+ <entry>1</entry>
+ <entry>Value for the variable as custom object, either this element or <literal>init-expr</literal> attribute must be specified</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section id="variablehistory">
+ <title>Variables history</title>
+ <para>(Since jBPM 4.4)</para>
+
+ <para>Variables can be marked to be persisted as history records. This means that once process instance is ended and
+ its runtime information is removed, history details are preserved.
+ </para>
+ <para>History can be enabled for variable in two ways:</para>
+ <itemizedlist>
+ <listitem>via public API <literal>ExecutionService</literal>:
+ <itemizedlist>
+ <listitem><literal>void createVariable(String executionId, String name, Object value, boolean historyEnabled);</literal></listitem>
+ <listitem><literal>void createVariables(String executionId, Map<String, ?> variables, boolean historyEnabled);</literal></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>on variable declaration
+ <programlisting>
+<variable name="declaredVar" type="string" init-expr="testing declared variable" history="true"/>
+ </programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>Currently all variables are persisted in history as <literal>String</literal> values.
+ Variable (regardless of its type) will be converted to a string value using <literal>toString()</literal>
+ method. In case of custom objects they should override <literal>toString()</literal> method to provide string representation
+ of the variable that will be available as history record. This will provide an easy way for enabling convienient search
+ capabilities based on variable values. </para>
+ <para>Access to history variables is given via <literal>HistoryService</literal> methods:</para>
+ <itemizedlist>
+ <listitem><literal>Object getVariable(String processInstnceId, String name);</literal></listitem>
+ <listitem><literal>Map<String, Object> getVariables(String processInstnceId, Set<String> variableNames);</literal></listitem>
+ <listitem><literal>Set<String> getVariableNames(String processInstnceId);</literal></listitem>
+ </itemizedlist>
+ </section>
+
</chapter>
More information about the jbpm-commits
mailing list