### Eclipse Workspace Patch 1.0
#P jbpm4
Index: modules/examples/src/test/resources/org/jbpm/examples/variable/declared/simple-process.jpdl.xml
===================================================================
--- modules/examples/src/test/resources/org/jbpm/examples/variable/declared/simple-process.jpdl.xml (revision 0)
+++ modules/examples/src/test/resources/org/jbpm/examples/variable/declared/simple-process.jpdl.xml (revision 0)
@@ -0,0 +1,14 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
Index: modules/examples/src/test/java/org/jbpm/examples/variable/declared/DeclaredCustomVariableTest.java
===================================================================
--- modules/examples/src/test/java/org/jbpm/examples/variable/declared/DeclaredCustomVariableTest.java (revision 0)
+++ modules/examples/src/test/java/org/jbpm/examples/variable/declared/DeclaredCustomVariableTest.java (revision 0)
@@ -0,0 +1,59 @@
+package org.jbpm.examples.variable.declared;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import org.jbpm.api.Execution;
+import org.jbpm.api.ProcessInstance;
+import org.jbpm.test.JbpmTestCase;
+
+
+public class DeclaredCustomVariableTest extends JbpmTestCase {
+
+ String deploymentId;
+
+ protected void setUp() throws Exception {
+ super.setUp();
+
+ deploymentId = repositoryService.createDeployment()
+ .addResourceFromClasspath("org/jbpm/examples/variable/declared/custom-process.jpdl.xml")
+ .deploy();
+ }
+
+ protected void tearDown() throws Exception {
+ repositoryService.deleteDeploymentCascade(deploymentId);
+
+ super.tearDown();
+ }
+
+ public void testExistenceOfDeclaredVariable() {
+
+ ProcessInstance processInstance = executionService.startProcessInstanceByKey("CustomDeclaredVariable");
+ String processInstanceId = processInstance.getId();
+
+ Set expectedVariableNames = new HashSet();
+ expectedVariableNames.add("declaredVar");
+
+ // get all variable names for the process instance
+ Set variableNames = executionService.getVariableNames(processInstanceId);
+
+ assertEquals(expectedVariableNames, variableNames);
+
+ // get declared variable
+ HistoryVariable variableValue = (HistoryVariable) executionService.getVariable(processInstanceId, "declaredVar");
+
+ assertNotNull(variableValue);
+ assertEquals("History", variableValue.getName());
+
+ // signal execution to end process
+ Execution exc = executionService.signalExecutionById(processInstanceId);
+
+ assertEquals(ProcessInstance.STATE_ENDED, exc.getState());
+
+ // check value stored in history
+ String variableValueStr = (String) historyService.getVariable(processInstanceId, "declaredVar");
+ assertTrue(variableValueStr.startsWith("Class: " + HistoryVariable.class.getName()));
+
+ }
+
+}
Index: modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml
===================================================================
--- modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml (revision 6285)
+++ modules/userguide/src/main/docbook/en/modules/ch07-Variables.xml (working copy)
@@ -114,4 +114,143 @@
+
+ Declared variables
+ (Since jBPM 4.4)
+
+ 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.
+
+ There are several possible ways for declaring variable:
+
+ declare String variable initialized with static text
+
+<variable name="declaredVar" type="string" init-expr="testing declared variable"/>
+
+
+ declare custom variable initialized with EL
+
+<variable name="declaredVar" type="long" init-expr="#{anotherVar}"/>
+
+
+ declare custom variable initialized with serializable class
+
+<variable name="declaredVar" type="serializable" >
+ <object class="org.jbpm.examples.variable.declared.HistoryVariable" />
+</variable>
+
+
+
+ As shown above variable values can be assigned in two ways: using attribute init-expr or
+ by nesting init descriptor (element object) within variable tags.
+
+
+ Note: Only one of value assignment can be used for a variable declaration.
+
+
Attribute for <literal>variable</literal> element:
+
+
+
+ Attribute
+ Type
+ Default
+ Required?
+ Description
+
+
+
+
+ name
+ text
+
+ required
+ name of the variable
+
+
+ type
+ text
+
+ required
+ type of the variable, must refer to types defined in jbpm.variable.types.xml
+
+
+ init-expr
+ text (EL expression)
+
+ optional
+ value for the variable, this attribute or nested element must be given
+
+
+ init-expr-type
+ text
+ UEL
+ optional
+ defines language for expression evaluation
+
+
+ history
+ boolean
+ false
+ optional
+ indicates wheater variable should be stored in history or not - default false,
+ for more information about history see
+
+
+
+
+
+
Nested element for <literal>variable</literal>:
+
+
+
+ Element
+ Multiplicity
+ Description
+
+
+
+
+ object
+ 1
+ Value for the variable as custom object, either this element or init-expr attribute must be specified
+
+
+
+
+
+
+
+ Variables history
+ (Since jBPM 4.4)
+
+ 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.
+
+ History can be enabled for variable in two ways:
+
+ via public API ExecutionService:
+
+ void setVariable(String executionId, String name, Object value, boolean historyEnabled);
+ void setVariables(String executionId, Map<String, ?> variables, boolean historyEnabled);
+
+
+ on variable declaration
+
+<variable name="declaredVar" type="string" init-expr="testing declared variable" history="true"/>
+
+
+
+ Currently all variables are persisted in history as String values.
+ Variable (regardless of its type) will be converted to a string value using toString()
+ method. In case of custom objects they should override toString() 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.
+ Access to history variables is given via HistoryService methods:
+
+ Object getVariable(String processInstnceId, String name);
+ Map<String, Object> getVariables(String processInstnceId, Set<String> variableNames);
+ Set<String> getVariableNames(String processInstnceId);
+
+
+
Index: modules/examples/src/test/java/org/jbpm/examples/variable/declared/DeclaredVariableTest.java
===================================================================
--- modules/examples/src/test/java/org/jbpm/examples/variable/declared/DeclaredVariableTest.java (revision 0)
+++ modules/examples/src/test/java/org/jbpm/examples/variable/declared/DeclaredVariableTest.java (revision 0)
@@ -0,0 +1,53 @@
+package org.jbpm.examples.variable.declared;
+
+
+import java.util.HashSet;
+import java.util.Set;
+
+import org.jbpm.api.Execution;
+import org.jbpm.api.ProcessInstance;
+import org.jbpm.test.JbpmTestCase;
+
+
+public class DeclaredVariableTest extends JbpmTestCase {
+
+ String deploymentId;
+
+ protected void setUp() throws Exception {
+ super.setUp();
+
+ deploymentId = repositoryService.createDeployment()
+ .addResourceFromClasspath("org/jbpm/examples/variable/declared/simple-process.jpdl.xml")
+ .deploy();
+ }
+
+ protected void tearDown() throws Exception {
+ repositoryService.deleteDeploymentCascade(deploymentId);
+
+ super.tearDown();
+ }
+
+ public void testExistenceOfDeclaredVariable() {
+
+ ProcessInstance processInstance = executionService.startProcessInstanceByKey("DeclaredVariable");
+
+ Set expectedVariableNames = new HashSet();
+ expectedVariableNames.add("declaredVar");
+
+ // get all variable names for the process instance
+ Set variableNames = executionService.getVariableNames(processInstance.getId());
+
+ assertEquals(expectedVariableNames, variableNames);
+
+ // get declared variable
+ String variableValue = (String) executionService.getVariable(processInstance.getId(), "declaredVar");
+
+ assertEquals("testing declared variable", variableValue);
+
+ // signal execution to end process
+ Execution exc = executionService.signalExecutionById(processInstance.getId());
+
+ assertEquals(ProcessInstance.STATE_ENDED, exc.getState());
+ }
+
+}
Index: modules/examples/src/test/resources/org/jbpm/examples/variable/declared/custom-process.jpdl.xml
===================================================================
--- modules/examples/src/test/resources/org/jbpm/examples/variable/declared/custom-process.jpdl.xml (revision 0)
+++ modules/examples/src/test/resources/org/jbpm/examples/variable/declared/custom-process.jpdl.xml (revision 0)
@@ -0,0 +1,16 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
Index: modules/examples/src/test/java/org/jbpm/examples/variable/declared/HistoryVariable.java
===================================================================
--- modules/examples/src/test/java/org/jbpm/examples/variable/declared/HistoryVariable.java (revision 0)
+++ modules/examples/src/test/java/org/jbpm/examples/variable/declared/HistoryVariable.java (revision 0)
@@ -0,0 +1,70 @@
+package org.jbpm.examples.variable.declared;
+
+import java.io.Serializable;
+import java.util.Date;
+
+
+public class HistoryVariable implements Serializable {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 1L;
+
+ private String name;
+ private String value;
+ private String text;
+
+ public HistoryVariable() {
+ this.name = "History";
+ this.value = "Created at " + new Date();
+ this.text = "I am going to be stored in history as variable!!!";
+ }
+
+
+ public String getName() {
+ return name;
+ }
+
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+
+ public String getValue() {
+ return value;
+ }
+
+
+ public void setValue(String value) {
+ this.value = value;
+ }
+
+
+ public String getText() {
+ return text;
+ }
+
+
+ public void setText(String text) {
+ this.text = text;
+ }
+
+
+ @Override
+ public String toString() {
+
+ // value returned by this method will be stored as variable in history
+
+ StringBuffer buffer = new StringBuffer();
+ buffer.append("Class: " + this.getClass().getName() + "{");
+ buffer.append("name: " + this.name + ";");
+ buffer.append("value: " + this.value + ";");
+ buffer.append("text: " + this.text + "}");
+ return buffer.toString();
+ }
+
+
+
+}
Index: modules/examples/src/test/resources/org/jbpm/examples/variable/history/process.jpdl.xml
===================================================================
--- modules/examples/src/test/resources/org/jbpm/examples/variable/history/process.jpdl.xml (revision 0)
+++ modules/examples/src/test/resources/org/jbpm/examples/variable/history/process.jpdl.xml (revision 0)
@@ -0,0 +1,14 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
Index: modules/examples/src/test/java/org/jbpm/examples/variable/history/HistoryEnabledVariableTest.java
===================================================================
--- modules/examples/src/test/java/org/jbpm/examples/variable/history/HistoryEnabledVariableTest.java (revision 0)
+++ modules/examples/src/test/java/org/jbpm/examples/variable/history/HistoryEnabledVariableTest.java (revision 0)
@@ -0,0 +1,100 @@
+package org.jbpm.examples.variable.history;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import org.jbpm.api.Execution;
+import org.jbpm.api.ProcessInstance;
+import org.jbpm.test.JbpmTestCase;
+
+
+public class HistoryEnabledVariableTest extends JbpmTestCase {
+
+ String deploymentId;
+
+ protected void setUp() throws Exception {
+ super.setUp();
+
+ deploymentId = repositoryService.createDeployment()
+ .addResourceFromClasspath("org/jbpm/examples/variable/history/process.jpdl.xml")
+ .deploy();
+ }
+
+ protected void tearDown() throws Exception {
+ repositoryService.deleteDeploymentCascade(deploymentId);
+
+ super.tearDown();
+ }
+
+ public void testExistenceOfDeclaredVariable() {
+
+ ProcessInstance processInstance = executionService.startProcessInstanceByKey("HistoryDeclaredVariable");
+ String processInstanceId = processInstance.getId();
+
+ Set expectedVariableNames = new HashSet();
+ expectedVariableNames.add("declaredVar");
+
+ // get all variable names for the process instance
+ Set variableNames = executionService.getVariableNames(processInstanceId);
+
+ assertEquals(expectedVariableNames, variableNames);
+
+ // get declared variable
+ String variableValue = (String) executionService.getVariable(processInstanceId, "declaredVar");
+
+ assertEquals("testing declared variable", variableValue);
+
+ // signal execution to end process
+ Execution exc = executionService.signalExecutionById(processInstanceId);
+
+ assertEquals(ProcessInstance.STATE_ENDED, exc.getState());
+
+ // check if variable is stored in history
+ variableNames = historyService.getVariableNames(processInstanceId);
+ assertEquals(expectedVariableNames, variableNames);
+
+ variableValue = (String) historyService.getVariable(processInstanceId, "declaredVar");
+ assertEquals("testing declared variable", variableValue);
+ }
+
+public void testSetVariableWithHistoryEnabled() {
+
+ ProcessInstance processInstance = executionService.startProcessInstanceByKey("HistoryDeclaredVariable");
+ String processInstanceId = processInstance.getId();
+
+ // set additional variable
+ executionService.setVariable(processInstanceId, "addedVar", "will be stored in history", true);
+
+ Set expectedVariableNames = new HashSet();
+ expectedVariableNames.add("declaredVar");
+ expectedVariableNames.add("addedVar");
+
+ // get all variable names for the process instance
+ Set variableNames = executionService.getVariableNames(processInstanceId);
+
+ assertEquals(expectedVariableNames, variableNames);
+
+ // get declared variable
+ String variableValue = (String) executionService.getVariable(processInstanceId, "declaredVar");
+ assertEquals("testing declared variable", variableValue);
+
+ // get added variable
+ variableValue = (String) executionService.getVariable(processInstanceId, "addedVar");
+ assertEquals("will be stored in history", variableValue);
+
+ // signal execution to end process
+ Execution exc = executionService.signalExecutionById(processInstanceId);
+
+ assertEquals(ProcessInstance.STATE_ENDED, exc.getState());
+
+ // check if variable is stored in history
+ variableNames = historyService.getVariableNames(processInstanceId);
+ assertEquals(expectedVariableNames, variableNames);
+
+ variableValue = (String) historyService.getVariable(processInstanceId, "declaredVar");
+ assertEquals("testing declared variable", variableValue);
+ variableValue = (String) historyService.getVariable(processInstanceId, "addedVar");
+ assertEquals("will be stored in history", variableValue);
+ }
+
+}