[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 <outputfile> <processfile></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("simple.jpdl");
- 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é</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>
+ <process-engine-context>
+ <command-service>
+ <emphasis role="bold"><spring-transaction-interceptor current="true" /></emphasis>
+ ...
+ </command-service>
+ ...
+ </process-engine-context>
+ <transaction-context>
+ ...
+ <emphasis role="bold"><hibernate-session current="true"/></emphasis>
+ </transaction-context>
+ </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>
+ <bean id="jbpmConfiguration" class="org.jbpm.pvm.internal.cfg.SpringConfiguration">
+ <constructor-arg value="be/inze/spring/demo/jbpm.cfg.xml" />
+ </bean>
+ </programlisting>
+ </para>
+
+ <para>
+ The jBPM services can also be defined in the Spring applicationContext, as following:
+ <programlisting>
+<bean id="processEngine" factory-bean="jbpmConfiguration" factory-method="buildProcessEngine" />
+<bean id="repositoryService" factory-bean="processEngine" factory-method="getRepositoryService" />
+<bean id="executionService" factory-bean="processEngine" factory-method="getExecutionService" />
+ </programlisting>
+ </para>
+
+ <para>
+ For accessing Spring beans from withing a process, we need to register
+ the Spring applicationContext with the scripting-manager.
+
+ <programlisting>
+ <script-manager default-expression-language="juel"
+ default-script-language="juel"
+ read-contexts="execution, environment, process-engine, <emphasis role="bold">spring</emphasis>"
+ write-context="">
+ <script-language name="juel"
+ factory="org.jbpm.pvm.internal.script.JuelScriptEngineFactory" />
+ </script-manager>
+ </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>
+<java name="echo" expr="#{echoService}" method="sayHello" >
+ <transition name="to accept" to="join1"/>
+ </java>
+ </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 <outputfile> <processfile></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("simple.jpdl");
+ 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