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>