[jbpm-commits] JBoss JBPM SVN: r5201 - in jbpm4/trunk/modules/devguide/src/main/docbook/en: modules and 1 other directory.

do-not-reply at jboss.org do-not-reply at jboss.org
Thu Jul 2 19:37:21 EDT 2009


Author: jbarrez
Date: 2009-07-02 19:37:21 -0400 (Thu, 02 Jul 2009)
New Revision: 5201

Added:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml
Removed:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-Jpdl3Migration.xml
Modified:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml
Log:
JBPM-2362: added documentation for Spring integration to dev guide

Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml	2009-07-02 22:47:21 UTC (rev 5200)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml	2009-07-02 23:37:21 UTC (rev 5201)
@@ -14,7 +14,8 @@
   <!ENTITY ch11-SoftwareLogging                SYSTEM "modules/ch11-SoftwareLogging.xml">
   <!ENTITY ch12-History                        SYSTEM "modules/ch12-History.xml">
   <!ENTITY ch13-JBossIntegration               SYSTEM "modules/ch13-JBossIntegration.xml">
-  <!ENTITY ch14-Jpdl3Migration               SYSTEM "modules/ch14-Jpdl3Migration.xml">
+  <!ENTITY ch14-SpringIntegration              	SYSTEM "modules/ch14-SpringIntegration.xml">
+  <!ENTITY ch15-Jpdl3Migration               	SYSTEM "modules/ch15-Jpdl3Migration.xml">
 ]>
 
 <book lang="en">
@@ -38,6 +39,7 @@
   &ch11-SoftwareLogging;
   &ch12-History;
   &ch13-JBossIntegration;
-  &ch14-Jpdl3Migration;
+  &ch14-SpringIntegration;
+  &ch15-Jpdl3Migration;
 
 </book>
