[jbpm-commits] JBoss JBPM SVN: r6552 - in jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US: extras and 1 other directories.

Author: dlesage Date: 2010-08-08 20:42:27 -0400 (Sun, 08 Aug 2010) New Revision: 6552 Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/async_1.sql jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/cal3.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/cal4.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/calendar_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/calendar_2.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/code_example_tutorial_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/con1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_10.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_11.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_2.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_2.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_3.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_4.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_5.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_6.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_7.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_8.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_9.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_a.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_b.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_2.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_2.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_3.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_4.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_5.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_6.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/differentmethods.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_2.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_3.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_4.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_5.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_6.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/jpdl_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_2.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_3.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_4.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_5.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_6.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_0.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_10.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_11.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_12.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_13.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_14.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_15.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_16.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_17.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_18.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_2.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_3.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_4.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_5.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_6.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_7.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_8.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_9.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_2.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_2.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_3.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_3.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_4.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_5.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_6.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_7.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_8.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_2.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_2.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_3.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_3.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_4.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_4.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_5.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_5.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_6.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_6.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_7.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_7.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_8.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/pluggable_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/scheduler_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_2.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_2.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_3.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_3.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_4.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_5.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_2.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_3.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_4.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/timer1.xmlt jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_1.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_2.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_3.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_4.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_5.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_6.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_7.java jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/assignment.model.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/async.continuation.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/async1.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/asynchronous.continuations.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/auction.process.graph.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/auction.test.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/bpm.product.continuum.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/concurrent.executions.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/create_database.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/database.update.example.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/db.factory.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/designer.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/example.process.language.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/example.process.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/execution.class.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/execution.event.method.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/graph.execution.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/graphexecution.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hello.world.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hidden.actions.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hsqldb_dbm.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hsqldb_mbean.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/identity.model.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/improved.bpm.approach.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/install_driver.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/jmx_console.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/languages.overview.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/load_mysql_shell1.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/load_mysql_shell2.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/logging.model.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mixed.responsibilities.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/model.transformations.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mysql_admin.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mysql_create_database.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/new.execution.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/node.execute.method.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/node.transition.classes.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/overview.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/persistence.api.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/pluggable.architecture.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/pojo.command.executor.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/responsibility.matrix.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/scheduler.classes.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/scheduler.overview.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/service.orchestration.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/task.controllers.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/title_logo.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/traditional.bpm.approach.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/transition.take.method.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/two.dim.fragmentation.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/update.erp.example.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/wait.state.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/workflow.landscape.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_Reference_Guide.ent jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_Reference_Guide.xml Removed: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_jPDL_User_Guide.ent jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_jPDL_User_Guide.xml Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/Book_Info.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/Legal_Notice.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/async.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/calendar.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/configuration.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/context.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/enterprise.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/introduction.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jpdl.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/logging.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/mail.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/modelling.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/persistence.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/scheduler.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/taskmgmt.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/tdd.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/tutorial.xml Log: Grammar and coding patches - phase 2 Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/Book_Info.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/Book_Info.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/Book_Info.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -7,7 +7,7 @@ <title>jBPM User Guide</title> <subtitle>Guide to using and developing with jBPM 3</subtitle> <productname>jBPM</productname> - <productnumber>3.2.10-SNAPSHOT</productnumber> + <productnumber>3.2.10</productnumber> <edition>1</edition> <pubsnumber>1</pubsnumber> <!-- ignore, needed by redhat pubs system --> <abstract> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/Legal_Notice.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/Legal_Notice.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/Legal_Notice.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -1,12 +1,12 @@ <?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "jBPM_jPDL_User_Guide.ent"> +<!ENTITY % BOOK_ENTITIES SYSTEM "jBPM_Reference_Guide.ent"> %BOOK_ENTITIES; ]> <legalnotice lang="en-US"> <para> - Copyright <trademark class="copyright"></trademark> &YEAR; &HOLDER;. + Copyright <trademark class="copyright"></trademark> 2010 the jBPM Project. </para> <para> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/async.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/async.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/async.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -106,8 +106,12 @@ </para> <figure id="asynchronous.continuations.image"> - <title>Example 2: A process with asynchronous continuations</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/asynchronous.continuations.gif"/></imageobject></mediaobject> + <title>A Process with Asynchronous Continuations</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/asynchronous.continuations.png"/> + </imageobject> + </mediaobject> </figure> <para> @@ -211,11 +215,7 @@ this query will only update one row in exactly one of the competing transactions. </para> - <programlisting>update JBPM_JOB job -set job.version = 2 - job.lockOwner = '192.168.1.3:2' -where - job.version = 1</programlisting> + <programlisting language="SQL"><xi:include href="extras/async_1.sql" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> @@ -256,9 +256,9 @@ message in the database. The command executor filters out all messages that contain an exception. </para> - <figure id="job.executor.image"> - <title>Job executor transactions</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/pojo.command.executor.gif"/></imageobject></mediaobject> + <figure id="pojo.command.executor.image"> + <title>POJO command executor transactions</title> + <mediaobject><imageobject><imagedata fileref="images/pojo.command.executor.png"/></imageobject></mediaobject> </figure> <para> If the transaction that adds the exception to the command message fails, it @@ -275,4 +275,5 @@ </section> + </chapter> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/calendar.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/calendar.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/calendar.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -5,7 +5,7 @@ ]> <chapter id="businesscalendar"> - <title> + <title> Business Calendar </title> @@ -98,21 +98,12 @@ <para> The following uses are all valid: </para> - - <programlisting>&lt;timer name="daysBeforeHoliday" duedate="5 business days"&gt;...&lt;/timer&gt; - -&lt;timer name="pensionDate" duedate="#{dateOfBirth} + 65 years" &gt;...&lt;/timer&gt; - -&lt;timer name="pensionReminder" duedate="#{dateOfPension} - 1 year" &gt;...&lt;/timer&gt; - -&lt;timer name="fireWorks" duedate="#{chineseNewYear} repeat="1 year" &gt;...&lt;/timer&gt; - -&lt;reminder name="hitBoss" duedate="#{payRaiseDay} + 3 days" repeat="1 week" /&gt; -</programlisting> + <programlisting language="XML"><xi:include href="extras/timer1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + </section> </section> - </section> - <section id="calendarconfiguration"> + <section id="calendarconfiguration"> <title> Calendar Configuration </title> @@ -128,40 +119,27 @@ This is the default business hour specification found in <filename>jbpm.business.calendar.properties</filename>: </para> - <programlisting>hour.format=HH:mm -#weekday ::= [&lt;daypart&gt; [&amp; &lt;daypart&gt;]*] -#daypart ::= &lt;start-hour&gt;-&lt;to-hour&gt; -#start-hour and to-hour must be in the hour.format -#dayparts have to be ordered -weekday.monday= 9:00-12:00 &amp; 12:30-17:00 -weekday.tuesday= 9:00-12:00 &amp; 12:30-17:00 -weekday.wednesday= 9:00-12:00 &amp; 12:30-17:00 -weekday.thursday= 9:00-12:00 &amp; 12:30-17:00 -weekday.friday= 9:00-12:00 &amp; 12:30-17:00 -weekday.saturday= -weekday.sunday= + + <programlisting><xi:include href="extras/calendar_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> -day.format=dd/MM/yyyy -# holiday syntax: &lt;holiday&gt; -# holiday period syntax: &lt;start-day&gt;-&lt;end-day&gt; -# below are the belgian official holidays -holiday.1= 01/01/2005 # nieuwjaar -holiday.2= 27/3/2005 # pasen -holiday.3= 28/3/2005 # paasmaandag -holiday.4= 1/5/2005 # feest van de arbeid -holiday.5= 5/5/2005 # hemelvaart -holiday.6= 15/5/2005 # pinksteren -holiday.7= 16/5/2005 # pinkstermaandag -holiday.8= 21/7/2005 # my birthday -holiday.9= 15/8/2005 # moederkesdag -holiday.10= 1/11/2005 # allerheiligen -holiday.11= 11/11/2005 # wapenstilstand -holiday.12= 25/12/2005 # kerstmis + <section id="duedateExample"> + <title> + Examples + </title> -business.day.expressed.in.hours= 8 -business.week.expressed.in.hours= 40 -business.month.expressed.in.business.days= 21 -business.year.expressed.in.business.days= 220</programlisting> - + <para> + The following examples demonstrate different ways in which it + can be used: + </para> + + <programlisting><xi:include href="extras/cal3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <programlisting><xi:include href="extras/cal4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + +<para> + Having studied this chapter, the reader now understands how the Business + Calendar works. +</para> </section> -</chapter> \ No newline at end of file +</chapter> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/configuration.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/configuration.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/configuration.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -14,7 +14,7 @@ jBPM. </para> - <para> + <para> The simplest way to configure the Business Process Manager is by putting the <filename>jbpm.cfg.xml</filename> configuration file into the root of the classpath. If the file is not available for use as a @@ -40,8 +40,8 @@ </para> </note> - <programlisting>static JbpmConfinguration jbpmConfiguration = JbpmConfinguration.parseResource("my.jbpm.cfg.xml");</programlisting> - + <programlisting language="Java"><xi:include href="extras/differentmethods.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> The <classname>JbpmConfiguration</classname> is "thread safe" and, hence, can be kept in a <firstterm>static member</firstterm>. @@ -55,94 +55,25 @@ <firstterm>context blocks</firstterm> which looks like this: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); -try { - // This is what we call a context block. - // Here you can perform workflow operations + <programlisting language="Java"><xi:include href="extras/configuration_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -} finally { - jbpmContext.close(); -}</programlisting> - - <para> + <para> The <classname>JbpmContext</classname> makes both a set of services and the configuration settings available to the Business Process Manager. The services are configured by the values in the <filename>jbpm.cfg.xml</filename> file. They make it possible for the jBPM to run in any Java environment, using whatever services are available within said environment. - </para> + </para> - <para> + <para> Here are the default configuration settings for the <classname>JbpmContext</classname>: </para> + <programlisting language="XML"><xi:include href="extras/configuration_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -<programlisting><![CDATA[<jbpm-configuration> - - <jbpm-context> - <service name="authentication" factory="org.jbpm.security.authentication.DefaultAuthenticationServiceFactory" /> - <service name="logging" factory="org.jbpm.logging.db.DbLoggingServiceFactory" /> - <service name="message" factory="org.jbpm.msg.db.DbMessageServiceFactory" /> - <service name="persistence" factory="org.jbpm.persistence.db.DbPersistenceServiceFactory" /> - <service name="scheduler" factory="org.jbpm.scheduler.db.DbSchedulerServiceFactory" /> - <service name="tx" factory="org.jbpm.tx.TxServiceFactory" /> - </jbpm-context> - <!-- database persistence configuration --> - <string name="resource.hibernate.cfg.xml" value="hibernate.cfg.xml" /> - <!-- additional database persistence properties - <string name="resource.hibernate.properties" value="hibernate.properties" /> - --> - - <!-- entries pointing to default configuration resources in jbpm-jpdl.jar --> - <string name="resource.business.calendar" value="org/jbpm/calendar/jbpm.business.calendar.properties" /> - <string name="resource.default.modules" value="org/jbpm/graph/def/jbpm.default.modules.properties" /> - <string name="resource.converter" value="org/jbpm/db/hibernate/jbpm.converter.properties" /> - <string name="resource.action.types" value="org/jbpm/graph/action/action.types.xml" /> - <string name="resource.node.types" value="org/jbpm/graph/node/node.types.xml" /> - <string name="resource.parsers" value="org/jbpm/jpdl/par/jbpm.parsers.xml" /> - <string name="resource.varmapping" value="org/jbpm/context/exe/jbpm.varmapping.xml" /> - <string name="resource.mail.templates" value="jbpm.mail.templates.xml" /> - - <!-- alternate delegation class loader - <string name="jbpm.class.loader" value="context" /> - --> - <bean name="process.class.loader.factory" class="org.jbpm.instantiation.SharedProcessClassLoaderFactory" singleton="true" /> - <bean name="jbpm.task.instance.factory" class="org.jbpm.taskmgmt.impl.DefaultTaskInstanceFactoryImpl" singleton="true" /> - - <!-- make sure the block size matches the length in ByteArray.hbm.xml --> - <int name="jbpm.byte.block.size" value="1024" singleton="true" /> - - <bean name="jbpm.expression.evaluator" class="org.jbpm.jpdl.el.impl.ExpressionEvaluatorImpl" singleton="true" /> - <bean name="jbpm.variable.resolver" class="org.jbpm.jpdl.el.impl.JbpmVariableResolver" singleton="true" /> - <!-- custom function mapper - <bean name="jbpm.function.mapper" class="org.example.FunctionMapperImpl" /> - --> - <!-- user code interceptor - <bean name="jbpm.user.code.interceptor" class="org.example.UserCodeInterceptorImpl" /> - --> - - <!-- mail settings --> - <string name="jbpm.mail.smtp.host" value="localhost" /> - <string name="jbpm.mail.from.address" value="jbpm@noreply" /> - <bean name="jbpm.mail.address.resolver" class="org.jbpm.identity.mail.IdentityAddressResolver" singleton="true" /> - - <bean name="jbpm.job.executor" class="org.jbpm.job.executor.JobExecutor"> - <property name="jbpmConfiguration"><ref bean="jbpmConfiguration" /></property> - <property name="name"><string value="JbpmJobExecutor" /></property> - <property name="nbrOfThreads"><int value="1" /></property> - <property name="retries"><int value="3" /></property> - <property name="idleInterval"><int value="5000" /></property> - <property name="maxIdleInterval"><int value="3600000" /><!-- 1 hour --></property> - <property name="maxLockTime"><int value="600000" /><!-- 10 minutes --></property> - <property name="lockMonitorInterval"><int value="60000" /><!-- 1 minute --></property> - <property name="lockBufferTime"><int value="5000" /><!-- 5 seconds --></property> - </bean> - -</jbpm-configuration>]]></programlisting> - <para> The above file contains three parts: </para> @@ -185,30 +116,15 @@ connection (without the need for a transaction manager.) </para> - - <para> + <para> <classname>JbpmContext</classname> contains <firstterm>convenience methods</firstterm> for most of the common process operations. They are demonstrated in this code sample: </para> -<programlisting> public void deployProcessDefinition(ProcessDefinition processDefinition) {...} - public List getTaskList() {...} - public List getTaskList(String actorId) {...} - public List getGroupTaskList(List actorIds) {...} - public TaskInstance loadTaskInstance(long taskInstanceId) {...} - public TaskInstance loadTaskInstanceForUpdate(long taskInstanceId) {...} - public Token loadToken(long tokenId) {...} - public Token loadTokenForUpdate(long tokenId) {...} - public ProcessInstance loadProcessInstance(long processInstanceId) {...} - public ProcessInstance loadProcessInstanceForUpdate(long processInstanceId) {...} - public ProcessInstance newProcessInstance(String processDefinitionName) {...} - public void save(ProcessInstance processInstance) {...} - public void save(Token token) {...} - public void save(TaskInstance taskInstance) {...} - public void setRollbackOnly() {...}</programlisting> + <programlisting language="Java"><xi:include href="extras/configuration_2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> +<note> <para> There is no need to call any of the save methods explicitly because the <methodname>XxxForUpdate</methodname> methods are @@ -249,7 +165,7 @@ </para> <section id="customizingfactories"> - <title> + <title> Customizing Factories </title> @@ -273,20 +189,18 @@ configuration: for that: <code>log4j.logger.org.hibernate.event.def.AbstractFlushingEventListener=FATAL</code> </para> - <programlisting> ... - &lt;service name='persistence' factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt;</programlisting> - <para>If specific properties on a service need to be specified, the short notation can't be used, but instead, - the long notation has to be used like this: E.g. + + <programlisting language="XML"><xi:include href="extras/persistence.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + +<important> + <para> + If one needs to note specific properties on a service, only the long + notation can be used. </para> - <programlisting> &lt;service name="persistence"&gt; - &lt;factory&gt; - &lt;bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"&gt; - &lt;field name="dataSourceJndiName"&gt;&lt;string value="java:/myDataSource"/&gt;&lt;/field&gt; - &lt;field name="isCurrentSessionEnabled"&gt;&lt;true /&gt;&lt;/field&gt; - &lt;field name="isTransactionEnabled"&gt;&lt;false /&gt;&lt;/field&gt; - &lt;/bean&gt; - &lt;/factory&gt; - &lt;/service&gt; </programlisting> +</important> + + <programlisting language="XML"><xi:include href="extras/configuration_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> <section id="configurationproperties"> @@ -489,74 +403,18 @@ <application>log4j</application> by using the following configuration: </para> - - - <programlisting>&lt;boolean name="jbpm.hide.stale.object.exceptions" value="false" /&gt;</programlisting> - - </section> - <section id="configuringjobexecutor"> - <title>Configuring the job executor</title> - - <para>The job executor exposes a few properties you can tune. To change any of the - values described below, edit the <literal>jbpm.job.executor</literal> bean in - <literal>jbpm.cfg.xml</literal>. The role of the job executor is described with - great detail in <xref linkend="thejobexecutor"></xref>. + <programlisting language="XML"><xi:include href="extras/configuration_a.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> + In order to log jBPM stack traces, add the following line to the + <filename>jbpm.cfg.xml</filename> file: </para> - <table><title>Job executor properties</title> - <tgroup cols='3'> - <colspec colname='attr' colwidth="*" /> - <colspec colname='desc' colwidth="4*" /> - <colspec colname="def" colwidth="*"/> - - <thead> - <row> - <entry>Property</entry> - <entry>Description</entry> - <entry>Default</entry> - </row> - </thead> + <programlisting language="XML"><xi:include href="extras/configuration_b.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <tbody> - <row> - <entry>nbrOfThreads</entry> - <entry>Size of the job executor thread pool</entry> - <entry>1</entry> - </row> - <row> - <entry>retries</entry> - <entry>Number of times the job executor retries a failed job</entry> - <entry>3</entry> - </row> - <row> - <entry>idleInterval</entry> - <entry>Period between checks for new jobs (milliseconds)</entry> - <entry>5 seconds</entry> - </row> - <row> - <entry>maxIdleInterval</entry> - <entry>When a job fails, the affected thread pauses for a period initially equal - to <literal>idleInterval</literal>, which is increased twofold until it reaches - <literal>maxIdleInterval</literal> (milliseconds)</entry> - <entry>1 hour</entry> - </row> - <row> - <entry>maxLockTime</entry> - <entry>Amount of time a job executor thread is allowed to hold a job before - the job is released and offered to other threads (milliseconds)</entry> - <entry>10 minutes</entry> - </row> - <row> - <entry>lockMonitorInterval</entry> - <entry>Period between checks for job lock times (milliseconds)</entry> - <entry>1 minute</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - + </section> + <section id="objectfactory"> <title>Object Factory</title> <para> @@ -573,135 +431,59 @@ basic <firstterm>types</firstterm> and Java beans from such a configuration, as shown in the following examples: </para> - <programlisting>&lt;beans&gt; - &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance"/&gt; - &lt;string name="greeting"&gt;hello world&lt;/string&gt; - &lt;int name="answer"&gt;42&lt;/int&gt; - &lt;boolean name="javaisold"&gt;true&lt;/boolean&gt; - &lt;float name="percentage"&gt;10.2&lt;/float&gt; - &lt;double name="salary"&gt;100000000.32&lt;/double&gt; - &lt;char name="java"&gt;j&lt;/char&gt; - &lt;null name="dusttodust" /&gt; -&lt;/beans&gt; + + <programlisting language="XML"><xi:include href="extras/configuration_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> ---------------------------------------------------------- + <programlisting language="Java"><xi:include href="extras/configuration_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -ObjectFactory of = ObjectFactory.parseXmlFromAbove(); -assertEquals(TaskInstance.class, of.getNewObject("task").getClass()); -assertEquals("hello world", of.getNewObject("greeting")); -assertEquals(new Integer(42), of.getNewObject("answer")); -assertEquals(Boolean.TRUE, of.getNewObject("javaisold")); -assertEquals(new Float(10.2), of.getNewObject("percentage")); -assertEquals(new Double(100000000.32), of.getNewObject("salary")); -assertEquals(new Character('j'), of.getNewObject("java")); -assertNull(of.getNewObject("dusttodust"));</programlisting> - - - <para> + <para> This code shows how to configure lists: </para> - <programlisting>&lt;beans&gt; - &lt;list name="numbers"&gt; - &lt;string&gt;one&lt;/string&gt; - &lt;string&gt;two&lt;/string&gt; - &lt;string&gt;three&lt;/string&gt; - &lt;/list&gt; -&lt;/beans&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/configuration_5.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <para> This code demonstrates how to configure maps: </para> - <programlisting>&lt;beans&gt; - &lt;map name="numbers"&gt; - &lt;entry&gt;&lt;key&gt;&lt;int&gt;1&lt;/int&gt;&lt;/key&gt;&lt;value&gt;&lt;string&gt;one&lt;/string&gt;&lt;/value&gt;&lt;/entry&gt; - &lt;entry&gt;&lt;key&gt;&lt;int&gt;2&lt;/int&gt;&lt;/key&gt;&lt;value&gt;&lt;string&gt;two&lt;/string&gt;&lt;/value&gt;&lt;/entry&gt; - &lt;entry&gt;&lt;key&gt;&lt;int&gt;3&lt;/int&gt;&lt;/key&gt;&lt;value&gt;&lt;string&gt;three&lt;/string&gt;&lt;/value&gt;&lt;/entry&gt; - &lt;/map&gt; -&lt;/beans&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/configuration_6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> Use <firstterm>direct field injection</firstterm> and property <systemitem>setter</systemitem> methods to configure beans: </para> - - <programlisting>&lt;beans&gt; - &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" &gt; - &lt;field name="name"&gt;&lt;string&gt;do dishes&lt;/string&gt;&lt;/field&gt; - &lt;property name="actorId"&gt;&lt;string&gt;theotherguy&lt;/string&gt;&lt;/property&gt; - &lt;/bean&gt; -&lt;/beans&gt;</programlisting> - <para> + <programlisting language="XML"><xi:include href="extras/configuration_7.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> Beans can be <firstterm>referenced</firstterm>. The referenced object doesn't have to be a bean; it can be a string, an integer or any other kind. Here is some code that demonstrates this capability: </para> - <programlisting>&lt;beans&gt; - &lt;bean name="a" class="org.jbpm.A" /> - &lt;ref name="b" bean="a" /> -&lt;/beans&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/configuration_8.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> Beans can be built with any constructor, as this code shows: </para> - <programlisting>&lt;beans&gt; - &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" &gt; - &lt;constructor&gt; - &lt;parameter class="java.lang.String"&gt; - &lt;string&gt;do dishes&lt;/string&gt; - &lt;/parameter&gt; - &lt;parameter class="java.lang.String"&gt; - &lt;string&gt;theotherguy&lt;/string&gt; - &lt;/parameter&gt; - &lt;/constructor&gt; - &lt;/bean&gt; -&lt;/beans&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/configuration_9.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> Beans can be constructed using a <methodname>factory</methodname> method: </para> - <programlisting>&lt;beans&gt; - &lt;bean name="taskFactory" - class="org.jbpm.UnexistingTaskInstanceFactory" - singleton="true"/&gt; + <programlisting language="XML"><xi:include href="extras/configuration_10.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" &gt; - &lt;constructor factory="taskFactory" method="createTask" &gt; - &lt;parameter class="java.lang.String"&gt; - &lt;string&gt;do dishes&lt;/string&gt; - &lt;/parameter&gt; - &lt;parameter class="java.lang.String"&gt; - &lt;string&gt;theotherguy&lt;/string&gt; - &lt;/parameter&gt; - &lt;/constructor&gt; - &lt;/bean&gt; -&lt;/beans&gt;</programlisting> - - <para> + <para> Beans can be constructed using a <methodname>static factory</methodname> method on a class: </para> - <programlisting>&lt;beans&gt; - &lt;bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" &gt; - &lt;constructor factory-class="org.jbpm.UnexistingTaskInstanceFactory" method="createTask" &gt; - &lt;parameter class="java.lang.String"&gt; - &lt;string&gt;do dishes&lt;/string&gt; - &lt;/parameter&gt; - &lt;parameter class="java.lang.String"&gt; - &lt;string&gt;theotherguy&lt;/string&gt; - &lt;/parameter&gt; - &lt;/constructor&gt; - &lt;/bean&gt; -&lt;/beans&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/configuration_11.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <para> Use the attribute <code>singleton="true"</code> to mark each named object as a <systemitem>singleton</systemitem>. Doing so will ensure that a given <classname>object factory</classname> always returns the @@ -736,10 +518,11 @@ the plain one is cleared every time a <methodname>getNewObject</methodname> method is started. </para> + <para> Having studied this chapter, one now has a thorough knowledge of the many ways in which the jBPM can be configured. - </para> + </para> </section> </chapter> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/context.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/context.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/context.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -34,18 +34,14 @@ instance in this manner: </para> -<programlisting>ProcessInstance processInstance = ...; -ContextInstance contextInstance = (ContextInstance) processInstance.getInstance(ContextInstance.class);</programlisting> +<programlisting language="Java"><xi:include href="extras/context_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <para> These are the basic operations: </para> -<programlisting>void ContextInstance.setVariable(String variableName, Object value); -void ContextInstance.setVariable(String variableName, Object value, Token token); -Object ContextInstance.getVariable(String variableName); -Object ContextInstance.getVariable(String variableName, Token token);</programlisting> - +<programlisting language="Java"><xi:include href="extras/context_2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> The variable name is <classname>java.lang.String</classname>. By default, the Business Process Manager supports the following @@ -74,14 +70,19 @@ </para> </note> - <para>To configure jBPM for storing hibernate persistent objects in the variables, - see Storing hibernate persistent objects. +<warning> + <para> + Do not save a process instance if there are any other types + stored in the process variables as this + will cause an exception error. </para> +</warning> + </section> -<section id="variablelifetime"> + <section id="variablelifetime"> <title> - Variable Life Time + Lifes of Variables </title> <para> @@ -92,9 +93,8 @@ variables can also be deleted. </para> -<programlisting>ContextInstance.deleteVariable(String variableName); -ContextInstance.deleteVariable(String variableName, Token token);</programlisting> - +<programlisting language="Java"><xi:include href="extras/context_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> Types can change automatically. This means that a type is allowed to overwrite a variable with a value of a different type. It is @@ -105,7 +105,7 @@ </section> <section id="variablepersistence"> - <title> + <title> Variable Persistence </title> @@ -147,7 +147,8 @@ example: </para> -<programlisting>ContextInstance.createVariable(String name, Object value, Token token);</programlisting> +<programlisting language="Java"><xi:include href="extras/context_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <section id="variableoverloading"> <title> @@ -194,6 +195,7 @@ To learn about task instance variables, read <xref linkend="taskinstancevariables" />. </para> + </section> </section> @@ -208,8 +210,8 @@ variable in a delegation class without storing it in the database. This can be achieved with <firstterm>transient variables</firstterm>. </para> - - <note> + +<note> <para> The lifespan of a transient variable is the same as that of a <systemitem>ProcessInstance</systemitem> Java object. @@ -231,119 +233,13 @@ <filename>processdefinition.xml</filename> file. </para> -<programlisting>Object ContextInstance.getTransientVariable(String name); -void ContextInstance.setTransientVariable(String name, Object value);</programlisting> - - </section> - - <section id="customizingvariablepersistence"> - <title>Customizing variable persistence</title> - - <para>Variables are stored in the database in a 2-step approach :</para> - -<programlisting>user-java-object &lt;---&gt; converter &lt;---&gt; variable instance</programlisting> - - <para>Variables are stored in <literal>VariableInstance</literal>s. - The members of <literal>VariableInstance</literal>s are mapped to fields - in the database with hibernate. In the default configuration of jBPM, - 6 types of VariableInstances are used:</para> - - <itemizedlist> - <listitem><para><literal>DateInstance</literal> (with one java.lang.Date - field that is mapped to a <literal>Types.TIMESTAMP</literal> in the - database)</para></listitem> - - <listitem><para><literal>DoubleInstance</literal> (with one java.lang.Double - field that is mapped to a <literal>Types.DOUBLE</literal> in the - database)</para></listitem> - - <listitem><para><literal>StringInstance</literal> (with one java.lang.String - field that is mapped to a <literal>Types.VARCHAR</literal> in the - database)</para></listitem> - - <listitem><para><literal>LongInstance</literal> (with one java.lang.Long - field that is mapped to a <literal>Types.BIGINT</literal> in the - database)</para></listitem> - - <listitem><para><literal>HibernateLongInstance</literal> (this is used for - hibernatable types with a long id field. One java.lang.Object field is mapped - as a reference to a hibernate entity in the database)</para></listitem> - - <listitem><para><literal>HibernateStringInstance</literal> (this is used for - hibernatable types with a string id field. One java.lang.Object field is mapped - as a reference to a hibernate entity in the database)</para></listitem> - </itemizedlist> - - <para><literal>Converter</literal>s convert between java-user-objects - and the java objects that can be stored by the - <literal>VariableInstance</literal>s. So when a process variable is set - with e.g. <literal>ContextInstance.setVariable(String variableName, Object value)</literal>, - the value will optionally be converted with a converter. Then the converted - object will be stored in a <literal>VariableInstance</literal>. - <literal>Converter</literal>s are implementations of the following - interface: </para> - -<programlisting>public interface Converter extends Serializable { - boolean supports(Object value); - Object convert(Object o); - Object revert(Object o); -}</programlisting> - - <para>Converters are optional. Converters must be available to - the jBPM class loader</para> - - <para>The way that user-java-objects are converted and stored in - variable instances is configured in the file - <literal>org/jbpm/context/exe/jbpm.varmapping.properties</literal>. - To customize this property file, put a modified version in the root of - the classpath, as explained in - Each line of the properties file specifies 2 or 3 class-names separated by spaces : - the classname of the user-java-object, optionally the classname of the converter - and the classname of the variable instance. When you refer your custom converters, - make sure they are in the jBPM class path . - When you refer to your custom variable instances, they also have to be in - the the jBPM class path and the hibernate - mapping file for <literal>org/jbpm/context/exe/VariableInstance.hbm.xml</literal> - has to be updated to include the custom subclass of VariableInstance. - </para> - - <para>For example, take a look at the following xml snippet in the file - <literal>org/jbpm/context/exe/jbpm.varmapping.xml</literal>.</para> - -<programlisting> &lt;jbpm-type&gt; - &lt;matcher&gt; - &lt;bean class="org.jbpm.context.exe.matcher.ClassNameMatcher"&gt; - &lt;field name="className"&gt;&lt;string value="java.lang.Boolean" /&gt;&lt;/field&gt; - &lt;/bean&gt; - &lt;/matcher&gt; - &lt;converter class="org.jbpm.context.exe.converter.BooleanToStringConverter" /&gt; - &lt;variable-instance class="org.jbpm.context.exe.variableinstance.StringInstance" /&gt; - &lt;/jbpm-type&gt;</programlisting> - - <para>This snippet specifies that all objects of type <literal>java.lang.Boolean</literal> have - to be converted with the converter <literal>BooleanToStringConverter</literal> and - that the resulting object (a String) will be stored in a variable instance object - of type StringInstance.</para> - - <para>If no converter is specified as in</para> - -<programlisting> &lt;jbpm-type&gt; - &lt;matcher&gt; - &lt;bean class="org.jbpm.context.exe.matcher.ClassNameMatcher"&gt; - &lt;field name="className"&gt;&lt;string value="java.lang.Long" /&gt;&lt;/field&gt; - &lt;/bean&gt; - &lt;/matcher&gt; - &lt;variable-instance class="org.jbpm.context.exe.variableinstance.LongInstance" /&gt; - &lt;/jbpm-type&gt;</programlisting> - - <para>that means that the Long objects that are put in the variables are just stored - in a variable instance of type LongInstance without being converted.</para> - - <para> +<programlisting language="Java"><xi:include href="extras/context_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> This chapter has covered process variables in great detail. The reader should now be confident that he or she understands this topic. </para> - </section> - + </section> + </chapter> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/enterprise.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/enterprise.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/enterprise.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -194,7 +194,7 @@ the <systemitem>command service</systemitem> bean. </para> - <para> + <para> The <systemitem>TimerEntityBean</systemitem> requires access to the Business Process Manager's data source. The Enterprise Java Bean deployment descriptor does not define how an entity bean is to map @@ -265,377 +265,298 @@ <title>jBPM Enterprise Configuration</title> - <para><literal>jbpm.cfg.xml</literal> includes the following configuration items: + <para> + The following configuration items are included in + <filename>jbpm.cfg.xml</filename>: </para> - <programlisting>&lt;jbpm-context&gt; - &lt;service name="persistence" - factory="org.jbpm.persistence.jta.JtaDbPersistenceServiceFactory" /&gt; - &lt;service name="message" - factory="org.jbpm.msg.jms.JmsMessageServiceFactory" /&gt; - &lt;service name="scheduler" - factory="org.jbpm.scheduler.ejbtimer.EntitySchedulerServiceFactory" /&gt; -&lt;/jbpm-context&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/enterprise_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para><literal>JtaDbPersistenceServiceFactory</literal> enables jBPM to participate in JTA - transactions. If an existing transaction is underway, the JTA persistence service clings to it; - otherwise it starts a new transaction. The jBPM enterprise beans are configured to delegate - transaction management to the container. However, if you create a JbpmContext in an environment - where no transaction is active (say, in a web application), one will be started automatically. - The JTA persistence service factory has the configurable fields described below. + <para> + The <classname>JtaDbPersistenceServiceFactory</classname> allows the + Business Process Manager to participate in JTA transactions. If an + existing transaction is underway, the JTA persistence service + "clings" to it; otherwise it starts a new transaction. The Business + Process Manager's enterprise beans are configured to delegate + transaction management to the container. However, a new one will be + started automatically if one creates a JbpmContext in an environment + in which no transaction is active (such as a web application.) The + JTA <systemitem>persistence service factory</systemitem> contains + the configurable fields described below. </para> - <variablelist> + <variablelist> - <varlistentry> - <term>isCurrentSessionEnabled</term> - - <listitem><para>if <literal>true</literal>, jBPM will - use the "current" Hibernate session associated with the ongoing JTA transaction. This is the - default setting. See the Hibernate guide, section <ulink - url="http://www.hibernate.org/hib_docs/v3/reference/en/html/architec... - 2.5 Contextual sessions</ulink> for a description of the behavior. You can take advantage - of the contextual session mechanism to use the same session used by jBPM in other parts - of your application through a call to <literal>SessionFactory.getCurrentSession()</literal>. - On the other hand, you might want to supply your own Hibernate session to jBPM. To do so, - set <literal>isCurrentSessionEnabled</literal> to <literal>false</literal> and inject the - session via the <literal>JbpmContext.setSession(session)</literal> method. This will also - ensure that jBPM uses the same Hibernate session as other parts of your application. Note, - the Hibernate session can be injected into a stateless session bean via a persistence context, - for example. - </para></listitem> - </varlistentry> + <varlistentry> + <term><property>isCurrentSessionEnabled</property></term> + <listitem> + <para> + When this is set to <code>true</code>, the Business Process + Manager will use the "current" + <application>Hibernate</application> session associated with + the ongoing JTA transaction. This is the default setting. + (See <ulink + url="http://www.hibernate.org/hib_docs/v3/reference/en/html/architec... + /> for more information.) + </para> + + <para> + Use the same session as by jBPM in other parts of the + application by taking advantage of the contextual + session mechanism. Do so through a call to + <methodname>SessionFactory.getCurrentSession()</methodname>. + Alternatively, supply a + <application>Hibernate</application> session to jBPM by + setting <property>isCurrentSessionEnabled</property> to + <code>false</code> and injecting the session via the + <methodname>JbpmContext.setSession(session)</methodname> + method. This also ensures that jBPM uses the same + <application>Hibernate</application> session as other + parts of the application. + </para> + + <note> + <para> + The <application>Hibernate</application> session can + be injected into a stateless session bean (via a + persistence context, for example.) + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term><property>isTransactionEnabled</property></term> + <listitem> + <para> + When this is set to <code>true</code>, jBPM will begin a + transaction through + <application>Hibernate</application>'s + <systemitem>transaction API</systemitem>, using the + <methodname>JbpmConfiguration.createJbpmContext()</methodname> + method to commit it. (The + <application>Hibernate</application> session is closed + when <methodname>JbpmContext.close()</methodname> is + called.) + </para> + <warning> + <para> + This is not the desired behavior when the Business + Process Manager is deployed as an EAR and hence + <property>isTransactionEnabled</property> is set to + <code>false</code> by default. (See <ulink + url="http://www.hibernate.org/hib_docs/v3/reference/en/html/transact... + /> for more details.) + </para> + </warning> + + </listitem> + </varlistentry> - <varlistentry> - <term>isTransactionEnabled</term> - - <listitem><para>a <literal>true</literal> value for this - field means jBPM will begin a transaction through Hibernate's transaction API (section <ulink - url="http://www.hibernate.org/hib_docs/v3/reference/en/html/transact... - 11.2. Database transaction demarcation</ulink> of the Hibernate manual shows the API) upon - <literal>JbpmConfiguration.createJbpmContext()</literal>, commit the transaction and close the - Hibernate session upon <literal>JbpmContext.close()</literal>. This is NOT the desired - behaviour when jBPM is deployed as an ear, hence <literal>isTransactionEnabled</literal> is set - to <literal>false</literal> by default. - </para></listitem> - </varlistentry> + </variablelist> + + + <para> + <systemitem>JmsMessageServiceFactory</systemitem> delivers + <systemitem>asynchronous continuation messages</systemitem> to the + <classname>JobListenerBean</classname> by leveraging the reliable + communication infrastructure exposed through the Java Message Service + interfaces. The <systemitem>JmsMessageServiceFactory</systemitem> + exposes the following configurable fields: + </para> - - - <para><literal>JmsMessageServiceFactory</literal> leverages the reliable communication - infrastructure exposed through JMS interfaces to deliver asynchronous continuation messages - to the <literal>JobListenerBean</literal>. The JMS message service factory exposes the following - configurable fields.</para> - - - <variablelist> - <varlistentry> - <term>connectionFactoryJndiName</term> - - <listitem><para>the JNDI name of the JMS connection - factory. Defaults to <literal>java:comp/env/jms/JbpmConnectionFactory</literal>. - </para></listitem> - </varlistentry> + <varlistentry> + <term><property>connectionFactoryJndiName</property></term> + <listitem> + <para> + This is the name of the JMS connection factory in the + JNDI initial context. It defaults to + <systemitem>java:comp/env/jms/JbpmConnectionFactory</systemitem>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>destinationJndiName</term> - - <listitem><para>the JNDI name of the JMS destination where - job messages are sent. Must match the destination where <literal>JobListenerBean</literal> - receives messages. Defaults to <literal>java:comp/env/jms/JobQueue</literal>. - </para></listitem> - </varlistentry> + <varlistentry> + <term><property>destinationJndiName</property></term> + <listitem> + <para> + This is the name of the JMS destination to which job + messages will be sent. It must match the destination + from which <systemitem>JobListenerBean</systemitem> + receives messages. It defaults to + <systemitem>java:comp/env/jms/JobQueue</systemitem>. + </para> + </listitem> + </varlistentry> - <varlistentry> - <term>isCommitEnabled</term> - - <listitem><para>tells whether the message service should - create a transacted session and either commit or rollback on close. Messages produced by the - JMS message service are never meant to be received before the database transaction commits. - The <ulink url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JMS7.html#wp9201... - tutorial</ulink> states "when you create a session in an enterprise bean, the container - ignores the arguments you specify, because it manages all transactional properties for - enterprise beans". Unfortunately the tutorial fails to indicate that said behavior is not - prescriptive. JBoss ignores the <literal>transacted</literal> argument if the - connection factory supports XA, since the overall JTA transaction controls the session. - Otherwise, <literal>transacted</literal> produces a locally transacted session. In <ulink - url="http://e-docs.bea.com/wls/docs103/jms/trans.html">Weblo...;, JMS transacted - sessions are agnostic to JTA transactions even if the connection factory is XA enabled. - With <literal>isCommitEnabled</literal> set to <literal>false</literal> (the default), - the message service creates a nontransacted, auto-acknowledging session. Such a session - works with containers that either disregard the creation arguments or do not bind - transacted sessions to JTA. Conversely, setting <literal>isCommitEnabled</literal> to - <literal>true</literal> causes the message service to create a transacted session and commit - or rollback according to the <literal>TxService.isRollbackOnly</literal> method. - </para></listitem> - </varlistentry> + <varlistentry> + <term><property>isCommitEnabled</property></term> + <listitem> + <para> + This specifies whether the Business Process Manager + should commit the Java Message Service session upon + <methodname>JbpmContext.close()</methodname>. Messages + produced by the JMS message service are never meant to + be received before the current transaction commits; + hence the sessions created by the service are always + transacted. The default value is <code>false</code>, + which is appropriate when the <systemitem>connection + factory</systemitem> in use is XA-capable, as the + messages produced by the Java Message Service session + will be controlled by the overall JTA transaction. This + field should be set to <code>true</code> if the JMS + connection factory is not XA-capable so that the + Business Process Manager explicitly commits the JMS + session's local transaction. + </para> + </listitem> + </varlistentry> + </variablelist> - <para><literal>EntitySchedulerServiceFactory</literal> builds on the transactional notification - service for timed events provided by the EJB container to schedule business process timers. The - EJB scheduler service factory has the configurable field described below. + + <para> + The <systemitem>EntitySchedulerServiceFactory</systemitem> is used + to schedule business process timers. It does so by building upon on + the transactional notification service for timed events provided by + the Enterprise Java Bean container. The EJB + <systemitem>scheduler service factory</systemitem> has the + configurable field described + below. </para> <variablelist> - <varlistentry> - <term>timerEntityHomeJndiName</term> - - <listitem><para>the name of the - <literal>TimerEntityBean</literal>'s local home interface in the JNDI initial context. - Defaults to <literal>java:comp/env/ejb/TimerEntityBean</literal>. - </para></listitem> - </varlistentry> - </variablelist> + <varlistentry> + <term><property>timerEntityHomeJndiName</property></term> + <listitem> + <para> + This is the name of the + <systemitem>TimerEntityBean</systemitem>'s local home + interface in the JNDI initial context. The default value + is + <systemitem>java:comp/env/ejb/TimerEntityBean</systemitem>. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> <section id="enterprisehibernateconfig"> - <title>Hibernate Enterprise Configuration</title> + <title> + Hibernate Enterprise Configuration + </title> - <para><literal>hibernate.cfg.xml</literal> includes the following configuration items that may - be modified to support other databases or application servers. + <para> + The <filename>hibernate.cfg.xml</filename> file includes the + following configuration items. Modify them to support other + databases or application servers. </para> - <programlisting>&lt;!-- sql dialect --&gt; -&lt;property name="hibernate.dialect"&gt;org.hibernate.dialect.HSQLDialect&lt;/property&gt; + <programlisting language="XML"><xi:include href="extras/enterprise_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -&lt;property name="hibernate.cache.provider_class"&gt; - org.hibernate.cache.HashtableCacheProvider -&lt;/property&gt; -&lt;!-- DataSource properties (begin) --&gt; -&lt;property name="hibernate.connection.datasource"&gt;java:comp/env/jdbc/JbpmDataSource&lt;/property&gt; -&lt;!-- DataSource properties (end) --&gt; - -&lt;!-- JTA transaction properties (begin) --> -&lt;property name="hibernate.transaction.factory_class"&gt; - org.hibernate.transaction.JTATransactionFactory -&lt;/property&gt; -&lt;property name="hibernate.transaction.manager_lookup_class"&gt; - org.hibernate.transaction.JBossTransactionManagerLookup -&lt;/property&gt; -&lt;!-- JTA transaction properties (end) --&gt; - -&lt;!-- CMT transaction properties (begin) === -&lt;property name="hibernate.transaction.factory_class"&gt; - org.hibernate.transaction.CMTTransactionFactory -&lt;/property&gt; -&lt;property name="hibernate.transaction.manager_lookup_class"&gt; - org.hibernate.transaction.JBossTransactionManagerLookup -&lt;/property&gt; -==== CMT transaction properties (end) --&gt;</programlisting> - - <para>You may replace the <literal>hibernate.dialect</literal> with one that corresponds to your - database management system. The Hibernate reference guide enumerates the available database - dialects in section <ulink - url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-... - 3.4.1 SQL dialects</ulink>. + <para> + Replace the <code>hibernate.dialect</code> setting with that which + is appropriate for one's database management system. (For more + information, read <ulink + url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-... + />.) </para> - <para><literal>HashtableCacheProvider</literal> can be replaced with other - supported cache providers. Refer to section <ulink - url="http://www.hibernate.org/hib_docs/v3/reference/en/html/performa... - 19.2 The second level cache</ulink> of the Hibernate manual for a list of the - supported cache providers. + <para> + The <systemitem>HashtableCacheProvider</systemitem> can be replaced + with other supported cache providers. (Refer to <ulink + url="http://www.hibernate.org/hib_docs/v3/reference/en/html/performa... + /> for more information.) </para> - <para>The <literal>JBossTransactionManagerLookup</literal> may be replaced with a strategy - appropriate to applications servers other than JBoss. See section <ulink - url="http://www.hibernate.org/hib_docs/v3/reference/en/html/session-... - 3.8.1 Transaction strategy configuration</ulink> to find the lookup class that - corresponds to each application server. + <para> + Out of the box, jBPM is configured to use the + <systemitem>JTATransactionFactory</systemitem>. If an existing + transaction is underway, the JTA transaction factory uses it; + otherwise it creates a new transaction. The jBPM enterprise beans + are configured to delegate transaction management to the container. + However, if the jBPM APIs are being used in a context in which no + transaction is active (such as a web application), one will be + started automatically. </para> - <para>Note that the JNDI name used in <literal>hibernate.connection.datasource</literal> - is, in fact, a resource manager reference, portable across application servers. Said - reference is meant to be bound to an actual data source in the target application server - at deployment time. In the included <code>jboss.xml</code> descriptor, the reference is - bound to <code>java:JbpmDS</code>. + <para> + To prevent unintended transaction creations when using + <firstterm>container-managed transactions</firstterm>, switch to the + <systemitem>CMTTransactionFactory</systemitem>. This setting ensures + that <application>Hibernate</application> will always look for an + existing transaction and will report a problem if none is found. </para> - <para>Out of the box, jBPM is configured to use the <literal>JTATransactionFactory</literal>. - If an existing transaction is underway, the JTA transaction factory uses it; otherwise it - creates a new transaction. The jBPM enterprise beans are configured to delegate transaction - management to the container. However, if you use the jBPM APIs in a context where no - transaction is active (say, in a web application), one will be started automatically. - </para> - - <para>If your own EJBs use container-managed transactions and you want to prevent unintended - transaction creations, you can switch to the <literal>CMTTransactionFactory</literal>. With - that setting, Hibernate will always look for an existing transaction and will report a problem - if none is found. - </para> - </section> <section id="clientcomponents"> - <title>Client Components</title> + <title> + Client Components + </title> - <para>Client components written directly against the jBPM APIs that wish to leverage the - enterprise services must ensure that their deployment descriptors have the appropriate - environment references in place. The descriptor below can be regarded as typical for - a client session bean. + <para> + Ensure that the appropriate environmental references are in place + for deployment descriptors for client components written directly + against those Business Process Manager APIs that can leverage the + enterprise services. The descriptor below can be regarded as typical + for a client session bean: </para> - <programlisting><![CDATA[<session> + <programlisting language="XML"><xi:include href="extras/enterprise_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <ejb-name>MyClientBean</ejb-name> - <home>org.example.RemoteClientHome</home> - <remote>org.example.RemoteClient</remote> - <local-home>org.example.LocalClientHome</local-home> - <local>org.example.LocalClient</local> - <ejb-class>org.example.ClientBean</ejb-class> - <session-type>Stateless</session-type> - <transaction-type>Container</transaction-type> - <ejb-local-ref> - <ejb-ref-name>ejb/TimerEntityBean</ejb-ref-name> - <ejb-ref-type>Entity</ejb-ref-type> - <local-home>org.jbpm.ejb.LocalTimerEntityHome</local-home> - <local>org.jbpm.ejb.LocalTimerEntity</local> - </ejb-local-ref> + <para> + The environmental references above can be bound to resources in the + target operational environment as follows. Note that the JNDI names + match the values used by the Business Process Manager enterprise + beans. + </para> - <resource-ref> - <res-ref-name>jdbc/JbpmDataSource</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> - </resource-ref> + <programlisting language="XML"><xi:include href="extras/enterprise_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <resource-ref> - <res-ref-name>jms/JbpmConnectionFactory</res-ref-name> - <res-type>javax.jms.ConnnectionFactory</res-type> - <res-auth>Container</res-auth> - </resource-ref> - <message-destination-ref> - <message-destination-ref-name>jms/JobQueue</message-destination-ref-name> - <message-destination-type>javax.jms.Queue</message-destination-type> - <message-destination-usage>Produces</message-destination-usage> - </message-destination-ref> - -</session>]]></programlisting> - - <para>Provided the target application server was JBoss, the above environment references - could be bound to resources in the target operational environment as follows. Note that - the JNDI names match the values used by the jBPM enterprise beans. + <para> + If the client component is a web application, as opposed to an + enterprise bean, the deployment descriptor shall look like this: </para> - <programlisting><![CDATA[<session> + <programlisting language="XML"><xi:include href="extras/enterprise_5.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <ejb-name>MyClientBean</ejb-name> - <jndi-name>ejb/MyClientBean</jndi-name> - <local-jndi-name>java:ejb/MyClientBean</local-jndi-name> - <ejb-local-ref> - <ejb-ref-name>ejb/TimerEntityBean</ejb-ref-name> - <local-jndi-name>java:ejb/TimerEntityBean</local-jndi-name> - </ejb-local-ref> - - <resource-ref> - <res-ref-name>jdbc/JbpmDataSource</res-ref-name> - <jndi-name>java:JbpmDS</jndi-name> - </resource-ref> - - <resource-ref> - <res-ref-name>jms/JbpmConnectionFactory</res-ref-name> - <jndi-name>java:JmsXA</jndi-name> - </resource-ref> - - <message-destination-ref> - <message-destination-ref-name>jms/JobQueue</message-destination-ref-name> - <jndi-name>queue/JbpmJobQueue</jndi-name> - </message-destination-ref> - -</session>]]></programlisting> - - <para>In case the client component is a web application, as opposed to an enterprise bean, - the deployment descriptor would look like this:</para> - - <programlisting><![CDATA[<web-app> - - <servlet> - <servlet-name>MyClientServlet</servlet-name> - <servlet-class>org.example.ClientServlet</servlet-class> - </servlet> - - <servlet-mapping> - <servlet-name>MyClientServlet</servlet-name> - <url-pattern>/client/servlet</url-pattern> - </servlet-mapping> - - <ejb-local-ref> - <ejb-ref-name>ejb/TimerEntityBean</ejb-ref-name> - <ejb-ref-type>Entity</ejb-ref-type> - <local-home>org.jbpm.ejb.LocalTimerEntityHome</local-home> - <local>org.jbpm.ejb.LocalTimerEntity</local> - <ejb-link>TimerEntityBean</ejb-link> - </ejb-local-ref> - - <resource-ref> - <res-ref-name>jdbc/JbpmDataSource</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> - </resource-ref> - - <resource-ref> - <res-ref-name>jms/JbpmConnectionFactory</res-ref-name> - <res-type>javax.jms.ConnectionFactory</res-type> - <res-auth>Container</res-auth> - </resource-ref> - - <message-destination-ref> - <message-destination-ref-name>jms/JobQueue</message-destination-ref-name> - <message-destination-type>javax.jms.Queue</message-destination-type> - <message-destination-usage>Produces</message-destination-usage> - <message-destination-link>JobQueue</message-destination-link> - </message-destination-ref> - -</web-app>]]></programlisting> - - <para>The above environment references could be bound to resources in the target - operational environment as follows, if the target application server was JBoss. + <para> + The above environmental references can also be bound to resources in + the target operational environment, as per this code sample: </para> - <programlisting><![CDATA[<jboss-web> + <programlisting language="XML"><xi:include href="extras/enterprise_6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <ejb-local-ref> - <ejb-ref-name>ejb/TimerEntityBean</ejb-ref-name> - <local-jndi-name>java:ejb/TimerEntityBean</local-jndi-name> - </ejb-local-ref> - <resource-ref> - <res-ref-name>jdbc/JbpmDataSource</res-ref-name> - <jndi-name>java:JbpmDS</jndi-name> - </resource-ref> - - <resource-ref> - <res-ref-name>jms/JbpmConnectionFactory</res-ref-name> - <jndi-name>java:JmsXA</jndi-name> - </resource-ref> - - <message-destination-ref> - <message-destination-ref-name>jms/JobQueue</message-destination-ref-name> - <jndi-name>queue/JbpmJobQueue</jndi-name> - </message-destination-ref> - -</jboss-web>]]></programlisting> - + + + </section> + <section> + <title> + Conclusion + </title> <para> Having studied this chapter, you should now have a thorough understanding of the facilities offered by the jBPM that can be used to leverage the Java EE infrastructure and should be comfortable with testing some of these in your corporate environment. </para> + </section> + - </section> - </chapter> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/async_1.sql =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/async_1.sql (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/async_1.sql 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,5 @@ +update JBPM_JOB job +set job.version = 2 + job.lockOwner = '192.168.1.3:2' +where + job.version = 1 \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/cal3.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/cal3.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/cal3.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,9 @@ +<timer name="daysBeforeHoliday" duedate="5 business days">...</timer> + +<timer name="pensionDate" duedate="#{dateOfBirth} + 65 years" >...</timer> + +<timer name="pensionReminder" duedate="#{dateOfPension} - 1 year" >...</timer> + +<timer name="fireWorks" duedate="#{chineseNewYear} repeat="1 year" >...</timer> + +<reminder name="hitBoss" duedate="#{payRaiseDay} + 3 days" repeat="1 week" /> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/cal4.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/cal4.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/cal4.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,34 @@ +hour.format=HH:mm +#weekday ::= [<daypart> [&amp; <daypart>]*] +#daypart ::= <start-hour>-<to-hour> +#start-hour and to-hour must be in the hour.format +#dayparts have to be ordered +weekday.monday= 9:00-12:00 &amp; 12:30-17:00 +weekday.tuesday= 9:00-12:00 &amp; 12:30-17:00 +weekday.wednesday= 9:00-12:00 &amp; 12:30-17:00 +weekday.thursday= 9:00-12:00 &amp; 12:30-17:00 +weekday.friday= 9:00-12:00 &amp; 12:30-17:00 +weekday.saturday= +weekday.sunday= + +day.format=dd/MM/yyyy +# holiday syntax: <holiday> +# holiday period syntax: <start-day>-<end-day> +# below are the belgian official holidays +holiday.1= 01/01/2005 # nieuwjaar +holiday.2= 27/3/2005 # pasen +holiday.3= 28/3/2005 # paasmaandag +holiday.4= 1/5/2005 # feest van de arbeid +holiday.5= 5/5/2005 # hemelvaart +holiday.6= 15/5/2005 # pinksteren +holiday.7= 16/5/2005 # pinkstermaandag +holiday.8= 21/7/2005 # my birthday +holiday.9= 15/8/2005 # moederkesdag +holiday.10= 1/11/2005 # allerheiligen +holiday.11= 11/11/2005 # wapenstilstand +holiday.12= 25/12/2005 # kerstmis + +business.day.expressed.in.hours= 8 +business.week.expressed.in.hours= 40 +business.month.expressed.in.business.days= 21 +business.year.expressed.in.business.days= 220 Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/calendar_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/calendar_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/calendar_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,18 @@ +<timer name="daysBeforeHoliday" duedate="5 business days"> + ... +</timer> + +<timer name="pensionDate" duedate="#{dateOfBirth} + 65 years" > + ... +</timer> + +<timer name="pensionReminder" duedate="#{dateOfPension} - 1 year" > + ... +</timer> + +<timer name="fireWorks" duedate="#{chineseNewYear} repeat="1 year" > + ... +</timer> + +<reminder name="hitBoss" duedate="#{payRaiseDay} + 3 days" +repeat="1 week" /> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/calendar_2.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/calendar_2.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/calendar_2.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,34 @@ +hour.format=HH:mm +#weekday ::= [<daypart> [&amp; <daypart>]*] +#daypart ::= <start-hour>-<to-hour> +#start-hour and to-hour must be in the hour.format +#dayparts have to be ordered +weekday.monday= 9:00-12:00 &amp; 12:30-17:00 +weekday.tuesday= 9:00-12:00 &amp; 12:30-17:00 +weekday.wednesday= 9:00-12:00 &amp; 12:30-17:00 +weekday.thursday= 9:00-12:00 &amp; 12:30-17:00 +weekday.friday= 9:00-12:00 &amp; 12:30-17:00 +weekday.saturday= +weekday.sunday= + +day.format=dd/MM/yyyy +# holiday syntax: <holiday> +# holiday period syntax: <start-day>-<end-day> +# below are the belgian official holidays +holiday.1= 01/01/2005 # nieuwjaar +holiday.2= 27/3/2005 # pasen +holiday.3= 28/3/2005 # paasmaandag +holiday.4= 1/5/2005 # feest van de arbeid +holiday.5= 5/5/2005 # hemelvaart +holiday.6= 15/5/2005 # pinksteren +holiday.7= 16/5/2005 # pinkstermaandag +holiday.8= 21/7/2005 # my birthday +holiday.9= 15/8/2005 # moederkesdag +holiday.10= 1/11/2005 # allerheiligen +holiday.11= 11/11/2005 # wapenstilstand +holiday.12= 25/12/2005 # kerstmis + +business.day.expressed.in.hours= 8 +business.week.expressed.in.hours= 40 +business.month.expressed.in.business.days= 21 +business.year.expressed.in.business.days= 220 \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/code_example_tutorial_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/code_example_tutorial_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/code_example_tutorial_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,54 @@ +public void testHelloWorldProcess() { + // This method shows a process definition and one execution + // of the process definition. The process definition has + // 3 nodes: an unnamed start-state, a state 's' and an + // end-state named 'end'. + // The next line parses a piece of xml text into a + // ProcessDefinition. A ProcessDefinition is the formal + // description of a process represented as a java object. + ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( + "<process-definition>" + + " <start-state>" + + " <transition to='s' />" + + " </start-state>" + + " <state name='s'>" + + " <transition to='end' />" + + " </state>" + + " <end-state name='end' />" + + "</process-definition>" + ); + + // The next line creates one execution of the process definition. + // After construction, the process execution has one main path + // of execution (=the root token) that is positioned in the + // start-state. + ProcessInstance processInstance = + new ProcessInstance(processDefinition); + + // After construction, the process execution has one main path + // of execution (=the root token). + Token token = processInstance.getRootToken(); + + // Also after construction, the main path of execution is positioned + // in the start-state of the process definition. + assertSame(processDefinition.getStartState(), token.getNode()); + + // Let's start the process execution, leaving the start-state + // over its default transition. + token.signal(); + // The signal method will block until the process execution + // enters a wait state. + + // The process execution will have entered the first wait state + // in state 's'. So the main path of execution is now + // positioned in state 's' + assertSame(processDefinition.getNode("s"), token.getNode()); + + // Let's send another signal. This will resume execution by + // leaving the state 's' over its default transition. + token.signal(); + // Now the signal method returned because the process instance + // has arrived in the end-state. + + assertSame(processDefinition.getNode("end"), token.getNode()); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/con1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/con1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/con1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +user-java-object <---> converter <---> variable instance Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,8 @@ +JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); +try { + // This is what we call a context block. + // Here you can perform workflow operations + +} finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,73 @@ +<jbpm-configuration> + +<jbpm-context> + <service name='persistence' + factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /> + <service name='message' + factory='org.jbpm.msg.db.DbMessageServiceFactory' /> + <service name='scheduler' + factory='org.jbpm.scheduler.db.DbSchedulerServiceFactory' /> + <service name='logging' + factory='org.jbpm.logging.db.DbLoggingServiceFactory' /> + <service name='authentication' + factory= +'org.jbpm.security.authentication.DefaultAuthenticationServiceFactory' /> +</jbpm-context> + +<!-- configuration resource files pointing to default + configuration files in jbpm-{version}.jar --> +<string name='resource.hibernate.cfg.xml' value='hibernate.cfg.xml' /> + + <!-- <string name='resource.hibernate.properties' + value='hibernate.properties' /> --> + <string name='resource.business.calendar' + value='org/jbpm/calendar/jbpm.business.calendar.properties' /> + <string name='resource.default.modules' + value='org/jbpm/graph/def/jbpm.default.modules.properties' /> + <string name='resource.converter' + value='org/jbpm/db/hibernate/jbpm.converter.properties' /> + <string name='resource.action.types' + value='org/jbpm/graph/action/action.types.xml' /> + <string name='resource.node.types' + value='org/jbpm/graph/node/node.types.xml' /> + <string name='resource.parsers' + value='org/jbpm/jpdl/par/jbpm.parsers.xml' /> + <string name='resource.varmapping' + value='org/jbpm/context/exe/jbpm.varmapping.xml' /> + <string name='resource.mail.templates' + value='jbpm.mail.templates.xml' /> + + <int name='jbpm.byte.block.size' value="1024" singleton="true" /> + <bean name='jbpm.task.instance.factory' + class='org.jbpm.taskmgmt.impl.DefaultTaskInstanceFactoryImpl' + singleton='true' /> + + <bean name='jbpm.variable.resolver' + class='org.jbpm.jpdl.el.impl.JbpmVariableResolver' + singleton='true' /> + + <string name='jbpm.mail.smtp.host' value='localhost' /> + + <bean name='jbpm.mail.address.resolver' + class='org.jbpm.identity.mail.IdentityAddressResolver' + singleton='true' /> + <string name='jbpm.mail.from.address' value='jbpm@noreply' /> + + <bean name='jbpm.job.executor' + class='org.jbpm.job.executor.JobExecutor'> + <field name='jbpmConfiguration'><ref bean='jbpmConfiguration' /> + </field> + <field name='name'><string value='JbpmJobExecutor' /></field> + <field name='nbrOfThreads'><int value='1' /></field> + <field name='idleInterval'><int value='5000' /></field> + <!-- 1 hour --> + <field name='maxIdleInterval'><int value='3600000' /></field> + <field name='historyMaxSize'><int value='20' /></field> + <!-- 10 minutes --> + <field name='maxLockTime'><int value='600000' /></field> + <!-- 1 minute --> + <field name='lockMonitorInterval'><int value='60000' /></field> + <!-- 5 seconds --> + <field name='lockBufferTime'><int value='5000' /></field> + </bean> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_10.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_10.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_10.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,16 @@ +<beans> + <bean name="taskFactory" + class="org.jbpm.UnexistingTaskInstanceFactory" + singleton="true"/> + + <bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" > + <constructor factory="taskFactory" method="createTask" > + <parameter class="java.lang.String"> + <string>do dishes</string> + </parameter> + <parameter class="java.lang.String"> + <string>theotherguy</string> + </parameter> + </constructor> + </bean> +</beans> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_11.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_11.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_11.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,14 @@ +<beans> + <bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" > + <constructor + factory-class="org.jbpm.UnexistingTaskInstanceFactory" + method="createTask" > + <parameter class="java.lang.String"> + <string>do dishes</string> + </parameter> + <parameter class="java.lang.String"> + <string>theotherguy</string> + </parameter> + </constructor> + </bean> +</beans> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_2.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_2.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_2.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,15 @@ +public void deployProcessDefinition(ProcessDefinition processDefinition) +public List getTaskList() +public List getTaskList(String actorId) +public List getGroupTaskList(List actorIds) +public TaskInstance loadTaskInstance(long taskInstanceId) +public TaskInstance loadTaskInstanceForUpdate(long taskInstanceId) +public Token loadToken(long tokenId) +public Token loadTokenForUpdate(long tokenId) +public ProcessInstance loadProcessInstance(long processInstanceId) +public ProcessInstance loadProcessInstanceForUpdate(long processInstanceId) +public ProcessInstance newProcessInstance(String processDefinitionName) +public void save(ProcessInstance processInstance) +public void save(Token token) +public void save(TaskInstance taskInstance) +public void setRollbackOnly() \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_2.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_2.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_2.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,11 @@ +<service name="persistence"> + <factory> + <bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"> + <field name="dataSourceJndiName"> + <string value="java:/myDataSource"/> + </field> + <field name="isCurrentSessionEnabled"><true /></field> + <field name="isTransactionEnabled"><false /></field> + </bean> + </factory> +</service> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_3.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_3.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_3.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,10 @@ +<beans> + <bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance"/> + <string name="greeting">hello world</string> + <int name="answer">42</int> + <boolean name="javaisold">true</boolean> + <float name="percentage">10.2</float> + <double name="salary">100000000.32</double> + <char name="java">j</char> + <null name="dusttodust" /> +</beans> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_4.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_4.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_4.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,9 @@ +ObjectFactory of = ObjectFactory.parseXmlFromAbove(); +assertEquals(TaskInstance.class, of.getNewObject("task").getClass()); +assertEquals("hello world", of.getNewObject("greeting")); +assertEquals(new Integer(42), of.getNewObject("answer")); +assertEquals(Boolean.TRUE, of.getNewObject("javaisold")); +assertEquals(new Float(10.2), of.getNewObject("percentage")); +assertEquals(new Double(100000000.32), of.getNewObject("salary")); +assertEquals(new Character('j'), of.getNewObject("java")); +assertNull(of.getNewObject("dusttodust"));]]> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_5.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_5.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_5.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,7 @@ +<beans> + <list name="numbers"> + <string>one</string> + <string>two</string> + <string>three</string> + </list> +</beans> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_6.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_6.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_6.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,16 @@ +<beans> + <map name="numbers"> + <entry> + <key><int>1</int></key> + <value><string>one</string></value> + </entry> + <entry> + <key><int>2</int></key> + <value><string>two</string></value> + </entry> + <entry> + <key><int>3</int></key> + <value><string>three</string></value> + </entry> + </map> +</beans> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_7.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_7.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_7.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +<beans> + <bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" > + <field name="name"><string>do dishes</string></field> + <property name="actorId"><string>theotherguy</string></property> + </bean> +</beans> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_8.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_8.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_8.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<beans> + <bean name="a" class="org.jbpm.A" /> + <ref name="b" bean="a" /> +</beans> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_9.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_9.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_9.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,12 @@ +<beans> + <bean name="task" class="org.jbpm.taskmgmt.exe.TaskInstance" > + <constructor> + <parameter class="java.lang.String"> + <string>do dishes</string> + </parameter> + <parameter class="java.lang.String"> + <string>theotherguy</string> + </parameter> + </constructor> + </bean> +</beans> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_a.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_a.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_a.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +log4j.logger.org.hibernate.event.def.AbstractFlushingEventListener=FATAL Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_b.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_b.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/configuration_b.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +<boolean name="jbpm.hide.stale.object.exceptions" value="false" /> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +ProcessInstance processInstance = ...; +ContextInstance contextInstance = + (ContextInstance) processInstance.getInstance(ContextInstance.class); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,13 @@ +<jbpm-type> + <matcher> + <bean class="org.jbpm.context.exe.matcher.ClassNameMatcher"> + <field name="className"> + <string value="java.lang.Boolean" /> + </field> + </bean> + </matcher> + <converter + class="org.jbpm.context.exe.converter.BooleanToStringConverter" /> + <variable-instance + class="org.jbpm.context.exe.variableinstance.StringInstance" /> +</jbpm-type> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_2.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_2.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_2.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +void ContextInstance.setVariable(String variableName, Object value); +void ContextInstance.setVariable( + String variableName, Object value, Token token); + +Object ContextInstance.getVariable(String variableName); +Object ContextInstance.getVariable(String variableName, Token token); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_2.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_2.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_2.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,9 @@ +<jbpm-type> + <matcher> + <bean class="org.jbpm.context.exe.matcher.ClassNameMatcher"> + <field name="className"><string value="java.lang.Long" /></field> + </bean> + </matcher> + <variable-instance + class="org.jbpm.context.exe.variableinstance.LongInstance" /> +</jbpm-type> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_3.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_3.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_3.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,2 @@ +ContextInstance.deleteVariable(String variableName); +ContextInstance.deleteVariable(String variableName, Token token); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_4.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_4.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_4.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +ContextInstance.createVariable(String name, Object value, Token token); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_5.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_5.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_5.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,2 @@ +Object ContextInstance.getTransientVariable(String name); +void ContextInstance.setTransientVariable(String name, Object value); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_6.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_6.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/context_6.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,5 @@ +public interface Converter extends Serializable { + boolean supports(Object value); + Object convert(Object o); + Object revert(Object o); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/differentmethods.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/differentmethods.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/differentmethods.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +static JbpmConfinguration jbpmConfiguration = JbpmConfinguration.parseResource("my.jbpm.cfg.xml"); Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,8 @@ +<jbpm-context> + <service name="persistence" + factory="org.jbpm.persistence.jta.JtaDbPersistenceServiceFactory" /> + <service name="message" + factory="org.jbpm.msg.jms.JmsMessageServiceFactory" /> + <service name="scheduler" + factory="org.jbpm.scheduler.ejbtimer.EntitySchedulerServiceFactory" /> +</jbpm-context> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_2.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_2.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_2.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,32 @@ +<!-- sql dialect --> +<property name="hibernate.dialect"> + org.hibernate.dialect.HSQLDialect +</property> + +<property name="hibernate.cache.provider_class"> + org.hibernate.cache.HashtableCacheProvider +</property> + +<!-- DataSource properties (begin) --> +<property name="hibernate.connection.datasource"> + java:comp/env/jdbc/JbpmDataSource +</property> +<!-- DataSource properties (end) --> + +<!-- JTA transaction properties (begin) --> +<property name="hibernate.transaction.factory_class"> + org.hibernate.transaction.JTATransactionFactory +</property> +<property name="hibernate.transaction.manager_lookup_class"> + org.hibernate.transaction.JBossTransactionManagerLookup +</property> +<!-- JTA transaction properties (end) --> + +<!-- CMT transaction properties (begin) === +<property name="hibernate.transaction.factory_class"> + org.hibernate.transaction.CMTTransactionFactory +</property> +<property name="hibernate.transaction.manager_lookup_class"> + org.hibernate.transaction.JBossTransactionManagerLookup +</property> +==== CMT transaction properties (end) --> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_3.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_3.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_3.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,39 @@ +<session> + + <ejb-name>MyClientBean</ejb-name> + <home>org.example.RemoteClientHome</home> + <remote>org.example.RemoteClient</remote> + <local-home>org.example.LocalClientHome</local-home> + <local>org.example.LocalClient</local> + <ejb-class>org.example.ClientBean</ejb-class> + <session-type>Stateless</session-type> + <transaction-type>Container</transaction-type> + + <ejb-local-ref> + <ejb-ref-name>ejb/TimerEntityBean</ejb-ref-name> + <ejb-ref-type>Entity</ejb-ref-type> + <local-home>org.jbpm.ejb.LocalTimerEntityHome</local-home> + <local>org.jbpm.ejb.LocalTimerEntity</local> + </ejb-local-ref> + + <resource-ref> + <res-ref-name>jdbc/JbpmDataSource</res-ref-name> + <res-type>javax.sql.DataSource</res-type> + <res-auth>Container</res-auth> + </resource-ref> + + <resource-ref> + <res-ref-name>jms/JbpmConnectionFactory</res-ref-name> + <res-type>javax.jms.ConnnectionFactory</res-type> + <res-auth>Container</res-auth> + </resource-ref> + + <message-destination-ref> + <message-destination-ref-name> + jms/JobQueue + </message-destination-ref-name> + <message-destination-type>javax.jms.Queue</message-destination-type> + <message-destination-usage>Produces</message-destination-usage> + </message-destination-ref> + +</session> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_4.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_4.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_4.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,29 @@ +<session> + + <ejb-name>MyClientBean</ejb-name> + <jndi-name>ejb/MyClientBean</jndi-name> + <local-jndi-name>java:ejb/MyClientBean</local-jndi-name> + + <ejb-local-ref> + <ejb-ref-name>ejb/TimerEntityBean</ejb-ref-name> + <local-jndi-name>java:ejb/TimerEntityBean</local-jndi-name> + </ejb-local-ref> + + <resource-ref> + <res-ref-name>jdbc/JbpmDataSource</res-ref-name> + <jndi-name>java:JbpmDS</jndi-name> + </resource-ref> + + <resource-ref> + <res-ref-name>jms/JbpmConnectionFactory</res-ref-name> + <jndi-name>java:JmsXA</jndi-name> + </resource-ref> + + <message-destination-ref> + <message-destination-ref-name> + jms/JobQueue + </message-destination-ref-name> + <jndi-name>queue/JbpmJobQueue</jndi-name> + </message-destination-ref> + +</session> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_5.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_5.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_5.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,42 @@ +<web-app> + + <servlet> + <servlet-name>MyClientServlet</servlet-name> + <servlet-class>org.example.ClientServlet</servlet-class> + </servlet> + + <servlet-mapping> + <servlet-name>MyClientServlet</servlet-name> + <url-pattern>/client/servlet</url-pattern> + </servlet-mapping> + + <ejb-local-ref> + <ejb-ref-name>ejb/TimerEntityBean</ejb-ref-name> + <ejb-ref-type>Entity</ejb-ref-type> + <local-home>org.jbpm.ejb.LocalTimerEntityHome</local-home> + <local>org.jbpm.ejb.LocalTimerEntity</local> + <ejb-link>TimerEntityBean</ejb-link> + </ejb-local-ref> + + <resource-ref> + <res-ref-name>jdbc/JbpmDataSource</res-ref-name> + <res-type>javax.sql.DataSource</res-type> + <res-auth>Container</res-auth> + </resource-ref> + + <resource-ref> + <res-ref-name>jms/JbpmConnectionFactory</res-ref-name> + <res-type>javax.jms.ConnectionFactory</res-type> + <res-auth>Container</res-auth> + </resource-ref> + + <message-destination-ref> + <message-destination-ref-name> + jms/JobQueue + </message-destination-ref-name> + <message-destination-type>javax.jms.Queue</message-destination-type> + <message-destination-usage>Produces</message-destination-usage> + <message-destination-link>JobQueue</message-destination-link> + </message-destination-ref> + +</web-app> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_6.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_6.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/enterprise_6.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,25 @@ +<jboss-web> + + <ejb-local-ref> + <ejb-ref-name>ejb/TimerEntityBean</ejb-ref-name> + <local-jndi-name>java:ejb/TimerEntityBean</local-jndi-name> + </ejb-local-ref> + + <resource-ref> + <res-ref-name>jdbc/JbpmDataSource</res-ref-name> + <jndi-name>java:JbpmDS</jndi-name> + </resource-ref> + + <resource-ref> + <res-ref-name>jms/JbpmConnectionFactory</res-ref-name> + <jndi-name>java:JmsXA</jndi-name> + </resource-ref> + + <message-destination-ref> + <message-destination-ref-name> + jms/JobQueue + </message-destination-ref-name> + <jndi-name>queue/JbpmJobQueue</jndi-name> + </message-destination-ref> + +</jboss-web> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/jpdl_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/jpdl_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/jpdl_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +<target name="deploy.par"> + <taskdef name="deploypar" classname="org.jbpm.ant.DeployProcessTask"> + <classpath --make sure the jbpm-[version].jar is in this classpath--/> + </taskdef> + <deploypar par="build/myprocess.par" /> +</target> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,5 @@ +public class LoggingInstance extends ModuleInstance { + ... + public void addLog(ProcessLog processLog) {...} + ... +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_2.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_2.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_2.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +public class LoggingInstance extends ModuleInstance { + ... + public void startCompositeLog(CompositeLog compositeLog) {...} + public void endCompositeLog() {...} + ... +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_3.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_3.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_3.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +startCompositeLog(new MyCompositeLog()); +try { + ... +} finally { + endCompositeLog(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_4.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_4.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_4.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,2 @@ +<service name='logging' + factory='org.jbpm.logging.db.DbLoggingServiceFactory' /> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_5.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_5.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_5.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,5 @@ +public class LoggingSession { + ... + public Map findLogsByProcessInstance(long processInstanceId) {...} + ... +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_6.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_6.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/logging_6.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +public class LoggingSession { + public List findLogsByToken(long tokenId) {...} + ... +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_0.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_0.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_0.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +&lt;mail actors="#{president}" subject="readmylips" text="nomoretaxes" /&gt; Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +public interface AddressResolver extends Serializable { + Object resolveAddress(String actorId); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<mail actors="#{president}" > + <subject>readmylips</subject> + <text>nomoretaxes</text> +</mail> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_10.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_10.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_10.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<jbpm-configuration> + ... + <string name="jbpm.mail.bcc.address" value=&quot;bcc(a)mycompany.com&quot; /> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_11.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_11.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_11.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<mail to='#{initiator}' + bcc=&#39;bcc(a)mycompany.com&#39; + subject='websale' + text='your websale of #{quantity} #{item} was approved' /> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_12.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_12.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_12.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,5 @@ +<jbpm-configuration> + <bean name='jbpm.mail.address.resolver' + class='org.jbpm.identity.mail.IdentityAddressResolver' + singleton='true' /> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_13.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_13.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_13.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,24 @@ +<mail-templates> + <variable name="BaseTaskListURL" + value="http://localhost:8080/jbpm/task?id=" /> + + <mail-template name='task-assign'> + <actors>#{taskInstance.actorId}</actors> + <subject>Task '#{taskInstance.name}'</subject> + <text><![CDATA[Hi, +Task '#{taskInstance.name}' has been assigned to you. +Go for it: #{BaseTaskListURL}#{taskInstance.id} +Thanks. +---powered by JBoss jBPM---]]></text> + </mail-template> + + <mail-template name='task-reminder'> + <actors>#{taskInstance.actorId}</actors> + <subject>Task '#{taskInstance.name}' !</subject> + <text><![CDATA[Hey, +Don't forget about #{BaseTaskListURL}#{taskInstance.id} +Get going ! +---powered by JBoss jBPM---]]></text> + </mail-template> + +</mail-templates> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_14.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_14.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_14.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +<jbpm-configuration> + <string name="resource.mail.templates" value="jbpm.mail.templates.xml" /> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_15.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_15.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_15.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +<jbpm-configuration> + <string name="jbpm.mail.smtp.host" value="localhost" /> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_16.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_16.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_16.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +<jbpm-configuration> + <string name='resource.mail.properties' value='jbpm.mail.properties' /> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_17.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_17.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_17.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +<jbpm-configuration> + <string name='jbpm.mail.from.address' value=&#39;jbpm(a)yourcompany.com&#39; /> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_18.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_18.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_18.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<jbpm-configuration> + <string name='jbpm.mail.class.name' + value='com.your.specific.CustomMail' /> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_2.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_2.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_2.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<mail + to='#{initiator}' + subject='websale' + text='your websale of #{quantity} #{item} was approved' /> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_3.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_3.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_3.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<mail + to=&#39;admin(a)mycompany.com&#39; + subject='urgent' + text='the mailserver is down :-)' /> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_4.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_4.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_4.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +<mail template='sillystatement' actors="#{president}" /> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_5.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_5.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_5.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +<mail-node name="send email" + to="#{president}" + subject="readmylips" + text="nomoretaxes"> + <transition to="the next node" /> +</mail-node> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_6.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_6.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_6.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<task-node name='a'> + <task name='laundry' swimlane="grandma" notify='yes' /> + <transition to='b' /> +</task-node> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_7.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_7.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_7.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<task-node name='a'> + <task name='laundry' swimlane="grandma" notify='yes' /> + <transition to='b' /> +</task-node> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_8.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_8.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_8.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +<task-node name='a'> + <task name='laundry' swimlane="grandma" notify='yes'> + <reminder duedate="2 business days" repeat="2 business hours"/> + </task> + <transition to='b' /> +</task-node> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_9.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_9.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/mail_9.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +<mail actors="#{president}" + subject="readmylips" + text="nomoretaxes" /> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,16 @@ +public class RemoveEmployeeUpdate implements ActionHandler { + public void execute(ExecutionContext ctx) throws Exception { + // get the fired employee from the process variables. + String firedEmployee = + (String) ctx.getContextInstance().getVariable("fired employee"); + + // by taking the same database connection as used for the jbpm + // updates, we reuse the jbpm transaction for our database update. + Connection connection = + ctx.getProcessInstance().getJbpmSession().getSession().getConnection(); + Statement statement = connection.createStatement(); + statement.execute("DELETE FROM EMPLOYEE WHERE ..."); + statement.execute(); + statement.close(); + } +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,39 @@ +<process-definition> + + <start-state> + <transition to="auction" /> + </start-state> + + <state name="auction"> + <transition name="auction ends" to="salefork" /> + <transition name="cancel" to="end" /> + </state> + + <fork name="salefork"> + <transition name="shipping" to="send item" /> + <transition name="billing" to="receive money" /> + </fork> + + <state name="send item"> + <transition to="receive item" /> + </state> + + <state name="receive item"> + <transition to="salejoin" /> + </state> + + <state name="receive money"> + <transition to="send money" /> + </state> + + <state name="send money"> + <transition to="salejoin" /> + </state> + + <join name="salejoin"> + <transition to="end" /> + </join> + + <end-state name="end" /> + +</process-definition> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_2.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_2.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_2.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,16 @@ +public class AmountUpdate implements ActionHandler { + public void execute(ExecutionContext ctx) throws Exception { + // business logic + Float erpAmount = ...get amount from erp-system...; + Float processAmount = (Float) ctx.getContextInstance().getVariable("amount"); + float result = erpAmount.floatValue() + processAmount.floatValue(); + ...update erp-system with the result...; + + // graph execution propagation + if (result > 5000) { + ctx.leaveNode(ctx, "big amounts"); + } else { + ctx.leaveNode(ctx, "small amounts"); + } + } +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_2.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_2.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_2.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,10 @@ +<process-definition name="yearly evaluation"> + <state name="fire employee"> + <transition to="collect badge"> + <action class="com.nomercy.hr.RemoveEmployeeUpdate" /> + </transition> + </state> + + <state name="collect badge"> + +</process-definition> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_3.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_3.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_3.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,10 @@ +//start a transaction +JbpmContext jbpmContext = jbpmConfiguration.createContext(); +try { + ProcessInstance processInstance = + jbpmContext.newProcessInstance("my async process"); + processInstance.signal(); + jbpmContext.save(processInstance); +} finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_3.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_3.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_3.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,8 @@ +<process-definition> + <event type="node-enter"> + <script> + System.out.println("this script is entering node "+node); + </script> + </event> + ... +</process-definition> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_4.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_4.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_4.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,13 @@ +<process-definition> + <event type="process-end"> + <script> + <expression> + a = b + c; + </expression> + <variable name='XXX' access='write' mapped-name='a' /> + <variable name='YYY' access='read' mapped-name='b' /> + <variable name='ZZZ' access='read' mapped-name='c' /> + </script> + </event> + ... +</process-definition> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_5.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_5.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_5.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,8 @@ +<process-definition> + <state name="preparation"> + <transition to="phase one/invite murphy"/> + </state> + <super-state name="phase one"> + <state name="invite murphy"/> + </super-state> +</process-definition> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_6.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_6.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_6.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,10 @@ +<process-definition> + <super-state name="phase one"> + <state name="preparation"> + <transition to="../phase two/invite murphy"/> + </state> + </super-state> + <super-state name="phase two"> + <state name="invite murphy"/> + </super-state> +</process-definition> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_7.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_7.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_7.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,12 @@ +<process-definition name="hire"> + <start-state> + <transition to="initial interview" /> + </start-state> + <process-state name="initial interview"> + <sub-process name="interview" /> + <variable name="a" access="read,write" mapped-name="aa" /> + <variable name="b" access="read" mapped-name="bb" /> + <transition to="..." /> + </process-state> + ... +</process-definition> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_8.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_8.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/modelling_8.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,17 @@ +<start-state> + <transition to="one" /> +</start-state> +<node async="true" name="one"> + <action class="com...MyAutomaticAction" /> + <transition to="two" /> +</node> +<node async="true" name="two"> + <action class="com...MyAutomaticAction" /> + <transition to="three" /> +</node> +<node async="true" name="three"> + <action class="com...MyAutomaticAction" /> + <transition to="end" /> +</node> +<end-state name="end" /> +... Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,2 @@ +&lt;service name='persistence' + factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt; Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); +try { + // Invoke persistence operations here +} finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,6 @@ +<jbpm-configuration> + <jbpm-context> + <service name='persistence' + factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /> + </jbpm-context> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_2.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_2.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_2.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,7 @@ +JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); +try { + ProcessDefinition processDefinition = ...; + jbpmContext.deployProcessDefinition(processDefinition); +} finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_2.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_2.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_2.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,8 @@ +<jbpm-configuration> + <!-- configuration resource files pointing to default + configuration files in jbpm-{version}.jar --> + <string name='resource.hibernate.cfg.xml' + value='hibernate.cfg.xml' /> + <!-- <string name='resource.hibernate.properties' + value='hibernate.properties' /> --> +</jbpm-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_3.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_3.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_3.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,8 @@ +JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); +try { + String processName = ...; + ProcessInstance processInstance = + jbpmContext.newProcessInstance(processName); +} finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_3.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_3.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_3.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +<property name="hibernate.cache.provider_class"> + org.hibernate.cache.HashtableCacheProvider +</property> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_4.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_4.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_4.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,10 @@ +JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); +try { + long processInstanceId = ...; + ProcessInstance processInstance = + jbpmContext.loadProcessInstance(processInstanceId); + processInstance.signal(); + jbpmContext.save(processInstance); +} finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_4.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_4.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_4.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,13 @@ +<jbpm-context> + <service name="persistence"> + <factory> + <bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"> + <field name="isTransactionEnabled"><false /></field> + <field name="isCurrentSessionEnabled"><true /></field> + <field name="sessionFactoryJndiName"> + <string value="java:/myHibSessFactJndiName" /> + </field> + </bean> + </factory> + </service> +</jbpm-context> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_5.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_5.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_5.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,10 @@ +JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); +try { + long taskInstanceId = ...; + TaskInstance taskInstance = + jbpmContext.loadTaskInstanceForUpdate(taskInstanceId); + taskInstance.end(); + } +finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_5.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_5.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_5.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,28 @@ +<hibernate-configuration> + <session-factory> + + <!-- hibernate dialect --> + <property name="hibernate.dialect"> + org.hibernate.dialect.HSQLDialect + </property> + + <!-- DataSource properties (begin) --> + <property name="hibernate.connection.datasource"> + java:/JbpmDS + </property> + + <!-- JTA transaction properties (begin) --> + <property name="hibernate.transaction.factory_class"> + org.hibernate.transaction.JTATransactionFactory + </property> + + <property name="hibernate.transaction.manager_lookup_class"> + org.hibernate.transaction.JBossTransactionManagerLookup + </property> + + <property name="jta.UserTransaction"> + java:comp/UserTransaction + </property> + + </session-factory> +</hibernate-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_6.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_6.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_6.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,10 @@ +JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); +try { + jbpmContext.setSession(SessionFactory.getCurrentSession()); + + // your jBPM operations on jbpmContext + +} +finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_6.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_6.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_6.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<hibernate-configuration> + <!-- hql queries and type defs --> + <mapping resource="org/jbpm/db/hibernate.queries.hbm.xml" /> +</hibernate-configuration> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_7.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_7.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_7.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,14 @@ +JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); +try { + // to inject resources in the jbpmContext + //before they are used, you can use + jbpmContext.setConnection(connection); + // or + jbpmContext.setSession(session); + // or + jbpmContext.setSessionFactory(sessionFactory); + +} +finally { + jbpmContext.close(); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_7.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_7.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_7.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +<cache usage="nonstrict-read-write"/> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_8.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_8.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/persistence_8.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,16 @@ +<jbpm-context> + <service name="persistence"> + <factory> + <bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"> + <field name="isTransactionEnabled"><false /></field> + <field name="sessionFactoryJndiName"> + <string value="java:/myHibSessFactJndiName" /> + </field> + <field name="dataSourceJndiName"> + <string value="java:/myDataSourceJndiName" /> + </field> + </bean> + </factory> + </service> +... +</jbpm-context> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/pluggable_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/pluggable_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/pluggable_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,9 @@ +public interface ProcessArchiveParser { + + void writeToArchive( + ProcessDefinition processDefinition, ProcessArchive archive); + + ProcessDefinition readFromArchive( + ProcessArchive archive, ProcessDefinition processDefinition); + +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/scheduler_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/scheduler_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/scheduler_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,9 @@ +<state name='catch crooks'> + <timer name='reminder' + duedate='3 business hours' + repeat='10 business minutes' + transition='time-out-transition' > + <action class='the-remainder-action-class-name' /> + </timer> + <transition name='time-out-transition' to='...' /> +</state> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,13 @@ +public class CreateTasks implements ActionHandler { + public void execute(ExecutionContext executionContext) throws Exception { + Token token = executionContext.getToken(); + TaskMgmtInstance tmi = executionContext.getTaskMgmtInstance(); + + TaskNode taskNode = (TaskNode) executionContext.getNode(); + Task changeNappy = taskNode.getTask("change nappy"); + + // now, 2 task instances are created for the same task. + tmi.createTaskInstance(changeNappy, token); + tmi.createTaskInstance(changeNappy, token); + } +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,7 @@ +<task name="clean ceiling"> + <controller> + <variable name="a" access="read" mapped-name="x" /> + <variable name="b" access="read,write,required" mapped-name="y" /> + <variable name="c" access="read,write" /> + </controller> +</task> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_2.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_2.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_2.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +public interface TaskControllerHandler extends Serializable { + void initializeTaskVariables(TaskInstance taskInstance, ContextInstance contextInstance, Token token); + void submitTaskVariables(TaskInstance taskInstance, ContextInstance contextInstance, Token token); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_2.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_2.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_2.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,5 @@ +<task name="clean ceiling"> + <controller class="com.yourcom.CleanCeilingTaskControllerHandler"> + -- here goes your task controller handler configuration -- + </controller> +</task> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_3.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_3.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_3.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1 @@ +protected ExpressionSession getExpressionSession(AssignmentContext assignmentContext); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_3.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_3.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_3.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,8 @@ +<process-definition> + <swimlane name='initiator' /> + <start-state> + <task swimlane='initiator' /> + <transition to='...' /> + </start-state> + ... +</process-definition> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_4.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_4.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_4.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,24 @@ +<process-definition> + <task-node name='a'> + <task name='laundry'> + <assignment expression='previous --> group(hierarchy) --> member(boss)' /> + </task> + <transition to='b' /> + </task-node> + + <para>Syntax of the assignment expression is like this:</para> + first-term --> next-term --> next-term --> ... --> next-term + +where + +first-term ::= previous | + swimlane(swimlane-name) | + variable(variable-name) | + user(user-name) | + group(group-name) + +and + +next-term ::= group(group-type) | + member(role-name) +</programlisting> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_5.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_5.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/taskmgmt_5.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,3 @@ +<mapping resource="org/jbpm/identity/User.hbm.xml"/> +<mapping resource="org/jbpm/identity/Group.hbm.xml"/> +<mapping resource="org/jbpm/identity/Membership.hbm.xml"/> \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,44 @@ +public class AuctionTest extends TestCase { + + // parse the process definition + static ProcessDefinition auctionProcess = + ProcessDefinition.parseParResource("org/jbpm/tdd/auction.par"); + + // get the nodes for easy asserting + static StartState start = auctionProcess.getStartState(); + static State auction = (State) auctionProcess.getNode("auction"); + static EndState end = (EndState) auctionProcess.getNode("end"); + + // the process instance + ProcessInstance processInstance; + + // the main path of execution + Token token; + + public void setUp() { + // create a new process instance for the given process definition + processInstance = new ProcessInstance(auctionProcess); + + // the main path of execution is the root token + token = processInstance.getRootToken(); + } + + public void testMainScenario() { + // after process instance creation, the main path of + // execution is positioned in the start state. + assertSame(start, token.getNode()); + + token.signal(); + + // after the signal, the main path of execution has + // moved to the auction state + assertSame(auction, token.getNode()); + + token.signal(); + + // after the signal, the main path of execution has + // moved to the end state and the process has ended + assertSame(end, token.getNode()); + assertTrue(processInstance.hasEnded()); + } +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_2.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_2.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_2.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,11 @@ +static ProcessDefinition auctionProcess = + ProcessDefinition.parseXmlString( + "<process-definition>" + + " <start-state name='start'>" + + " <transition to='auction'/>" + + " </start-state>" + + " <state name='auction'>" + + " <transition to='end'/>" + + " </state>" + + " <end-state name='end'/>" + + "</process-definition>"); Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_3.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_3.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_3.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,2 @@ +static ProcessDefinition auctionProcess = + ProcessDefinition.parseXmlResource("org/jbpm/tdd/auction.xml"); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_4.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_4.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tdd_4.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,2 @@ +static ProcessDefinition auctionProcess = + ProcessDefinition.parseParResource("org/jbpm/tdd/auction.par"); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/timer1.xmlt =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/timer1.xmlt (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/timer1.xmlt 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,5 @@ +<timer name="daysBeforeHoliday" duedate="5 business days">...</timer> +<timer name="pensionDate" duedate="#{dateOfBirth} + 65 years" >...</timer> +<timer name="pensionReminder" duedate="#{dateOfPension} - 1 year" >...</timer> +<timer name="fireWorks" duedate="#{chineseNewYear} repeat="1 year" >...</timer> +<reminder name="hitBoss" duedate="#{payRaiseDay} + 3 days" repeat="1 week" /> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_1.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_1.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_1.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,42 @@ +// This example also starts from the hello world process. +// This time even without modification. +ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( + "<process-definition>" + + " <start-state>" + + " <transition to='s' />" + + " </start-state>" + + " <state name='s'>" + + " <transition to='end' />" + + " </state>" + + " <end-state name='end' />" + + "</process-definition>" +); + +ProcessInstance processInstance = + new ProcessInstance(processDefinition); + +// Fetch the context instance from the process instance +// for working with the process variables. +ContextInstance contextInstance = + processInstance.getContextInstance(); + +// Before the process has left the start-state, +// we are going to set some process variables in the +// context of the process instance. +contextInstance.setVariable("amount", new Integer(500)); +contextInstance.setVariable("reason", "i met my deadline"); + +// From now on, these variables are associated with the +// process instance. The process variables are now accessible +// by user code via the API shown here, but also in the actions +// and node implementations. The process variables are also +// stored into the database as a part of the process instance. + +processInstance.signal(); + +// The variables are accessible via the contextInstance. + +assertEquals(new Integer(500), + contextInstance.getVariable("amount")); +assertEquals("i met my deadline", + contextInstance.getVariable("reason")); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_2.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_2.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_2.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,62 @@ +public void testTaskAssignment() { + // The process shown below is based on the hello world process. + // The state node is replaced by a task-node. The task-node + // is a node in JPDL that represents a wait state and generates + // task(s) to be completed before the process can continue to + // execute. + ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( + "<process-definition name='the baby process'>" + + " <start-state>" + + " <transition name='baby cries' to='t' />" + + " </start-state>" + + " <task-node name='t'>" + + " <task name='change nappy'>" + + " <assignment" + + " class='org.jbpm.tutorial.taskmgmt.NappyAssignmentHandler' />" + + " </task>" + + " <transition to='end' />" + + " </task-node>" + + " <end-state name='end' />" + + "</process-definition>" + ); + + // Create an execution of the process definition. + ProcessInstance processInstance = + new ProcessInstance(processDefinition); + Token token = processInstance.getRootToken(); + + // Let's start the process execution, leaving the start-state + // over its default transition. + token.signal(); + // The signal method will block until the process execution + // enters a wait state. In this case, that is the task-node. + assertSame(processDefinition.getNode("t"), token.getNode()); + + // When execution arrived in the task-node, a task 'change nappy' + // was created and the NappyAssignmentHandler was called to determine + // to whom the task should be assigned. The NappyAssignmentHandler + // returned 'papa'. + + // In a real environment, the tasks would be fetched from the + // database with the methods in the org.jbpm.db.TaskMgmtSession. + // Since we don't want to include the persistence complexity in + // this example, we just take the first task-instance of this + // process instance (we know there is only one in this test + // scenario). + TaskInstance taskInstance = (TaskInstance) + processInstance + .getTaskMgmtInstance() + .getTaskInstances() + .iterator().next(); + + // Now, we check if the taskInstance was actually assigned to 'papa'. + assertEquals("papa", taskInstance.getActorId() ); + + // Now we suppose that 'papa' has done his duties and mark the task + // as done. + taskInstance.end(); + // Since this was the last (only) task to do, the completion of this + // task triggered the continuation of the process instance execution. + + assertSame(processDefinition.getNode("end"), token.getNode()); +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_3.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_3.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_3.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,15 @@ +// MyActionHandler represents a class that could execute +// some user code during the execution of a jBPM process. +public class MyActionHandler implements ActionHandler { + + // Before each test (in the setUp), the isExecuted member + // will be set to false. + public static boolean isExecuted = false; + + // The action will set the isExecuted to true so the + // unit test will be able to show when the action + // is being executed. + public void execute(ExecutionContext executionContext) { + isExecuted = true; + } +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_4.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_4.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_4.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,5 @@ + // Each test will start with setting the static isExecuted + // member of MyActionHandler to false. + public void setUp() { + MyActionHandler.isExecuted = false; + } \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_5.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_5.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_5.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,44 @@ +public void testTransitionAction() { + // The next process is a variant of the hello world process. + // We have added an action on the transition from state 's' + // to the end-state. The purpose of this test is to show + // how easy it is to integrate Java code in a jBPM process. + ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( + "<process-definition>" + + " <start-state>" + + " <transition to='s' />" + + " </start-state>" + + " <state name='s'>" + + " <transition to='end'>" + + " <action class='org.jbpm.tutorial.action.MyActionHandler' />" + + " </transition>" + + " </state>" + + " <end-state name='end' />" + + "</process-definition>" + ); + + // Let's start a new execution for the process definition. + ProcessInstance processInstance = + new ProcessInstance(processDefinition); + + // The next signal will cause the execution to leave the start + // state and enter the state 's' + processInstance.signal(); + + // Here we show that MyActionHandler was not yet executed. + assertFalse(MyActionHandler.isExecuted); + // ... and that the main path of execution is positioned in + // the state 's' + assertSame(processDefinition.getNode("s"), + processInstance.getRootToken().getNode()); + + // The next signal will trigger the execution of the root + // token. The token will take the transition with the + // action and the action will be executed during the + // call to the signal method. + processInstance.signal(); + + // Here we can see that MyActionHandler was executed during + // the call to the signal method. + assertTrue(MyActionHandler.isExecuted); + } \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_6.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_6.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_6.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,36 @@ +ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( + "<process-definition>" + + " <start-state>" + + " <transition to='s' />" + + " </start-state>" + + " <state name='s'>" + + " <event type='node-enter'>" + + " <action class='org.jbpm.tutorial.action.MyActionHandler' />" + + " </event>" + + " <event type='node-leave'>" + + " <action class='org.jbpm.tutorial.action.MyActionHandler' />" + + " </event>" + + " <transition to='end'/>" + + " </state>" + + " <end-state name='end' />" + + "</process-definition>" +); + +ProcessInstance processInstance = + new ProcessInstance(processDefinition); + +assertFalse(MyActionHandler.isExecuted); +// The next signal will cause the execution to leave the start +// state and enter the state 's'. So the state 's' is entered +// and hence the action is executed. +processInstance.signal(); +assertTrue(MyActionHandler.isExecuted); + +// Let's reset the MyActionHandler.isExecuted +MyActionHandler.isExecuted = false; + +// The next signal will trigger execution to leave the +// state 's'. So the action will be executed again. +processInstance.signal(); +// Voila. +assertTrue(MyActionHandler.isExecuted); \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_7.java =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_7.java (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/extras/tutorial_7.java 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,194 @@ +public class HelloWorldDbTest extends TestCase { + + static JbpmConfiguration jbpmConfiguration = null; + + static { + // An example configuration file such as this can be found in + // 'src/config.files'. Typically the configuration information + // is in the resource file 'jbpm.cfg.xml', but here we pass in + // the configuration information as an XML string. + + // First we create a JbpmConfiguration statically. One + // JbpmConfiguration can be used for all threads in the system, + // that is why we can safely make it static. + + jbpmConfiguration = JbpmConfiguration.parseXmlString( + "<jbpm-configuration>" + + + // A jbpm-context mechanism separates the jbpm core + // engine from the services that jbpm uses from + // the environment. + + "<jbpm-context>"+ + "<service name='persistence' "+ + " factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' />" + + "</jbpm-context>"+ + + // Also all the resource files that are used by jbpm are + // referenced from the jbpm.cfg.xml + + "<string name='resource.hibernate.cfg.xml' " + + " value='hibernate.cfg.xml' />" + + "<string name='resource.business.calendar' " + + " value='org/jbpm/calendar/jbpm.business.calendar.properties' />" + + "<string name='resource.default.modules' " + + " value='org/jbpm/graph/def/jbpm.default.modules.properties' />" + + "<string name='resource.converter' " + + " value='org/jbpm/db/hibernate/jbpm.converter.properties' />" + + "<string name='resource.action.types' " + + " value='org/jbpm/graph/action/action.types.xml' />" + + "<string name='resource.node.types' " + + " value='org/jbpm/graph/node/node.types.xml' />" + + "<string name='resource.varmapping' " + + " value='org/jbpm/context/exe/jbpm.varmapping.xml' />" + + "</jbpm-configuration>" + ); + } + + public void setUp() { + jbpmConfiguration.createSchema(); + } + + public void tearDown() { + jbpmConfiguration.dropSchema(); + } + + public void testSimplePersistence() { + // Between the 3 method calls below, all data is passed via the + // database. Here, in this unit test, these 3 methods are executed + // right after each other because we want to test a complete process + // scenario. But in reality, these methods represent different + // requests to a server. + + // Since we start with a clean, empty in-memory database, we have to + // deploy the process first. In reality, this is done once by the + // process developer. + deployProcessDefinition(); + + // Suppose we want to start a process instance (=process execution) + // when a user submits a form in a web application... + processInstanceIsCreatedWhenUserSubmitsWebappForm(); + + // Then, later, upon the arrival of an asynchronous message the + // execution must continue. + theProcessInstanceContinuesWhenAnAsyncMessageIsReceived(); + } + + public void deployProcessDefinition() { + // This test shows a process definition and one execution + // of the process definition. The process definition has + // 3 nodes: an unnamed start-state, a state 's' and an + // end-state named 'end'. + ProcessDefinition processDefinition = + ProcessDefinition.parseXmlString( + "<process-definition name='hello world'>" + + " <start-state name='start'>" + + " <transition to='s' />" + + " </start-state>" + + " <state name='s'>" + + " <transition to='end' />" + + " </state>" + + " <end-state name='end' />" + + "</process-definition>" + ); + + //Lookup the pojo persistence context-builder that is configured above + JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + try { + // Deploy the process definition in the database + jbpmContext.deployProcessDefinition(processDefinition); + + } finally { + // Tear down the pojo persistence context. + // This includes flush the SQL for inserting the process definition + // to the database. + jbpmContext.close(); + } + } + + public void processInstanceIsCreatedWhenUserSubmitsWebappForm() { + // The code in this method could be inside a struts-action + // or a JSF managed bean. + + //Lookup the pojo persistence context-builder that is configured above + JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + try { + + GraphSession graphSession = jbpmContext.getGraphSession(); + + ProcessDefinition processDefinition = + graphSession.findLatestProcessDefinition("hello world"); + + //With the processDefinition that we retrieved from the database, we + //can create an execution of the process definition just like in the + //hello world example (which was without persistence). + ProcessInstance processInstance = + new ProcessInstance(processDefinition); + + Token token = processInstance.getRootToken(); + assertEquals("start", token.getNode().getName()); + // Let's start the process execution + token.signal(); + // Now the process is in the state 's'. + assertEquals("s", token.getNode().getName()); + + // Now the processInstance is saved in the database. So the + // current state of the execution of the process is stored in the + // database. + jbpmContext.save(processInstance); + // The method below will get the process instance back out + // of the database and resume execution by providing another + // external signal. + + } finally { + // Tear down the pojo persistence context. + jbpmContext.close(); + } + } + + public void theProcessInstanceContinuesWhenAnAsyncMessageIsReceived() { + //The code in this method could be the content of a message driven bean. + + // Lookup the pojo persistence context-builder that is configured above + JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); + try { + + GraphSession graphSession = jbpmContext.getGraphSession(); + // First, we need to get the process instance back out of the + // database. There are several options to know what process + // instance we are dealing with here. The easiest in this simple + // test case is just to look for the full list of process instances. + // That should give us only one result. So let's look up the + // process definition. + + ProcessDefinition processDefinition = + graphSession.findLatestProcessDefinition("hello world"); + + //Now search for all process instances of this process definition. + List processInstances = + graphSession.findProcessInstances(processDefinition.getId()); + + // Because we know that in the context of this unit test, there is + // only one execution. In real life, the processInstanceId can be + // extracted from the content of the message that arrived or from + // the user making a choice. + ProcessInstance processInstance = + (ProcessInstance) processInstances.get(0); + + // Now we can continue the execution. Note that the processInstance + // delegates signals to the main path of execution (=the root token). + processInstance.signal(); + + // After this signal, we know the process execution should have + // arrived in the end-state. + assertTrue(processInstance.hasEnded()); + + // Now we can update the state of the execution in the database + jbpmContext.save(processInstance); + + } finally { + // Tear down the pojo persistence context. + jbpmContext.close(); + } + } +} \ No newline at end of file Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/assignment.model.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/assignment.model.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/async.continuation.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/async.continuation.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/async1.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/async1.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/asynchronous.continuations.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/asynchronous.continuations.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/auction.process.graph.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/auction.process.graph.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/auction.test.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/auction.test.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/bpm.product.continuum.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/bpm.product.continuum.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/concurrent.executions.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/concurrent.executions.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/create_database.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/create_database.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/database.update.example.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/database.update.example.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/db.factory.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/db.factory.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/designer.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/designer.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/example.process.language.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/example.process.language.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/example.process.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/example.process.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/execution.class.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/execution.class.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/execution.event.method.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/execution.event.method.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/graph.execution.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/graph.execution.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/graphexecution.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/graphexecution.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hello.world.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hello.world.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hidden.actions.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hidden.actions.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hsqldb_dbm.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hsqldb_dbm.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hsqldb_mbean.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/hsqldb_mbean.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/identity.model.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/identity.model.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/improved.bpm.approach.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/improved.bpm.approach.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/install_driver.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/install_driver.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/jmx_console.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/jmx_console.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/languages.overview.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/languages.overview.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/load_mysql_shell1.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/load_mysql_shell1.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/load_mysql_shell2.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/load_mysql_shell2.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/logging.model.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/logging.model.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mixed.responsibilities.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mixed.responsibilities.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/model.transformations.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/model.transformations.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mysql_admin.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mysql_admin.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mysql_create_database.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/mysql_create_database.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/new.execution.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/new.execution.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/node.execute.method.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/node.execute.method.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/node.transition.classes.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/node.transition.classes.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/overview.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/overview.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/persistence.api.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/persistence.api.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/pluggable.architecture.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/pluggable.architecture.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/pojo.command.executor.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/pojo.command.executor.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/responsibility.matrix.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/responsibility.matrix.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/scheduler.classes.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/scheduler.classes.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/scheduler.overview.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/scheduler.overview.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/service.orchestration.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/service.orchestration.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/task.controllers.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/task.controllers.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/title_logo.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/title_logo.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/traditional.bpm.approach.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/traditional.bpm.approach.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/transition.take.method.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/transition.take.method.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/two.dim.fragmentation.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/two.dim.fragmentation.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/update.erp.example.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/update.erp.example.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/wait.state.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/wait.state.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/workflow.landscape.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/images/workflow.landscape.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/introduction.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/introduction.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/introduction.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -3,8 +3,9 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "jBPM_jPDL_User_Guide.ent"> %BOOK_ENTITIES; ]> + <chapter id="introduction"> - <title> + <title> Introduction </title> @@ -15,8 +16,16 @@ this book not only teaches how to use the software but explains, in significant detail, how it works. </para> + + <note> + <para> + This <emphasis>Guide</emphasis> contains a lot of terminology. + Definitions for the key terms can be found in <xref + linkend="helpfuldefinitions"/>. + </para> + </note> - <para> + <para> The JBoss <firstterm>Business Process Manager</firstterm> (jBPM) is a flexible and extensible scaffolding for process languages. The <firstterm>jBPM Process Definition Language</firstterm> (JPDL) is @@ -30,8 +39,8 @@ the language has a powerful and extensible <firstterm>control flow mechanism</firstterm>. </para> - - <para> + + <para> The JPDL has few dependencies, making it is as easy to install as a Java library. To do so, deploy it on a <firstterm>J2EE clustered application server</firstterm>. One will find it particularly useful @@ -43,9 +52,9 @@ The JPDL can be configured for use with any database. It can also be deployed on any application server. </para> - </note> - - <section> + </note> + + <section> <title> Overview </title> @@ -62,13 +71,13 @@ processes. </para> - <figure id="overview.image"> - <title>Overview of the jPDL components</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/overview.gif"/></imageobject></mediaobject> - </figure> - </section> + <figure id="overview.image"> + <title>Overview of the jPDL components</title> + <mediaobject><imageobject><imagedata fileref="images/overview.png"/></imageobject></mediaobject> + </figure> + </section> - <section> + <section> <title> The jPDL Suite </title> @@ -272,28 +281,53 @@ </para> </note> - - - </section> - - <section> - <title>The JBoss jBPM Job Executor</title> - <para>The job executor is a component for monitoring and executing jobs in - a standard Java environment. Jobs are used for timers and asynchronous messages. In an - enterprise environment, JMS and the EJB Timer Service can be used for that purpose. Conversely, - the job executor can be used in an environment where neither JMS nor EJB are available. + + </section> + + +<section> + <title> + The JBoss jBPM Job Executor + </title> + + <para> + The <firstterm>JBoss jBPM Job Executor</firstterm> is a component + designed for the purpose of monitoring and executing jobs in a + standard Java environment. <firstterm>Jobs</firstterm> are used for + timers and asynchronous messages. (In an enterprise environment, the + Java Message Service and the Enterprise Java Bean + <classname>TimerService</classname> might be used for this purpose; + the Job Executor is best used in a "standard" environment.) </para> - <para>The job executor component is packaged in the core jbpm-jpdl library, but it needs - to be deployed in one of the following ways: either register the <literal>JobExecutorLauncher</literal> - servlet context listener in the web app deployment descriptor to start/stop the job - executor during creation/destruction of the servlet context, or start up a separate JVM - and start the job executor in there programatically.</para> - <para> + The Job Executor component is packaged in the core + <classname>jbpm-jpdl</classname> library. It can only be deployed in + one of the following two scenarios: + </para> + + <itemizedlist> + <listitem><para>if the <classname>JbpmThreadsServlet</classname> has + been configured to start the Job Executor.</para></listitem> + + <listitem><para>if a separate Java Virtual Machine has been started so that the Job + Executor thread can be run from within it</para></listitem> + </itemizedlist> + + + + </section> + <section> + <title> + Conclusion + </title> + <para> Having read this chapter, you have gained a broad overview of the jBPM and its constituent components. </para> - </section> + + </section> + + </chapter> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_Reference_Guide.ent =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_Reference_Guide.ent (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_Reference_Guide.ent 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,4 @@ +<!ENTITY PRODUCT "jBPM3"> +<!ENTITY BOOKID "jBPM_jPDL_User_Guide"> +<!ENTITY YEAR "2010"> +<!ENTITY HOLDER "The jBPM Project"> Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_Reference_Guide.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_Reference_Guide.xml (rev 0) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_Reference_Guide.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -0,0 +1,35 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "jBPM_jPDL_User_Guide.ent"> +%BOOK_ENTITIES; +]> +<book> + <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +<!-- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> + + <xi:include href= "introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="persistence.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="database.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="enterprise.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="modelling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="context.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="taskmgmt.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="scheduler.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="async.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="calendar.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="mail.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jpdl.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="tdd.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="pluggable.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="LGPL_Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</book> + Deleted: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_jPDL_User_Guide.ent =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_jPDL_User_Guide.ent 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_jPDL_User_Guide.ent 2010-08-09 00:42:27 UTC (rev 6552) @@ -1,4 +0,0 @@ -<!ENTITY PRODUCT "jBPM3"> -<!ENTITY BOOKID "jBPM_jPDL_User_Guide"> -<!ENTITY YEAR "2010"> -<!ENTITY HOLDER "The jBPM Project"> Deleted: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_jPDL_User_Guide.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_jPDL_User_Guide.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jBPM_jPDL_User_Guide.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -1,35 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY % BOOK_ENTITIES SYSTEM "jBPM_jPDL_User_Guide.ent"> -%BOOK_ENTITIES; -]> -<book> - <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -<!-- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> - - <xi:include href= "introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="persistence.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="database.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="enterprise.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="modelling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="context.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="taskmgmt.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="scheduler.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="async.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="calendar.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="mail.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="logging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="jpdl.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="tdd.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="pluggable.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="LGPL_Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - -</book> - Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jpdl.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jpdl.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/jpdl.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -5,141 +5,316 @@ ]> <chapter id="jpdl"> - <title>jBPM Process Definition Language (JPDL)</title> + <title> + The jBPM Process Definition Language + </title> - <para>JPDL specifies an xml schema and the mechanism to package all the process - definition related files into a process archive. + <para> + The <firstterm>jBPM Process Definition Language</firstterm> (JPDL) + specifies both an XML schema and the mechanism through which to + package all of the process definition-related files into a + <firstterm>process archive</firstterm>. </para> <section id="theprocessarchive"> - <title>The process archive</title> - <para>A process archive is a zip file. The central file in the process archive is - <literal>processdefinition.xml</literal>. The main information in that file is - the process graph. The <literal>processdefinition.xml</literal> also contains - information about actions and tasks. A process archive can also contain other - process related files such as classes, ui-forms for tasks, ...</para> + <title> + The Process Archive + </title> + + <para> + A process archive is a ZIP archive. The central file it contains is + called <filename>processdefinition.xml</filename>. The main thing + held within this file is the process graph. (It also contains + information about actions and tasks.) A process archive can also + contain other process-related files, such as classes and the user + interface forms needed by tasks. + </para> <section id="deployingaprocessarchive"> - <title>Deploying a process archive</title> - <para>Deploying process archives can be done in 3 ways: with the process designer tool, - with an ant task or programatically. + <title> + Deploying a Process Archive + </title> + + <para> + One can deploy a <filename>process archive</filename> in any of three + different ways: + </para> + + <itemizedlist> + <listitem> + <para> + via the <application>Process Designer Tool</application> + </para> + </listitem> + + <listitem> + <para> + with an <command>ant</command> task + </para> + </listitem> + + + <listitem> + <para> + programatically + </para> + </listitem> + + </itemizedlist> + + + + <para> + To deploying a process archive with the <application>Process + Designer Tool</application>, follow this step. (This process is + supported in the <systemitem>starter's kit</systemitem>.) </para> - <para>Deploying a process archive with the designer tool is supported in the starters-kit. - Right click on the process archive folder to find the "Deploy process archive" option. - The starters-kit server contains the jBPM webapp, which has a servlet to upload - process archives called ProcessUploadServlet. This servlet is capable of uploading - process archives and deploying them to the default jBPM instance configured. + + <orderedlist> + <listitem> + <para> + Right-click on the process archive folder and select + the <guimenuitem>Deploy process archive</guimenuitem> + option. + </para> + + <para> + The <systemitem>starter's kit</systemitem> + server contains the <application>jBPM</application> + application, which has a servlet to upload process + archives, called + <systemitem>ProcessUploadServlet</systemitem>. This + servlet is capable of uploading process archives and + deploying them to the default + <application>jBPM</application> instance. + </para> + </listitem> + + </orderedlist> + + <para> + To deploy a process archive with an <command>ant</command> + task, use this code: </para> - <para>Deploying a process archive with an ant task can be done as follows: - </para> - <programlisting>&lt;target name="deploy.par"&gt; - &lt;taskdef name="deploypar" classname="org.jbpm.ant.DeployProcessTask"&gt; - &lt;classpath --make sure the jbpm-[version].jar is in this classpath--/&gt; - &lt;/taskdef&gt; - &lt;deploypar par="build/myprocess.par" /&gt; -&lt;/target&gt;</programlisting> - <para>To deploy more process archives at once, use the nested fileset elements. - The file attribute itself is optional. Other attributes of the ant task are:</para> - <itemizedlist> - <listitem><para>cfg: cfg is optional, the default value - is 'hibernate.cfg.xml'. The hibernate configuration file that contains the jdbc - connection properties to the database and the mapping files.</para></listitem> - <listitem><para>properties: properties is optional and - overwrites *all* hibernate properties as found in the hibernate.cfg.xml</para></listitem> - <listitem><para>createschema: if set to true, the jbpm - database schema is created before the processes get deployed.</para></listitem> - </itemizedlist> - <para>Process archives can also be deployed programmatically with the class - <literal>org.jbpm.jpdl.par.ProcessArchiveDeployer</literal> </para> + + <programlisting language="XML"><xi:include href="extras/jpdl_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> + To deploy more process archives at once, use the nested + <property>fileset</property> elements. The process attribute + itself is optional. Here are some of the <command>ant</command> + task's other attributes: + </para> + + +<table> + <title>ant Attributes</title> + <tgroup cols="3" colsep="1" rowsep="1"> + <colspec colwidth="2*"/> + <colspec colwidth="5*"/> + <colspec colwidth="2*"/> + <thead> + <row><entry>Attribute</entry><entry>Description</entry><entry>Required?</entry></row> + </thead> + <tbody> + <row> + <entry> + <property>jbpmcfg</property> + </entry> + <entry> + <para> + The default value is <filename>jbpm.cfg.xml</filename>. The JBPM + configuration file can specify the location of the Hibernate configuration file + (default value is <filename>hibernate.cfg.xml</filename>) that contains the + JDBC connection properties for the database and the mapping files. + </para> + </entry> + <entry>No</entry> + </row> + + <row> + <entry> + <property>properties</property> + </entry> + <entry> + <para> + Overwrites all. Hibernate properties as found in + the <filename>hibernate.cfg.xml</filename> file. + </para> + </entry> + <entry>No</entry> + </row> + + <row> + <entry> + <property>createschema</property> + </entry> + <entry> + <para> + When set to <code>true</code>, the jBPM database + schema is created before any processes are deployed. + </para> + </entry> + <entry>No</entry> + </row> + </tbody></tgroup> + </table> + + <para> + To deploy process archives programmatically, use the + <classname>org.jbpm.jpdl.par.ProcessArchiveDeployer</classname> + class. + </para> </section> <section id="processversioning"> - <title>Process versioning</title> - <para>What happens when we have a process definition deployed, many executions - are not yet finished and we have a new version of the process definition that - we want to deploy ? + <title> + Process Versioning + </title> + + <!-- + <para> + What happens when we have a process definition deployed, many + executions are not yet finished and we have a new version of the + process definition that we want to deploy ? </para> + --> - <para>Process instances always execute to the process definition that they are - started in. But jBPM allows for multiple process definitions of - the same name to coexist in the database. So typically, a process instance is - started in the latest version available at that time and it will keep on executing in - that same process definition for its complete lifetime. When a newer version - is deployed, newly created instances will be started in the newest version, - while older process instances keep on executing in the older process - defintions.</para> + + <para> + Process instances always execute on the same process definition as + that in which they were started. However, the + <application>jBPM</application> allows multiple process + definitions of the same name to co-exist in the database. + Typically, a process instance is started in the latest version + available at that time and it will keep on executing in that + same process definition for its complete lifetime. When a newer + version is deployed, newly created instances will be started in + the newest version, while older process instances keep on + executing in the older process definitions. + </para> - <para>If the process includes references to Java classes, the java classes can be - made available to the jBPM runtime environment in 2 ways : by making sure these - classes are visible to the jBPM classloader. This usually means that you can - put your delegation classes in a <literal>.jar</literal> file next to the - <literal>jbpm-[version].jar</literal>. In that case, all the process definitions - will see that same class file. The java classes can also be included - in the process archive. When you include your delegation classes in the process - archive (and they are not visible to the jbpm classloader), jBPM will also version - these classes inside the process definition. More information about process classloading - can be found in the section on Delegation. + <para> + If the process includes references to Java classes, these can + be made available to the jBPM runtime environment in one of two + ways: </para> - <para>When a process archive gets deployed, it creates a process definition in - the jBPM database. Process definitions can be versioned on the basis of the - process definition name. When a named process archive gets deployed, the deployer - will assign a version number. To assign this number, the deployer will look - up the highest version number for process definitions with the same name and - adds 1. Unnamed process definitions will always have version number -1. + +<itemizedlist> + <listitem> + <para> + by making sure these classes are visible to the jBPM + class-loader. + </para> + + <para> + To do so, put the delegation + classes in a <filename>.JAR</filename> file "next to" the + <filename>jbpm-[version].jar</filename> so + that + all of the process definitions will see that class + file. The Java classes can also be included in the + process archive. When you include your delegation + classes in the process archive (and they are not + visible to the jbpm classloader), the <application>jBPM</application> will also + version these classes inside the process + definition. + </para> + + <note> + <para> + Learn more about process classloading by reading <xref linkend="delegation" /> + </para> + </note> + </listitem> +</itemizedlist> + + + + <para> + When a process archive is deployed, a <firstterm>process + definition</firstterm> is created in the jBPM database. Version + process definitions on the basis of their names. When a named + process archive is deployed, the deployer assigns it a version + number. It does so by searching for the highest number assigned + to a process definition of the same name and then adds one to + that value. (Unnamed process definitions will always be + versioned as <code>-1</code>.) </para> </section> <section id="changingdeployedprocessdefinitions"> - <title>Changing deployed process definitions</title> - <para>Changing process definitions after they are deployed into the - jBPM database has many potential pitfalls. Therefor, this is highly - discouraged. + <title> + Changing Deployed Process Definitions + </title> + +<warning> + <para> + It is dangerous to change process definitions after they are + deployed. Red Hat discourages this process. It is better to + migrate process instances to new definitions. </para> - <para>Actually, there is a whole variety of possible changes that can - be made to a process definition. Some of those process definitions - are harmless, but some other changes have implications far beyond the - expected and desirable. +</warning> + + + + <para> + Consider these factors before undertaking this process: </para> - <para>So please consider migrating - process instances to a new definition over this approach. + +<itemizedlist> + <listitem> + <para> + one can simply load a process definition, change it and save it + with the <application>Hibernate</application> session. (Access + the <application>Hibernate</application> session via the + <methodname>JbpmContext.getSession()</methodname> method.) </para> - <para>In case you would consider it, these are the points to take into - consideration: + </listitem> + <listitem> + <para> + one must remove a process definition from the second level + cache after having updated the existing definition. </para> - <para><emphasis role="bold">Use hibernate's update</emphasis>: You can - just load a process definition, change it and save it with the - hibernate session. The hibernate session can be accessed with - the method <literal>JbpmContext.getSession()</literal>. - </para> - <para><emphasis role="bold">The second level cache</emphasis>: A process - definition would need to be removed from the second level cache after - you've updated an existing process definition. - </para> + </listitem> +</itemizedlist> + </section> <section id="migratingprocessinstances"> - <title>Migrating process instances</title> - <para>An alternative approach to changing process definitions might be - to convert the executions to a new process definition. Please take - into account that this is not trivial due to the long-lived nature of - business processes. Currently, this is an experimental area so for which - there are not yet much out-of-the-box support. + <title> + Migrating Process Instances + </title> + + <para> + An alternative approach is to convert the executions to a new process definition. + Please take into account that this is not trivial due to the + long-lived nature of business processes. + </para> + + <note> + <para> + Currently, this is an experimental feature and is not supported + "out-of-the-box." </para> - <para>As you know - there is a clear distinction between process definition data, process - instance data (the runtime data) and the logging data. With this approach, you create a separate new process definition - in the jBPM database (by e.g. deploying a new version of the same - process). Then the runtime information is converted to the new process - definition. This might involve a translation cause tokens in the old - process might be pointing to nodes that have been removed in the new - version. So only new data is created in the database. But one execution of - a process is spread over two process instance objects. This might - become a bit tricky for the tools and statistics calculations. - When resources permit us, we are going to add support for this in the - future. E.g. a pointer could be added from one process instance to - it's predecessor. + </note> + + <para> + There is a clear distinction between process definition + data, process instance (run-time) data and logging data. + Because of this distinction, one creates a separate process + definition in the jBPM database (by, for example, deploying + a new version of the same process) and then the run-time + information is transformed into the new process definition. + (This will involve a translation if tokens in the old + process point to nodes that have been removed in the new + version.) Hence, only new data is added to the database. + Note, though, that one execution of a process is spread over + two process instance objects. This can present challenges + when developing tools and making statistics calculations. + When resources permit, Red Hat will add support for this. </para> </section> @@ -148,207 +323,359 @@ <section id="delegation"> <title>Delegation</title> - <para>Delegation is the mechanism used to include the users' custom code - in the execution of processes.</para> + <para> + Use the <firstterm>delegation</firstterm> mechanism to include + custom code in process executions. + </para> <section id="thejbpmclassloader"> - <title>The jBPM class loader</title> - <para>The jBPM class loader is the class loader that loads the jBPM classes. - Meaning, the classloader that has the library <literal>jbpm-3.x.jar</literal> - in its classpath. To make classes visible to the jBPM classloader, put them - in a jar file and put the jar file besides the <literal>jbpm-3.x.jar</literal>. - E.g. in the WEB-INF/lib folder in the case of webapplications. + <title> + The jBPM Class Loader + </title> + + <para> + The jBPM class loader is that which loads the jBPM classes. It + can do so as it has the <filename>jbpm-3.x.jar</filename> + filename in its class-path. To make classes visible to the jBPM + class loader, place them in a JAR file and put that JAR file + "besides" the <filename>jbpm-3.x.jar</filename> (in the + <filename>WEB-INF/lib</filename> directory, for instance, in + the case of web applications.) </para> </section> <section id="theprocessclassloader"> - <title>The process class loader</title> - <para>Delegation classes are loaded with the process class loader of their - respective process definition. The process class loader is a class loader - that has the jBPM classloader as a parent. The process class loader adds all - the classes of one particular process definition. You can add classes to a - process definition by putting them in the <literal>/classes</literal> folder - in the process archive. Note that this is only useful when you want to version - the classes that you add to the process definition. If versioning is not necessary, - it is much more efficient to make the classes available to the jBPM class loader.</para> + <title> + The Process Class Loader + </title> + + <para> + Delegation classes are loaded with their respective process + definitions' <firstterm>process class loader</firstterm>. (The + process class loader is a class loader that has the jBPM class + loader as a parent. It adds all of the classes of one + particular process definition.) Add classes to a process + definition by putting them in the process archive's + <filename>/classes</filename> directory. Note that this is only + useful when one wishes to version the classes that have been + added to the process definition. If versioning is not required, + make the classes available to the jBPM class loader instead. + </para> - <para>If the resource name doesn't start with a slash, resources are also loaded - from the <literal>/classes</literal> directory in the process archive. If you - want to load resources outside of the classes - directory, start with a double slash (<literal> // </literal>). For example - to load resource <literal>data.xml</literal> wich is located next to the - processdefinition.xml on the root of the process archive file, you can do - <literal>clazz.getResource("//data.xml")</literal> or - <literal>classLoader.getResourceAsStream("//data.xml")</literal> or any of those - variants. + <para> + If the resource name does not start with a slash, resources are + also loaded from the process archive's + <filename>/classes</filename> directory. To load resources that + reside outside this directory, start the path with a double + forward slash (<code>//</code>). (For example, to load + <filename>data.xml</filename> which is located "next to" the + <filename>processdefinition.xml</filename> on the root of the + process archive file, use + <methodname>class.getResource("//data.xml")</methodname> or + <methodname>classLoader.getResourceAsStream("//data.xml")</methodname> + or any variant of these.) </para> </section> <section id="configurationofdelegations"> - <title>Configuration of delegations</title> - <para>Delegation classes contain user code that is called from within the - execution of a process. The most common example is an action. In the case of - action, an implementation of the interface <literal>ActionHandler</literal> can - be called on an event in the process. Delegations are specified in the - <literal>processdefinition.xml</literal>. 3 pieces of data can be supplied when - specifying a delegation : </para> - <itemizedlist> - <listitem><para>1) the class name (required) : the fully qualified class name of the - delegation class.</para></listitem> - <listitem><para>2) configuration type (optional) : specifies the way to instantiate - and configure the delegation object. By default the default + <title> + Configuring Delegations + </title> + + <para> + Delegation classes contain user code that is called from within + a process execution, the most common example being an + <firstterm>action</firstterm>. In the case of action, an + implementation of the + <interfacename>ActionHandler</interfacename> interface can be + called on an event in the process. (Delegations are specified + in the <filename>processdefinition.xml</filename> file.) One + can supply any of these three pieces of data when specifying a + delegation: + </para> + + + <orderedlist> + <listitem><para>the class name (required): this is the delegation class' fully-qualified name.</para></listitem> + <listitem><para>configuration type (optional): this specifies the way in which to instantiate + and configure the delegation object. By default, the constructor is used and the configuration information is ignored.</para></listitem> - <listitem><para>3) configuration (optional) : the configuration of the delegation - object in the format as required by the configuration type.</para></listitem> - </itemizedlist> - <para>Next is a description of all the configuration types:</para> + <listitem><para>configuration (optional): this is the configuration of the delegation + object, which must be in the format required by the configuration type.</para></listitem> + </orderedlist> + + + <para> + Here are descriptions of every type of configuration: + </para> + <section id="configtypefield"> - <title>config-type field</title> - <para>This is the default configuration type. The <literal>config-type field</literal> will first instantiate an object - of the delegation class and then set values in the fields of the object as - specified in the configuration. The configuration is xml, where the - elementnames have to correspond with the field names of the class. The content - text of the element is put in the corresponding field. If necessary and possible, - the content text of the element is converted to the field type. + <title> + config-type field + </title> + + <para> + This is the default configuration type. The + <property>config-type</property> field first instantiates + an object of the delegation class and then set values in + those object fields specified in the configuration. The + configuration is stored in an XML file. In this file, the + element names have to correspond to the class' field names. + The element's content text is put in the corresponding + field. If both necessary and possible to do, the element's + content text is converted to the field type. </para> - <para>Supported type conversions:</para> + + <para> + These are the supported type conversions: + </para> + <itemizedlist> - <listitem><para>String doesn't need converting, of course. But it is trimmed.</para> + <listitem><para>string is trimmed but not converted.</para> </listitem> <listitem><para>primitive types such as int, long, float, double, ...</para> </listitem> - <listitem><para>and the basic wrapper classes for the primitive types.</para> + <listitem><para>the basic wrapper classes for the primitive types.</para> </listitem> - <listitem><para>lists, sets and collections. In that case each element of the - xml-content is consitered as an element of the collection and is parsed, recursively applying the - conversions. If the type of the elements is different from <literal>java.lang.String</literal> - this can be indicated by specifying a type attribute with the fully qualified type name. - For example, following snippet will inject an ArrayList of Strings into field 'numbers': - </para></listitem></itemizedlist> - <programlisting>&lt;numbers&gt; + <listitem><para>lists, sets and collections. In these cases, each element of the + xml-content is considered an element of the collection and is parsed recursively, applying the + conversions. If the element types differ from <classname>java.lang.String</classname> + indicate this by specifying a type attribute with the fully-qualified type name. + For example, this code injects an <classname>ArrayList</classname> of strings into <property>numbers</property> field:</para> + + + <programlisting language="XML">&lt;numbers&gt; &lt;element&gt;one&lt;/element&gt; &lt;element&gt;two&lt;/element&gt; &lt;element&gt;three&lt;/element&gt; &lt;/numbers&gt;</programlisting> - <para>The text in the elements can be converted to any object that has a String constructor. - To use another type then String, specify the <literal>element-type</literal> in the - field element ('numbers' in this case). + + + <para> + One can convert the text in the elements to any object + that has a string constructor. To use a type other than + a string, specify the <property>element-type</property> + in the field (<property>numbers</property> in this + case). </para> - <para>Here's another example of a map: + + <para> + Here is another example of a map: </para> - <programlisting>&lt;numbers&gt; + + <programlisting language="XML">&lt;numbers&gt; &lt;entry&gt;&lt;key&gt;one&lt;/key&gt;&lt;value&gt;1&lt;/value&gt;&lt;/entry&gt; &lt;entry&gt;&lt;key&gt;two&lt;/key&gt;&lt;value&gt;2&lt;/value&gt;&lt;/entry&gt; &lt;entry&gt;&lt;key&gt;three&lt;/key&gt;&lt;value&gt;3&lt;/value&gt;&lt;/entry&gt; &lt;/numbers&gt;</programlisting> - <itemizedlist> - <listitem><para>maps. In this case, each element of the field-element is expected to have one subelement - <literal>key</literal> and one element <literal>value</literal>. The key and element are both - parsed using the conversion rules recursively. Just the same as with collections, a conversion to - <literal>java.lang.String</literal> is assumed if no <literal>type</literal> attribute is specified.</para> + </listitem> + + + <listitem> + <para> + In this case, each of the field elements is expected to + have one <property>key</property> and one + <property>value</property> sub-element. Parse both of these + by using the conversion rules recursively. As with + collections, it will be assumed that a conversion to + <classname>java.lang.String</classname> is intended if one + does not specify a <property>type</property> attribute. + </para> </listitem> - <listitem><para>org.dom4j.Element</para> + <listitem><para><classname>org.dom4j.Element</classname></para> </listitem> <listitem><para>for any other type, the string constructor is used.</para> </listitem> </itemizedlist> - <para>For example in the following class...</para> - <programlisting>public class MyAction implements ActionHandler { + <para> + Look at this class: + </para> + + + <programlisting language="Java">public class MyAction implements ActionHandler { // access specifiers can be private, default, protected or public private String city; Integer rounds; ... }</programlisting> - <para>...this is a valid configuration:</para> - <programlisting>... + + + <para> + This is a valid configuration for that class: + </para> + + <programlisting language="XML">... &lt;action class="org.test.MyAction"&gt; &lt;city&gt;Atlanta&lt;/city&gt; &lt;rounds&gt;5&lt;/rounds&gt; &lt;/action&gt; ...</programlisting> + </section> + + <section id="configtypebean"> - <title>config-type bean</title> - <para>Same as <literal>config-type field</literal> but then the properties are - set via setter methods, rather then directly on the fields. The same conversions - are applied.</para> + <title> + config-type bean + </title> + + <para> + This is the same as the <property>config-type</property> + field but, in that case, the properties are configured via + "setter" methods. Here they are set directly on the fields. + The same conversions are applied. + </para> </section> + <section id="configtypeconstructor"> - <title>config-type constructor</title> - <para>This instantiator will take the complete contents of the delegation - xml element and passes this as text in the delegation class constructor.</para> + <title> + config-type constructor + </title> + + <para> + This method takes the complete contents of the delegation + XML element and passes them as text to the delegation class + constructor. + </para> + </section> + <section id="configtypeconfigurationproperty"> - <title>config-type configuration-property</title> - <para>First, the default constructor is used, then this instantiator will - take the complete contents of the delegation xml element, and pass it as text - in method <literal>void configure(String);</literal>. (as in jBPM 2)</para> + + <title> + config-type configuration-property + </title> + + <para> + If one firstly use the default constructor this method will then + take the complete contents of the delegation XML + element, and pass it as text in the <methodname>void + configure(String);</methodname> method. + </para> + </section> </section> </section> <section id="expressions"> - <title>Expressions</title> - <para>For some of the delegations, there is support for a JSP/JSF EL like expression - language. In actions, assignments and decision conditions, you can write an - expression like e.g. <literal>expression="#{myVar.handler[assignments].assign}"</literal> + <title> + Expressions + </title> + + <para> + There is limited support for a JSP/JSF EL-like expression + language. In actions, assignments and decision conditions, one + can write this kind of expression: + <code>expression="#{myVar.handler[assignments].assign}"</code> </para> - <para>The basics of this expression language can be found - in the J2EE - tutorial (<ulink url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JSPIntro7.html&q... />). + + +<note> + <para> + To learn about this expression language, study this tutorial: + <ulink + url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JSPIntro7.html&q... + />. </para> - <para>The jPDL expression language is similar to the JSF expression language. Meaning that - jPDL EL is based on JSP EL, but it uses <literal>#{...}</literal> notation and that it - includes support for method binding. +</note> + + <para> + The jPDL and JSF expression languages are similar. jPDL EL is + based on JSF EL but, in contrast to the latter, it employs + <code>#{...}</code> notation and includes support for + method-binding. </para> - <para>Depending on the context, the process variables or task instance variables can - be used as starting variables along with the following implicit objects: + + + <para> + Depending on the context, the process and task + instance variables can be used as starting variables, as can the + the following implicit objects: </para> + <itemizedlist> - <listitem><para>taskInstance (org.jbpm.taskmgmt.exe.TaskInstance)</para></listitem> - <listitem><para>processInstance (org.jbpm.graph.exe.ProcessInstance)</para></listitem> - <listitem><para>processDefinition (org.jbpm.graph.def.ProcessDefinition)</para></listitem> - <listitem><para>token (org.jbpm.graph.exe.Token)</para></listitem> - <listitem><para>taskMgmtInstance (org.jbpm.taskmgmt.exe.TaskMgmtInstance)</para></listitem> - <listitem><para>contextInstance (org.jbpm.context.exe.ContextInstance)</para></listitem> + <listitem><para>taskInstance (<classname>org.jbpm.taskmgmt.exe.TaskInstance</classname>)</para></listitem> + <listitem><para>processInstance (<classname>org.jbpm.graph.exe.ProcessInstance</classname>)</para></listitem> + <listitem><para>processDefinition (<classname>org.jbpm.graph.def.ProcessDefinition</classname>)</para></listitem> + <listitem><para>token (<classname>org.jbpm.graph.exe.Token</classname>)</para></listitem> + <listitem><para>taskMgmtInstance (<classname>org.jbpm.taskmgmt.exe.TaskMgmtInstance</classname>)</para></listitem> + <listitem><para>contextInstance (<classname>org.jbpm.context.exe.ContextInstance</classname>)</para></listitem> </itemizedlist> - <para>This feature becomes really powerfull in a JBoss SEAM environment. - Because of the integration between jBPM and - JBoss SEAM (<ulink url="http://www.jboss.com/products/seam" />), all of your backed - beans, EJB's and other <literal>one-kind-of-stuff</literal> becomes available right - inside of your process definition. Thanks Gavin ! Absolutely awsome ! :-) - </para> + + <para> + This feature becomes powerful when used in a <application>JBoss + SEAM</application> environment (<ulink + url="http://www.jboss.com/products/seam" />). Because of the + integration between the jBPM and SEAM, every <firstterm>backed + bean</firstterm>, Enterprise Java Bean and so forth becomes accessible from + within one's process definition. + </para> </section> <section> - <title>jPDL xml schema</title> - <para>The jPDL schema is the schema used in the file - <literal>processdefinition.xml</literal> in the process archive.</para> + <title> + jPDL XML Schema + </title> + + <para> + The jPDL schema is the schema used in the process archive's + <filename>processdefinition.xml</filename> file. + </para> <section id="processdefinition.validation"> - <title>Validation</title> - <para>When parsing a jPDL XML document, jBPM will validate your document against the - jPDL schema when two conditions are met: first, the schema has to be referenced in the - XML document like this + <title> + Validation + </title> + + <para> + When parsing a jPDL XML document, jBPM will validate it against + the schema when these two conditions are met: </para> - <programlisting>&lt;process-definition xmlns=&quot;urn:jbpm.org:jpdl-3.2&quot;&gt; + + <orderedlist> + <listitem> + <para> + The schema is referenced in the XML document: + </para> + + <programlisting language="XML">&lt;process-definition xmlns=&quot;urn:jbpm.org:jpdl-3.2&quot;&gt; ... &lt;/process-definition&gt;</programlisting> - <para>And second, the xerces parser has to be on the classpath.</para> - <para>The jPDL schema can be found in <literal>${jbpm.home}/src/java.jbpm/org/jbpm/jpdl/xml/jpdl-3.2.xsd</literal> - or at <ulink url="http://jbpm.org/jpdl-3.2.xsd" />. + + </listitem> + <listitem> + <para> + The <application>Xerces</application> parser is on the + class-path. + </para> + </listitem> + </orderedlist> + + <note> + <para> + Find the jPDL schema at + <filename>${jbpm.home}/src/java.jbpm/org/jbpm/jpdl/xml/jpdl-3.2.xsd</filename> + or at <ulink url="http://jbpm.org/jpdl-3.2.xsd" />. </para> + </note> + </section> <section id="processdefinition.element"> - <title>process-definition</title> + + <title> + process-definition + </title> + <table id="process.definition.schema"> - <title>process-definition schema</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Process Definition Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -362,63 +689,55 @@ <entry>name</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>the name of the process</entry> + <entry>This is the name of the process</entry> </row> <row> <entry>swimlane</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the swimlanes used in this process. The swimlanes represent process roles - and they are used for task assignments.</entry> + <entry>These are the <firstterm>swim-lanes</firstterm> used + in the process. The swim-lanes represent process roles and + are used for task assignments.</entry> </row> <row> <entry>start-state</entry> <entry>element</entry> <entry>[0..1]</entry> - <entry>the start state of the process. Note that a process without a start-state + <entry>This is the process' start state. Note that a process without a start-state is valid, but cannot be executed.</entry> </row> <row> - <entry>{end-state| - state|node| - task-node - process-state - super-state| - fork|join| - decision}</entry> + <entry>{end-state|state|node|task-node|process-state|super-state|fork|join|decision}</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the nodes of the process definition. Note that a process without nodes is valid, - but cannot be executed.</entry> + <entry>These are the process definition's nodes. Note that a process without nodes is valid, but + cannot be executed.</entry> </row> <row> <entry>event</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the process events that serve as a container for actions</entry> + <entry>These serve as a container for actions</entry> </row> <row> - <entry>{action| - script| - create-timer| - cancel-timer}</entry> + <entry>{action|script|create-timer|cancel-timer}</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>global defined actions that can be referenced from events and transitions. - Notice these actions must specify a name in order to be referenced.</entry> + <entry>These are globally-defined actions that can be referenced from events and transitions. Note that + these actions must specify a name in order to be referenced.</entry> </row> <row> <entry>task</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>global defined tasks that can be used in e.g. actions.</entry> + <entry>These are globally-defined tasks that can be used in e.g. actions.</entry> </row> <row> <entry>exception-handler</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>a list of exception handlers that applies to all - exceptions thrown by delegation classes thrown in this process definition.</entry> + <entry>This is a list of those exception handlers that applies to all + errors thrown by delegation classes in this process definition.</entry> </row> </tbody> </tgroup> @@ -429,9 +748,11 @@ <title>node</title> <table frame="topbot" id="node.schema"> <title>Node Schema</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -442,19 +763,16 @@ </thead> <tbody> <row> - <entry>{action| - script| - create-timer| - cancel-timer}</entry> + <entry>{action|script|create-timer|cancel-timer}</entry> <entry>element</entry> <entry>1</entry> - <entry>a custom action that represents the behaviour for this node</entry> + <entry>This is a custom action that represents the behaviour for this node</entry> </row> <row> <entry>common node elements</entry> <entry></entry> <entry></entry> - <entry>See common node elements</entry> + <entry><xref linkend="common.node.elements" /></entry> </row> </tbody> </tgroup> @@ -464,10 +782,12 @@ <section id="common.node.elements"> <title>common node elements</title> <table frame="topbot" id="common.node.schema"> - <title>common node elements</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Common Node Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -481,23 +801,23 @@ <entry>name</entry> <entry>attribute</entry> <entry>required</entry> - <entry>the name of the node</entry> + <entry>This is the name of the node</entry> </row> <row> <entry>async</entry> <entry>attribute</entry> <entry>{ true | false }, false is the default</entry> <entry>If set to true, this node will be executed asynchronously. - + See also <xref linkend="asynchronouscontinuations" /> </entry> </row> <row> <entry>transition</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the leaving transitions. Each transition leaving a + <entry>These are the leaving transitions. Each transition leaving a node *must* have a distinct name. A maximum of one of the leaving transitions is - allowed to have no name. The first transition that is specifed is called + allowed to have no name. The first transition that is specified is called the default transition. The default transition is taken when the node is left without specifying a transition.</entry> </row> @@ -505,20 +825,20 @@ <entry>event</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>supported event types: {node-enter|node-leave}</entry> + <entry>There are two supported event types: <code>{node-enter|node-leave}</code></entry> </row> <row> <entry>exception-handler</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>a list of exception handlers that applies to all - exceptions thrown by delegation classes thrown in this process node.</entry> + <entry>This is a list of exception handlers that applies to every + bug thrown by a delegation class from within this process node.</entry> </row> <row> <entry>timer</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>specifies a timer that monitors the duration of an execution in this node.</entry> + <entry>This specifies a timer that monitors the duration of an execution in this node.</entry> </row> </tbody> </tgroup> @@ -528,10 +848,12 @@ <section id="startstate.element"> <title>start-state</title> <table frame="topbot" id="start.state.schema"> - <title>start-state</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Start State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -545,33 +867,34 @@ <entry>name</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>the name of the node</entry> + <entry>This is the name of the node</entry> </row> <row> <entry>task</entry> <entry>element</entry> <entry>[0..1]</entry> - <entry>the task to start a new instance for this process or to capture the process initiator. </entry> + <entry>This is the task used to start a new instance for this process or to capture the process initiator. + See <xref linkend="swimlaneinstarttask"/></entry> </row> <row> <entry>event</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>supported event types: {node-leave}</entry> + <entry>This is the supported event type: <code>{node-leave}</code></entry> </row> <row> <entry>transition</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the leaving transitions. Each transition leaving a - node *must* have a distinct name.</entry> + <entry>These are the leaving transitions. Each transition leaving a + node must have a distinct name.</entry> </row> <row> <entry>exception-handler</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>a list of exception handlers that applies to all - exceptions thrown by delegation classes thrown in this process node.</entry> + <entry>This is a list of exception handlers that applies to every + bug thrown by a delegation class from within this process node.</entry> </row> </tbody> </tgroup> @@ -581,10 +904,12 @@ <section id="endstate.element"> <title>end-state</title> <table frame="topbot" id="end.state.schema"> - <title>end-state</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>End State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -598,30 +923,31 @@ <entry>name</entry> <entry>attribute</entry> <entry>required</entry> - <entry>the name of the end-state</entry> + <entry>This is the name of the end-state</entry> </row> <row> <entry>end-complete-process</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>By default end-complete-process is false which means - that only the token ending this end-state is - ended. If this token was the last child to end, the parent - token is ended recursively. If you set this property to - true, then the full process instance is ended.</entry> + <entry>If the <classname>end-complete-process</classname> is + set to <code>false</code>, only the token concluding + this end-state is finished. If this token was the last + child to end, the parent token is ended recursively. + Set this property to <code>true</code>, to ensure that + the full process instance is ended.</entry> </row> <row> <entry>event</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>supported event types: {node-enter}</entry> + <entry>The supported event type is <code>{node-enter}</code></entry> </row> <row> <entry>exception-handler</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>a list of exception handlers that applies to all - exceptions thrown by delegation classes thrown in this process node.</entry> + <entry>This is a list of exception handlers that applies to every + bug thrown by a delegation class from within this process node.</entry> </row> </tbody> </tgroup> @@ -631,10 +957,12 @@ <section id="state.element"> <title>state</title> <table frame="topbot" id="state.schema"> - <title>state</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -648,7 +976,7 @@ <entry>common node elements</entry> <entry></entry> <entry></entry> - + <entry>See <xref linkend="common.node.elements" /></entry> </row> </tbody> </tgroup> @@ -658,10 +986,12 @@ <section id="tasknode.element"> <title>task-node</title> <table frame="topbot" id="task.node.schema"> - <title>task-node</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Task Node Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -675,40 +1005,48 @@ <entry>signal</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{unsynchronized|never|first|first-wait|last|last-wait}, default - is <literal>last</literal>. signal specifies the effect of task completion - on the process execution continuation.</entry> + <entry>This can be + <code>{unsynchronized|never|first|first-wait|last|last-wait}</code>, + the default being <code>last</code>. It specifies the + way in which task completion affects + <firstterm>process execution + continuation</firstterm>.</entry> </row> <row> <entry>create-tasks</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{yes|no|true|false}, default is <literal>true</literal>. can be set - to false when a runtime calculation has to determine which of the tasks have - to be created. in that case, add an action on <literal>node-enter</literal>, - create the tasks in the action and set <literal>create-tasks</literal> to - <literal>false</literal>.</entry> + <entry>This can be <code>{yes|no|true|false}</code>, with the + default being <code>true</code>. Set it to + <code>false</code> when a run-time calculation has to + determine which of the tasks have to be created. In + that case, add an action on + <property>node-enter</property>, create the tasks in + the action and set <property>create-tasks</property> + to <code>false</code>.</entry> </row> <row> <entry>end-tasks</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{yes|no|true|false}, default is <literal>false</literal>. In case - remove-tasks is set to true, on <literal>node-leave</literal>, - all the tasks that are still open are ended. + <entry>This can be <code>{yes|no|true|false}</code>, with the + default being <code>false</code>. If + <property>remove-tasks</property> is set to + <code>true</code> on <property>node-leave</property>, + every open task is ended. </entry> </row> <row> <entry>task</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the tasks that should be created when execution arrives in this task node.</entry> + <entry>These are the tasks that arecreated when execution arrives in this task node.</entry> </row> <row> <entry>common node elements</entry> <entry></entry> <entry></entry> - + <entry>See <xref linkend="common.node.elements" /></entry> </row> </tbody> </tgroup> @@ -718,10 +1056,12 @@ <section id="processstate.element"> <title>process-state</title> <table frame="topbot" id="process.state.schema"> - <title>process-state</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Process State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -735,27 +1075,29 @@ <entry>binding</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>Defines the moment a subprocess is resolved. {late|*} defaults to resolving deploytime</entry> + <entry>This defines the moment at which a sub-process is + resolved. The options are: <code>{late|*}</code>. It defaults + to resolving the <property>deploytime</property></entry> </row> <row> <entry>sub-process</entry> <entry>element</entry> <entry>1</entry> - <entry>the sub process that is associated with this node</entry> + <entry>This is the sub-process that is associated with this node</entry> </row> <row> <entry>variable</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>specifies how data should be copied from the super process - to the sub process at the start and from the sub process to the - super process upon completion of the sub process.</entry> + <entry>This specifies how data should be copied from the super-process + to the sub-process at the commencement, and from the sub-process to the + super-process upon completion, of the sub-process.</entry> </row> <row> <entry>common node elements</entry> <entry></entry> <entry></entry> - + <entry>See <xref linkend="common.node.elements" /></entry> </row> </tbody> </tgroup> @@ -765,10 +1107,12 @@ <section id="superstate.element"> <title>super-state</title> <table frame="topbot" id="super.state.schema"> - <title>super-state</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Super State Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -779,24 +1123,16 @@ </thead> <tbody> <row> - <entry>{end-state| - state| - node| - task-node| - process-state| - super-state| - fork| - join| - decision}</entry> + <entry>{end-state|state|node|task-node|process-state|super-state|fork|join|decision}</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the nodes of the superstate. superstates can be nested.</entry> + <entry>These are the super-state's nodes. Super-states can be nested.</entry> </row> <row> <entry>common node elements</entry> <entry></entry> <entry></entry> - + <entry>See <xref linkend="common.node.elements" /></entry> </row> </tbody> </tgroup> @@ -806,10 +1142,12 @@ <section id="fork.element"> <title>fork</title> <table frame="topbot" id="fork.schema"> - <title>fork</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Fork Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -823,7 +1161,7 @@ <entry>common node elements</entry> <entry></entry> <entry></entry> - <entry>See common node elements</entry> + <entry>See <xref linkend="common.node.elements" /></entry> </row> </tbody> </tgroup> @@ -833,10 +1171,12 @@ <section id="join.element"> <title>join</title> <table frame="topbot" id="join.schema"> - <title>join</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Join Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -850,7 +1190,7 @@ <entry>common node elements</entry> <entry></entry> <entry></entry> - + <entry>See <xref linkend="common.node.elements" /></entry> </row> </tbody> </tgroup> @@ -860,10 +1200,12 @@ <section id="decision.element"> <title>decision</title> <table frame="topbot" id="decision.schema"> - <title>decision</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Decision Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -876,13 +1218,12 @@ <row> <entry>handler</entry> <entry>element</entry> - <entry>required, unless conditions are placed in the leaving transitions</entry> - <entry>the fully qualified name of a class that implements the - <literal>org.jbpm.graph.node.DecisionHandler</literal> interface</entry> + <entry>either a 'handler' element or conditions on the transitions should be specified</entry> + <entry>the name of a <code>org.jbpm.jpdl.Def.DecisionHandler</code> implementation</entry> </row> <row> <entry>transition conditions</entry> - <entry>'condition' attribute or element in each child 'transition' element</entry> + <entry>attribute or element text on the transitions leaving a decision</entry> <entry></entry> <entry>Every transition may have a guard condition. The decision node examines the leaving transitions having a condition, and selects the first @@ -897,7 +1238,7 @@ <entry>common node elements</entry> <entry></entry> <entry></entry> - + <entry>See <xref linkend="common.node.elements" /></entry> </row> </tbody> </tgroup> @@ -907,10 +1248,12 @@ <section id="event.element"> <title>event</title> <table frame="topbot" id="event.schema"> - <title>event</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Event Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -924,14 +1267,14 @@ <entry>type</entry> <entry>attribute</entry> <entry>required</entry> - <entry>the event type that is expressed relative to the element + <entry>This is the event type that is expressed relative to the element on which the event is placed</entry> </row> <row> <entry>{action|script|create-timer|cancel-timer}</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the list of actions that should be executed on this event</entry> + <entry>This is the list of actions that should be executed on this event</entry> </row> </tbody> </tgroup> @@ -941,10 +1284,12 @@ <section id="transition.element"> <title>transition</title> <table frame="topbot" id="transition.schema"> - <title>transition</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Transition Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -958,38 +1303,39 @@ <entry>name</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>the name of the transition. Note that each transition leaving a + <entry>This is the name of the transition. Note that each transition leaving a node *must* have a distinct name.</entry> </row> <row> <entry>to</entry> <entry>attribute</entry> <entry>required</entry> - <entry>the hierarchical name of the destination node. </entry> + <entry>This is the destination node's hierarchical name. For more information about hierarchical + names, see <xref linkend="hierarchicalnames" /></entry> </row> <row> <entry>condition</entry> <entry>attribute or element text</entry> <entry>optional</entry> - <entry>a guard condition expression. These condition - attributes (or child elements) can be used in decision nodes, or to calculate the - available transitions on a token at runtime. + <entry>This is a <firstterm>guard condition</firstterm> expression. Use these condition + attributes (or child elements) in decision nodes, or to calculate the + available transitions on a token at run-time. </entry> </row> <row> <entry>{action|script|create-timer|cancel-timer}</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>the actions to be executed upon taking this transition. Note that the - actions of a transition do not need to be put in an event (because there is - only one)</entry> + <entry>These are the actions that will execute when this transition occurs. Note that + a transition's actions do not need to be put in an event (because there is + only one.)</entry> </row> <row> <entry>exception-handler</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>a list of exception handlers that applies to all - exceptions thrown by delegation classes thrown in this process node.</entry> + <entry>This is a list of exception handlers that applies to every + bug thrown by a delegation class from within this process node.</entry> </row> </tbody> </tgroup> @@ -999,10 +1345,12 @@ <section id="action.element"> <title>action</title> <table frame="topbot" id="action.schema"> - <title>action</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Action Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1016,7 +1364,7 @@ <entry>name</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>the name of the action. When actions are given names, they can be + <entry>This is the name of the action. When actions are given names, they can be looked up from the process definition. This can be useful for runtime actions and declaring actions only once.</entry> </row> @@ -1024,57 +1372,62 @@ <entry>class</entry> <entry>attibute</entry> <entry>either, a ref-name or an expression</entry> - <entry>the fully qualified class name of the class that implements the - <literal>org.jbpm.graph.def.ActionHandler</literal> interface. + <entry>This is the fully-qualified class name of the class that implements the + <interfacename>org.jbpm.graph.def.ActionHandler</interfacename> interface. </entry> </row> <row> <entry>ref-name</entry> <entry>attibute</entry> <entry>either this or class</entry> - <entry>the name of the referenced action. The content of this action is + <entry>This is the name of the referenced action. The content of this action is not processed further if a referenced action is specified.</entry> </row> <row> <entry>expression</entry> <entry>attibute</entry> <entry>either this, a class or a ref-name</entry> - <entry>A jPDL expression that resolves to a method. + <entry>This is a jPDL expression that resolves to a method. See also <xref linkend="expressions" /> </entry> </row> <row> <entry>accept-propagated-events</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{yes|no|true|false}. Default is yes|true. If set to false, the action + <entry>The options are <code>{yes|no|true|false}</code>. The default is <code>yes|true</code>. If set to <code>false</code>, the action will only be executed on events that were fired on this action's element. - + For more information, read <xref linkend="eventpropagation"/> </entry> </row> <row> <entry>config-type</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>{field|bean|constructor|configuration-property}. - Specifies how the action-object should be constructed and how the content of this element should be used as configuration information for that action-object. + <entry>The options are <code>{field|bean|constructor|configuration-property}</code>. + This specifies how the action-object should be constructed and how the content of this element should be used as configuration information for that action-object. </entry> </row> <row> <entry>async</entry> - <entry>attibute</entry> + <entry>attribute</entry> <entry>{true|false}</entry> - <entry>Default is false, which means that the action is executed in the thread of the - execution. If set to true, a message will be sent to the command executor and that - component will execute the action asynchonously in a separate transaction. + <entry> + <code>'async="true"</code> is only supported in <classname>action</classname> + when it is triggered in an event. The default value is <code>false</code>, + which means that the <classname>action</classname> is executed in the thread of the + execution. If set to <code>true</code>, a message will be sent to the command + executor and that component will execute the action asynchronously in a separate + transaction. </entry> </row> <row> <entry></entry> <entry>{content}</entry> <entry>optional</entry> - <entry>the content of the action can be used as configuration information - for your custom action implementations. This allows the creation of reusable - delegation classes. + <entry>The action's content can be used as the configuration information + for custom action implementations. This allows one to create reusable + delegation classes. For more about delegation configuration, read + <xref linkend="configurationofdelegations"/>. </entry> </row> </tbody> @@ -1085,10 +1438,12 @@ <section id="script.element"> <title>script</title> <table frame="topbot" id="script.schema"> - <title>script</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Script Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1102,7 +1457,7 @@ <entry>name</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>the name of the script-action. When actions are given names, they can be + <entry>This is the name of the script-action. When actions are given names, they can be looked up from the process definition. This can be useful for runtime actions and declaring actions only once.</entry> </row> @@ -1112,14 +1467,14 @@ <entry>optional [0..*]</entry> <entry>{yes|no|true|false}. Default is yes|true. If set to false, the action will only be executed on events that were fired on this action's element. - + for more information, see <xref linkend="eventpropagation"/> </entry> </row> <row> <entry>expression</entry> <entry>element</entry> <entry>[0..1]</entry> - <entry>the beanshell script. If you don't specify variable + <entry>the beanshell script. If you don't specify variable elements, you can write the expression as the content of the script element (omitting the expression element tag).</entry> </row> @@ -1140,10 +1495,12 @@ <section id="expression.element"> <title>expression</title> <table frame="topbot" id="expression.schema"> - <title>expression</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Expression Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1168,10 +1525,12 @@ <section id="variable.element"> <title>variable</title> <table frame="topbot" id="variable.schema"> - <title>variable</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Variable Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1191,10 +1550,12 @@ <entry>access</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>default is <literal>read,write</literal>. It is a comma + <entry>default is <code>read,write</code>. It is a comma separated list of access specifiers. The only access specifiers - used so far are <literal>read</literal>, <literal>write</literal> - and <literal>required</literal>.</entry> + used so far are <code>read</code>, <code>write</code> + and <code>required</code>. "required" is only relevant + when one is a submitting task variable to a process + variable.</entry> </row> <row> <entry>mapped-name</entry> @@ -1216,10 +1577,12 @@ <section id="handler.element"> <title>handler</title> <table frame="topbot" id="handler.schema"> - <title>handler</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Handler Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1235,7 +1598,7 @@ <entry>either this or a class</entry> <entry>A jPDL expression. The returned result is transformed to a string with the toString() method. The resulting string should match one of the leaving - transitions. + transitions. See also <xref linkend="expressions" />. </entry> </row> <row> @@ -1243,7 +1606,7 @@ <entry>attibute</entry> <entry>either this or ref-name</entry> <entry>the fully qualified class name of the class that implements the - <literal>org.jbpm.graph.node.DecisionHandler</literal> interface. + <code>org.jbpm.graph.node.DecisionHandler</code> interface. </entry> </row> <row> @@ -1260,7 +1623,8 @@ <entry>optional</entry> <entry>the content of the handler can be used as configuration information for your custom handler implementations. This allows the creation of reusable - delegation classes. + delegation classes. For more about delegation configuration, see + <xref linkend="configurationofdelegations"/>. </entry> </row> </tbody> @@ -1271,10 +1635,12 @@ <section id="timer.element"> <title>timer</title> <table frame="topbot" id="timer.schema"> - <title>timer</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Timer Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1297,7 +1663,7 @@ <entry>required</entry> <entry>the duration (optionally expressed in business hours) that specifies the time period between the creation of the timer and the execution of the timer. - See Duration for the syntax.</entry> + See <xref linkend="duration" /> for the syntax.</entry> </row> <row> <entry>repeat</entry> @@ -1305,7 +1671,8 @@ <entry>optional</entry> <entry>{duration | 'yes' | 'true'}after a timer has been executed on the duedate, 'repeat' optionally specifies duration between repeating timer executions until the node is left. - If <literal>yes</literal> or <literal>true</literal> is specified, the same duration for the + If <code>yes</code> or <code>true</code> is specified, the same duration + as for the due date is taken for the repeat. See <xref linkend="duration" /> for the syntax.</entry> </row> <row> @@ -1321,9 +1688,9 @@ <entry>optional</entry> <entry>this attribute is only to be used in timers of tasks. it specifies the event on which the timer should be cancelled. by default, this is the - <literal>task-end</literal> event, but it can be set to e.g. - <literal>task-assign</literal> or <literal>task-start</literal>. - The <literal>cancel-event</literal> types can be combined by specifying them in a + <code>task-end</code> event, but it can be set to e.g. + <code>task-assign</code> or <code>task-start</code>. + The <code>cancel-event</code> types can be combined by specifying them in a comma separated list in the attribute. </entry> </row> @@ -1341,10 +1708,12 @@ <section id="create.timer.element"> <title>create-timer</title> <table frame="topbot" id="create.timer.schema"> - <title>create-timer</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Create Timer Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1367,7 +1736,7 @@ <entry>required</entry> <entry>the duration (optionally expressed in business hours) that specifies the the time period between the creation of the timer and the execution of the timer. - See Duration for the syntax.</entry> + See <xref linkend="duration" /> for the syntax.</entry> </row> <row> <entry>repeat</entry> @@ -1375,8 +1744,8 @@ <entry>optional</entry> <entry>{duration | 'yes' | 'true'}after a timer has been executed on the duedate, 'repeat' optionally specifies duration between repeating timer executions until the node is left. - If <literal>yes</literal> of <literal>true</literal> is specified, the same duration - as for the due date is taken for the repeat. See Duration for the + If <code>yes</code> of <code>true</code> is specified, the same duration + as for the due date is taken for the repeat. See <xref linkend="duration" /> for the syntax.</entry> </row> <row> @@ -1394,10 +1763,12 @@ <section id="cancel.timer.element"> <title>cancel-timer</title> <table frame="topbot" id="cancel.timer.schema"> - <title>cancel-timer</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Cancel Timer Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1421,10 +1792,12 @@ <section id="task.element"> <title>task</title> <table frame="topbot" id="task.schema"> - <title>task</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Task Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1439,7 +1812,7 @@ <entry>attribute</entry> <entry>optional</entry> <entry>the name of the task. Named tasks can be referenced and looked up via the - <literal>TaskMgmtDefinition</literal></entry> + <code>TaskMgmtDefinition</code></entry> </row> <row> <entry>blocking</entry> @@ -1463,7 +1836,8 @@ <entry>duedate</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>is a duration expressed in absolute or business hours</entry> + <entry>is a duration expressed in absolute or business hours as + explained in <xref linkend="businesscalendar"/></entry> </row> <row> <entry>swimlane</entry> @@ -1491,8 +1865,8 @@ <entry>element</entry> <entry>[0..*]</entry> <entry>supported event types: {task-create|task-start|task-assign|task-end}. Especially - for the <literal>task-assign</literal> we have added a non-persisted property - <literal>previousActorId</literal> to the <literal>TaskInstance</literal></entry> + for the <code>task-assign</code> we have added a non-persisted property + <code>previousActorId</code> to the <code>TaskInstance</code></entry> </row> <row> <entry>exception-handler</entry> @@ -1506,10 +1880,10 @@ <entry>element</entry> <entry>[0..*]</entry> <entry>specifies a timer that monitors the duration of an execution in this task. - special for task timers, the <literal>cancel-event</literal> can be specified. - by default the <literal>cancel-event</literal> is <literal>task-end</literal>, - but it can be customized to e.g. <literal>task-assign</literal> or - <literal>task-start</literal>. + special for task timers, the <code>cancel-event</code> can be specified. + by default the <code>cancel-event</code> is <code>task-end</code>, + but it can be customized to e.g. <code>task-assign</code> or + <code>task-start</code>. </entry> </row> <row> @@ -1529,10 +1903,12 @@ <section id="swimlane.element"> <title>swimlane</title> <table frame="topbot" id="swimlane.schema"> - <title>swimlane</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Swimlane Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1547,7 +1923,7 @@ <entry>attribute</entry> <entry>required</entry> <entry>the name of the swimlane. Swimlanes can be referenced and looked up via the - <literal>TaskMgmtDefinition</literal></entry> + <code>TaskMgmtDefinition</code></entry> </row> <row> <entry>assignment</entry> @@ -1565,10 +1941,12 @@ <section id="assignment.element"> <title>assignment</title> <table frame="topbot" id="assignment.schema"> - <title>assignment</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Assignment Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1582,9 +1960,11 @@ <entry>expression</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>For historical reasons, this attribute expression does <emphasis role="bold">not</emphasis> + <entry>For historical reasons, this attribute expression does <emphasis>not</emphasis> refer to the jPDL expression, but instead, it is - an assignment expression for the jBPM identity component. + an assignment expression for the jBPM identity component. For + more information on how to write + jBPM identity component expressions, see <xref linkend="assignmentexpressions" />. Note that this implementation has a dependency on the jbpm identity component. </entry> </row> @@ -1594,9 +1974,9 @@ <entry>optional</entry> <entry>An actorId. Can be used in conjunction with pooled-actors. The actor-id is resolved as an expression. So you can refer to - a fixed actorId like this <literal>actor-id="bobthebuilder"</literal>. Or you can refer + a fixed actorId like this <code>actor-id="bobthebuilder"</code>. Or you can refer to a property or method that returns a String like this: - <literal>actor-id="myVar.actorId"</literal>, which will invoke the getActorId method + <code>actor-id="myVar.actorId"</code>, which will invoke the getActorId method on the task instance variable "myVar". </entry> </row> @@ -1606,7 +1986,7 @@ <entry>optional</entry> <entry>A comma separated list of actorIds. Can be used in conjunction with actor-id. A fixed set of pooled actors can be specified like this: - <literal>pooled-actors="chicagobulls, pointersisters"</literal>. The + <code>pooled-actors="chicagobulls, pointersisters"</code>. The pooled-actors will be resolved as an expression. So you can also refer to a property or method that has to return, a String[], a Collection or a comma separated list of pooled actors. @@ -1617,7 +1997,7 @@ <entry>attribute</entry> <entry>optional</entry> <entry>the fully qualified classname of an implementation of - <literal>org.jbpm.taskmgmt.def.AssignmentHandler</literal></entry> + <code>org.jbpm.taskmgmt.def.AssignmentHandler</code></entry> </row> <row> <entry>config-type</entry> @@ -1633,7 +2013,8 @@ <entry>optional</entry> <entry>the content of the assignment-element can be used as configuration information for your AssignmentHandler implementations. This allows the creation of reusable - delegation classes. + delegation classes. for more about delegation configuration, see + <xref linkend="configurationofdelegations"/>. </entry> </row> </tbody> @@ -1642,12 +2023,14 @@ </section> <section id="controller.element"> - <title>controller</title> + <title>Controller</title> <table frame="topbot" id="controller.schema"> - <title>controller</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Controller Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1662,21 +2045,21 @@ <entry>attribute</entry> <entry>optional</entry> <entry>the fully qualified classname of an implementation of - <literal>org.jbpm.taskmgmt.def.TaskControllerHandler</literal></entry> + <code>org.jbpm.taskmgmt.def.TaskControllerHandler</code></entry> </row> <row> <entry>config-type</entry> <entry>attribute</entry> <entry>optional</entry> <entry>{field|bean|constructor|configuration-property}. - Specifies how the assignment-handler-object should be constructed and how the content of this element should be used as configuration information for that assignment-handler-object. + This specifies how the assignment-handler-object should be constructed and how the content of this element should be used as configuration information for that assignment-handler-object. </entry> </row> <row> <entry></entry> <entry>{content}</entry> <entry></entry> - <entry>either the content of the controller is the configuration + <entry>This is either the content of the controller is the configuration of the specified task controller handler (if the class attribute is specified. if no task controller handler is specified, the content must be a list of variable elements.</entry> @@ -1685,7 +2068,7 @@ <entry>variable</entry> <entry>element</entry> <entry>[0..*]</entry> - <entry>in case no task controller handler is specified by the class + <entry>When no task controller handler is specified by the class attribute, the content of the controller element must be a list of variables.</entry> </row> @@ -1697,10 +2080,12 @@ <section id="subprocess.element"> <title>sub-process</title> <table frame="topbot" id="sub.process.schema"> - <title>sub-process</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Sub Process Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1711,32 +2096,39 @@ </thead> <tbody> <row> - <entry>name</entry> + <entry><property>name</property></entry> <entry>attribute</entry> <entry>required</entry> - <entry>the name of the sub process. Can be an EL expression, as long as it resolves to a String. Powerful especially with late binding in the process-state. </entry> + <entry> + This is the name of the + <classname>sub-process</classname>. It can be an EL + expression but it must resolve to a + <classname>String</classname>. + </entry> </row> <row> - <entry>version</entry> + <entry><property>version</property></entry> <entry>attribute</entry> <entry>optional</entry> - <entry>the version of the sub process. If no version is - specified, the latest version of the given process as known - while deploying the parent - process-state - will be taken.</entry> + <entry> + This is the version of the <classname>sub-process</classname>. If + <property>version</property> is not specified, jBPM will use the latest known version of the + given process whilst it deploys the parent process-state. + </entry> </row> <row> - <entry>binding</entry> + <entry><property>binding</property></entry> <entry>attribute</entry> <entry>optional</entry> - <entry>indicates if the version of the sub process should be determined - when deploying the parent process-state - (default behavior), or when actually invoking the sub process - (<literal>binding="late"</literal>). When both <literal>version</literal> and - <literal>binding="late"</literal> are given then jBPM will use the version as - requested, but will not yet try to find the sub process when the parent - process-state is deployed. + <entry> + Controls when the version of the <classname>sub-process</classname> is determined. + The default behaviour is to determine the version when deploying the parent + <classname>process-state</classname>. If <property>binding</property> is defined as + <code>late</code> (<code>binding="late"</code>) then it is determined + when the <classname>sub-process</classname> is invoked. If + <property>binding</property> is set to "late" and <property>version</property> is + specified, then the value of version will be ignored and the latest version will be + used. </entry> </row> </tbody> @@ -1747,10 +2139,12 @@ <section id="condition.element"> <title>condition</title> <table frame="topbot" id="condition.schema"> - <title>condition</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Condition Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1762,14 +2156,20 @@ <tbody> <row> <entry></entry> - <entry>{content} For backwards compatibility, the condition can also be entered with the 'expression' - attribute, but that attribute is deprecated since 3.2</entry> + <entry>The option is <code>{content}</code>. For backwards + compatibility, the condition can also be entered with + the <property>expression</property> attribute, but + that attribute has been deprecated since Version + 3.2</entry> <entry>required</entry> - <entry>The contents of the condition element is a - jPDL expression that should evaluate to a boolean. A decision takes the - first transition (as ordered in the processdefinition.xml) for which the expression - resolves to <literal>true</literal>. If none of the conditions resolve - to true, the default leaving transition (== the first one) will be taken. + <entry>The contents of the condition element is a jPDL + expression that should evaluate to a Boolean. A + decision takes the first transition (as ordered in the + <filename>processdefinition.xml</filename> file) for + which the expression resolves to <code>true</code>. If + none of the conditions resolve to <code>true</code>, + the default leaving transition (the first one) will be + taken. </entry> </row> </tbody> @@ -1780,10 +2180,12 @@ <section id="exceptionhandler.element"> <title>exception-handler</title> <table frame="topbot" id="exception.handler.schema"> - <title>exception-handler</title> - <tgroup cols="4" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="2*" /> + <title>Exception Handler Schema</title> + <tgroup cols="4" rowsep="2" colsep="1"> + <colspec colname="c1" colwidth="2*"/> + <colspec colname="c2" colwidth="1*"/> + <colspec colname="c3" colwidth="1*"/> + <colspec colname="c4" colwidth="4*"/> <thead> <row> <entry align="center">Name</entry> @@ -1797,15 +2199,15 @@ <entry>exception-class</entry> <entry>attribute</entry> <entry>optional</entry> - <entry>specifies the fully qualified name of the java throwable class that should match + <entry>This specifies the Java "throwable" class' fully-qualified name which should match this exception handler. If this attribute is not specified, it matches all exceptions - (<literal>java.lang.Throwable</literal>).</entry> + (<exceptionname>java.lang.Throwable</exceptionname>).</entry> </row> <row> <entry>action</entry> <entry>element</entry> <entry>[1..*]</entry> - <entry>a list of actions to be executed when an exception is being handled by this + <entry>This is a list of actions to be executed when an error is being handled by this exception handler.</entry> </row> </tbody> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/logging.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/logging.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/logging.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -3,6 +3,7 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "jBPM_jPDL_User_Guide.ent"> %BOOK_ENTITIES; ]> + <chapter id="logging"> <title> Logging @@ -104,19 +105,16 @@ Use this API method to add process logs: </para> - <programlisting>public class LoggingInstance extends ModuleInstance { - ... - public void addLog(ProcessLog processLog) {...} - ... -}</programlisting> + <programlisting language="Java"><xi:include href="extras/logging_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> This is the UML diagram for information logging: </para> <figure id="logging.model.image"> <title>The jBPM logging information class diagram</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/logging.model.gif"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata fileref="images/logging.model.png"/></imageobject></mediaobject> </figure> <para> @@ -127,24 +125,15 @@ insert a log: </para> - <programlisting>public class LoggingInstance extends ModuleInstance { - ... - public void startCompositeLog(CompositeLog compositeLog) {...} - public void endCompositeLog() {...} - ... -}</programlisting> + <programlisting language="Java"><xi:include href="extras/logging_2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <para> The <systemitem>CompositeLog</systemitem>s should always be called in a <methodname>try-finally-block</methodname> to make sure that the hierarchical structure is consistent. For example: - </para> - <programlisting>startCompositeLog(new MyCompositeLog()); -try { - ... -} finally { - endCompositeLog(); -}</programlisting> + </para> + + <programlisting language="Java"><xi:include href="extras/logging_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> </section> @@ -158,8 +147,9 @@ the logging line from the <property>jbpm-context</property> section of the <filename>jbpm.cfg.xml</filename> configuration file: </para> - <programlisting>&lt;service name='logging' factory='org.jbpm.logging.db.DbLoggingServiceFactory' /&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/logging_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> In order to filter the logs, write a custom implementation of the <classname>LoggingService</classname> (this is a subclass of @@ -189,45 +179,25 @@ which they were created. </para> - <programlisting>public class LoggingSession { - ... - public Map findLogsByProcessInstance(long processInstanceId) {...} - ... -}</programlisting> + <programlisting language="Java"><xi:include href="extras/logging_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> The second method retrieves the logs for a specific token. The list will contain the <systemitem>ProcessLogs</systemitem> in the same order as that in which they were created. </para> - <programlisting>public class LoggingSession { - public List findLogsByToken(long tokenId) {...} - ... -}</programlisting> + <programlisting language="Java"><xi:include href="extras/logging_6.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - </section> - - <section id="datawarehousing"> - <title>Database warehousing</title> - <para>Sometimes you may want to apply data warehousing techniques to the jbpm - process logs. Data warehousing means that you create a separate database containing - the process logs to be used for various purposes. - </para> - - <para>There may be many reasons why you want to create a data warehouse with the - process log information. Sometimes it might be to offload heavy queryies from the - 'live' production database. In other situations it might be to do some extensive - analysis. Data warehousing even might be done on a modified database schema which is - optimized for its purpose.</para> - - <para> + <para> Having perused this chapter, the reader will now know how logging works in jBPM and has some idea of the various uses to which it can be put. </para> - + </section> + </chapter> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/mail.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/mail.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/mail.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -3,8 +3,9 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "jBPM_jPDL_User_Guide.ent"> %BOOK_ENTITIES; ]> + <chapter id="mail"> - <title> + <title> E. Mail Support </title> @@ -42,20 +43,29 @@ action can be added. </para> </note> - <programlisting>&lt;mail actors="#{president}" subject="readmylips" text="nomoretaxes" /&gt;</programlisting> - <para>The subject and text attributes can also be specified as an element like this:</para> - <programlisting>&lt;mail actors="#{president}" &gt; - &lt;subject&gt;readmylips&lt;/subject&gt; - &lt;text&gt;nomoretaxes&lt;/text&gt; -&lt;/mail&gt; - </programlisting> + +<programlisting language="XML"><xi:include href="extras/mail_0.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> Specify the subject and text attributes as an element like this: </para> - - <programlisting>&lt;mail to='#{initiator}' subject='websale' text='your websale of #{quantity} #{item} was approved' /&gt;</programlisting> +<programlisting language="XML"><xi:include href="extras/mail_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> + Each of the fields can contain JSF-like expressions: + </para> + +<programlisting language="XML"><xi:include href="extras/mail_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + +<note> + <para> + To learn more about expressions, study <xref + linkend="expressions" />. + </para> +</note> + + <para> Two attribute specify the recipients: <property>actors</property> and <property>to</property>. The <property>to</property> attribute should "resolve" to a semi-colon separated list of e. mail @@ -65,19 +75,30 @@ will, in turn, resolve to e. mail addresses. (Refer to <xref linkend="addressresolving" /> for more details.) </para> - - <programlisting>&lt;mail to=&#39;admin(a)mycompany.com&#39; subject='urgent' text='the mailserver is down :-)' /&gt;</programlisting> - <para>For more about how to specify recipients, see <xref linkend="specifyingmailrecipients" /></para> - <para>Mails can be defined in templates and in the process you can overwrite properties of the - templates like this: + +<programlisting language="XML"><xi:include href="extras/mail_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <note> + <para> + To learn how to specify recipients, read <xref + linkend="specifyingmailrecipients" /> </para> - <programlisting>&lt;mail template='sillystatement' actors="#{president}" /&gt;</programlisting> - <note> + </note> + <para> + E. mails can be defined by the use of templates. Overwrite + template properties in this way: + </para> + +<programlisting language="XML"><xi:include href="extras/mail_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + +<note> + <para> Learn more about templates by reading <xref linkend="mailtemplates" /> </para> -</note> +</note> + </section> <section id="mailnode"> @@ -98,20 +119,19 @@ to find out more.) </para> - <programlisting>&lt;mail-node name="send email" to="#{president}" subject="readmylips" text="nomoretaxes"&gt; - &lt;transition to="the next node" /&gt; -&lt;/mail-node&gt;</programlisting> - +<programlisting language="XML"><xi:include href="extras/mail_5.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <important> <para> Always ensure that mail nodes have exactly one <firstterm>leaving</firstterm> transition. </para> -</important> +</important> </section> <section id="taskassignmails"> + <title> "Task Assigned" E. Mail </title> @@ -123,11 +143,7 @@ manner: </para> - <programlisting>&lt;task-node name='a'&gt; - &lt;task name='laundry' swimlane="grandma" <emphasis role="bold">notify='yes'</emphasis> /&gt; - &lt;transition to='b' /&gt; -&lt;/task-node&gt; -</programlisting> +<programlisting language="XML"><xi:include href="extras/mail_7.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> Set notify to <code>yes</code>, <code>true</code> or @@ -151,13 +167,8 @@ to be specified. </para> - <programlisting>&lt;task-node name='a'&gt; - &lt;task name='laundry' swimlane="grandma" notify='yes'&gt; - &lt;reminder duedate="2 business days" repeat="2 business hours"/&gt; - &lt;/task&gt; - &lt;transition to='b' /&gt; -&lt;/task-node&gt; -</programlisting> + <programlisting language="XML"><xi:include href="extras/mail_8.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> </section> @@ -186,11 +197,19 @@ resolving</firstterm> functionality. (Refer to <xref linkend="addressresolving"/>. for more information.) </para> - <programlisting>&lt;mail actors="#{president}" subject="readmylips" text="nomoretaxes" /&gt;</programlisting> - <para> + + <para> + This example pre-supposes the existence of a + <property>swimlane</property> called <literal>president</literal>: + </para> + + <programlisting language="XML"><xi:include href="extras/mail_9.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> The code will send an e. mail to the person that acts as the <literal>president</literal> for that particular process execution. </para> + </section> <section id="specifyingmailrecipients"> @@ -218,29 +237,22 @@ <property>bccActors</property> or the <property>bcc</property> attribute in the process definition. </para> - - <programlisting>&lt;mail to='#{initiator}' bcc=&#39;bcc(a)mycompany.com&#39; subject='websale' text='your websale of #{quantity} #{item} was approved' /&gt;</programlisting> + + <programlisting language="XML"><xi:include href="extras/mail_11.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <para> An alternative approach is to always send BCC messages to some location that has been centrally configured in <filename>jbpm.cfg.xml</filename>. This example demonstrates how to do so: </para> - - <programlisting>&lt;jbpm-configuration&gt; - ... - &lt;string name="jbpm.mail.bcc.address" value=&quot;bcc(a)mycompany.com&quot; /&gt; -&lt;/jbpm-configuration&gt;</programlisting> + + <programlisting language="XML"><xi:include href="extras/mail_10.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> - <section id="CC"> - <title>Sending Mails to a CC recipient</title> - <para>It is possible to send a carbon copy of an email in much the same way as BCC recipients.</para> - <programlisting>&lt;mail to='#{initiator}' cc='#{supervisor}' subject='websale' text='your websale of #{quantity} #{item} was approved' /&gt;</programlisting> - <para>There is no provision to send mail to a preconfigured CC recipient though.</para> - </section> + <section id="addressresolving"> - <title> + <title> Address Resolving </title> @@ -261,9 +273,9 @@ <para> Make sure the address resolver implements the following interface: </para> - <programlisting>public interface AddressResolver extends Serializable { - Object resolveAddress(String actorId); -}</programlisting> + + <programlisting language="Java"><xi:include href="extras/mail_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> An address resolver will return one of the following three types: a string, a collection of strings or an array of strings. @@ -278,36 +290,29 @@ <systemitem>jbpm.mail.address.resolver</systemitem>, as per this example: </para> - - <programlisting>&lt;jbpm-configuration&gt; - ... - &lt;bean name='jbpm.mail.address.resolver' class='org.jbpm.identity.mail.IdentityAddressResolver' singleton='true' /&gt; -&lt;/jbpm-configuration&gt; - </programlisting> - + + <programlisting language="XML"><xi:include href="extras/mail_12.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> The Business Process Manager's <systemitem>identity</systemitem> component includes an address resolver. This address resolver will look for the given <systemitem>actorId</systemitem>'s user. If the user exists, his or her e. mail address will be returned. If not, null will be returned. - </para> - - <note> + </para> + + <note> <para> To learn more about the identity component, read <xref linkend="theidentitycomponent" />. </para> - </note> - - + </note> </section> </section> <section id="mailtemplates"> - - <title> + <title> E. Mail Templates </title> @@ -319,34 +324,11 @@ <filename>processdefinition.xml</filename>. Specify a templates like this: </para> - - <programlisting> -&lt;mail-templates&gt; - &lt;variable name="BaseTaskListURL" value="http://localhost:8080/jbpm/task?id=" /&gt; + <programlisting language="XML"><xi:include href="extras/mail_13.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - &lt;mail-template name='task-assign'&gt; - &lt;actors&gt;#{taskInstance.actorId}&lt;/actors&gt; - &lt;subject&gt;Task '#{taskInstance.name}'&lt;/subject&gt; - &lt;text&gt;&lt;![CDATA[Hi, -Task '#{taskInstance.name}' has been assigned to you. -Go for it: #{BaseTaskListURL}#{taskInstance.id} -Thanks. ----powered by JBoss jBPM---]]&gt;&lt;/text&gt; - &lt;/mail-template&gt; - &lt;mail-template name='task-reminder'&gt; - &lt;actors&gt;#{taskInstance.actorId}&lt;/actors&gt; - &lt;subject&gt;Task '#{taskInstance.name}' !&lt;/subject&gt; - &lt;text&gt;&lt;![CDATA[Hey, -Don't forget about #{BaseTaskListURL}#{taskInstance.id} -Get going ! ----powered by JBoss jBPM---]]&gt;&lt;/text&gt; - &lt;/mail-template&gt; - -&lt;/mail-templates&gt; - </programlisting> - <para> + <para> As per the above, extra variables can be defined in the mail templates and these will be available in the expressions. </para> @@ -355,11 +337,9 @@ Configure the resource that contains the templates via the <filename>jbpm.cfg.xml</filename> like this: </para> - - <programlisting>&lt;jbpm-configuration&gt; - ... - &lt;string name="resource.mail.templates" value="jbpm.mail.templates.xml" /&gt; -&lt;/jbpm-configuration&gt;</programlisting> + + <programlisting language="XML"><xi:include href="extras/mail_14.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> <section id="mailserverconfiguration"> @@ -372,19 +352,15 @@ <property>jbpm.mail.smtp.host</property> property in the <filename>jbpm.cfg.xml</filename> file, as per this example code: </para> - - <programlisting>&lt;jbpm-configuration&gt; - ... - &lt;string name="jbpm.mail.smtp.host" value="localhost" /&gt; - &lt;int name="jbpm.mail.smtp.port" value="25" /&gt; -&lt;/jbpm-configuration&gt;</programlisting> - <para>Alternatively, when more properties need to be specified, a mail properties - resource can be specified with <literal>resource.mail.properties</literal>. + +<programlisting language="XML"><xi:include href="extras/mail_15.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> + Alternatively, when more properties need to be specified, give a + resource reference to a properties file in this way: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - &lt;string name='resource.mail.properties' value='jbpm.mail.properties' /&gt; -&lt;/jbpm-configuration&gt;</programlisting> + +<programlisting language="XML"><xi:include href="extras/mail_16.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> </section> @@ -399,11 +375,8 @@ <filename>jbpm.xfg.xml</filename> file with key <systemitem>jbpm.mail.from.address</systemitem> like this: </para> - - <programlisting>&lt;jbpm-configuration&gt; - ... - &lt;string name='jbpm.mail.from.address' value=&#39;jbpm(a)yourcompany.com&#39; /&gt; -&lt;/jbpm-configuration&gt;</programlisting> + + <programlisting language="XML"><xi:include href="extras/mail_17.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> </section> <section id="customizingmailsupport"> @@ -425,10 +398,9 @@ configuration string in the <filename>jbpm.cfg.xml</filename> like this: </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - &lt;string name='jbpm.mail.class.name' value='com.your.specific.CustomMail' /&gt; -&lt;/jbpm-configuration&gt;</programlisting> + + <programlisting language="XML"><xi:include href="extras/mail_18.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> The customized mail class will be read during parsing. Actions will be configured in the process that reference the configured (or @@ -443,5 +415,5 @@ various e. mail settings. Having studied the examples carefully, one can now practice configuring one's own environment </para> - </section> + </section> </chapter> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/modelling.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/modelling.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/modelling.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -100,56 +100,20 @@ <figure id="auction.process.graph.image"> <title>The auction process graph</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/auction.process.graph.gif"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata fileref="images/auction.process.graph.png"/></imageobject></mediaobject> </figure> - <para> + <para> Below is the process graph for the same auction process, albeit represented in XML this time: </para> -<programlisting>&lt;process-definition&gt; - &lt;start-state&gt; - &lt;transition to="auction" /&gt; - &lt;/start-state&gt; - - &lt;state name="auction"&gt; - &lt;transition name="auction ends" to="salefork" /&gt; - &lt;transition name="cancel" to="end" /&gt; - &lt;/state&gt; - - &lt;fork name="salefork"&gt; - &lt;transition name="shipping" to="send item" /&gt; - &lt;transition name="billing" to="receive money" /&gt; - &lt;/fork&gt; - - &lt;state name="send item"&gt; - &lt;transition to="receive item" /&gt; - &lt;/state&gt; + <programlisting language="XML"><xi:include href="extras/modelling_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - &lt;state name="receive item"&gt; - &lt;transition to="salejoin" /&gt; - &lt;/state&gt; - - &lt;state name="receive money"&gt; - &lt;transition to="send money" /&gt; - &lt;/state&gt; - - &lt;state name="send money"&gt; - &lt;transition to="salejoin" /&gt; - &lt;/state&gt; - - &lt;join name="salejoin"&gt; - &lt;transition to="end" /&gt; - &lt;/join&gt; - - &lt;end-state name="end" /&gt; - -&lt;/process-definition&gt;</programlisting> </section> <section id="nodes"> - <title> + <title> Nodes </title> @@ -251,6 +215,7 @@ users complete their tasks, the execution will be triggered, making it resume. </para> + </section> <section id="nodetypetaskstate"> <title> @@ -437,7 +402,7 @@ structure of the graph. The main event types are entering a node, leaving a node and taking a transition.</para> - <important> + <important> <para> There is a difference between an action that is placed on an event and an action that is placed in a node. Actions that are put in @@ -447,7 +412,7 @@ contrast, an action placed on a node has the responsibility of passing on the execution. </para> -</important> +</important> <para> Read this section to study an example of an action on an event. It demonstrates @@ -458,46 +423,22 @@ <figure id="database.update.example.image"> <title>A database update action</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/database.update.example.gif"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata fileref="images/database.update.example.png"/></imageobject></mediaobject> </figure> - <programlisting>public class RemoveEmployeeUpdate implements ActionHandler { - public void execute(ExecutionContext ctx) throws Exception { - // get the fired employee from the process variables. - String firedEmployee = (String) ctx.getContextInstance().getVariable("fired employee"); - - // by taking the same database connection as used for the jbpm updates, we - // reuse the jbpm transaction for our database update. - Connection connection = ctx.getProcessInstance().getJbpmSession().getSession().getConnection(); - Statement statement = connection.createStatement(); - statement.execute("DELETE FROM EMPLOYEE WHERE ..."); - statement.execute(); - statement.close(); - } -}</programlisting> - -<programlisting>&lt;process-definition name="yearly evaluation"&gt; + <programlisting language="Java"><xi:include href="extras/modelling_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - ... - &lt;state name="fire employee"&gt; - &lt;transition to="collect badge"&gt; - &lt;action class="com.nomercy.hr.RemoveEmployeeUpdate" /> - &lt;/transition&gt; - &lt;/state&gt; - - &lt;state name="collect badge"&gt; - ... - -&lt;/process-definition&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/modelling_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> + + <note> <para> To learn more about adding configurations to custom actions, see <xref linkend="configurationofdelegations"/> </para> - </note> - </section> + </note> + <section id="actionreferences"> <title> Action References @@ -583,16 +524,10 @@ <listitem><para>taskInstance</para></listitem> </itemizedlist> -<programlisting>&lt;process-definition&gt; - &lt;event type="node-enter"&gt; - &lt;script&gt; - System.out.println("this script is entering node "+node); - &lt;/script&gt; - &lt;/event&gt; - ... -&lt;/process-definition&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/modelling_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + + <para> To customize the default behavior of loading and storing variables into the script, use the <property>variable</property> element as a sub-element of script. If doing so, also place the @@ -600,20 +535,9 @@ <property>expression</property>. </para> -<programlisting>&lt;process-definition&gt; - &lt;event type="process-end"&gt; - &lt;script&gt; - &lt;expression&gt; - a = b + c; - &lt;/expression&gt; - &lt;variable name='XXX' access='write' mapped-name='a' /&gt; - &lt;variable name='YYY' access='read' mapped-name='b' /&gt; - &lt;variable name='ZZZ' access='read' mapped-name='c' /&gt; - &lt;/script&gt; - &lt;/event&gt; - ... -&lt;/process-definition&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/modelling_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> Before the script starts, the process variables <code>YYY</code> and <code>ZZZ</code> will be made @@ -649,7 +573,7 @@ the names of the event types freely. </para> </section> - + </section> <section id="superstates"> <title> @@ -712,7 +636,7 @@ </section> <section id="hierarchicalnames"> - <title> + <title> Hierarchical Names </title> @@ -727,34 +651,15 @@ example shows how to refer to a node in a super-state: </para> - <programlisting>&lt;process-definition&gt; - ... - &lt;state name="preparation"&gt; - &lt;transition to="phase one/invite murphy"/&gt; - &lt;/state&gt; - &lt;super-state name="phase one"&gt; - &lt;state name="invite murphy"/&gt; - &lt;/super-state&gt; - ... -&lt;/process-definition&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/modelling_5.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> The next example shows how to travel up the super-state hierarchy: </para> - <programlisting>&lt;process-definition&gt; - ... - &lt;super-state name="phase one"&gt; - &lt;state name="preparation"&gt; - &lt;transition to="../phase two/invite murphy"/&gt; - &lt;/state&gt; - &lt;/super-state&gt; - &lt;super-state name="phase two"&gt; - &lt;state name="invite murphy"/&gt; - &lt;/super-state&gt; - ... -&lt;/process-definition&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/modelling_6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> </section> </section> @@ -825,18 +730,7 @@ graph execution in the super-process. </para> - <programlisting>&lt;process-definition name=&quot;hire&quot;&gt; - &lt;start-state&gt; - &lt;transition to=&quot;initial interview&quot; /&gt; - &lt;/start-state&gt; - &lt;process-state name=&quot;initial interview&quot;&gt; - &lt;sub-process name=&quot;interview&quot; /&gt; - &lt;variable name=&quot;a&quot; access=&quot;read,write&quot; mapped-name=&quot;aa&quot; /&gt; - &lt;variable name=&quot;b&quot; access=&quot;read&quot; mapped-name=&quot;bb&quot; /&gt; - &lt;transition to=&quot;...&quot; /&gt; - &lt;/process-state&gt; - ... -&lt;/process-definition&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/modelling_7.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> In the example above, the <literal>hire</literal> process contains a @@ -892,34 +786,20 @@ </para> <figure id="update.erp.example.image"> - <title>The update erp example process snippet</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/update.erp.example.gif"/></imageobject></mediaobject> + <title>Process Snippet for Updating ERP Example</title> + <mediaobject><imageobject><imagedata fileref="images/update.erp.example.png"/></imageobject></mediaobject> </figure> - <programlisting>public class AmountUpdate implements ActionHandler { - public void execute(ExecutionContext ctx) throws Exception { - // business logic - Float erpAmount = ...get amount from erp-system...; - Float processAmount = (Float) ctx.getContextInstance().getVariable("amount"); - float result = erpAmount.floatValue() + processAmount.floatValue(); - ...update erp-system with the result...; - - // graph execution propagation - if (result > 5000) { - ctx.leaveNode(ctx, "big amounts"); - } else { - ctx.leaveNode(ctx, "small amounts"); - } - } -}</programlisting> + <programlisting language="Java"><xi:include href="extras/modelling_2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> +<note> <para> One can also create and join tokens in custom node implementations. To learn how to do this, study the Fork and Join node implementation in the jBPM source code. </para> </note> + </section> <section id="graphexecution"> @@ -975,8 +855,8 @@ </para> <figure id="graph.execution.image"> - <title>The graph execution related methods</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/graph.execution.gif"/></imageobject></mediaobject> + <title>The graph execution-related methods</title> + <mediaobject><imageobject><imagedata fileref="images/graph.execution.png"/></imageobject></mediaobject> </figure> <para> @@ -1034,7 +914,7 @@ </section> - <section id="transactiondemarcation"> + <section id="transactiondemarcation"> <title> Transaction Demarcation </title> @@ -1081,6 +961,7 @@ words, <methodname>token.signal()</methodname> or <methodname>taskInstance.end()</methodname> will be returned.) </para> + <para> The Business Process Manager's client code can now commit the transaction. Send messages in the same transaction as that @@ -1104,9 +985,8 @@ <classname>CommandExecutionServlet</classname>. </para> </important> - - - <note> + +<note> <para> Process modelers do not need to be excessively concerned with asynchronous messaging. The main point to remember is transaction @@ -1121,41 +1001,17 @@ <para> Here is an example: </para> - <programlisting>... -&lt;start-state&gt; - &lt;transition to=&quot;one&quot; /&gt; -&lt;/start-state&gt; -&lt;node async=&quot;true&quot; name=&quot;one&quot;&gt; - &lt;action class=&quot;com...MyAutomaticAction&quot; /&gt; - &lt;transition to=&quot;two&quot; /&gt; -&lt;/node&gt; -&lt;node async=&quot;true&quot; name=&quot;two&quot;&gt; - &lt;action class=&quot;com...MyAutomaticAction&quot; /&gt; - &lt;transition to=&quot;three&quot; /&gt; -&lt;/node&gt; -&lt;node async=&quot;true&quot; name=&quot;three&quot;&gt; - &lt;action class=&quot;com...MyAutomaticAction&quot; /&gt; - &lt;transition to=&quot;end&quot; /&gt; -&lt;/node&gt; -&lt;end-state name=&quot;end&quot; /&gt; -...</programlisting> + <programlisting language="XML"><xi:include href="extras/modelling_8.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> The client code needed to both start and resume process executions is exactly the same as that needed for normal synchronous processes. </para> - <programlisting>...start a transaction... -JbpmContext jbpmContext = jbpmConfiguration.createContext(); -try { - ProcessInstance processInstance = jbpmContext.newProcessInstance("my async process"); - processInstance.signal(); - jbpmContext.save(processInstance); -} finally { - jbpmContext.close(); -}</programlisting> - -<para> + <programlisting language="Java"><xi:include href="extras/modelling_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> After this first transaction occurs, the process execution's <systemitem>root token</systemitem> will point to <literal>node one</literal> and an <classname>ExecuteNodeCommand</classname> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/persistence.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/persistence.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/persistence.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -3,6 +3,7 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "jBPM_jPDL_User_Guide.ent"> %BOOK_ENTITIES; ]> + <chapter id="persistence"> <title> Persistence @@ -30,21 +31,25 @@ </para> <figure id="model.transformations.image"> - <title>The transformations and different forms</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/model.transformations.jpg"/></imageobject></mediaobject> + <title>The Transformations and Different Forms</title> + <mediaobject><imageobject><imagedata fileref="images/model.transformations.png"/></imageobject></mediaobject> </figure> - + <note> <para> To learn more about XML representations of process definitions and process archives, see <xref linkend="jpdl" />. </para> </note> - <!-- - <para>More information on how to deploy a process archive to the database - can be found in <xref linkend="deployingaprocessarchive" /> </para> --> - - <section id="sect-persistance_API"> + + <note> + <para> + To learn more about how to deploy a process archive to the database, + read <xref linkend="deployingaprocessarchive" /> + </para> + </note> + + <section id="sect-persistance_API"> <title> The Persistence Application Programming Interface </title> @@ -64,43 +69,33 @@ operations. </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); -try { + <programlisting language="Java"><xi:include href="extras/persistence_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - // Invoke persistence operations here - -} finally { - jbpmContext.close(); -}</programlisting> - - <para>In the following sections, the configuration is assumed to include a persistence - service as shown below.</para> - - <programlisting>&lt;jbpm-configuration&gt; - - &lt;jbpm-context&gt; - &lt;service name='persistence' factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt; - ... - &lt;/jbpm-context&gt; - ... -&lt;/jbpm-configuration&gt;</programlisting> </section> - + <section id="conveniencemethodsonjbpmcontext"> - <title> + <title> Convenience Methods on JbpmContext </title> - <para>The three most commonly-performed persistence operations are:</para> +<!-- + <para> + In this section, it is presumed that the reader's configuration + includes a persistence service similar to this one (found in the + example + <filename>src/config.files/jbpm.cfg.xml</filename> configuration file): + </para> + + <programlisting language="XML"><xi:include href="extras/persistence_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> +--> + <para>The three most commonly-performed persistence operations are: <orderedlist> <listitem><para>process. deployment</para></listitem> <listitem><para>new process execution commencement</para></listitem> <listitem><para>process execution continuation</para></listitem> </orderedlist> - + </para> - - <para> <firstterm>Process deployment</firstterm> is normally undertaken directly from the <application>Graphical Process Designer</application> or from the @@ -108,15 +103,10 @@ task. However, to do it directly from Java, use this code: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); -try { - ProcessDefinition processDefinition = ...; - jbpmContext.deployProcessDefinition(processDefinition); -} finally { - jbpmContext.close(); -}</programlisting> +<programlisting language="Java"><xi:include href="extras/persistence_2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + + <para> Create a new process execution by specifying the process definition of which it will be an instance. The most common way to do this is by referring to the name of the process. The jBPM will then @@ -124,15 +114,9 @@ some demonstration code: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); -try { - String processName = ...; - ProcessInstance processInstance = - jbpmContext.newProcessInstance(processName); -} finally { - jbpmContext.close(); -}</programlisting> + <programlisting language="Java"><xi:include href="extras/persistence_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + <para> To continue a process execution, fetch the process instance, the token or the <classname>taskInstance</classname> from the database @@ -141,18 +125,8 @@ to the <classname>processInstance</classname> into the database. </para> + <programlisting language="Java"><xi:include href="extras/persistence_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); -try { - long processInstanceId = ...; - ProcessInstance processInstance = - jbpmContext.loadProcessInstance(processInstanceId); - processInstance.signal(); - jbpmContext.save(processInstance); -} finally { - jbpmContext.close(); -}</programlisting> - <para> Note that it is not necessary to explicitly invoke the <methodname>jbpmContext.save</methodname> method if the @@ -168,17 +142,9 @@ <methodname>loadTaskInstanceForUpdate</methodname> method: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); -try { - long taskInstanceId = ...; - TaskInstance taskInstance = - jbpmContext.loadTaskInstanceForUpdate(taskInstanceId); - taskInstance.end(); -} finally { - jbpmContext.close(); -}</programlisting> + <programlisting language="Java"><xi:include href="extras/persistence_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <important> +<important> <para> Read the following explanation to learn how the jBPM manages the persistence feature and uses @@ -203,11 +169,11 @@ <methodname>ServiceFactory</methodname> but this is only instantiated the first time that it is requested. </para> -</important> +</important> <figure id="persistence.api.image"> - <title>Classes related to persistence</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/persistence.api.gif"/></imageobject></mediaobject> + <title>The Persistence-Related Classes</title> + <mediaobject><imageobject><imagedata fileref="images/persistence.api.png"/></imageobject></mediaobject> </figure> <para> @@ -225,122 +191,174 @@ when the first operation that requires persistence is invoked.) </para> - </section><section id="managedtransactions"><title>Managed transactions</title> + - <para>The most common scenario for managed transactions is when using jBPM in a JEE application - server like JBoss. The most common scenario is the following: - </para> - <itemizedlist> - <listitem><para>Configure a DataSource in your application server</para> + </section> + <!-- + <section id="managedtransactions"> + <title> Managed Transactions</title> + + <para> + One is most likely to require transaction management when jBPM + is used in the <application>JBoss + Application Server</application>. To configure it, follow these + steps: + </para> + + <orderedlist> + <listitem><para>configure a data-source in the <application>JBoss + Application Server</application></para> </listitem> - <listitem><para>Configure hibernate to use that data source for its connections</para> + <listitem><para>configure <application>Hibernate</application> to use + that data source for its connections</para> </listitem> - <listitem><para>Use container managed transactions</para> + <listitem><para>use <firstterm>container-managed transactions</firstterm></para> </listitem> - <listitem><para>Disable transactions in jBPM</para> + <listitem><para>disable transactions in the jBPM</para> </listitem> - </itemizedlist> + </orderedlist> - <para>A stateless session facade in front of jBPM is a good practice. The easiest way - on how to bind the jbpm transaction to the container transaction is to make sure that - the hibernate configuration used by jbpm refers to an xa-datasource. So jbpm will - have its own hibernate session, there will only be 1 jdbc connection and 1 transaction. - </para> + <note> + <para> + It is a good practice to place a <systemitem>stateless + session</systemitem> "facade" in front of the jBPM. The easiest way + to bind the jBPM transaction to the <systemitem>container + transaction</systemitem> is to make sure that the + <application>Hibernate</application> configuration refers to an + <systemitem>xa-datasource</systemitem>. By doing so, the Business + Process Manager will have its own + <application>Hibernate</application> session and there will be only + one JDBC connection and one transaction apiece. + </para> + </note> - <para>The transaction attribute of the jbpm session facade methods should be 'required' +<note> + <para> + Be aware that the the session facade methods' transaction attributes + are mandatory in most situations. </para> - - <para>The the most important configuration property to specify in the hibernate.cfg.xml - that is used by jbpm is: +</note> + + <para> + The most important configuration property specified in the + <filename>hibernate.cfg.xml</filename> file is + <property>hibernate.connection.datasource</property>. Set this to + the data-source's JNDI name, such as <code>java:/JbpmDS</code>. </para> - <programlisting>hibernate.connection.datasource= --datasource JNDI name-- like e.g. java:/JbpmDS</programlisting> - - <para>More information on how to configure jdbc connections in hibernate, see <ulink url="http://www.hibernate.org/hib_docs/reference/en/html/session-con... - the hibernate reference manual, section 'Hibernate provided JDBC connections'</ulink> +<note> + <para>To learn more about configuring JDBC connections in <application>Hibernate</application>, read + <ulink url="http://www.hibernate.org/hib_docs/reference/en/html/session-con... /> </para> - <para>For more information on how to configure xa datasources in jboss, see <ulink url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch7.chapt.htm... - the jboss application server guide, section 'Configuring JDBC DataSources'</ulink> + <para> + To learn more about XA data-sources in JBoss, read + <ulink url="http://docs.jboss.org/jbossas/jboss4guide/r4/html/ch7.chapt.htm... /> </para> +</note> - </section><section id="injectingthehibernatesession"><title>Injecting the hibernate session</title> + </section> + <section id="injectingthehibernatesession"> + <title>"Injecting" the Hibernate Session</title> - <para>In some scenarios, you already have a hibernate session and you want to combine all the - persistence work from jBPM into that hibernate session. + <para> + In some scenarios, one will need to combine all of the + persistence information from jBPM and add it to a pre-existing + <application>Hibernate</application> session. </para> - <para>Then the first thing to do is make sure that the hibernate configuration is aware of all - the jBPM mapping files. You should make sure that all the hibernate mapping files that are - referenced in the file <literal>src/config.files/hibernate.cfg.xml</literal> are provided - in the used hibernate configuration. + <para> + Firstly, make sure that the <application>Hibernate</application> + configuration is aware of all of the jBPM mapping files. Ensure that + these files are referenced in + <filename>src/config.files/hibernate.cfg.xml</filename> and that + they are also in the <application>Hibernate</application> + configuration file. </para> - <para>Then, you can inject a hibernate session into the jBPM context as is shown in the following - API snippet: + <para> + Next, inject a <application>Hibernate</application> session into the + jBPM context. The following piece of application + programming interface code shows how: </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); -try { - jbpmContext.setSession(SessionFactory.getCurrentSession()); + <programlisting language="Java"><xi:include href="extras/persistence_6.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - // your jBPM operations on jbpmContext - -} finally { - jbpmContext.close(); -}</programlisting> - - <para>That will pass in the current hibernate session used by the container to the jBPM - context. No hibernate transaction is initiated when a session is injected in the context. - So this can be used with the default configurations. + <para> + This code will pass the current <application>Hibernate</application> + session being used by the container to the jBPM context. Note that + no <application>Hibernate</application> transaction will be + initiated when a session is injected in this context. Therefore, + this can be used with the default configuration. </para> - <para>The hibernate session that is passed in, will <emphasis role="bold">not</emphasis> be - closed in the jbpmContext.close() method. This is in line with the overall philosophy of - programmatic injection which is explained in the next section. +<important> + <para> + The <application>Hibernate</application> session that is passed in + will <emphasis>not</emphasis> be closed in the + <methodname>jbpmContext.close()</methodname> method. This is in + accordance with the overall philosophy of programmatic injection as + explained in the next section. </para> - - </section><section id="injectingresourcesprogrammatically"><title>Injecting resources programmatically</title> +</important> - <para>The configuration of jBPM provides the necessary information for jBPM to create a hibernate - session factory, hibernate session, jdbc connections, jbpm required services,... But all of - these resources can also be provided to jBPM programmatically. Just inject them in the jbpmContext. - Injected resources always are taken before creating resources from the jbpm configuration information. + </section> + <section id="injectingresourcesprogrammatically"> + <title> + Injecting Resources Programmatically + </title> + + <para> + jBPM's configuration provides the necessary information for the + software to create a <application>Hibernate</application> session + factory, a <application>Hibernate</application> session, JDBC + connections, and required jBPM services. However, all of these + resources can also be provided to jBPM programmatically: just inject + them into the <classname>jbpmContext</classname>. Injected resources + are always taken before resources are created from jBPM + configuration information. </para> - <para>The main philosophy is that the API-user remains responsible for all the things that the user - injects programmatically in the jbpmContext. On the other hand, all items that are opened by - jBPM, will be closed by jBPM. There is one exception. That is when fetching a connection that - was created by hibernate. When calling jbpmContext.getConnection(), this transfers responsibility - for closing the connection from jBPM to the API user. + <para> + The design philosophy behind this is that the application + programming interface user is to remain responsible everything they + inject into the <classname>jbpmContext</classname>. On the other + hand, all items that are opened by jBPM will also be closed by jBPM. + However, there is one exception, this being when a connection that + was created by <application>Hibernate</application> is fetched as + calling <methodname>jbpmContext.getConnection()</methodname> + transfers responsibility for closing the connection from jBPM to the + API user. </para> - <programlisting>JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); -try { - // to inject resources in the jbpmContext before they are used, you can use - jbpmContext.setConnection(connection); - // or - jbpmContext.setSession(session); - // or - jbpmContext.setSessionFactory(sessionFactory); + <programlisting language="Java"><xi:include href="extras/persistence_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -} finally { - jbpmContext.close(); -}</programlisting> - - </section><section id="advancedapiusage"><title>Advanced API usage</title> + </section> - <para>The DbPersistenceService maintains a lazy initialized hibernate session. All - database access is done through this hibernate session. All queries and updates - done by jBPM are exposed by the XxxSession classes like e.g. GraphSession, - SchedulerSession, LoggingSession,... These session classes refer to the hibernate - queries and all use the same hibernate session underneath. - </para> + <section id="advancedapiusage"> + <title>Advanced API Usage</title> - <para>The XxxxSession classes are accessible via the JbpmContext as well. + <para> + The <classname>DbPersistenceService</classname> maintains a + "lazily" initialized <application>Hibernate</application> + session, through which all database access is undertaken. All of + the queries and updates that jBPM processes are exposed by the + <classname>XxxSession</classname> classes, some examples being + <classname>GraphSession</classname>, + <classname>SchedulerSession</classname> and + <classname>LoggingSession</classname>. (These session classes + refer to the <application>Hibernate</application> queries; they + all use the same session.) + </para> +<note> + <para> + One can use the <classname>JbpmContext</classname> to access the + <classname>XxxSession</classname> classes as well. </para> +</note> </section> + --> </section> <section id="configurationthepersistenceservice"> @@ -350,222 +368,296 @@ <section id="thedbpersistenceservicefactory"> <title>The DbPersistenceServiceFactory</title> - <para>The DbPersistenceServiceFactory itself has 3 more configuration properties: isTransactionEnabled, - sessionFactoryJndiName and dataSourceJndiName. To specify any of these properties in the jbpm.cfg.xml, - you need to specify the service factory as a bean in the factory element like this: + <para> + The <classname>DbPersistenceServiceFactory</classname> class has + three more configuration properties: + <property>isTransactionEnabled</property>, + <property>sessionFactoryJndiName</property>, and + <property>dataSourceJndiName</property>. To specify any of these + properties in the <filename>jbpm.cfg.xml</filename> file, specify + the <property>Service Factory</property> as a bean within the + <property>factory</property> element. This sample code + demonstrates how to do so: </para> - <para>IMPORTANT: don't mix the short and long notation for configuring the factories. See also - <xref linkend="customizingfactories" />. If the factory - is just a new instance of a class, you can use the factory attribute to refer to the factory class name. - But if properties in a factory must be configured, the long notation must be used and factory and bean - must be combined as nested elements. Like this: - </para> - - <programlisting> &lt;jbpm-context&gt; - &lt;service name="persistence"&gt; - &lt;factory&gt; - &lt;bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"&gt; - &lt;field name="isTransactionEnabled"&gt;&lt;false /&gt;&lt;/field&gt; - &lt;field name="sessionFactoryJndiName"&gt; - &lt;string value="java:/myHibSessFactJndiName" /&gt; - &lt;/field&gt; - &lt;field name="dataSourceJndiName"&gt; - &lt;string value="java:/myDataSourceJndiName" /&gt; - &lt;/field&gt; - &lt;/bean&gt; - &lt;/factory&gt; - &lt;/service&gt; - ... - &lt;/jbpm-context&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/persistence_8.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <variablelist> - <varlistentry><term>isTransactionEnabled</term> - - - <listitem><para>by default, jBPM will - begin a hibernate transaction when the session is fetched the first time and if the - jbpmContext is closed, the hibernate transaction will be ended. The transaction is then - committed or rolled back depending on wether jbpmContext.setRollbackOnly was called. The - isRollbackOnly property is maintained in the TxService. To disable transactions and - prohibit jBPM from managing transactions with hibernate, configure the isTransactionEnabled - property to false as in the example above. This property only controls the behaviour of - the jbpmContext, you can still call the DbPersistenceService.beginTransaction() directly - with the API, which ignores the isTransactionEnabled setting. - For more info about transactions, see - <xref linkend="hibernatetransactions" />. - </para></listitem> - </varlistentry> - - - <varlistentry><term>sessionFactoryJndiName</term> - <listitem><para>by default, this - is null, meaning that the session factory is not fetched from JNDI. If set and - a session factory is needed to create a hibernate session, the session factory - will be fetched from jndi using the provided JNDI name. - </para></listitem> - </varlistentry> + <important> + <para> + Do not mix the short and long notation for configuring the + factories. (See also <xref linkend="customizingfactories" />.) + If the factory is just a new instance of a class, use the + factory attribute to refer to its factory class name but if + properties in a factory require configuration, the long notation + must be used and, furthermore, the factory and the bean must be + combined as nested elements. + </para> + </important> - <varlistentry><term>dataSourceJndiName</term> + <variablelist> + <varlistentry> + <term><classname>isTransactionEnabled</classname></term> + <listitem> + <para> + By default, jBPM will begin a + <application>Hibernate</application> transaction when + the session is retrieved for the first time and, if the + <classname>jbpmContext</classname> is closed, the + <application>Hibernate</application> transaction will be + ended. The transaction is then committed or rolled back + depending on whether or not + <methodname>jbpmContext.setRollbackOnly</methodname> was + called. (The <property>isRollbackOnly</property> property + is maintained in the <classname>TxService</classname>.) + To disable transactions and prohibit jBPM from managing + them with <application>Hibernate</application>, + set the <property>isTransactionEnabled</property> + property value to <code>false</code>. (This property only + controls the behaviour + of the <classname>jbpmContext</classname>; the + <methodname>DbPersistenceService.beginTransaction()</methodname> + can still be called directly directly with the + application programming interface, which ignores the + <property>isTransactionEnabled</property> setting.) To + learn more about transactions, please study <xref + linkend="hibernatetransactions" />. + </para> + </listitem> + </varlistentry> - <listitem><para>by default, this is - null and creation of JDBC connections will be delegated to hibernate. By specifying - a datasource, jBPM will fetch a JDBC connection from the datasource and provide that - to hibernate while opening a new session. For user provided JDBC connections, - see <xref linkend="injectingresourcesprogrammatically" />. - </para></listitem> - </varlistentry> + <varlistentry> + <term><classname>sessionFactoryJndiName</classname></term> + <listitem> + <para> + By default, this is <code>null</code>, which means that the + session factory will not be fetched from JNDI. If it is set and a + session factory is needed in order to create a + <application>Hibernate</application> session, it will be + fetched from JNDI. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><classname>dataSourceJndiName</classname></term> + <listitem> + <para> + By default, this is <code>null</code>, resulting in creation + of JDBC connections being delegated to + <application>Hibernate</application>. By specifying a + data-source, one makes the Business Process Manager fetch a + JDBC connection from the data-source and provide it to + <application>Hibernate</application> whilst opening a new + session. + </para> + </listitem> + </varlistentry> + </variablelist> - </section> + + <section id="thehibernatesessionfactory"> - <title>The hibernate session factory</title> + <title> + The Hibernate Session Factory + </title> - <para>By default, the DbPersistenceServiceFactory will use the resource hibernate.cfg.xml - in the root of the classpath to create the hibernate session factory. Note that the - hibernate configuration file resource is mapped in the property 'jbpm.hibernate.cfg.xml' - and can be customized in the jbpm.cfg.xml. This is the default configuration: - </para> + <para> + By default, the + <classname>DbPersistenceServiceFactory</classname> uses the + <filename>hibernate.cfg.xml</filename> file in the root of the + classpath to create the <application>Hibernate</application> + session factory. Note that the + <application>Hibernate</application> configuration file resource + is mapped in <property>jbpm.hibernate.cfg.xml</property>. + Customise it by reconfiguring <filename>jbpm.cfg.xml</filename>. + </para> - <programlisting>&lt;jbpm-configuration&gt; - ... - &lt;!-- configuration resource files pointing to default configuration files in jbpm-{version}.jar --&gt; - &lt;string name='resource.hibernate.cfg.xml' - value='hibernate.cfg.xml' /&gt; - &lt;!-- &lt;string name='resource.hibernate.properties' - value='hibernate.properties' /&gt; --&gt; - ... -&lt;/jbpm-configuration&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/persistence_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para>When the property <emphasis role="bold">resource.hibernate.properties</emphasis> - is specified, the properties in that resource file will <emphasis role="bold">overwrite - all</emphasis> the properties in the hibernate.cfg.xml. Instead of updating the hibernate.cfg.xml to - point to your DB, the hibernate.properties can be used to handle jbpm upgrades conveniently: - The hibernate.cfg.xml can then be copied without having to reapply the changes. - </para> +<important> + <para> + When <property>resource.hibernate.properties</property> is + specified, the properties in that resource file will overwrite + all of those in <filename>hibernate.cfg.xml</filename>. Instead + of updating the <filename>hibernate.cfg.xml</filename> to point + to the database, use <property>hibernate.properties</property> + to handle jBPM upgrades. The + <filename>hibernate.cfg.xml</filename> file can then be copied + without the need to reapply the changes. + </para> +</important> + </section> <section id="configuringac3poconnectionpool"> - <title>Configuring a c3po connection pool</title> - <para>Please refer to the hibernate documentation: - <ulink url="http://www.hibernate.org/214.html">http://www.hibernate... + <title> + Configuring a C3PO Connection Pool + </title> + <para> + Please refer to the Hibernate documentation at + <ulink url="http://www.hibernate.org/214.html" /> </para> </section> <section id="configuringehcache"> - <title>Configuring a ehcache cache provider</title> - <para>If you want to configure jBPM with JBossCache, have a look at <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JbpmConfiguration"... - the jBPM configuration wiki page</ulink> - </para> - <para>For more information about configuring a cache provider in hibernate, take a look at <ulink url="http://www.hibernate.org/hib_docs/reference/en/html/performance... - the hibernate documentation, section 'Second level cache'</ulink> - </para> - <para>The hibernate.cfg.xml that ships with jBPM includes the following line: - </para> - <programlisting>&lt;property name="hibernate.cache.provider_class"&gt;org.hibernate.cache.HashtableCacheProvider&lt;/property&gt;</programlisting> - <para>This is done to get people up and running as fast as possible without having to worrie about classpaths. - Note that hibernate contains a warning that states not to use the HashtableCacheProvider in production. - </para> - <para>To use ehcache instead of the HashtableCacheProvider, simply remove that line and put ehcache.jar on the - classpath. Note that you might have to search for the right ehcache library version that is compatible with - your environmment. Previous incompatibilities between a jboss version and a perticular ehcache version were - the reason to change the default to HashtableCacheProvider. - </para> + <title> + Configuring an ehCache Provider + </title> + + <para> + To learn how to configure jBPM with + <application>JBossCache</application>, read <ulink + url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JbpmConfiguration" + /> + </para> + + <para> + To learn how to configure a cache provider to work with + <application>Hibernate</application>, study <ulink + url="http://www.hibernate.org/hib_docs/reference/en/html/performance... + />. + </para> + + <para> + The <filename>hibernate.cfg.xml</filename> file that ships with jBPM + includes the following line: + </para> + + <programlisting language="XML"><xi:include href="extras/persistence_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> + This is provided so that users do not have to concern themselves with configuring + classpaths. + </para> + + <warning> + <para> + Do not use <application>Hibernate</application>'s + <classname>HashtableCacheProvider</classname> in a + production environment. + </para> + + <para> + To use <classname>ehcache</classname> instead of the + <classname>HashtableCacheProvider</classname>, simply remove + the relevant line from the classpath and substitute + <filename>ehcache.jar</filename> instead. Note that one might + have to search for the right + <classname>ehcache</classname> library version that is + compatible with one's environment. + </para> + </warning> + </section> </section> <section id="hibernatetransactions"> - <title>Hibernate transactions</title> - <para>By default, jBPM will delegate transaction to hibernate and use the session per transaction - pattern. jBPM will begin a hibernate transaction when a hibernate session is opened. - This will happen the first time when a persistent operation is invoked on the jbpmContext. - The transaction will be committed right before the hibernate session is closed. That - will happen inside the jbpmContext.close(). + <title> + Hibernate Transactions + </title> + + <para> + By default, jBPM delegates transactions to + <application>Hibernate</application> by using the + <emphasis>"session per transaction"</emphasis> pattern. jBPM will + begin a <application>Hibernate</application> transaction when a + session is opened the first time when a persistent operation is + invoked on the <classname>jbpmContext</classname>. The transaction + will be committed right before the Hibernate session is closed. That + will happen inside the <methodname>jbpmContext.close()</methodname>. </para> - <para>Use <literal>jbpmContext.setRollbackOnly()</literal> to mark a transaction for rollback. - In that case, the transaction will be rolled back right before the session is closed - inside of the jbpmContext.close(). + + <para> + Use <methodname>jbpmContext.setRollbackOnly()</methodname> to mark a + transaction for rollback. In doing so, the transaction will be + rolled back imediately before the session is closed inside the + <methodname>jbpmContext.close()</methodname> method. </para> - <para>To prohibit jBPM from invoking any of the transaction methods on the hibernate - API, set the isTransactionEnabled property to false as explained in <xref linkend="thedbpersistenceservicefactory" /> - above. + + <para> + To prohibit the Business Process Manager from invoking any of + the transaction methods + via the <application>Hibernate</application> application + programming interface, set the + <property>isTransactionEnabled</property> property to + <code>false</code>, as explained in more detail in <xref + linkend="thedbpersistenceservicefactory" />. </para> </section> <section id="jtatransactions"> - <title>JTA transactions</title> - <para>The most common scenario for managed transactions is when using jBPM in a JEE application - server like JBoss. The most common scenario to bind your transactions to JTA is the following: + <title> + JTA Transactions + </title> + + <para> + Managed transactions are most commonly found when jBPM is used in + conjuction with the <application>JBoss Application + Server</application>. The following code sample shows a common + way in which transactions are bound to JTA: </para> - <programlisting> &lt;jbpm-context&gt; - &lt;service name="persistence"&gt; - &lt;factory&gt; - &lt;bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory"&gt; - &lt;field name="isTransactionEnabled"&gt;&lt;false /&gt;&lt;/field&gt; - &lt;field name="isCurrentSessionEnabled"&gt;&lt;true /&gt;&lt;/field&gt; - &lt;field name="sessionFactoryJndiName"&gt; - &lt;string value="java:/myHibSessFactJndiName" /&gt; - &lt;/field&gt; - &lt;/bean&gt; - &lt;/factory&gt; - &lt;/service&gt; - ... - &lt;/jbpm-context&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/persistence_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + - <para>Then you should specify in your hibernate session factory to use a datasource and - bind hibernate to the transaction manager. Make sure that you bind the datasource - to an XA datasource in case you're using more then 1 resource. For more information - about binding hibernate to your transaction manager, please, refer to - <ulink url="http://www.hibernate.org/hib_docs/v3/reference/en/html_single/#... - 'Transaction strategy configuration' in the hibernate documentation</ulink>. + <para> + Next, configure the <application>Hibernate</application> session + factory to use a data-source and bind + <application>Hibernate</application> itself to the Transaction + Manager. If using more than one datasource, bind them to an + <systemitem>XA datasource</systemitem>. </para> - <programlisting>&lt;hibernate-configuration&gt; - &lt;session-factory&gt; - &lt;!-- hibernate dialect --&gt; - &lt;property name="hibernate.dialect"&gt;org.hibernate.dialect.HSQLDialect&lt;/property&gt; + <programlisting language="XML"><xi:include href="extras/persistence_5.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - &lt;!-- DataSource properties (begin) --&gt; - &lt;property name="hibernate.connection.datasource"&gt;java:/JbpmDS&lt;/property&gt; - &lt;!-- JTA transaction properties (begin) --&gt; - &lt;property name="hibernate.transaction.factory_class"&gt;org.hibernate.transaction.JTATransactionFactory&lt;/property&gt; - &lt;property name="hibernate.transaction.manager_lookup_class"&gt;org.hibernate.transaction.JBossTransactionManagerLookup&lt;/property&gt; - &lt;property name="jta.UserTransaction"&gt;java:comp/UserTransaction&lt;/property&gt; +<note> + <para> + For more information about binding + <application>Hibernate</application> to a Transaction Manager, + please, refer to <ulink + url="http://www.hibernate.org/hib_docs/v3/reference/en/html_single/#... + />. + </para> +</note> - ... - &lt;/session-factory&gt; -&lt;/hibernate-configuration&gt;</programlisting> - - <para>Then make sure that you have configured hibernate to use an XA datasource. + <para> + Next, configure Hibernate to use an <systemitem>XA + datasource</systemitem>. </para> - <para>These configurations allow for the enterprise beans to use CMT and still allow the - web console to use BMT. That is why the property 'jta.UserTransaction' is also specified. + <para> + These configurations allow the enterprise beans to use CMT whilst + the web console uses BMT. (This is why + <property>jta.UserTransaction</property> is also specified.) </para> </section> - <section id="customizingqueries"> - <title>Customizing queries</title> - <para>All the HQL queries that jBPM uses are centralized in one configuration file. - That resource file is referenced in the hibernate.cfg.xml configuration file - like this: - </para> - <programlisting>&lt;hibernate-configuration&gt; - ... - &lt;!-- hql queries and type defs --&gt; - &lt;mapping resource="org/jbpm/db/hibernate.queries.hbm.xml" /&gt; - ... -&lt;/hibernate-configuration&gt;</programlisting> - <para>To customize one or more of those queries, take a copy of the original file - and put your customized version somewhere on the classpath. Then update the - reference 'org/jbpm/db/hibernate.queries.hbm.xml' in the hibernate.cfg.xml to point to your - customized version. - </para> + <section id="customizingqueries"> + <title> + Customizing Queries + </title> + + <para> + All of the SQL queries that jBPM uses are found in one central + configuration file. That resource file is referenced in the + <filename>hibernate.cfg.xml</filename> configuration file: + </para> + + <programlisting language="XML"><xi:include href="extras/persistence_6.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> + To customize one or more of those queries, make a back-up of the + original file. Next, place the customized version somewhere on the + classpath, then update the reference to + <filename>org/jbpm/db/hibernate.queries.hbm.xml</filename> in + the <filename>hibernate.cfg.xml</filename> to point to the + customized version. + </para> </section> <section id="databasecompatibility"> @@ -671,92 +763,21 @@ Be aware that there is no constraint on invoking these methods other than the privileges of the configured database user. </para> + +<note> <para>The aforementioned APIs constitute a facade to the broader functionality offered by class <ulink url="http://docs.jboss.com/jbpm/v3.2/javadoc-jpdl/org/jbpm/db/JbpmSc... <classname>org.jbpm.db.JbpmSchema</classname></ulink>: </para> - <itemizedlist> - <listitem><para>Create, drop, update and clean (drop-create) the database schema</para></listitem> - <listitem><para>Generate SQL scripts for the above operations</para></listitem> - <listitem><para>List the mapped tables and query the existing tables in the database</para></listitem> - </itemizedlist> - </section> - <section id="jbpmschematask"> - <title>The jBPM schema Ant task</title> - <para>As an alternative to programmatic schema manipulation, jBPM provides an Ant task - for generating scripts that create, drop and update the database schema. - The listing below illustrates the task being used to generate the schema - creation script and save it to file <literal>create.sql</literal>. The Hibernate - configuration is read from the resource <literal>hibernate.cfg.xml</literal>.</para> - <programlisting><![CDATA[<taskdef name="jbpmschema" classname="org.jbpm.ant.JbpmSchemaTask"> - <classpath> - <pathelement location="jbpm-jpdl.jar" /> - <pathelement location="hibernate.jar" /> - <pathelement location="dom4j.jar" /> - <pathelement location="commons-logging.jar"/> - <pathelement location="commons-collections.jar"/> - </classpath> -</taskdef> - -<jbpmschema config="hibernate.cfg.xml" action="create" output="create.sql" />]]></programlisting> - <para>The task parameters are documented below.</para> - <table><title>jBPM schema task parameters</title><tgroup cols='3'> - <colspec colname='attr' colwidth="*" /> - <colspec colname='desc' colwidth="3*" /> - <colspec colname='req' colwidth="*" /> - <thead> - <row> - <entry>Attribute</entry> - <entry>Description</entry> - <entry>Required</entry> - </row> - </thead> - <tbody> - <row> - <entry>config</entry> - <entry>Hibernate configuration resource</entry> - <entry>No, default <literal>hibernate.cfg.xml</literal></entry> - </row> - <row> - <entry>properties</entry> - <entry>Hibernate properties resource. These properties override - property values from the <literal>config</literal> resource.</entry> - <entry>No</entry> - </row> - <row> - <entry>action</entry> - <entry>Database schema operation to script. Can be <literal>create</literal>, - <literal>drop</literal>, <literal>update</literal> or - <literal>clean</literal>.</entry> - <entry>No, default <literal>create</literal></entry> - </row> - <row> - <entry>output</entry> - <entry>The output file. The generated script is written to this file.</entry> - <entry>Yes</entry> - </row> - <row> - <entry>delimiter</entry> - <entry>String that separates SQL statements</entry> - <entry>No, default <literal>;</literal></entry> - </row> - <row> - <entry>delimiterType</entry> - <entry>Control whether the delimiter should be placed on a line by itself. - Can be <literal>normal</literal>, at the end of line, or <literal>row</literal>, - on a line by itself.</entry> - <entry>No, default <literal>normal</literal></entry> - </row> - </tbody> - </tgroup></table> - </section> - </section> + </note> + </section> + </section> <section> - <title> + <title> Combining Hibernate Classes </title> @@ -787,54 +808,79 @@ </para> </section> - <section> - <title>Customizing the jBPM hibernate mapping files</title> - <para>To customize any of the jBPM hibernate mapping files, you can proceed as - follows: - </para> - <itemizedlist> - <listitem><para>copy the jBPM hibernate mapping file(s) you want to copy from the - sources (<literal>src/jbpm-jpdl-sources.jar</literal>)</para> - </listitem> - <listitem><para> - put the copy anywhere you want on the classpath, but make sure it is not - the exact same location as they were before.</para> - </listitem> - <listitem><para> - update the references to the customized mapping files in the hibernate.cfg.xml - configuration file</para> - </listitem> - </itemizedlist> - </section> + <section> + <title> + Customizing the jBPM Hibernate Mapping Files + </title> + + <para> + Follow these steps to customize any of the jBPM + <application>Hibernate</application> mapping files: + </para> - <section id="secondlevelcache"> - <title>Second level cache</title> - <para>jBPM uses hibernate's second level cache for keeping the process definitions - in memory after loading them once. The process definition classes and collections - are configured in the jBPM hibernate mapping files with the cache element like this: - </para> - <programlisting>&lt;cache usage="nonstrict-read-write"/&gt;</programlisting> - <para>Since process definitions (should) never change, it is ok to keep them in the - second level cache. - </para> - <para>The second level cache is an important aspect of the JBoss jBPM implementation. - If it weren't for this cache, JBoss jBPM could have a serious drawback in comparison - to the other techniques to implement a BPM engine. - </para> - <para>The default caching strategy is set to <literal>nonstrict-read-write</literal>. During - runtime execution of processes, the process definitions are static. This way, - we get the maximum caching during runtime execution of processes. In theory, - caching strategy <literal>read-only</literal> would be even better for runtime - execution. But in that case, deploying new process definitions would not be - possible as that operation is not read-only. - </para> - <para> + <procedure> + <step> + <para> + copy the jBPM <application>Hibernate</application> mapping + files from the + sources (<filename>src/jbpm-jpdl-sources.jar</filename>). + </para> + </step> + <step> + <para> + place the copy somewhere on the classpath, (ensuring that + it is not the same location as they were in previously. + </para> + </step> + <step> + <para> + update the references to the customized mapping files in + <filename>hibernate.cfg.xml</filename></para> + </step> + </procedure> + </section> + + <section id="secondlevelcache"> + <title> + Second Level Cache + </title> + + <para> + jBPM uses <application>Hibernate</application>'s + <firstterm>second level cache</firstterm> to keep the process + definitions in memory after loading they have been loaded once. + The process definition classes and collections are configured in + the <application>Hibernate</application> mapping files so that the + cache element looks like this: + </para> + + <programlisting language="XML"><xi:include href="extras/persistence_7.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> + Since process definitions will never change, it is acceptable to + keep them in the second level cache. (See also <xref + linkend="changingdeployedprocessdefinitions" />.) + </para> + + <para> + The default caching strategy is set to + <code>nonstrict-read-write</code>. During run-time execution, + the process definitions remain static, allowing maximum caching + to be achieved. In theory, setting the caching strategy + <code>read-only</code> would be even better for run-time + execution but, that setting would not permit the deployment of + new process definitions. + </para> +<para> Having read this chapter, you have learned a great deal of theoretical information and practical advice relating to the topic of persistence in jBPM, including how to utilize <application>Hibernate</application> to its fullest potential. </para> - + + + </section> + </section> - + </section> </chapter> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/scheduler.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/scheduler.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/scheduler.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -13,6 +13,7 @@ <firstterm>timers</firstterm> in the Business Process Manager. </para> + <para> Timers can be created upon events in the process. Set them to trigger either action executions or event transitions. @@ -28,15 +29,7 @@ element</firstterm> to the node. This sample code shows how to do so: </para> - <programlisting>&lt;state name='catch crooks'&gt; - &lt;timer name='reminder' - duedate='3 business hours' - repeat='10 business minutes' - transition='time-out-transition' &gt; - &lt;action class='the-remainder-action-class-name' /&gt; - &lt;/timer&gt; - &lt;transition name='time-out-transition' to='...' /&gt; -&lt;/state&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/scheduler_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <para> A timer specified on a node is not executed after that node @@ -44,7 +37,7 @@ is executed, the following events occur in sequence: </para> - <orderedlist> + <orderedlist> <listitem><para>an event of type <systemitem>timer</systemitem> is fired.</para></listitem> <listitem><para>if an action is specified, it executes.</para></listitem> <listitem><para>a signal is to resume execution @@ -90,8 +83,8 @@ </para> <figure id="scheduler.overview.image"> - <title>Scheduler components overview</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/scheduler.overview.gif"/></imageobject></mediaobject> + <title>Scheduler Components Overview</title> + <mediaobject><imageobject><imagedata fileref="images/scheduler.overview.png"/></imageobject></mediaobject> </figure> </section> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/taskmgmt.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/taskmgmt.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/taskmgmt.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -5,306 +5,538 @@ ]> <chapter id="taskmanagement"> - <title>Task management</title> - <para>The core business of jBPM is the ability to persist the execution - of a process. A situation in which this feature is extremely useful is - the management of tasks and tasklists for people. jBPM allows to - specify a piece of software describing an overall process which - can have wait states for human tasks.</para> + <title> + Task Management + </title> + + <para> + The jBPM's core role is to <firstterm>persist</firstterm> the + execution of a process. This feature is extremely useful when one + is seeking to manage tasks and task-lists for people. The jBPM + allows one to specify a piece of software that describes an overall + process. Such a piece of software can have <firstterm>wait + states</firstterm> for human tasks. + </para> <section id="tasks"> - <title>Tasks</title> + <title> + Tasks + </title> - <para>Tasks are part of the process definition and they define how - task instances must be created and assigned during process - executions.</para> - <para>Tasks can be defined in <literal>task-node</literal>s and in the - <literal>process-definition</literal>. The most common way is to define - one or more <literal>task</literal>s in a <literal>task-node</literal>. - In that case the <literal>task-node</literal> represents a task to be - done by the user and the process execution should wait until the actor - completes the task. When the actor completes the task, process execution - should continue. When more tasks are specified in a - <literal>task-node</literal>, the default behaviour is to wait for all the - tasks to complete. + <para> + <firstterm>Tasks</firstterm> are part of the process + definition. They define how task instances will be created and + assigned during process executions. </para> - <para>Tasks can also be specified on the <literal>process-definition</literal>. - Tasks specified on the process definition can be looked up by name and - referenced from within <literal>task-node</literal>s or used from - inside actions. In fact, all tasks (also in task-nodes) that are given a - name can be looked up by name in the process-definition. + <para> + Define tasks in <systemitem>task-node</systemitem>s and in the + <systemitem>process-definition</systemitem>. The most common + way is to define one or more <systemitem>task</systemitem>s in + a <systemitem>task-node</systemitem>. In that case the + <systemitem>task-node</systemitem> represents a task to be + undertaken by the user and the process execution should wait + until the actor completes the task. When the actor completes + the task, process execution continues. When more tasks are + specified in a <systemitem>task-node</systemitem>, the default + behaviour is to wait until all the tasks have ended. </para> - <para>Task names must be unique in the whole process definition. Tasks - can be given a <literal>priority</literal>. This priority will be used - as the initial priority for each task instance that is created for this task. - TaskInstances can change this initial priority afterwards.</para> + <para> + One can also specify tasks on the + <systemitem>process-definition</systemitem>. Tasks specified in + this way can be found by searching for their names. One can + also reference them from within + <systemitem>task-node</systemitem>s or use them from within + actions. In fact, every task (or + <systemitem>task-node</systemitem>) that is given a name can be + found in the <systemitem>process-definition</systemitem>. + </para> + + <para> + Ensure that each task name is unique. Also, give the task a + <systemitem>priority</systemitem>. This will be used as the + initial priority for each task instance created for this task. + (This initial priority can be changed by the task instance + afterwards.) + </para> </section> <section id="taskinstances"> - <title>Task instances</title> + <title> + Task Instances + </title> - <para>A task instance can be assigned to an actorId (java.lang.String). All task instances - are stored in one table of the database (JBPM_TASKINSTANCE). By querying this table for - all task instances for a given actorId, you get the task list for that perticular user. + <para> + It is possible to assign a task instance to an + <systemitem>actorId</systemitem> + (<classname>java.lang.String</classname>). Every task instance + is stored in one table (<literal>JBPM_TASKINSTANCE</literal>.) + Query this table for every task instances for a given actorId, + in order to obtain the task list for that particular user. </para> - <para>The jBPM task list mechanism can combine jBPM tasks with other tasks, even when those - tasks are unrelated to a process execution. That way jBPM developers can easily combine - jBPM-process-tasks with tasks of other applications in one centralized task-list-repository. + <para> + Use the jBPM task list mechanism to combine jBPM tasks with + other tasks, even when those other tasks are unrelated to a + process execution. In this way, one can easily combine + jBPM-process-tasks with other application's tasks in one + centralised repository. </para> <section id="taskinstancelifecycle"> - <title>Task instance lifecycle</title> - <para>The task instance lifecycle is straightforward: After creation, task instances can optionally - be started. Then, task instances can be ended, which means that the task instance is marked as - completed.</para> - <para>Note that for flexibility, assignment is not part of the life cycle. So task instances - can be assigned or not assigned. Task instance assignment does not have an influence on the - task instance life cycle.</para> - <para>Task instances are typically created by the process execution entering a - <literal>task-node</literal> (with the method <literal>TaskMgmtInstance.createTaskInstance(...)</literal>). - Then, a user interface component will query the database for the tasklists using the - <literal>TaskMgmtSession.findTaskInstancesByActorId(...)</literal>. Then, after collecting input - from the user, the UI component calls <literal>TaskInstance.assign(String)</literal>, - <literal>TaskInstance.start()</literal> or <literal>TaskInstance.end(...)</literal>. + <title> + Task Instance Life-Cycle + </title> + + + <para> + The task instance life-cycle is straightforward: after + creation, one can start the instances. They can then be ended, + which means that they will be marked as completed. </para> - <para>A task instance maintains it's state by means of date-properties : <literal>create</literal>, - <literal>start</literal> and <literal>end</literal>. Those properties can be accessed by - their respective getters on the <literal>TaskInstance</literal>.</para> - <para>Currently, completed task instances are marked with an end date so that they are not - fetched with subsequent queries for tasks lists. But they remain in the JBPM_TASKINSTANCE - table.</para> + +<note> + <para> + For the sake of flexibility, <firstterm>assignment</firstterm> is + not part of the life-cycle. + </para> +</note> + +<orderedlist> + <listitem> + <para> + Task instances are normally created when the process execution + enters a <systemitem>task-node</systemitem> (via the + <methodname>TaskMgmtInstance.createTaskInstance(...)</methodname> + method.) + </para> + </listitem> + <listitem> + <para> + A user interface component then queries the database + for the task lists. It does so by using the + <methodname>TaskMgmtSession.findTaskInstancesByActorId(...)</methodname> method. + </para> + </listitem> + <listitem> + <para> + Then, after collecting input from the user, the UI component + calls <methodname>TaskInstance.assign(String)</methodname>, + <methodname>TaskInstance.start()</methodname> or + <methodname>TaskInstance.end(...)</methodname>. + </para> + </listitem> +</orderedlist> + + + + <para> + A task instance maintains its state by means of three date-properties: + </para> + +<orderedlist> + <listitem> + <para> + <systemitem>create</systemitem> + </para> + </listitem> + <listitem> + <para> + <systemitem>start</systemitem> + </para> + </listitem> + <listitem> + <para> + <systemitem>end</systemitem> + </para> + </listitem> +</orderedlist> + + + <para> + Access these properties via their respective "getters", which + can be found on the <systemitem>TaskInstance</systemitem>. + </para> + + + <para> + Completed task instances are marked with an end date so that + they are not fetched when subsequent queries search for tasks + lists. The completed tasks do, however, remain in the + <literal>JBPM_TASKINSTANCE</literal> table. + </para> </section> <section id="taskinstancesandgraphexecution"> - <title>Task instances and graph execution</title> - <para>Task instances are the items in an actor's tasklist. Task instances - can be signalling. A signalling task instance is a task instance that, when - completed, can send a signal to its token to continue the process execution. - Task instances can be blocking, meaning that the related token (=path of - execution) is not allowed to leave the task-node before the task instance is - completed. By default task instances are signalling and non-blocking. + <title> + Task Instances and Graph Executions + </title> + + <para> + <firstterm>Task instances</firstterm> are the items in an + actor's task list. A signalling task instance is a task + instance that, when completed, sends a signal to its token to + continue the process execution. Blocking task instances are + those that the related token (the path of execution) is not + allowed to leave the <systemitem>task-node</systemitem> before + the task instance is completed. By default, task instances are + configured to be signalling and non-blocking. </para> - <para>In case more than one task instance are associated with a task-node, - the process developer can specify how completion of the task instances affects - continuation of the process. Following is the list of values that can be - given to the signal-property of a task-node.</para> + <para> + If more than one task instance is associated with a + <systemitem>task-node</systemitem>, the process developer can + specify the way in which completion of the task instances + affects continuation of the process. Give any of these values to + the <systemitem>task-node</systemitem>'s + <systemitem>signal-property</systemitem>: + </para> - <variablelist> + <variablelist> <varlistentry> - <term>last</term> - - <listitem><para>This is the default. Proceeds execution when the last task instance is completed. When no tasks are created on entrance of this node, execution is continued.</para></listitem> - </varlistentry> + <term>last</term> + <listitem> + <para> + This is the default. It proceeds execution when the last + task instance has been completed. When no tasks are created + on entrance of this node, execution is continued. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>last-wait</term> + <listitem> + <para> + This proceeds execution when the last task instance has + been completed. When no tasks are created on entrance of + this node, execution waits in the task node until tasks are + created. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>first</term> + <listitem> + <para> + This proceeds execution when the first task instance has been completed. When no tasks + are created upon the entry of this node, execution is continued. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>first-wait</term> + <listitem> + <para> + This proceeds execution when the first task instance has + been completed. When no tasks are created on entrance of + this node, execution waits in the task node until tasks are + created. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>unsynchronized</term> + <listitem> + <para> + In this case, execution always continues, regardless of whether tasks are created or still + unfinished. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>never</term> + <listitem> + <para> + In this case, execution never continues, regardless whether tasks are created or still + unfinished. + </para> + </listitem> + </varlistentry> + </variablelist> - - <varlistentry> - <term>last-wait</term> - - - <listitem><para>Proceeds execution when the last task instance is completed. When no tasks are created on entrance of this node, execution waits in the task node till tasks are created.</para></listitem> - </varlistentry> - - - <varlistentry> - <term>first</term> - - <listitem><para>Proceeds execution when the first task instance is completed. When no tasks are created on entrance of this node, execution is continued.</para></listitem> - </varlistentry> - - <varlistentry> - <term>first-wait</term> - - - <listitem><para>Proceeds execution when - the first task instance is completed. When no tasks are created on entrance of this node, execution waits in the task node till tasks are created.</para></listitem> - </varlistentry> - - <varlistentry> - <term>unsynchronized</term> - - <listitem><para>Execution always continues, regardless wether tasks are created or still unfinished.</para></listitem> - </varlistentry> - - - - <varlistentry> - <term>never</term> - - <listitem><para>Execution never continues, regardless wether tasks are created or still unfinished.</para></listitem> - </varlistentry> - - </variablelist> - - <para>Task instance creation might be based upon a runtime calculation. In that case, add an - <literal>ActionHandler</literal> on the <literal>node-enter</literal> event of the <literal>task-node</literal> and - set the attribute <literal>create-tasks="false"</literal>. Here is an example of such an action handler implementation: + <para> + Task instance creation can be based upon a run-time + calculation. In these cases, add an + <systemitem>ActionHandler</systemitem> to the + <systemitem>task-node</systemitem>'s + <systemitem>node-enter</systemitem> event and set + <code>create-tasks="false"</code>. Here is an example: </para> - <programlisting>public class CreateTasks implements ActionHandler { - public void execute(ExecutionContext executionContext) throws Exception { - Token token = executionContext.getToken(); - TaskMgmtInstance tmi = executionContext.getTaskMgmtInstance(); - - TaskNode taskNode = (TaskNode) executionContext.getNode(); - Task changeNappy = taskNode.getTask("change nappy"); + <programlisting language="Java"><xi:include href="extras/taskmgmt_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - // now, 2 task instances are created for the same task. - tmi.createTaskInstance(changeNappy, token); - tmi.createTaskInstance(changeNappy, token); - } -}</programlisting> - <para>As shown in the example the tasks to be created can be specified - in the task-node. They could also be specified in the - <literal>process-definition</literal> and fetched from the - <literal>TaskMgmtDefinition</literal>. <literal>TaskMgmtDefinition</literal> extends - the ProcessDefinition with task management information.</para> + <para> + Here, the tasks to be created are specified in the + <systemitem>task-node</systemitem>. They could also be + specified in the <systemitem>process-definition</systemitem> + and fetched from the + <systemitem>TaskMgmtDefinition</systemitem>. + (<systemitem>TaskMgmtDefinition</systemitem> extends the + process definition by adding task management information.) + </para> - <para>The API method for marking task instances as completed is - <literal>TaskInstance.end()</literal>. Optionally, you can specify a transition - in the end method. In case the completion of this task instance triggers - continuation of the execution, the task-node is left over the specified - transition.</para> + <para> + The <methodname>TaskInstance.end()</methodname> method is + used to mark task instances as completed. One can optionally + specify a transition in the end method. In case the completion + of this task instance triggers continuation of the execution, + the <systemitem>task-node</systemitem> is left over the + specified transition. + </para> </section> </section> <section id="assignment"> - <title>Assignment</title> + <title> + Assignment + </title> - <para>A process definition contains task nodes. A <literal>task-node</literal> - contains zero or more tasks. Tasks are a static description as part of the process - definition. At runtime, tasks result in the creation of task instances. A task - instance corresponds to one entry in a person's task list.</para> + <para> + A process definition contains task nodes. A + <systemitem>task-node</systemitem> contains zero or more tasks. + Tasks are static descriptions of part of the process + definition. At run-time, executing tasks result in the creation + of task instances. A task instance corresponds to one entry in + a person's task list. + </para> - <para>With jBPM, push (personal task list) (<xref linkend="thepersonaltasklist" />) and - pull (group task list) (<xref linkend="thegrouptasklist" />) model (see below) of - task assignment can be applied in combination. - The process can calculate the responsible for a task and push it in his/her tasklist. - Or alternatively, a task can be assigned to a pool of actors, in which case - each of the actors in the pool can pull the task and put it in the actor's - personal tasklist. + <para> + With the jBPM, one can apply the push (personal task list) and + pull (group task list) models of task assignment in + combination. The process determines those responsible for a + task and push it to their task lists. A task can also be + assigned to a pool of actors, in which case each of the actors + pull the task and put it in their + personal task lists. (Refer to <xref + linkend="thepersonaltasklist"/> and <xref + linkend="thegrouptasklist"/> for more information.) </para> <section id="assignmentinterfaces"> - <title>Assignment interfaces</title> - <para>Assigning task instances is done via the interface - <literal>AssignmentHandler</literal>:</para> + <title> + Assignment Interfaces + </title> + + <para> + Assign task instances via the + <interfacename>AssignmentHandler</interfacename> interface: + </para> - <programlisting>public interface AssignmentHandler extends Serializable { + <programlisting language="Java">public interface AssignmentHandler extends Serializable { void assign( Assignable assignable, ExecutionContext executionContext ); }</programlisting> - <para>An assignment handler implementation is called when a task instance is - created. At that time, the task instance can be assigned to one or more actors. - The <literal>AssignmentHandler</literal> implementation should - call the <literal>Assignable</literal> methods (<literal>setActorId</literal> or - <literal>setPooledActors</literal>) to assign a task. The <literal>Assignable</literal> is either - a <literal>TaskInstance</literal> or a <literal>SwimlaneInstance</literal> (=process role). + <para> + An assignment handler implementation is called when a task + instance is created. At that time, the task instance is + assigned to one or more actors. The + <systemitem>AssignmentHandler</systemitem> implementation calls + the assignable methods (<methodname>setActorId</methodname> or + <methodname>setPooledActors</methodname>) to assign a task. The + assignable item is either a + <systemitem>TaskInstance</systemitem> or a + <systemitem>SwimlaneInstance</systemitem> (that is, a process + role). </para> - <programlisting>public interface Assignable { + <programlisting language="Java">public interface Assignable { public void setActorId(String actorId); public void setPooledActors(String[] pooledActors); }</programlisting> - <para>Both <literal>TaskInstance</literal>s - and <literal>SwimlaneInstance</literal>s can be assigned to a specific user or to a pool - of actors. To assign a TaskInstance to a user, call - <literal>Assignable.setActorId(String actorId)</literal>. To assign a TaskInstance to a pool - of candidate actors, call <literal>Assignable.setPooledActors(String[] actorIds)</literal>. + <para> + Both <systemitem>TaskInstance</systemitem>s and + <systemitem>SwimlaneInstance</systemitem>s can be assigned to a + specific user or to a pool of actors. To assign a + <systemitem>TaskInstance</systemitem> to a user, call + <methodname>Assignable.setActorId(String actorId)</methodname>. + To assign a <systemitem>TaskInstance</systemitem> to a pool of + candidate actors, call + <methodname>Assignable.setPooledActors(String[] + actorIds)</methodname>. </para> - <para>Each task in the process definition can be associated with an assignment - handler implementation to perform the assignment at runtime.</para> - <para>When more than one task in a process should be assigned to the same person - or group of actors, consider the usage of a swimlane (<xref linkend="swimlanes" />)</para> - <para>To allow for the creation of reusable <literal>AssignmentHandler</literal>s, - each usage of an <literal>AssignmentHandler</literal> can be configured in - the <literal>processdefinition.xml</literal>. See the section on Delegation - for more information on how to add configuration to assignment handlers.</para> + + <para> + One can associate each task in the process definition with an + handler implementation to perform the assignment at run-time. + </para> + + <para> + When more than one task in a process should be assigned to the + same person or group of actors, consider the usage of a + swimlane, see <xref linkend="swimlanes"/>. + </para> + + <para> + To create reusable <systemitem>AssignmentHandler</systemitem>s, + configure each one via the + <systemitem>processdefinition.xml</systemitem> file. (See <xref + linkend="delegation" /> for more information on how to add + configuration to assignment handlers.) + </para> </section> <section id="theassignmentdatamodel"> - <title>The assignment data model</title> - <para>The datamodel for managing assignments of task instances and swimlane instances to - actors is the following. Each <literal>TaskInstance</literal> has an actorId - and a set of pooled actors.</para> + <title> + The Assignment Data Model + </title> + <para> + The data model for managing assignments of task instances and + swimlane instances to actors is the following. Each + <systemitem>TaskInstance</systemitem> has an + <systemitem>actorId</systemitem> and a set of pooled actors. + </para> + <figure id="assignment.model.image"> <title>The assignment model class diagram</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/assignment.model.gif"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata fileref="images/assignment.model.png"/></imageobject></mediaobject> </figure> - <para>The actorId is the responsible for the task, while the - set of pooled actors represents a collection of candidates that can become responsible - if they would take the task. Both actorId and pooledActors are optional and can - also be combined.</para> + <para> + The <systemitem>actorId</systemitem> is the responsible for the + task, while the set of pooled actors represents a collection of + candidates one of whom will become responsible if they take the + task. Both <systemitem>actorId</systemitem> and + <systemitem>pooledActors</systemitem> are optional and can also + be combined. + </para> </section> <section id="thepersonaltasklist"> - <title>The personal task list</title> - <para>The personal task list denotes all the task instances that are assigned to a specific individual. - This is indicated with the property <literal>actorId</literal> on a <literal>TaskInstance</literal>. So - to put a TaskInstance in someone's personal task list, you just use one of the following ways: + <title> + The Personal Task List + </title> + + <para> + The personal task list denotes all the task instances that are + assigned to a specific individual. This is indicated by the + presence of the <property>actorId</property> property on a + <systemitem>TaskInstance</systemitem>. Put a + <systemitem>TaskInstance</systemitem> in someone's task list in + one of these ways: </para> - + <itemizedlist> - <listitem><para>Specify an expression in the attribute <literal>actor-id</literal> of the task element in the process</para></listitem> - <listitem><para>Use TaskInstance.setActorId(String) from anywhere in your code</para></listitem> - <listitem><para>Use assignable.setActorId(String) in an AssignmentHandler</para></listitem> + <listitem><para>specify an expression in the task element's <systemitem>actor-id</systemitem> attribute</para></listitem> + <listitem><para>use the <methodname>TaskInstance.setActorId(String)</methodname> method from anywhere in the code</para></listitem> + <listitem><para>use the <methodname>assignable.setActorId(String)</methodname> in an <classname>AssignmentHandler</classname></para></listitem> </itemizedlist> - - <para>To fetch the personal task list for a given user, use <literal>TaskMgmtSession.findTaskInstances(String actorId)</literal>. + + + <para> + To fetch the personal task list for a given user, use + <methodname>TaskMgmtSession.findTaskInstances(String + actorId)</methodname>. </para> + + </section> <section id="thegrouptasklist"> - <title>The group task list</title> - <para>The pooled actors denote the candidates for the task instance. This means that the task is offered to many users - and one candidate has to step up and take the task. Users can not start working on tasks in their group task list - immediately. That would result in a potential conflict that many people start working on the same task. To prevent this, - users can only take task instances of their group task list and move them into their personal task list. Users are only - allowed to start working on tasks that are in their personal task list. + <title> + The Group Task List + </title> + + <para> + The pooled actors are the group of candidates to whom the task + is offered. One candidate has to accept it. Users can not start + working on tasks immediately as that would, potentially, result + in a conflict if many people commenced work on the same task. + To prevent this, users can only take task instances from the + group task list and move these into their personal task lists. + It is only when a task is placed on the user's personal task + list that her or she can commence working on it. </para> - <para>To put a taskInstance in someone's group task list, you must put the user's actorId or one of the user's - groupIds in the pooledActorIds. So specify the pooled actors, use one of the following: + + <para> + To put a <systemitem>taskInstance</systemitem> in someone's + group task list, add the user's <property>actorId</property> + or one of the user's <systemitem>groupIds</systemitem> to the + <systemitem>pooledActorIds</systemitem>. To specify the pooled + actors, use one of the following methods: </para> + <itemizedlist> - <listitem><para>Specify an expression in the attribute <literal>pooled-actor-ids</literal> of the task element in the process</para></listitem> - <listitem><para>Use TaskInstance.setPooledActorIds(String[]) from anywhere in your code</para></listitem> - <listitem><para>Use assignable.setPooledActorIds(String[]) in an AssignmentHandler</para></listitem> + <listitem><para>specify an expression in the attribute + <systemitem>pooled-actor-ids</systemitem> of the task + element in the process</para></listitem> + <listitem><para>use + <methodname>TaskInstance.setPooledActorIds(String[])</methodname> + from anywhere in your code</para></listitem> + <listitem><para>use + <methodname>assignable.setPooledActorIds(String[])</methodname> + in an AssignmentHandler</para></listitem> </itemizedlist> - <para>To fetch the group task list for a given user, proceed as follows: Make a collection that includes the user's actorId - and all the ids of groups that the user belongs to. With <literal>TaskMgmtSession.findPooledTaskInstances(String actorId)</literal> or - <literal>TaskMgmtSession.findPooledTaskInstances(List actorIds)</literal> you can search for task instances that are not in a personal - task list (actorId==null) and for which there is a match in the pooled actorIds. + + <para> + To fetch the group task list for a given user, make a + collection that includes the user's + <property>actorId</property> and those of all the groups to + which the user belongs. Use + <methodname>TaskMgmtSession.findPooledTaskInstances(String + actorId)</methodname> or + <methodname>TaskMgmtSession.findPooledTaskInstances(List + actorIds)</methodname> to search for task instances that are + not in a personal task list (<code>actorId==null</code>) and + for which there is a match amongst the pooled + <property>actorId</property>. </para> - <para>The motivation behind this is that we want to separate the identity component from jBPM task assignment. jBPM only stores - Strings as actorIds and doesn't know the relation between the users, groups and other identity information. + +<note> + <para> + The software was designed this way in order to separate the + identity component from jBPM task assignment. The jBPM only + stores strings as <property>actorId</property>s. It does not + understand the relationships between the users and groups or + any other identity information. </para> - - <para>The actorId will always override the pooled actors. So a taskInstance that has an actorId and a list of pooledActorIds, - will only show up in the actor's personal task list. Keeping the pooledActorIds around allows a user to put a task instance - back into the group by just setting the actorId property of the taskInstance to <literal>null</literal>. +</note> + + <para> + The <property>actorId</property> always overrides pooled + actors. Hence, a taskInstance that has an + <property>actorId</property> and a list of + <systemitem>pooledActorId</systemitem>s will only show up in + the actor's personal task list. Retain the + <systemitem>pooledActorId</systemitem>s in order to put a task + instance back into the group by simply setting the + <systemitem>taskInstance</systemitem>'s + <property>actorId</property> property to <code>null</code>. </para> </section> </section> <section id="taskinstancevariables"> - <title>Task instance variables</title> - <para>A task instance can have its own set of variables and a task instance can - also 'see' the process variables. Task instances are usually created in an execution - path (=token). This creates a parent-child relation between the token and the task - instance similar to the parent-child relation between the tokens themselves. - The normal scoping rules apply between the variables of a task instance and the - process variables of the related token. More info about scoping can be found - in <xref linkend="variablescopes" />. + <title> + Task Instance Variables + </title> + + <para> + A task instance can have its own set of variables and can + also "see" the process variables. Task instances are + usually created in an execution path (a token). This + creates a parent-child relation between the token and the + task instance, which is similar to the parent-child + relation between the tokens themselves. Note that the + normal scoping rules apply. + </para> + + + <para> + Use the <firstterm>controller</firstterm> to create, populate + and submit variables between the task instance scope and the + process scoped variables. </para> <para>This means that a task instance can 'see' its own variables plus all the variables of its related token. @@ -315,253 +547,382 @@ </section> <section id="taskcontrollers"> - <title>Task controllers</title> - <para>At creation of a task instance, the task controllers can populate the task instance variables - and when the task instance is finished, the task controller can submit the data of the - task instance into the process variables. + <title> + Task Controllers + </title> + + <para> + When task instances are created, one can use task controllers + populate the task instance variables. When the task instances + terminate, one can use task controllers to submit the data + belonging to them to the process variables. </para> - <para>Note that you are not forced to use task controllers. Task instances also are able - to 'see' the process variables related to its token. Use task controllers when you want - to: + +<note> + <para> + Use of task controllers is optional. Task instances also are + able to "see" the process variables related to its token. Use + task controllers to undertake these tasks: </para> + <itemizedlist> - <listitem><para>a) create copies of variables in the task instances so that intermediate updates - to the task instance variables don't affect the process variables untill the process - is finished and the copies are submitted back into the process variables.</para> + <listitem><para>create copies of task instance variabless so that + intermediate updates to them do not affect the + process variables until the process is finished. At + this time, the copies are submitted back into the + process variables.</para> </listitem> - <listitem><para>b) the task instance variables do not relate one-on-one with the process variables. - E.g. suppose the process has variables 'sales in januari' 'sales in februari' and 'sales in march'. - Then the form for the task instance might need to show the average sales in the 3 months.</para> + <listitem><para>the task instance variables do not have a one-to-one + relationship with the process variables. For + instance, if the process has variables named + <literal>sales in January</literal> <literal>sales in + February</literal> and <literal>sales in + March</literal>, then the task instance form might + need to show the average sales for those three + months.</para> </listitem> </itemizedlist> - <para>Tasks are intended to collect input from users. But there are many user interfaces - which could be used to present the tasks to the users. E.g. a web application, a swing application, - an instant messenger, an email form,... So the task controllers make the bridge between the - process variables (=process context) and the user interface application. The task controllers - provide a view of process variables to the user interface application. +</note> + + <para> + Tasks collect input from users. But there are many user + interfaces which could be used to present the tasks to the + users. E.g. a web application, a swing application, an instant + messenger, an email form,... So the task controllers make the + bridge between the process variables (=process context) and the + user interface application. The task controllers provide a view + of process variables to the user interface application. </para> - <para>The task controller makes the translation (if any) from the process variables to the - task variables. When a task instance is created, the task controller is responsible for extracting - information from the process variables and creating the task variables. The task variables serve - as the input for the user interface form. And the user input can be stored in the task variables. - When the user ends the task, the task controller is responsible for updating the process - variables based on the task instance data. + + <para> + When a task instance is created, the task controller translates + process variables, if there are any, into task variables. The + task variables serve as the input for the user interface form. + The user input itself is stored in the task variables. When the + user ends the task, the task controller updates the process + variables based on the task instance data. </para> + <figure id="task.controllers.image"> <title>The task controllers</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/task.controllers.jpg"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata fileref="images/task.controllers.png"/></imageobject></mediaobject> </figure> - <para>In a simple scenario, there is a one-on-one mapping between process variables and the - form parameters. Task controllers are specified in a task element. - In this case, the default jBPM task controller can be used and it takes a list of - <literal>variable</literal> elements inside. The variable elements express - how the process variables are copied in the task variables. + + <para> + In a simple scenario, there is a one-on-one mapping between + process variables and the form parameters. Specify task + controllers in a task element. In this case, the default JBPM + task controller can be used. It takes a list of + <systemitem>variable</systemitem> elementswhich express how the + process variables are copied in the task variables. </para> - <para>The next example shows how you can create separate task instance variable copies - based on the process variables: + <para> + The next example demonstrates how to create separate copies of + task instance variable, based on the process variables: </para> - <programlisting>&lt;task name=&quot;clean ceiling&quot;&gt; - &lt;controller&gt; - &lt;variable name=&quot;a&quot; access=&quot;read&quot; mapped-name=&quot;x&quot; /&gt; - &lt;variable name=&quot;b&quot; access=&quot;read,write,required&quot; mapped-name=&quot;y&quot; /&gt; - &lt;variable name=&quot;c&quot; access=&quot;read,write&quot; /&gt; - &lt;/controller&gt; -&lt;/task&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/taskmgmt_1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para>The <literal>name</literal> attribute refers to the name of the process variable. - The <literal>mapped-name</literal> is optional and refers to the name of the task instance - variable. If the mapped-name attribute is omitted, mapped-name defaults to the name. - Note that the mapped-name also is used as the label for the fields in the task instance - form of the web application. + <para> + The <property>name</property> attribute refers to the name of + the process variable. The <property>mapped-name</property> is + optional and refers to the name of the task instance variable. + If the <property>mapped-name</property> attribute is omitted, + <property>mapped-name</property> defaults to the name. Note + that the <property>mapped-name</property> is also used as the + label for the fields in the web application's task instance + form. </para> <para> - The <literal>access</literal> attribute specifies if the variable is copied at task instance - creation, will be written back to the process variables at task end and wether it is - required. This information can be used by the user interface to generate the proper - form controls. The access attribute is optional and the default - access is 'read,write'. + Use the <property>access</property> attribute to specify as to + whether or not the variable copied at task instance creation, will + be written back to the process variables at task instance + conclusion. (This information can be used by the user interface to + generate the proper form controls.) The <property>access</property> + attribute is optional and the default access is + <code>read,write</code>. </para> - <para>A <literal>task-node</literal> can have many tasks and a <literal>start-state</literal> can have - 1 task. + <para> + A <systemitem>task-node</systemitem> can have many tasks whilst a + <systemitem>start-state</systemitem> has one task. </para> - <para>If the simple one-to-one mapping between process variables and form parameters is too limiting, you - can also write your own TaskControllerHandler implementation. Here's the TaskControllerHandler interface: + <para> + If the simple one-to-one mapping between process variables and + form parameters is too limiting, create a custom + <classname>TaskControllerHandler</classname> implementation. + Here is the interface for it:. </para> - <programlisting>public interface TaskControllerHandler extends Serializable { - void initializeTaskVariables(TaskInstance taskInstance, ContextInstance contextInstance, Token token); - void submitTaskVariables(TaskInstance taskInstance, ContextInstance contextInstance, Token token); -}</programlisting> + <programlisting language="Java"><xi:include href="extras/taskmgmt_2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <para> + This code sample demonstrates how to configure it: + </para> - <para>And here's how to configure your custom task controller implementation in a task:</para> - - <programlisting>&lt;task name=&quot;clean ceiling&quot;&gt; - &lt;controller class=&quot;com.yourcom.CleanCeilingTaskControllerHandler&quot;&gt; - -- here goes your task controller handler configuration -- - &lt;/controller&gt; -&lt;/task&gt;</programlisting> + <programlisting language="XML"><xi:include href="extras/taskmgmt_2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> <section id="swimlanes"> - <title>Swimlanes</title> - <para>A swimlane is a process role. It is a mechanism to specify that - multiple tasks in the process should be done by the same actor. So - after the first task instance is created for a given swimlane, the actor - should be remembered in the process for all subsequent tasks that are in - the same swimlane. A swimlane therefore has one - <literal>assignment</literal> (<xref linkend="assignment" />) - and all tasks that reference a swimlane should not specify an - <literal>assignment</literal>(<xref linkend="assignment" />). - </para> + <title> + Swimlanes + </title> - <para>When the first task in a given swimlane is created, the - <literal>AssignmentHandler</literal> of the swimlane is called. - The <literal>Assignable</literal> that is passed to the <literal>AssignmentHandler</literal> - will be the <literal>SwimlaneInstance</literal>. Important to know is that - all assignments that are done on the task instances in a given swimlane will - propagate to the swimlane instance. This behaviour is implemented as the default - because the person that takes a task to fulfilling a certain process role will - have the knowledge of that perticular process. So all subsequent assignements - of task instances to that swimlane are done automatically to that user. + <para> + A <firstterm>swimlane</firstterm> is a process role. Use this + mechanism to specify that multiple tasks in the process are to + be be undertaken by the same actor. After the first task + instance for a given swimlane is created, the actor is + "remembered" for every subsequent task in the same swimlane. A + swimlane therefore has one <systemitem>assignment</systemitem>. + Study <xref linkend="assignment"/> to learn more. </para> + + <para> + When the first task in a given swimlane is created, the + <systemitem>AssignmentHandler</systemitem> is called. The + <systemitem>Assignable</systemitem> item that is passed to the + <systemitem>AssignmentHandler</systemitem> is + <systemitem>SwimlaneInstance</systemitem>. Every assignment + undertaken on the task instances in a given swimlane will + propagate to the swimlane instance. This is the default + behaviour because the person that takes a task will have a + knowledge of that particular process. Hence, ever subsequent + task instances in that swimlane is automatically assigned to + that user. + </para> - <para>Swimlane is a terminology borrowed from UML activity diagrams. - </para> + </section> <section id="swimlaneinstarttask"> - <title>Swimlane in start task</title> - <para>A swimlane can be associated with the start task to capture the process - initiator.</para> - <para>A task can be specified in a start-state. That task be associated with a - swimlane. When a new task instance is created for such a task, the current - authenticated actor will be captured with - Authentication.getAuthenticatedActorId() (<xref linkend="authentication" />) - and that actor will be stored in the swimlane of the start task. + <title> + Swimlane in Start Task + </title> + + <para> + It is possible to associate a swimlane with the start task. One + does this to capture the process initiator. </para> - <para>For example:</para> - <programlisting>&lt;process-definition&gt; - &lt;swimlane name='initiator' /&gt; - &lt;start-state&gt; - &lt;task swimlane='initiator' /&gt; - &lt;transition to='...' /&gt; - &lt;/start-state&gt; - ... -&lt;/process-definition&gt;</programlisting> - <para>Also variables can be added to the start task as with any other task to - define the form associated with the task. See <xref linkend="taskcontrollers"/></para> + + <para> + A task can be specified in a start-state, which will associate + it with a swimlane. When a new task instance is created, the + current authenticated actor is captured via the + <methodname>Authentication.getAuthenticatedActorId()</methodname> + method. The actor is stored in the start task's swimlane. + </para> + + <programlisting language="XML"><xi:include href="extras/taskmgmt_3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + + <para> + Add variables to the start task using the normal method. Do so + to define the form associated with the task. See <xref + linkend="taskcontrollers"/> for more information. + </para> </section> <section id="taskevents"> - <title>Task events</title> - <para>Tasks can have actions associated with them. There are 4 standard event types defined - for tasks: <literal>task-create</literal>, - <literal>task-assign</literal>, <literal>task-start</literal> and <literal>task-end</literal>.</para> - <para><literal>task-create</literal> is fired when a task instance is created.</para> - <para><literal>task-assign</literal> is fired when a task instance is being assigned. - Note that in actions that are executed on this event, you can access the previous - actor with <literal>executionContext.getTaskInstance().getPreviousActorId();</literal> + <title> + Task Events + </title> + + <para> + One can associate actions with tasks. There are four standard event + types: </para> - <para><literal>task-start</literal> is fired when <literal>TaskInstance.start()</literal> - is called. This can be used to indicate that the user is actually starting to work on this - task instance. Starting a task is optional.</para> - <para><literal>task-end</literal> is fired when <literal>TaskInstance.end(...)</literal> - is called. This marks the completion of the task. If the task is related to a process - execution, this call might trigger the resuming of the process execution. + +<orderedlist> + <listitem> + <para> + <systemitem>task-create</systemitem>, which is fired when a + task instance is created. + </para> + </listitem> + <listitem> + <para> + <systemitem>task-assign</systemitem>, which is fired when a + task instance is being assigned. Note that in actions that are + executed on this event, one can access the previous actor with + the + <methodname>executionContext.getTaskInstance().getPreviousActorId();</methodname> + method. + </para> + </listitem> + <listitem> + <para> + <systemitem>task-start</systemitem>, which is fired when the + <methodname>TaskInstance.start()</methodname> method is called. + Use this optional feature to indicate that the user is actually + starting work on the task instance. + </para> + </listitem> + <listitem> + <para> + <systemitem>task-end</systemitem>, which is fired when + <methodname>TaskInstance.end(...)</methodname> is called. This + marks the completion of the task. If the task is related to a + process execution, this call might trigger the resumption of + the process execution. + </para> + </listitem> +</orderedlist> + +<note> + <para> + Exception handlers can be associated with tasks, For more + information about this, read <xref linkend="exceptionhandling" + />. </para> - <para>Since tasks can have events and actions associated with them, also - exception handlers can be specified on a task. For more information about exception - handling, see <xref linkend="exceptionhandling" />.</para> +</note> </section> <section id="tasktimers"> - <title>Task timers</title> - <para>As on nodes, timers can be specified on tasks. See <xref linkend="timers" />.</para> - <para>The special thing about timers for tasks is that the <literal>cancel-event</literal> - for task timers can be customized. By default, a timer on a task will be cancelled when - the task is ended (=completed). But with the <literal>cancel-event</literal> attribute - on the timer, process developers can customize that to e.g. <literal>task-assign</literal> - or <literal>task-start</literal>. The <literal>cancel-event</literal> supports multiple - events. The <literal>cancel-event</literal> types can be combined by specifying them in a - comma separated list in the attribute.</para> + <title> + Task Timers + </title> + + <para> + One can specify timers on tasks. See <xref linkend="timers" />. + </para> + + <para> + It is possible to customise <property>cancel-event</property> + for task timers. By default, a task timer cancels when the task + is ended but with the <property>cancel-event</property> + attribute on the timer, one can customise that to + <property>task-assign</property> or + <property>task-start</property>. The + <property>cancel-event</property> supports multiple events. To + combine <property>cancel-event</property> types, specify them + in a comma-separated list in the attribute. + </para> + </section> <section id="customizingtaskinstances"> - <title>Customizing task instances</title> - <para>Task instances can be customized. The easiest way to do this is - to create a subclass of <literal>TaskInstance</literal>. Then create a - <literal>org.jbpm.taskmgmt.TaskInstanceFactory</literal> implementation and - configure it by setting the configuration property <literal>jbpm.task.instance.factory</literal> - to the fully qualified class name in the jbpm.cfg.xml. If you use a subclass of - TaskInstance, also create a hibernate - mapping file for the subclass (using the hibernate - <literal>extends="org.jbpm.taskmgmt.exe.TaskInstance"</literal>). Then - add that mapping file to the list of mapping files in the - <literal>hibernate.cfg.xml</literal></para> + <title> + Customizing Task Instances + </title> + + <para> + To customise a task instance, follow these steps: + </para> + +<orderedlist> + <listitem> + <para> + create a sub-class of <systemitem>TaskInstance</systemitem> + </para> + </listitem> + <listitem> + <para> + create a + <classname>org.jbpm.taskmgmt.TaskInstanceFactory</classname> + implementation + </para> + </listitem> + <listitem> + <para> + configure the implementation by setting the + <property>jbpm.task.instance.factory</property> configuration + property to the fully qualified class name in the + <filename>jbpm.cfg.xml</filename> file. + </para> + </listitem> + <listitem> + <para> + if using a sub-class of <systemitem>TaskInstance</systemitem>, + create a <application>Hibernate</application> mapping file for + the sub-class (using + <code>extends="org.jbpm.taskmgmt.exe.TaskInstance"</code> + </para> + </listitem> + <listitem> + <para> + add that mapping file to the list in + <filename>hibernate.cfg.xml</filename>. + </para> + </listitem> +</orderedlist> + + </section> <section id="theidentitycomponent"> - <title>The identity component</title> - <para>Management of users, groups and permissions is commonly known - as identity management. jBPM includes an optional identity component - that can be easily replaced by a company's own identity data store. + <title> + The Identity Component + </title> + + <para> + Management of users, groups and permissions is termed + <firstterm>identity management</firstterm>. The jBPM includes + an optional identity component. One can easily replace it with + one's company's own data store. </para> - <para>The jBPM identity management component - includes knowledge of the organisational model. - Task assignment is typically done with organisational knowledge. - So this implies knowledge of an organisational model, describing the - users, groups, systems and the relations between them. Optionally, - permissions and roles can be included too in an organisational model. - Various academic research attempts failed, proving that no generic - organisational model can be created that fits every organisation. + <para> + The jBPM identity management component holds knowledge of the + organisational model and uses this to assign tasks. This model + describes the users, groups, systems and the relationships + between these. Optionally, permissions and roles can also be + included. </para> - <para>The way jBPM handles this is by defining an actor as an actual - participant in a process. An actor is identified by its ID called an - actorId. jBPM has only knowledge about actorId's and they are represented - as <literal>java.lang.String</literal>s for maximum flexibility. So any - knowledge about the organisational model and the structure of that data - is outside the scope of the jBPM core engine.</para> - <para>As an extension to jBPM we will provide (in the future) a component - to manage that simple user-roles model. This many to many relation between - users and roles is the same model as is defined in the J2EE and the servlet - specs and it could serve as a starting point in new developments. People - interested in contributing should check the jboss jbpm jira issue tracker - for more details.</para> + <para> + The jBPM handles this by defining an actor as an actual + participant in a process. An actor is identified by its ID + called an actorId. The jBPM has only knowledge about actorIds and + they are represented as + <systemitem>java.lang.String</systemitem>s for maximum + flexibility. So any knowledge about the organizational model + and the structure of that data is outside the scope of the jBPM's + core engine. + </para> + + + <para>As an extension to jBPM we will + provide (in the future) a component to manage that simple + user-roles model. This many to many relation between users and + roles is the same model as is defined in the J2EE and the + servlet specs and it could serve as a starting point in new + developments. + </para> <para>Note that the user-roles model as it is used in the servlet, ejb and portlet specifications, is not sufficiently powerful for handling task assignments. That model is a many-to-many relation between users and roles. This doesn't include information about the teams and - the organisational structure of users involved in a process.</para> + the organizational structure of users involved in a process.</para> <section id="theidentitymodel"> <title>The identity model</title> <figure id="identity.model.image"> <title>The identity model class diagram</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/identity.model.gif"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata fileref="images/identity.model.png"/></imageobject></mediaobject> </figure> - <para>The classes in yellow are the relevant classes for the expression - assignment handler that is discussed next.</para> + <para> + The classes in yellow are those which pertain to the expression + assignment handler discussed next. + </para> - <para>A <literal>User</literal> represents a user or a service. A - <literal>Group</literal> is any kind of group of users. + <para>A <systemitem>User</systemitem> represents a user or a service. A + <systemitem>Group</systemitem> is any kind of group of users. Groups can be nested to model the relation between a team, a business unit and the whole company. Groups have a type to differentiate between the hierarchical groups and e.g. - haircolor groups. <literal>Membership</literal>s represent the + hair color groups. <systemitem>Membership</systemitem>s represent the many-to-many relation between users and groups. A membership can be used to represent a position in a company. The name of the membership - can be used to indicate the role that the user fullfills in the + can be used to indicate the role that the user fulfills in the group.</para> </section> @@ -571,70 +932,46 @@ expression for the calculation of actors during assignment of tasks. Here's an example of using the assignment expression in a process definition:</para> - <programlisting>&lt;process-definition&gt; - ... - &lt;task-node name='a'&gt; - &lt;task name='laundry'&gt; - &lt;assignment expression='previous --> group(hierarchy) --> member(boss)' /&gt; - &lt;/task&gt; - &lt;transition to='b' /&gt; - &lt;/task-node&gt; - ...</programlisting> - - <para>Syntax of the assignment expression is like this:</para> - <programlisting>first-term --> next-term --> next-term --> ... --> next-term + <programlisting language="XML"><xi:include href="extras/taskmgmt_4.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -where - -first-term ::= previous | - swimlane(swimlane-name) | - variable(variable-name) | - user(user-name) | - group(group-name) - -and - -next-term ::= group(group-type) | - member(role-name) -</programlisting> <section id="firstterms"> <title>First terms</title> <para>An expression is resolved from left to right. The first-term specifies - a <literal>User</literal> or <literal>Group</literal> in the identity model. + a <systemitem>User</systemitem> or <systemitem>Group</systemitem> in the identity model. Subsequent terms calculate the next term from the intermediate user or group.</para> - <para><literal>previous</literal> means the task is assigned to the current + <para><systemitem>previous</systemitem> means the task is assigned to the current authenticated actor. This means the actor that performed the previous step in the process.</para> - <para><literal>swimlane(swimlane-name)</literal> means the user or group is taken + <para><systemitem>swimlane(swimlane-name)</systemitem> means the user or group is taken from the specified swimlane instance.</para> - <para><literal>variable(variable-name)</literal> means the user or group is taken + <para><systemitem>variable(variable-name)</systemitem> means the user or group is taken from the specified variable instance. The variable instance can contain a - <literal>java.lang.String</literal>, in which case that user or group is fetched from - the identity component. Or the variable instance contains a <literal>User</literal> - or <literal>Group</literal> object. </para> + <systemitem>java.lang.String</systemitem>, in which case that user or group is fetched from + the identity component. Or the variable instance contains a <systemitem>User</systemitem> + or <systemitem>Group</systemitem> object. </para> - <para><literal>user(user-name)</literal> means the given user is taken from the + <para><systemitem>user(user-name)</systemitem> means the given user is taken from the identity component.</para> - <para><literal>group(group-name)</literal> means the given group is taken from the + <para><systemitem>group(group-name)</systemitem> means the given group is taken from the identity component.</para> </section> <section id="nextterms"> <title>Next terms</title> - <para><literal>group(group-type)</literal> gets the group for a user. Meaning that - previous terms must have resulted in a <literal>User</literal>. It searches for the + <para><systemitem>group(group-type)</systemitem> gets the group for a user. Meaning that + previous terms must have resulted in a <systemitem>User</systemitem>. It searches for the the group with the given group-type in all the memberships for the user.</para> - <para><literal>member(role-name)</literal> gets the user that performs a given role - for a group. The previous terms must have resulted in a <literal>Group</literal>. + <para><systemitem>member(role-name)</systemitem> gets the user that performs a given role + for a group. The previous terms must have resulted in a <systemitem>Group</systemitem>. This term searches for the user with a membership to the group for which the name of the membership matches the given role-name.</para> </section> @@ -643,22 +980,23 @@ <section id="removingtheidentitycomponent"> <title>Removing the identity component</title> - <para>When you want to use your own datasource for organisational - information such as your company's user database or ldap system, - you can just rip out the jBPM identity component. The only thing - you need to do is make sure that you delete the line ...</para> - <programlisting>&lt;mapping resource="org/jbpm/identity/User.hbm.xml"/&gt; -&lt;mapping resource="org/jbpm/identity/Group.hbm.xml"/&gt; -&lt;mapping resource="org/jbpm/identity/Membership.hbm.xml"/&gt;</programlisting> + <para>When you want to use your own datasource for organizational + information such as your company's user database or LDAP system, + you can remove the jBPM identity component. The only thing + you need to do is make sure that you delete the following line + from the <filename>hibernate.cfg.xml</filename>.</para> + + <programlisting language="XML"><xi:include href="extras/taskmgmt_5.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para>from the <literal>hibernate.cfg.xml</literal> </para> - <para>The <literal>ExpressionAssignmentHandler</literal> is dependent on the identity + <para>The <systemitem>ExpressionAssignmentHandler</systemitem> is dependent on the identity component so you will not be able to use it as is. In case you want - to reuse the <literal>ExpressionAssignmentHandler</literal> and bind it to your user data - store, you can extend from the <literal>ExpressionAssignmentHandler</literal> and override - the method <literal>getExpressionSession</literal>. + to reuse the <systemitem>ExpressionAssignmentHandler</systemitem> and bind it to your user data + store, you can extend from the <systemitem>ExpressionAssignmentHandler</systemitem> and override + the method <systemitem>getExpressionSession</systemitem>. </para> - <programlisting>protected ExpressionSession getExpressionSession(AssignmentContext assignmentContext);</programlisting> + + <programlisting language="Java"><xi:include href="extras/taskmgmt_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> </section> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/tdd.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/tdd.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/tdd.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -5,136 +5,119 @@ ]> <chapter id="tdd"> - <title>TDD for workflow</title> + <title> + Test Driven Development for Workflow + </title> <section id="intoducingtddforworkflow"> - <title>Introducing TDD for workflow</title> - <para>Since developing process oriented software is no different from - developing any other software, we believe that process definitions should - be easily testable. This chapter shows how you can use plain JUnit without - any extensions to unit test the process definitions that you author.</para> + <title> + Introducing Test Driven Development for Workflow + </title> - <para>The development cycle should be kept as short as possible. Changes - made to the sources of software should be immediately verifiable. Preferably, - without any intermediate build steps. The examples given below will show - you how to develop and test jBPM processes without intermediate steps.</para> + <para> + Since developing process-oriented programs is no different from + developing any other software, Red Hat believes that one should + be able to test process definitions easily. Read this chapter + to learn how to use <application>JUnit</application> without + any extensions to unit test custom process definitions. + </para> - <para>Mostly the unit tests of process definitions are execution scenarios. - Each scenario is executed in one JUnit testmethod and will feed in the external - triggers (read: signals) into a process execution and verifies after each signal - if the process is in the expected state.</para> + <para> + Keep the development cycle as short as possible. Verify all + changes to software source code immediately, (preferably, + without any intermediate build steps.) The following examples + demonstrate how to develop and test jBPM processes in this way. + </para> - <para>Let's look at an example of such a test. We take a simplified version of - the auction process with the following graphical representation:</para> + <para> + Most process definition unit tests are execution-based. Each + scenario is executed in one JUnit test method and this feeds the + external triggers (signals) into a process execution. It then + verifies after each signal to confirm that the process is in the + expected state. + </para> + <para> + Here is an example graphical representation of such a test. It + takes a simplified version of the auction process: + </para> + <figure id="auction.test.image"> <title>The auction test process</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/auction.test.gif"/></imageobject></mediaobject> + <mediaobject><imageobject><imagedata fileref="images/auction.test.png"/></imageobject></mediaobject> </figure> - <para>Now, let's write a test that executes the main scenario:</para> + <para> + Next, write a test that executes the main scenario: + </para> - <programlisting>public class AuctionTest extends TestCase { + <programlisting language="Java"><xi:include href="extras/tdd_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - // parse the process definition - static ProcessDefinition auctionProcess = - ProcessDefinition.parseParResource("org/jbpm/tdd/auction.par"); - // get the nodes for easy asserting - static StartState start = auctionProcess.getStartState(); - static State auction = (State) auctionProcess.getNode("auction"); - static EndState end = (EndState) auctionProcess.getNode("end"); - - // the process instance - ProcessInstance processInstance; - - // the main path of execution - Token token; - - public void setUp() { - // create a new process instance for the given process definition - processInstance = new ProcessInstance(auctionProcess); - - // the main path of execution is the root token - token = processInstance.getRootToken(); - } - - public void testMainScenario() { - // after process instance creation, the main path of - // execution is positioned in the start state. - assertSame(start, token.getNode()); - - token.signal(); - - // after the signal, the main path of execution has - // moved to the auction state - assertSame(auction, token.getNode()); - - token.signal(); - - // after the signal, the main path of execution has - // moved to the end state and the process has ended - assertSame(end, token.getNode()); - assertTrue(processInstance.hasEnded()); - } -}</programlisting> - </section> <section id="xmlsources"> - <title>XML sources</title> - <para>Before you can start writing execution scenario's, you need a - <literal>ProcessDefinition</literal>. The easiest way to get a - <literal>ProcessDefinition</literal> object is by parsing xml. If you - have code completion, type <literal>ProcessDefinition.parse</literal> - and activate code completion. Then you get the various parsing methods. - There are basically 3 ways to write xml that can be parsed to a - <literal>ProcessDefinition</literal> object:</para> + <title> + XML Sources + </title> + <para> + Before writing execution scenarios, one must compose a + <systemitem>ProcessDefinition</systemitem>. The easiest way to obtain + a <systemitem>ProcessDefinition</systemitem> object is by parsing + XML. With code completion switched on, type + <code>ProcessDefinition.parse</code>. + The various parsing methods will be displayed. There are + three ways in which to write XML that can be parsed to a + <systemitem>ProcessDefinition</systemitem> object: + </para> + <section id="parsingaprocessarchive"> - <title>Parsing a process archive</title> - <para>A process archive is a zip file that contains the process xml - in a file called <literal>processdefinition.xml</literal>. The jBPM - process designer reads and writes process archives. For example:</para> + <title> + Parsing a Process Archive + </title> - <programlisting>... -static ProcessDefinition auctionProcess = - ProcessDefinition.parseParResource("org/jbpm/tdd/auction.par"); -...</programlisting> + <para> + A <firstterm>process archive</firstterm> is a ZIP file that + contains the process XML file, namely + <filename>processdefinition.xml</filename>. The + <application>jBPM Process Designer</application> plug-in reads and + writes process archives. + </para> + + <programlisting language="Java"><xi:include href="extras/tdd_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> <section id="parsinganxmlfile"> - <title>Parsing an xml file</title> - <para>In other situations, you might want to write the - processdefinition.xml file by hand and later package the zip file - with e.g. an ant script. In that case, you can use the - <literal>JpdlXmlReader</literal></para> + <title> + Parsing an XML File + </title> + + <para> + To write the <filename>processdefinition.xml</filename> file by + hand, use the <classname>JpdlXmlReader</classname>. Use an + <command>ant</command> script to package the resulting ZIP + file. + </para> - <programlisting>... -static ProcessDefinition auctionProcess = - ProcessDefinition.parseXmlResource("org/jbpm/tdd/auction.xml"); -...</programlisting> + <programlisting language="Java"><xi:include href="extras/tdd_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> <section id="parsinganxmlstring"> - <title>Parsing an xml String</title> - <para>The simplest option is to parse the xml in the unit test - inline from a plain String.</para> + <title> + Parsing an XML String + </title> - <programlisting>... -static ProcessDefinition auctionProcess = - ProcessDefinition.parseXmlString( - "&lt;process-definition>" + - " &lt;start-state name='start'&gt;" + - " &lt;transition to='auction'/&gt;" + - " &lt;/start-state&gt;" + - " &lt;state name='auction'&gt;" + - " &lt;transition to='end'/&gt;" + - " &lt;/state&gt;" + - " &lt;end-state name='end'/&gt;" + - "&lt;/process-definition&gt;"); -...</programlisting> + <para> + Parse the XML in the unit test inline + from a plain string: + </para> + + <programlisting language="Java"><xi:include href="extras/tdd_2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </section> </section> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/tutorial.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/tutorial.xml 2010-08-07 21:45:37 UTC (rev 6551) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en-US/tutorial.xml 2010-08-09 00:42:27 UTC (rev 6552) @@ -54,64 +54,11 @@ </para> <figure id="hello.world.image"> - <title>The hello world process graph</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/hello.world.gif"/></imageobject></mediaobject> + <title>The Hello World Process Graph</title> + <mediaobject><imageobject><imagedata fileref="images/hello.world.png"/></imageobject></mediaobject> </figure> - <programlisting>public void testHelloWorldProcess() { - <emphasis role="bold">// This method shows a process definition and one execution</emphasis> - <emphasis role="bold">// of the process definition. The process definition has </emphasis> - <emphasis role="bold">// 3 nodes: an unnamed start-state, a state 's' and an </emphasis> - <emphasis role="bold">// end-state named 'end'.</emphasis> - <emphasis role="bold">// The next line parses a piece of xml text into a</emphasis> - <emphasis role="bold">// ProcessDefinition. A ProcessDefinition is the formal </emphasis> - <emphasis role="bold">// description of a process represented as a java object.</emphasis> - ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - &quot;<emphasis role="bold">&lt;process-definition&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;start-state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;transition to='s' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/start-state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;state name='s'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;transition to='end' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;end-state name='end' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold">&lt;/process-definition&gt;</emphasis>&quot; - ); - - <emphasis role="bold">// The next line creates one execution of the process definition.</emphasis> - <emphasis role="bold">// After construction, the process execution has one main path</emphasis> - <emphasis role="bold">// of execution (=the root token) that is positioned in the</emphasis> - <emphasis role="bold">// start-state.</emphasis> - ProcessInstance processInstance = - new ProcessInstance(processDefinition); - - <emphasis role="bold">// After construction, the process execution has one main path</emphasis> - <emphasis role="bold">// of execution (=the root token).</emphasis> - Token token = processInstance.getRootToken(); - - <emphasis role="bold">// Also after construction, the main path of execution is positioned</emphasis> - <emphasis role="bold">// in the start-state of the process definition.</emphasis> - assertSame(processDefinition.getStartState(), token.getNode()); - - <emphasis role="bold">// Let's start the process execution, leaving the start-state </emphasis> - <emphasis role="bold">// over its default transition.</emphasis> - token.signal(); - <emphasis role="bold">// The signal method will block until the process execution </emphasis> - <emphasis role="bold">// enters a wait state.</emphasis> - - <emphasis role="bold">// The process execution will have entered the first wait state</emphasis> - <emphasis role="bold">// in state 's'. So the main path of execution is now </emphasis> - <emphasis role="bold">// positioned in state 's'</emphasis> - assertSame(processDefinition.getNode("s"), token.getNode()); - - <emphasis role="bold">// Let's send another signal. This will resume execution by </emphasis> - <emphasis role="bold">// leaving the state 's' over its default transition.</emphasis> - token.signal(); - <emphasis role="bold">// Now the signal method returned because the process instance </emphasis> - <emphasis role="bold">// has arrived in the end-state.</emphasis> - - assertSame(processDefinition.getNode("end"), token.getNode()); -}</programlisting> + <programlisting language="Java"><xi:include href="extras/code_example_tutorial_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include&g... </section> <section id="databaseexample"> @@ -141,198 +88,8 @@ </para> </note> - <programlisting>public class HelloWorldDbTest extends TestCase { +<programlisting language="Java"><xi:include href="extras/tutorial_7.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - static JbpmConfiguration jbpmConfiguration = null; - - static { - <emphasis role="bold">// An example configuration file such as this can be found in </emphasis> - <emphasis role="bold">// 'src/config.files'. Typically the configuration information is in the </emphasis> - <emphasis role="bold">// resource file 'jbpm.cfg.xml', but here we pass in the configuration </emphasis> - <emphasis role="bold">// information as an XML string.</emphasis> - - <emphasis role="bold">// First we create a JbpmConfiguration statically. One JbpmConfiguration</emphasis> - <emphasis role="bold">// can be used for all threads in the system, that is why we can safely </emphasis> - <emphasis role="bold">// make it static.</emphasis> - - jbpmConfiguration = JbpmConfiguration.parseXmlString( - "&lt;jbpm-configuration&gt;" + - - <emphasis role="bold">// A jbpm-context mechanism separates the jbpm core </emphasis> - <emphasis role="bold">// engine from the services that jbpm uses from </emphasis> - <emphasis role="bold">// the environment. </emphasis> - - " &lt;jbpm-context&gt;" + - " &lt;service name='persistence' " + - " factory='org.jbpm.persistence.db.DbPersistenceServiceFactory' /&gt;" + - " &lt;/jbpm-context&gt;" + - - <emphasis role="bold">// Also all the resource files that are used by jbpm are </emphasis> - <emphasis role="bold">// referenced from the jbpm.cfg.xml</emphasis> - - " &lt;string name='resource.hibernate.cfg.xml' " + - " value='hibernate.cfg.xml' /&gt;" + - " &lt;string name='resource.business.calendar' " + - " value='org/jbpm/calendar/jbpm.business.calendar.properties' /&gt;" + - " &lt;string name='resource.default.modules' " + - " value='org/jbpm/graph/def/jbpm.default.modules.properties' /&gt;" + - " &lt;string name='resource.converter' " + - " value='org/jbpm/db/hibernate/jbpm.converter.properties' /&gt;" + - " &lt;string name='resource.action.types' " + - " value='org/jbpm/graph/action/action.types.xml' /&gt;" + - " &lt;string name='resource.node.types' " + - " value='org/jbpm/graph/node/node.types.xml' /&gt;" + - " &lt;string name='resource.varmapping' " + - " value='org/jbpm/context/exe/jbpm.varmapping.xml' /&gt;" + - "&lt;/jbpm-configuration&gt;" - ); - } - - public void setUp() { - jbpmConfiguration.createSchema(); - } - - public void tearDown() { - jbpmConfiguration.dropSchema(); - } - - public void testSimplePersistence() { - <emphasis role="bold">// Between the 3 method calls below, all data is passed via the </emphasis> - <emphasis role="bold">// database. Here, in this unit test, these 3 methods are executed</emphasis> - <emphasis role="bold">// right after each other because we want to test a complete process</emphasis> - <emphasis role="bold">// scenario. But in reality, these methods represent different </emphasis> - <emphasis role="bold">// requests to a server.</emphasis> - - <emphasis role="bold">// Since we start with a clean, empty in-memory database, we have to </emphasis> - <emphasis role="bold">// deploy the process first. In reality, this is done once by the </emphasis> - <emphasis role="bold">// process developer.</emphasis> - deployProcessDefinition(); - - <emphasis role="bold">// Suppose we want to start a process instance (=process execution)</emphasis> - <emphasis role="bold">// when a user submits a form in a web application...</emphasis> - processInstanceIsCreatedWhenUserSubmitsWebappForm(); - - <emphasis role="bold">// Then, later, upon the arrival of an asynchronous message the </emphasis> - <emphasis role="bold">// execution must continue.</emphasis> - theProcessInstanceContinuesWhenAnAsyncMessageIsReceived(); - } - - public void deployProcessDefinition() { - <emphasis role="bold">// This test shows a process definition and one execution </emphasis> - <emphasis role="bold">// of the process definition. The process definition has </emphasis> - <emphasis role="bold">// 3 nodes: an unnamed start-state, a state 's' and an </emphasis> - <emphasis role="bold">// end-state named 'end'.</emphasis> - ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - "&lt;process-definition name='hello world'&gt;" + - " &lt;start-state name='start'&gt;" + - " &lt;transition to='s' /&gt;" + - " &lt;/start-state&gt;" + - " &lt;state name='s'&gt;" + - " &lt;transition to='end' /&gt;" + - " &lt;/state&gt;" + - " &lt;end-state name='end' /&gt;" + - "&lt;/process-definition&gt;" - ); - - <emphasis role="bold">// Lookup the pojo persistence context-builder that is configured above</emphasis> - JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); - try { - <emphasis role="bold">// Deploy the process definition in the database </emphasis> - jbpmContext.deployProcessDefinition(processDefinition); - - } finally { - <emphasis role="bold">// Tear down the pojo persistence context.</emphasis> - <emphasis role="bold">// This includes flush the SQL for inserting the process definition </emphasis> - <emphasis role="bold">// to the database.</emphasis> - jbpmContext.close(); - } - } - - public void processInstanceIsCreatedWhenUserSubmitsWebappForm() { - <emphasis role="bold">// The code in this method could be inside a struts-action </emphasis> - <emphasis role="bold">// or a JSF managed bean. </emphasis> - - <emphasis role="bold">// Lookup the pojo persistence context-builder that is configured above</emphasis> - JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); - try { - - GraphSession graphSession = jbpmContext.getGraphSession(); - - ProcessDefinition processDefinition = - graphSession.findLatestProcessDefinition("hello world"); - - <emphasis role="bold">// With the processDefinition that we retrieved from the database, we </emphasis> - <emphasis role="bold">// can create an execution of the process definition just like in the </emphasis> - <emphasis role="bold">// hello world example (which was without persistence).</emphasis> - ProcessInstance processInstance = - new ProcessInstance(processDefinition); - - Token token = processInstance.getRootToken(); - assertEquals("start", token.getNode().getName()); - <emphasis role="bold">// Let's start the process execution</emphasis> - token.signal(); - <emphasis role="bold">// Now the process is in the state 's'.</emphasis> - assertEquals("s", token.getNode().getName()); - - <emphasis role="bold">// Now the processInstance is saved in the database. So the - <emphasis role="bold">// current state of the execution of the process is stored in the </emphasis></emphasis> - <emphasis role="bold">// database. </emphasis> - jbpmContext.save(processInstance); - <emphasis role="bold">// The method below will get the process instance back out </emphasis> - <emphasis role="bold">// of the database and resume execution by providing another </emphasis> - <emphasis role="bold">// external signal.</emphasis> - - } finally { - <emphasis role="bold">// Tear down the pojo persistence context.</emphasis> - jbpmContext.close(); - } - } - - public void theProcessInstanceContinuesWhenAnAsyncMessageIsReceived() { - <emphasis role="bold">// The code in this method could be the content of a message driven bean.</emphasis> - - <emphasis role="bold">// Lookup the pojo persistence context-builder that is configured above</emphasis> - JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext(); - try { - - GraphSession graphSession = jbpmContext.getGraphSession(); - <emphasis role="bold">// First, we need to get the process instance back out of the database.</emphasis> - <emphasis role="bold">// There are several options to know what process instance we are dealing </emphasis> - <emphasis role="bold">// with here. The easiest in this simple test case is just to look for </emphasis> - <emphasis role="bold">// the full list of process instances. That should give us only one </emphasis> - <emphasis role="bold">// result. So let's look up the process definition.</emphasis> - - ProcessDefinition processDefinition = - graphSession.findLatestProcessDefinition("hello world"); - - <emphasis role="bold">// Now, we search for all process instances of this process definition.</emphasis> - List processInstances = - graphSession.findProcessInstances(processDefinition.getId()); - - <emphasis role="bold">// Because we know that in the context of this unit test, there is </emphasis> - <emphasis role="bold">// only one execution. In real life, the processInstanceId can be </emphasis> - <emphasis role="bold">// extracted from the content of the message that arrived or from </emphasis> - <emphasis role="bold">// the user making a choice.</emphasis> - ProcessInstance processInstance = - (ProcessInstance) processInstances.get(0); - - <emphasis role="bold">// Now we can continue the execution. Note that the processInstance</emphasis> - <emphasis role="bold">// delegates signals to the main path of execution (=the root token).</emphasis> - processInstance.signal(); - - <emphasis role="bold">// After this signal, we know the process execution should have </emphasis> - <emphasis role="bold">// arrived in the end-state.</emphasis> - assertTrue(processInstance.hasEnded()); - - <emphasis role="bold">// Now we can update the state of the execution in the database</emphasis> - jbpmContext.save(processInstance); - - } finally { - <emphasis role="bold">// Tear down the pojo persistence context.</emphasis> - jbpmContext.close(); - } - } -}</programlisting> </section> <section> @@ -340,7 +97,7 @@ Contextual Example: Process Variables </title> - <para> + <para> Whilst processes are executed, the context information is held in <firstterm>process variables</firstterm>. These are similar to <classname>java.util.Map</classname> classes, in that they map variable @@ -362,48 +119,8 @@ </para> </note> - <programlisting><emphasis role="bold">// This example also starts from the hello world process.</emphasis> -<emphasis role="bold">// This time even without modification.</emphasis> -ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - &quot;&lt;process-definition&gt;&quot; + - &quot; &lt;start-state&gt;&quot; + - &quot; &lt;transition to='s' /&gt;&quot; + - &quot; &lt;/start-state&gt;&quot; + - &quot; &lt;state name='s'&gt;&quot; + - &quot; &lt;transition to='end' /&gt;&quot; + - &quot; &lt;/state&gt;&quot; + - &quot; &lt;end-state name='end' /&gt;&quot; + - &quot;&lt;/process-definition&gt;&quot; -); + <programlisting language="Java"><xi:include href="extras/tutorial_1.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -ProcessInstance processInstance = - new ProcessInstance(processDefinition); - -<emphasis role="bold">// Fetch the context instance from the process instance </emphasis> -<emphasis role="bold">// for working with the process variables.</emphasis> -ContextInstance contextInstance = - processInstance.getContextInstance(); - -<emphasis role="bold">// Before the process has left the start-state, </emphasis> -<emphasis role="bold">// we are going to set some process variables in the </emphasis> -<emphasis role="bold">// context of the process instance.</emphasis> -contextInstance.setVariable("amount", new Integer(500)); -contextInstance.setVariable("reason", "i met my deadline"); - -<emphasis role="bold">// From now on, these variables are associated with the </emphasis> -<emphasis role="bold">// process instance. The process variables are now accessible </emphasis> -<emphasis role="bold">// by user code via the API shown here, but also in the actions </emphasis> -<emphasis role="bold">// and node implementations. The process variables are also </emphasis> -<emphasis role="bold">// stored into the database as a part of the process instance.</emphasis> - -processInstance.signal(); - -<emphasis role="bold">// The variables are accessible via the contextInstance. </emphasis> - -assertEquals(new Integer(500), - contextInstance.getVariable("amount")); -assertEquals("i met my deadline", - contextInstance.getVariable("reason"));</programlisting> </section> <section id="taskassignmentexample"> @@ -420,67 +137,8 @@ it to include the calculation of actors for tasks. </para> - <programlisting>public void testTaskAssignment() { - <emphasis role="bold">// The process shown below is based on the hello world process.</emphasis> - <emphasis role="bold">// The state node is replaced by a task-node. The task-node </emphasis> - <emphasis role="bold">// is a node in JPDL that represents a wait state and generates </emphasis> - <emphasis role="bold">// task(s) to be completed before the process can continue to </emphasis> - <emphasis role="bold">// execute. </emphasis> - ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - &quot;<emphasis role="bold">&lt;process-definition name='the baby process'&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;start-state&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;transition name='baby cries' to='t' /&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;/start-state&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;task-node name='t'&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;task name='change nappy'&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;assignment class='org.jbpm.tutorial.taskmgmt.NappyAssignmentHandler' /&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;/task&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;transition to='end' /&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;/task-node&gt;&quot;</emphasis> + - &quot;<emphasis role="bold"> &lt;end-state name='end' /&gt;&quot;</emphasis> + - &quot;<emphasis role="bold">&lt;/process-definition&gt;&quot;</emphasis> - ); - - <emphasis role="bold">// Create an execution of the process definition.</emphasis> - ProcessInstance processInstance = - new ProcessInstance(processDefinition); - Token token = processInstance.getRootToken(); - - <emphasis role="bold">// Let's start the process execution, leaving the start-state </emphasis> - <emphasis role="bold">// over its default transition.</emphasis> - token.signal(); - <emphasis role="bold">// The signal method will block until the process execution </emphasis> - <emphasis role="bold">// enters a wait state. In this case, that is the task-node.</emphasis> - assertSame(processDefinition.getNode("t"), token.getNode()); + <programlisting language="Java"><xi:include href="extras/tutorial_2.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <emphasis role="bold">// When execution arrived in the task-node, a task 'change nappy'</emphasis> - <emphasis role="bold">// was created and the NappyAssignmentHandler was called to determine</emphasis> - <emphasis role="bold">// to whom the task should be assigned. The NappyAssignmentHandler </emphasis> - <emphasis role="bold">// returned 'papa'.</emphasis> - - <emphasis role="bold">// In a real environment, the tasks would be fetched from the</emphasis> - <emphasis role="bold">// database with the methods in the org.jbpm.db.TaskMgmtSession.</emphasis> - <emphasis role="bold">// Since we don't want to include the persistence complexity in </emphasis> - <emphasis role="bold">// this example, we just take the first task-instance of this </emphasis> - <emphasis role="bold">// process instance (we know there is only one in this test</emphasis> - <emphasis role="bold">// scenario).</emphasis> - TaskInstance taskInstance = (TaskInstance) - processInstance - .getTaskMgmtInstance() - .getTaskInstances() - .iterator().next(); - - <emphasis role="bold">// Now, we check if the taskInstance was actually assigned to 'papa'.</emphasis> - assertEquals("papa", taskInstance.getActorId() ); - - <emphasis role="bold">// Now we suppose that 'papa' has done his duties and mark the task </emphasis> - <emphasis role="bold">// as done. </emphasis> - taskInstance.end(); - <emphasis role="bold">// Since this was the last (only) task to do, the completion of this</emphasis> - <emphasis role="bold">// task triggered the continuation of the process instance execution.</emphasis> - - assertSame(processDefinition.getNode("end"), token.getNode()); -}</programlisting> </section> <section id="customactionexample"> @@ -512,87 +170,26 @@ <para> More information about "actions" can be found in <xref linkend="actions" /> </para> -</note> +</note> - <programlisting><emphasis role="bold">// MyActionHandler represents a class that could execute </emphasis> -<emphasis role="bold">// some user code during the execution of a jBPM process.</emphasis> -public class MyActionHandler implements ActionHandler { - - <emphasis role="bold">// Before each test (in the setUp), the isExecuted member </emphasis> - <emphasis role="bold">// will be set to false.</emphasis> - public static boolean isExecuted = false; - - <emphasis role="bold">// The action will set the isExecuted to true so the </emphasis> - <emphasis role="bold">// unit test will be able to show when the action</emphasis> - <emphasis role="bold">// is being executed.</emphasis> - public void execute(ExecutionContext executionContext) { - isExecuted = true; - } -}</programlisting> - - <important> + <programlisting language="Java"><xi:include href="extras/tutorial_3.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + + <important> <para> Prior to each test, set the static field <classname>MyActionHandler.isExecuted</classname> to <code>false</code>. </para> </important> - - <programlisting> <emphasis role="bold">// Each test will start with setting the static isExecuted </emphasis> - <emphasis role="bold">// member of MyActionHandler to false.</emphasis> - public void setUp() { - MyActionHandler.isExecuted = false; - }</programlisting> + + <programlisting language="Java"><xi:include href="extras/tutorial_4.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <para> The first example illustrates an action on a transition: </para> - <programlisting>public void testTransitionAction() { - <emphasis role="bold">// The next process is a variant of the hello world process.</emphasis> - <emphasis role="bold">// We have added an action on the transition from state 's' </emphasis> - <emphasis role="bold">// to the end-state. The purpose of this test is to show </emphasis> - <emphasis role="bold">// how easy it is to integrate java code in a jBPM process.</emphasis> - ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - &quot;<emphasis role="bold">&lt;process-definition&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;start-state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;transition to='s' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/start-state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;state name='s'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;transition to='end'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/transition&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/state&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;end-state name='end' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold">&lt;/process-definition&gt;</emphasis>&quot; - ); - - <emphasis role="bold">// Let's start a new execution for the process definition.</emphasis> - ProcessInstance processInstance = - new ProcessInstance(processDefinition); - - <emphasis role="bold">// The next signal will cause the execution to leave the start </emphasis> - <emphasis role="bold">// state and enter the state 's'</emphasis> - processInstance.signal(); + <programlisting language="Java"><xi:include href="extras/tutorial_5.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <emphasis role="bold">// Here we show that MyActionHandler was not yet executed. </emphasis> - assertFalse(MyActionHandler.isExecuted); - <emphasis role="bold">// ... and that the main path of execution is positioned in </emphasis> - <emphasis role="bold">// the state 's'</emphasis> - assertSame(processDefinition.getNode("s"), - processInstance.getRootToken().getNode()); - - <emphasis role="bold">// The next signal will trigger the execution of the root </emphasis> - <emphasis role="bold">// token. The token will take the transition with the</emphasis> - <emphasis role="bold">// action and the action will be executed during the </emphasis> - <emphasis role="bold">// call to the signal method.</emphasis> - processInstance.signal(); - - <emphasis role="bold">// Here we can see that MyActionHandler was executed during </emphasis> - <emphasis role="bold">// the call to the signal method.</emphasis> - assertTrue(MyActionHandler.isExecuted); - }</programlisting> - <para> The next example shows the same action now being placed on both the <systemitem>enter-node</systemitem> and @@ -603,45 +200,7 @@ element. </para> - - <programlisting>ProcessDefinition processDefinition = ProcessDefinition.parseXmlString( - &quot;&lt;process-definition&gt;&quot; + - &quot; &lt;start-state&gt;&quot; + - &quot; &lt;transition to='s' /&gt;&quot; + - &quot; &lt;/start-state&gt;&quot; + - &quot; &lt;state name='s'&gt;&quot; + - &quot;<emphasis role="bold"> &lt;event type='node-enter'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/event&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;event type='node-leave'&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;action class='org.jbpm.tutorial.action.MyActionHandler' /&gt;</emphasis>&quot; + - &quot;<emphasis role="bold"> &lt;/event&gt;</emphasis>&quot; + - &quot; &lt;transition to='end'/&gt;&quot; + - &quot; &lt;/state&gt;&quot; + - &quot; &lt;end-state name='end' /&gt;&quot; + - &quot;&lt;/process-definition&gt;&quot; -); - -ProcessInstance processInstance = - new ProcessInstance(processDefinition); - -assertFalse(MyActionHandler.isExecuted); -<emphasis role="bold">// The next signal will cause the execution to leave the start </emphasis> -<emphasis role="bold">// state and enter the state 's'. So the state 's' is entered </emphasis> -<emphasis role="bold">// and hence the action is executed. </emphasis> -processInstance.signal(); -assertTrue(MyActionHandler.isExecuted); - -<emphasis role="bold">// Let's reset the MyActionHandler.isExecuted </emphasis> -MyActionHandler.isExecuted = false; - -<emphasis role="bold">// The next signal will trigger execution to leave the </emphasis> -<emphasis role="bold">// state 's'. So the action will be executed again. </emphasis> -processInstance.signal(); -<emphasis role="bold">// Voila. </emphasis> -assertTrue(MyActionHandler.isExecuted); -</programlisting> - + <programlisting language="Java"><xi:include href="extras/tutorial_6.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> </section>