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

do-not-reply at jboss.org do-not-reply at jboss.org
Thu May 7 16:20:08 EDT 2009


Author: tom.baeyens at jboss.com
Date: 2009-05-07 16:20:07 -0400 (Thu, 07 May 2009)
New Revision: 4765

Removed:
   jbpm4/trunk/modules/userguide/src/main/docbook/en/images/gpd.open.in.xml.png
Modified:
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch01-Introduction.xml
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch03-Gpd.xml
   jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-Services.xml
Log:
userguide updates explaining the new build scripts

Deleted: jbpm4/trunk/modules/userguide/src/main/docbook/en/images/gpd.open.in.xml.png
===================================================================
(Binary files differ)

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch01-Introduction.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch01-Introduction.xml	2009-05-07 20:19:13 UTC (rev 4764)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch01-Introduction.xml	2009-05-07 20:20:07 UTC (rev 4765)
@@ -51,48 +51,5 @@
     are not part of the support offerings. 
     </para>
   </section>
-  
-  <section id="processdefinitionprocessinstanceandexecutions">
-    <title>Process definition, process instance and executions</title>
-    <para>A process definition is description of the steps in a procedure.
-    For example, an insurance company could have a <literal>loan</literal> 
-    process definition that describes the steps of how the company deals 
-    with loan requests.
-    </para> 
-    <figure id="loan.process.definition.example">
-      <title>The loan process definition example</title>
-      <mediaobject><imageobject><imagedata align="center" fileref="images/loan.process.definition.png"/></imageobject></mediaobject>
-    </figure>
-    <para>One process instance represents one particular run of a process definition.
-    For example, the loan request of John Doe last Friday to finance his new boat 
-    is represented in one process instance of the loan process definition.
-    </para>
-    <para>A process instance contains all the runtime state.  The 
-    most prominent property is the pointer that keeps track of the current activity.
-    </para>
-    <figure id="loan.process.instance.example">
-      <title>The loan process instance example</title>
-      <mediaobject><imageobject><imagedata align="center" fileref="images/loan.process.instance.png"/></imageobject></mediaobject>
-    </figure>
-    <para>Suppose that wiring the money and archiving can be done in parallel.
-    Then the main process instance will have two child executions to keep 
-    track of the state like this:   
-    </para>
-    <figure id="loan.executions.example">
-      <title>The loan executions example</title>
-      <mediaobject><imageobject><imagedata align="center" fileref="images/loan.executions.png"/></imageobject></mediaobject>
-    </figure>
-    <para>More general, a process instance is the root of a tree of executions.
-    When a new process instance is started, the process instance is in fact the root 
-    execution scope.  Only leaf executions can be active.
-    </para>
-    <para>The motivation to work with a tree structure like this is that
-    this conceptually remains simple in the case where there is only one path 
-    of execution.  The services API doesn't need to make a functional difference 
-    between process instances and executions.  Therefore, the API has only 
-    one Execution type to refer to both <literal>ProcessInstance</literal>s and 
-    <literal>Execution</literal>s. 
-    </para>
-  </section>
 
 </chapter>

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml	2009-05-07 20:19:13 UTC (rev 4764)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml	2009-05-07 20:20:07 UTC (rev 4765)
@@ -2,78 +2,170 @@
   <title>Installation</title>
   
   <para>This chapter describes how to install jBPM in different 
-  application environments.
+    application environments.
   </para>
 
   <section id="thedistribution">
     <title>The distribution</title>
     <para>Just unzip the jBPM download to some location on your hard drive.
-    You'll see following subdirectories.
+    You'll see following subdirectories:
     </para>
+    <itemizedlist>
+      <listitem><literal>db</literal>: DB schema creation scripts</listitem>
+      <listitem><literal>doc</literal>: User guide, javadocs and developers guide</listitem>
+      <listitem><literal>examples</literal>: Example processes that are used in the user guide</listitem>
+      <listitem><literal>gpd</literal>: Graphical process designer plugin as an eclipse archived site</listitem>
+      <listitem><literal>jboss</literal>: JBoss installer to install jBPM into JBoss</listitem>
+      <listitem><literal>lib</literal>: Third party libs and some special jBPM libraries</listitem>
+      <listitem><literal>src</literal>: Sources</listitem>
+      <listitem><literal>jbpm.jar</literal>: The jBPM main library archive</listitem>
+    </itemizedlist>
   </section>
 