\ No newline at end of file

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-Jpdl3Migration.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-Jpdl3Migration.xml	2009-07-02 22:47:21 UTC (rev 5200)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-Jpdl3Migration.xml	2009-07-02 23:37:21 UTC (rev 5201)
@@ -1,84 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="jpdl3Migration">
-  <title>JPDL3 migration</title>
-  
-  <para>
-	In many cases, a lot of work has been put in the design of JPDL3 process
-	definitions. To avoid a complete manual translation of these processes to the
-	JPDL4 format, the jBPM distribution contains a subdirectory called
-	<emphasis role="bold">migration</emphasis>, which contains a command-line
-	tool for converting JPDL3 process definition files to JPDL process XML files.
-  </para>
-  
-  <para>
-	The tool itself uses only dom4j to do the translation between
-	the two formats and should be easy extensible (the source code is also in
-	the same directory). The design of the tool is deliberately kept very simple
-	(ie most of the logic can be found in the <emphasis role="bold">Jpdl3Converter</emphasis> class).
-	Note that this tool is experimental and tested only a small set of JPDL3 
-	process files. 
-  </para>
-
-  <section id="migration_overview">
-    <title>Overview</title>
-    <para>
-		The jPDL Conversion tool takes a jpdl3 process file as input, and 
-		converts it to a jpdl4 process file.
-	</para>
-	<para>		
-		Syntax:
-		<programlisting>java org.jbpm.jpdl.internal.convert.JpdlConverterTool -v -o &lt;outputfile&gt; &lt;processfile&gt;</programlisting>
-	</para>
-  </section>
-  
-  <section id="migration_arguments">
-  	<title>Arguments</title>
-  	<itemizedlist>
-	    <listitem>
-	      <emphasis role="bold">-v (verbose):</emphasis> The tool will print the detail 
-	      messages while converting the process file. When this argument is used,
-	       it will also print the error stacktrace if exceptions are thrown.
-	    </listitem>
-	    <listitem>
-	      <emphasis role="bold">-o (output)</emphasis> Specifies the output file name.
-	      By default, the tool will generate a file name ending in 'converted.jpdl.xml' 
-	      using as a base file name the name derived from the input process file.
-	      The output-filename can be an absolute file name path or a relative file name path.
-	    </listitem>
-	  </itemizedlist>
-  </section>
-  
-  <section id="migration_examples">
-  	<title>Usage examples</title>
-  	<programlisting>
-  		java -jar jpdl-migration-XX.jar simple.jpdl.xml
-		java -jar jpdl-migration-XX.jar -v simple.jpdl.xml
-		java -jar jpdl-migration-XX.jar -o /home/scott/simple.converted.xml simple.jpdl.xml   
-  	</programlisting>
-  </section>
-  
-  <section id="migration_integration">
-  	<title>Advanced</title>
-  	<para>
-  		The conversion tool can easily be integrated with regular Java code
-  		(or with Maven or Ant). The following code example shows how to call the
-  		internal api to convert the process file:
-  		<programlisting>
-	URL url = new URL(&quot;simple.jpdl&quot;);
-	Jpdl3ConverterReader jpdlConverter = new Jpdl3ConverterReader(url);
-	Document jpdl4Doc = jpdlConverter.readAndConvert();
-
-	for (Problem problem : jpdlConverter.problems) {
-	   //do something to handle the problem
-	}
-
-	Writer fileWriter = new FileWriter(outputFile);
-	OutputFormat format = OutputFormat.createPrettyPrint();
-	XMLWriter writer = new XMLWriter( fileWriter, format );
-	writer.write(jpdl4Doc);
-	writer.close();
-  		</programlisting>
-  	</para>
-  </section>
-  
-</chapter>

Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-SpringIntegration.xml	2009-07-02 23:37:21 UTC (rev 5201)
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="springIntegration">
+  <title>Spring Integration</title>
+  
+  <para>
+  	The embeddability of the jBPM engine in different environments has always
+  	been one of its core strengths, but often extra libraries to do the integration
+  	were required. Since jBPM4 however, it is now possible to natively
+  	integrate jBPM with <ulink url="http://www.springsource.org/about">Spring</ulink>.
+  	This section will explain which steps are required for such an integration.
+  </para>
+  
+  <para>
+  	The Spring integration has started out as a community effort by
+  	<ulink url="http://www.inze.be/andries/">Andries Inz&#233;</ulink>.
+  	Do note that Spring integration currently is in 'incubation', before
+  	it is moved to the user guide.
+  </para>
+
+  <section id="spring_overview">
+    <title>Overview</title>
+    <para>
+		The default jBPM behaviour is to open a transaction for each operation
+		that is called on the service API. In a typical Spring setup, applications are 
+		accessed from the web tier and enter a transactional boundary by invoking
+		operations on service beans. These service beans will then access the jBPM services. 
+		All these operations run typically in a single transaction (ie one transaction
+		per request from the browser), which invalidates the standard jBPM 
+		transaction handling approach. Instead of starting and committing
+		a transaction for every service operation, the existing transaction
+		should be used (or a new one started if none exists).
+    </para>
+  </section>
+  
+  <section id="spring_configuration">
+  	<title>Configuration</title>
+    <para>
+		Replace the standard-transaction-interceptor with the 
+		spring-transaction-interceptor. The hibernate session needs the attribute current=”true”. 
+		This forces jBPM to search for the current session, 
+		which will be provided by Spring.
+		<programlisting>
+	&lt;process-engine-context&gt;
+	    &lt;command-service&gt;
+	      <emphasis role="bold">&lt;spring-transaction-interceptor current=&quot;true&quot; /&gt;</emphasis>
+	      ...
+	    &lt;/command-service&gt;
+	    ...
+	&lt;/process-engine-context&gt;
+	&lt;transaction-context&gt;
+	    ...
+		<emphasis role="bold">&lt;hibernate-session current=&quot;true&quot;/&gt;</emphasis>
+	&lt;/transaction-context&gt;
+		</programlisting>
+	</para>
+	
+	<para>
+		The Spring integration provides a special context, which is added to
+		the set of context where the jBPM engine will look for beans.
+		Using this SpringContext, it is now possible to retrieve beans from the 
+		Spring Application Context. For the Spring context to be known, a 
+		SpringConfiguration must be created. This class extends the JbpmConfiguration 
+		but will add itself as a context. The single constructor take the location of the jBPM configuration.
+		
+		<programlisting>
+	&lt;bean id=&quot;jbpmConfiguration&quot; class=&quot;org.jbpm.pvm.internal.cfg.SpringConfiguration&quot;&gt;
+   		&lt;constructor-arg value=&quot;be/inze/spring/demo/jbpm.cfg.xml&quot; /&gt;
+	&lt;/bean&gt;
+		</programlisting>
+	</para>	
+	
+	<para>
+		The jBPM services can also be defined in the Spring applicationContext, as following:
+		<programlisting>
+&lt;bean id=&quot;processEngine&quot; factory-bean=&quot;jbpmConfiguration&quot; factory-method=&quot;buildProcessEngine&quot; /&gt;
+&lt;bean id=&quot;repositoryService&quot; factory-bean=&quot;processEngine&quot; factory-method=&quot;getRepositoryService&quot; /&gt;
+&lt;bean id=&quot;executionService&quot; factory-bean=&quot;processEngine&quot; factory-method=&quot;getExecutionService&quot; /&gt;
+		</programlisting>
+	</para>
+
+	<para>
+		For accessing Spring beans from withing a process, we need to register 
+		the Spring applicationContext with the scripting-manager.
+		
+		<programlisting>
+	&lt;script-manager default-expression-language=&quot;juel&quot;
+	 default-script-language=&quot;juel&quot;
+	 read-contexts=&quot;execution, environment, process-engine, <emphasis role="bold">spring</emphasis>&quot;
+	 write-context=&quot;&quot;&gt;
+	 &lt;script-language name=&quot;juel&quot;
+	 factory=&quot;org.jbpm.pvm.internal.script.JuelScriptEngineFactory&quot; /&gt;
+	 &lt;/script-manager&gt;		
+		</programlisting>	
+    </para>
+  </section>
+  
+  <section id="spring_usage">
+  	<title>Usage</title>
+  	
+  	<para>
+  		The previous section already showed how the jBPM services can be made
+  		accessible for other Spring services. The other use case is calling
+  		Spring beans from within a process. This can be done by using
+  		an expression which resolves to the name of a Spring bean.
+  		
+  		<programlisting>
+&lt;java name=&quot;echo&quot; expr=&quot;#{echoService}&quot; method=&quot;sayHello&quot; &gt;
+    &lt;transition name=&quot;to accept&quot; to=&quot;join1&quot;/&gt;
+ &lt;/java&gt;
+  		</programlisting>
+  		
+  		The scripting engine will look into all contexts from the bean named echoService. 
+  		If you configured the ScriptManager as above, Spring will be the last context to search for.
+  		 A good practice is to use unique names for the beans.
+  	</para>
+  	
+  </section>
+  
+  <section id="spring_testing">
+  	<title>Testing</title>
+  	
+  	<para>
+  		Use the <emphasis role="bold">AbstractTransactionalJbpmTestCase</emphasis> 
+  		to test a process in isolation (ie without impact on the database).
+  		This class extends from
+  		the <emphasis role="italic">AbstractTransactionalDataSourceSpringContextTests</emphasis>
+  		class, which means that testing a process comes down to exactly the same
+  		approach as testing a DAO.
+  	</para>
+  
+  </section>
+    
+    
+  
+</chapter>

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml (from rev 5200, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch14-Jpdl3Migration.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch15-Jpdl3Migration.xml	2009-07-02 23:37:21 UTC (rev 5201)
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="jpdl3Migration">
+  <title>JPDL3 migration</title>
+  
+  <para>
+	In many cases, a lot of work has been put in the design of JPDL3 process
+	definitions. To avoid a complete manual translation of these processes to the
+	JPDL4 format, the jBPM distribution contains a subdirectory called
+	<emphasis role="bold">migration</emphasis>, which contains a command-line
+	tool for converting JPDL3 process definition files to JPDL process XML files.
+  </para>
+  
+  <para>
+	The tool itself uses only dom4j to do the translation between
+	the two formats and should be easy extensible (the source code is also in
+	the same directory). The design of the tool is deliberately kept very simple
+	(ie most of the logic can be found in the <emphasis role="bold">Jpdl3Converter</emphasis> class).
+	Note that this tool is experimental and tested only a small set of JPDL3 
+	process files. 
+  </para>
+
+  <section id="migration_overview">
+    <title>Overview</title>
+    <para>
+		The jPDL Conversion tool takes a jpdl3 process file as input, and 
+		converts it to a jpdl4 process file.
+	</para>
+	<para>		
+		Syntax:
+		<programlisting>java org.jbpm.jpdl.internal.convert.JpdlConverterTool -v -o &lt;outputfile&gt; &lt;processfile&gt;</programlisting>
+	</para>
+  </section>
+  
+  <section id="migration_arguments">
+  	<title>Arguments</title>
+  	<itemizedlist>
+	    <listitem>
+	      <emphasis role="bold">-v (verbose):</emphasis> The tool will print the detail 
+	      messages while converting the process file. When this argument is used,
+	       it will also print the error stacktrace if exceptions are thrown.
+	    </listitem>
+	    <listitem>
+	      <emphasis role="bold">-o (output)</emphasis> Specifies the output file name.
+	      By default, the tool will generate a file name ending in 'converted.jpdl.xml' 
+	      using as a base file name the name derived from the input process file.
+	      The output-filename can be an absolute file name path or a relative file name path.
+	    </listitem>
+	  </itemizedlist>
+  </section>
+  
+  <section id="migration_examples">
+  	<title>Usage examples</title>
+  	<programlisting>
+  		java -jar jpdl-migration-XX.jar simple.jpdl.xml
+		java -jar jpdl-migration-XX.jar -v simple.jpdl.xml
+		java -jar jpdl-migration-XX.jar -o /home/scott/simple.converted.xml simple.jpdl.xml   
+  	</programlisting>
+  </section>
+  
+  <section id="migration_integration">
+  	<title>Advanced</title>
+  	<para>
+  		The conversion tool can easily be integrated with regular Java code
+  		(or with Maven or Ant). The following code example shows how to call the
+  		internal api to convert the process file:
+  		<programlisting>
+	URL url = new URL(&quot;simple.jpdl&quot;);
+	Jpdl3ConverterReader jpdlConverter = new Jpdl3ConverterReader(url);
+	Document jpdl4Doc = jpdlConverter.readAndConvert();
+
+	for (Problem problem : jpdlConverter.problems) {
+	   //do something to handle the problem
+	}
+
+	Writer fileWriter = new FileWriter(outputFile);
+	OutputFormat format = OutputFormat.createPrettyPrint();
+	XMLWriter writer = new XMLWriter( fileWriter, format );
+	writer.write(jpdl4Doc);
+	writer.close();
+  		</programlisting>
+  	</para>
+  </section>
+  
+</chapter>




More information about the jbpm-commits mailing list