8:30 a.m.
Author: heiko.braun(a)jboss.com
Date: 2009-04-08 09:30:13 -0400 (Wed, 08 Apr 2009)
New Revision: 4500
Added:
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch09-JBossIntegration.xml
jbpm4/trunk/modules/userguide/userguide.iml
Modified:
jbpm4/trunk/modules/userguide/src/main/docbook/en/master.xml
Log:
Fix JBPM-2152: Document the JBoss integration
Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/master.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/master.xml 2009-04-08 12:33:28 UTC
(rev 4499)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/master.xml 2009-04-08 13:30:13 UTC
(rev 4500)
@@ -9,6 +9,7 @@
<!ENTITY ch06-Variables SYSTEM "modules/ch06-Variables.xml">
<!ENTITY ch07-Scripting SYSTEM "modules/ch07-Scripting.xml">
<!ENTITY ch08-Identity SYSTEM "modules/ch08-Identity.xml">
+ <!ENTITY ch08-JBossIntegration SYSTEM
"modules/ch09-JBossIntegration.xml">
]>
<book lang="en">
@@ -27,5 +28,6 @@
&ch06-Variables;
&ch07-Scripting;
&ch08-Identity;
+ &ch08-JBossIntegration;
</book>
\ No newline at end of file
Added:
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch09-JBossIntegration.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch09-JBossIntegration.xml
(rev 0)
+++
jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch09-JBossIntegration.xml 2009-04-08
13:30:13 UTC (rev 4500)
@@ -0,0 +1,140 @@
+<chapter id="identity">
+ <title>JBoss Integration</title>
+
+ <para>
+ jBPM provides integration with JBoss 4.2.x and JBoss 5.0.0.GA.
+ As part of the <link
linkend="runningtheinstaller">installation</link>, the ProcessEngine
and a deployer for jBPM archives
+ will be installed as a JBoss service.
+ </para>
+
+ <para>
+ After a successful installation you should see that the ProcessEngine
+ has been started and bound to JNDI:
+ </para>
+
+ <programlisting>
+ [...]
+ 14:12:09,301 INFO [JBPMService] jBPM 4 - Integration JBoss 4
+ 14:12:09,301 INFO [JBPMService] 4.0.0.Beta1
+ 14:12:09,301 INFO [JBPMService] ProcessEngine bound to: java:/ProcessEngine
+ </programlisting>
+
+ <section>
+ <title>Packaging process archives</title>
+ <para>
+ When jBPM is deployed on a JBoss instance, process deployments are treated like
+ any other deployment artifact (i.e. *.war, *.ear) and processed by the
JBPMDeployer.
+ In order to deploy a process archive simply create a *.jpdl archive (zip file) that
contains
+ the process definition (*.jpdl.xml) and all required resources to execute the
process (i.e. classes, property files):
+ </para>
+ <programlisting>
+ Bonanova:Desktop hbraun$ jar -tf OrderProcess.jpdl
+
+ META-INF/MANIFEST.MF
+ OrderProcess.jpdl.xml
+ org/mycompany/order/*.class
+ </programlisting>
+ </section>
+
+ <section>
+ <title>Deploying processes archives to a JBoss instance</title>
+ <para>
+ In order to deploy a process archive simply copy it to
$JBOSS_HOME/server/<config>/deploy:
+ </para>
+
+ <programlisting>
+ (1) cp OrderProcess.jpdl $JBOSS_HOME/server/default/deploy
+
+ (2) less $JBOSS_HOME/server/default/log
+ [...]
+ 2009-04-08 14:12:21,947 INFO [org.jbpm.integration.jboss4.JBPMDeployer]
+ Deploy file:/Users/hbraun/dev/prj/jboss/tags/JBoss_4_2_2_GA
+ /build/output/jboss-4.2.2.GA/server/default/deploy/OrderProcess.jpdl
+ </programlisting>
+
+ <para>
+ In order to remove a process simply remove the process archive from the deploy
directory.
+ </para>
+ </section>
+
+ <section>
+ <title>Process deployments and versioning</title>
+ <para>
+ TBD: A prelimenary explanation cn be found <ulink
url="http://relative-order.blogspot.com/2009/03/rfc-process-deployme...
+ </para>
+ </section>
+
+ <section>
+ <title>ProcessEngine and J2EE/JEE programming models</title>
+ <para>
+ As described above the ProcessEngine will be installed as JBoss service and bound
to JNDI.
+ This means that any EE component (i.e. servlet, ejb) can access it doing a JNDI
lookup:
+ </para>
+
+ <programlisting>
+ private ProcessEngine processEngine;
+ [...]
+
+ try
+ {
+ InitialContext ctx = new InitialContext();
+ this.processEngine = (ProcessEngine)ctx.lookup("java:/ProcessEngine");
+ }
+ catch (Exception e)
+ {
+ throw new RuntimeException("Failed to lookup process engine");
+ }
+ </programlisting>
+
+ <para>
+ Once you obtained an instance of the ProcessEngine you can invoke on it
+ as described in <link linkend="services">chapter
services</link>
+ </para>
+
+ <programlisting>
+ UserTransaction tx = (UserTransaction)ctx.lookup("UserTransaction");
(1)
+ Environment env = ((EnvironmentFactory)processEngine).openEnvironment();
+
+ try
+ {
+
+ ExecutionService execService = (ExecutionService)
+ this.processEngine.get(ExecutionService.class);
+
+ // begin transaction
+ tx.begin();
+
+ // invoke on process engine
+ executionService.signalExecutionById("ICL.82436");
+
+ // commit transaction
+ tx.commit();
+
+ }
+ catch (Exception e)
+ {
+ if(tx!=null)
+ {
+ try
+ {
+ tx.rollback();
+ }
+ catch (SystemException e1) {}
+ }
+
+ throw new RuntimeException("...", e);
+
+ }
+ finally
+ {
+ env.close();
+ }
+ </programlisting>
+
+ <para>
+ (1) Wrapping the call in a UserTransaction is not necessary if the invocation comes
a
+ CMT component, i.e. an EJB.
+ </para>
+ </section>
+
+</chapter>
Added: jbpm4/trunk/modules/userguide/userguide.iml
===================================================================
--- jbpm4/trunk/modules/userguide/userguide.iml (rev 0)
+++ jbpm4/trunk/modules/userguide/userguide.iml 2009-04-08 13:30:13 UTC (rev 4500)
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module version="4" relativePaths="true"
type="JAVA_MODULE">
+ <component name="ModuleRootManager" />
+ <component name="NewModuleRootManager"
inherit-compiler-output="true">
+ <exclude-output />
+ <content url="file://$MODULE_DIR$" />
+ <orderEntry type="inheritedJdk" />
+ <orderEntry type="sourceFolder" forTests="false" />
+ <orderEntryProperties />
+ </component>
+</module>
+