-  <section id="libraries">
-    <title>Libraries</title>
-    <para>The lib directory you'll find the jbpm libs and the third party libs. 
-    Including all the libraries in the lib directory, is the simplest way to get 
-    started.  To minimize the number of jars that you need to include, see 
-    the developers guide.
+  <section id="gettingstartedquickly">
+    <title>Getting started quickly</title>
+    <para>The <emphasis role="bold">demo setup</emphasis> is the simplest way to get started.
+    This section describes the steps to complete the demo setup.
     </para>
+    <para>If you have jboss-5.0.0.GA on locally on your machine, create a directory 
+    called <literal>downloads</literal> in your jBPM home directory and copy 
+    the jboss distribution zip file in there.  Same for an Eclipse Ganymede SR2 JEE distribution 
+    (eclipse-jee-ganymede-SR2-win32.zip).  If you have it already locally, copy it to 
+    the downloads directory.  If you don't have those files in that place, they will be downloaded 
+    automatically by the demo setup ant script.
+    </para>
+    <para>Open a command prompt and go do directory <literal>${jbpm.home}/jboss</literal>.  Then 
+    run
+    </para>
+    <programlisting>ant demo.setup</programlisting>
+    <para>That will</para>
+    <itemizedlist>
+      <listitem>Install JBoss into the <literal>${jbpm.home}/jboss-5.0.0.GA</literal> directory</listitem>
+      <listitem>Install jBPM into that JBoss installation.  By default, this includes a hypersonic 
+      database that is accessable over TCP/IP. 
+      </listitem>
+      <listitem>Start JBoss.  This will also start the hypersonic DB.</listitem>
+      <listitem>Create the DB Schema</listitem>
+      <listitem>Create an examples.bar business archive from the examples and deploy it to the jBPM DB.</listitem>
+      <listitem>Load the example users and groups from <literal>${jbpm.home}/db/example.identities.sql</literal> </listitem>
+      <listitem>Install eclipse into <literal>${jbpm.home}/eclipse</literal></listitem>
+      <listitem>Start eclipse</listitem>
+    </itemizedlist>
+    <para>Once this is done and eclipse has started, you can continue to follow the instructions
+    of <xref linkend="graphicalprocessdesigner" /> 
+    </para>
+    <para>And you can surf to <ulink url="http://localhost:8080/gwt-console">the jBPM console</ulink>
+    You can login as one of the following users:
+    </para>
+    <table><title>Example console users:</title>
+      <tgroup cols="2" rowsep="1" colsep="1">
+        <thead>
+          <row>
+            <entry>Username</entry>
+            <entry>Password</entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry>alex</entry>
+            <entry>password</entry>
+          </row>
+          <row>
+            <entry>mike</entry>
+            <entry>password</entry>
+          </row>
+          <row>
+            <entry>peter</entry>
+            <entry>password</entry>
+          </row>
+          <row>
+            <entry>mary</entry>
+            <entry>password</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
   </section>
-  
-  <section id="tomcat-xxx">
-    <title>Tomcat xxx</title>
-    <para>TODO: this will contain a description of how to use the 
-    installer to install jbpm on tomcat</para>
+
+  <section id="antscripts">
+    <title>Ant scripts</title>
+    <para>As you already saw one example in the demo setup, the distribution a couple of ant 
+    scripts:
+    </para>
+    <itemizedlist>
+      <listitem><literal>${jbpm.home}/jboss/build.xml</literal></listitem>
+      <listitem><literal>${jbpm.home}/db/build.xml</literal></listitem>
+      <listitem><literal>${jbpm.home}/gpd/build.xml</literal></listitem>
+      <listitem><literal>${jbpm.home}/examples/build.xml</literal></listitem>
+    </itemizedlist>
+    <para>With <literal>ant -p</literal> you can find out what each of these scripts can do.
+    </para>
+    <para>The scripts are parametrized with default values.  Following properties you might 
+    want to customize:
+    </para>
+    <itemizedlist>
+      <listitem><literal>database</literal> : Default value is <literal>hsqldb</literal>.  Alternative values 
+      are <literal>mysql</literal>, <literal>oracle</literal> and <literal>postgresql</literal></listitem>
+      <listitem><literal>jboss.version</literal> : Default value is <literal>5.0.0.GA</literal>.  Alternative 
+      value is <literal>5.0.1.GA</literal></listitem>
+    </itemizedlist>
+    <para>To customize the values for these properties, just use <literal>-D</literal> like this
+    </para>
+    <programlisting>ant -Ddatabase=postgresql demo.setup</programlisting>
+    <para>Or specify the customized values in <literal>${user.home}/.jbpm4/build.properties</literal> 
+    </para>
+    <para>To specify your jdbc properties that are used in the DB schema generation, direct DB access like 
+    deployment and for the JBoss datasource creation, the easiest is to update the appropriate
+    properties file in directory <literal>${jbpm.home}/db/jdbc</literal>.  The appropriate properties 
+    file will be loaded by the scripts that are DB related. 
+    </para>
   </section>
 
-  <section id="jboss-xxx">
-    <title>JBoss xxx</title>
-    <para>TODO: this will contain a description of how to use the 
-    installer to install jbpm on jboss</para>
+  <section id="jboss">
+    <title>JBoss</title>
+    <para>The build file <literal>${jbpm.home}/jboss/build.xml</literal> contains scripts for 
+    installing jBPM into JBoss 5.  Navigate to that directory and run <literal>ant -p</literal>
+    for more details.
+    </para>
   </section>
 
   <section id="database">
     <title>Database</title>
-    <para>jBPM works with your database of choice.  That way, jBPM's data 
-    tables can be placed next to your application tables in the same 
-    database.  In case you're working outside an application server 
-    you can combine your application updates with jBPM's process updates in a 
-    single transaction by using the same JDBC connection. 
+    <para>The build file <literal>${jbpm.home}/db/build.xml</literal> contains scripts for 
+    DB operations like creating and dropping the schema.  Navigate to that directory and run <literal>ant -p</literal>
+    for more details.
     </para>
-    <section>
-      <title>Creating the DB tables</title>
-      <para>In directory <literal>db</literal> the sql scripts to create 
-      the DB schema can be found for the supported databases.
-      </para>
-    </section>
   </section>
 
+  <section id="tomcat">
+    <title>Tomcat</title>
+    <para>TODO: this will contain a description of how to use the 
+    installer to install jbpm on tomcat</para>
+  </section>
+
   <section id="configurationfiles">
     <title>Configuration files</title>
-    <para>TODO
+    <para>If you're not deploying in JBoss, then the example configuration files 
+    in the examples <literal>src</literal> are the best starting point.  
     </para>
-    <para>In the meantime, see in the examples for a set of example 
-    configuration files.  Central file is jbpm.cfg.xml.  All other files 
-    are referenced from that file.
-    </para>
   </section>
 
   <section id="graphicalprocessdesigner">
     <title>Graphical Process Designer (GPD)</title>
     <para>Eclipse is used as the platform to host the jPDL graphical process
-    designer. This section will describe how to obtain Eclipse, install it
-    the GPD.</para>
+    designer. This section will describe how to obtain and install Eclipse and 
+    how to install the GPD plugin in Eclipse.</para>
     <section>
-      <title>Download Eclipse</title>
-      <para>You'll need Eclipse 3.4.1.
+      <title>Get Eclipse</title>
+      <para>You'll need Eclipse 3.4.2.
       </para>
-      <para>Download the    
-      <ulink url="http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/ganymede/SR1/eclipse-java-ganymede-SR1-win32.zip">Eclipse IDE for Java Developers (85 MB)</ulink> or
-      <ulink url="http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/ganymede/SR1/eclipse-jee-ganymede-SR1-win32.zip">Eclipse IDE for Java EE Developers (163 MB)</ulink>.
+      <para>Use the <link linkend="gettingstarted">demo setup</link> or download 
+      eclipse manually:      
+      <ulink url="http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/ganymede/SR2">Eclipse IDE for Java EE Developers (163 MB)</ulink>.
       </para>
       <para>The classic version of eclipse will not be sufficient as it does 
-      not have an XML editor.
+      not have an XML editor.  Eclipse for Java developers should also 
+      work.
       </para>
     </section>
     <section>
@@ -176,5 +268,18 @@
       </itemizedlist>
       <para>You're all set to start playing with the coolest Java process technology!</para>
     </section>
+
+    <section>
+      <title>Adding deployment with ant</title>
+      <para>You can leverage the eclipse ant integration to ease deployment of processes.
+      We'll show you how it works with the examples.  Then you can copy this practice in your 
+      own project.  First, open up the Ant view.  
+      </para>
+      <itemizedlist>
+        <listitem>Select <literal>Window</literal> --> <literal>Show View</literal> --> <literal>Other...</literal> --> <literal>Ant</literal> --> <literal>Ant</literal></listitem>
+        <listitem>Then drag the build file <literal>build.xml</literal> in the examples project from the package explorer to the Ant view</listitem>
+      </itemizedlist>
+    </section>
+
   </section>
 </chapter>
\ No newline at end of file

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch03-Gpd.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch03-Gpd.xml	2009-05-07 20:19:13 UTC (rev 4764)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch03-Gpd.xml	2009-05-07 20:20:07 UTC (rev 4765)
@@ -39,19 +39,6 @@
        <title>Editing jPDL using the source view</title>
       <mediaobject><imageobject><imagedata align="center" fileref="images/gpd.xml.view.png"/></imageobject></mediaobject>
     </figure>
-    <para>You can of course still edit the process XML sources using the built in XML editor. 
-    To do this, select the process file, right click
-    and select 'Open with...' --> 'XML editor'
-    </para>
-    <figure id="gpd.open.in.xml">
-      <title>Open a process file in XML editor</title>
-      <mediaobject><imageobject><imagedata align="center" fileref="images/gpd.open.in.xml.png"/></imageobject></mediaobject>
-    </figure>
-    <para>After you've done this, eclipse will remember that and the next time 
-    you double click it, eclipse will open your process file in the XML Editor 
-    automatically.  To open up the process file in the GPD, perform the 
-    same Open-with-action, but select 'jBPM jPDL 4 Editor'  
-    </para>
   </section>
   
 </chapter>

Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-Services.xml
===================================================================
--- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-Services.xml	2009-05-07 20:19:13 UTC (rev 4764)
+++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch04-Services.xml	2009-05-07 20:20:07 UTC (rev 4765)
@@ -1,14 +1,55 @@
 <chapter id="services">
   <title>Services</title>
   
-  <para>Interacting with jBPM occurs through services.
-  The service interfaces can be obtained from the <literal>ProcessEngine</literal>
-  which is build from a <literal>Configuration</literal>. 
-  </para>
-  
+  <section id="processdefinitionprocessinstanceandexecutions">
+    <title>Process definition, process instance and executions</title>
+    <para>A process definition is description of the steps in a procedure.
+    For example, an insurance company could have a <literal>loan</literal> 
+    process definition that describes the steps of how the company deals 
+    with loan requests.
+    </para> 
+    <figure id="loan.process.definition.example">
+      <title>The loan process definition example</title>
+      <mediaobject><imageobject><imagedata align="center" fileref="images/loan.process.definition.png"/></imageobject></mediaobject>
+    </figure>
+    <para>One process instance represents one particular run of a process definition.
+    For example, the loan request of John Doe last Friday to finance his new boat 
+    is represented in one process instance of the loan process definition.
+    </para>
+    <para>A process instance contains all the runtime state.  The 
+    most prominent property is the pointer that keeps track of the current activity.
+    </para>
+    <figure id="loan.process.instance.example">
+      <title>The loan process instance example</title>
+      <mediaobject><imageobject><imagedata align="center" fileref="images/loan.process.instance.png"/></imageobject></mediaobject>
+    </figure>
+    <para>Suppose that wiring the money and archiving can be done in parallel.
+    Then the main process instance will have two child executions to keep 
+    track of the state like this:   
+    </para>
+    <figure id="loan.executions.example">
+      <title>The loan executions example</title>
+      <mediaobject><imageobject><imagedata align="center" fileref="images/loan.executions.png"/></imageobject></mediaobject>
+    </figure>
+    <para>More general, a process instance is the root of a tree of executions.
+    When a new process instance is started, the process instance is in fact the root 
+    execution scope.  Only leaf executions can be active.
+    </para>
+    <para>The motivation to work with a tree structure like this is that
+    this conceptually remains simple in the case where there is only one path 
+    of execution.  The services API doesn't need to make a functional difference 
+    between process instances and executions.  Therefore, the API has only 
+    one Execution type to refer to both <literal>ProcessInstance</literal>s and 
+    <literal>Execution</literal>s. 
+    </para>
+  </section>
+
   <section id="processengine">
     <title>ProcessEngine</title>
-  
+    <para>Interacting with jBPM occurs through services.
+    The service interfaces can be obtained from the <literal>ProcessEngine</literal>
+    which is build from a <literal>Configuration</literal>.  
+    </para>
     <para>A <literal>ProcessEngine</literal> is thread safe and can be stored in a 
     static member field or even better in JNDI or some other central location.  
     One <literal>ProcessEngine</literal> object can be used by all requests and 




More information about the jbpm-commits mailing list