[jbpm-commits] JBoss JBPM SVN: r2834 - in jbpm3/trunk/modules/userguide/src/main/docbook/en: images and 1 other directories.

Author: tom.baeyens(a)jboss.com Date: 2008-11-09 10:08:15 -0500 (Sun, 09 Nov 2008) New Revision: 2834 Removed: jbpm3/trunk/modules/userguide/src/main/docbook/en/images/scheduler.classes.gif jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/docmgmt.xml Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/images/scheduler.overview.gif jbpm3/trunk/modules/userguide/src/main/docbook/en/master.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/async.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/calendar.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/configuration.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/database.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/jpdl.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/persistence.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/scheduler.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/taskmgmt.xml Log: [1727] docs updated Deleted: jbpm3/trunk/modules/userguide/src/main/docbook/en/images/scheduler.classes.gif =================================================================== (Binary files differ) Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/images/scheduler.overview.gif =================================================================== (Binary files differ) Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/master.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/master.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/master.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -12,14 +12,12 @@ <!ENTITY modelling SYSTEM "modules/modelling.xml"> <!ENTITY context SYSTEM "modules/context.xml"> <!ENTITY taskmgmt SYSTEM "modules/taskmgmt.xml"> -<!ENTITY docmgmt SYSTEM "modules/docmgmt.xml"> <!ENTITY scheduler SYSTEM "modules/scheduler.xml"> <!ENTITY async SYSTEM "modules/async.xml"> <!ENTITY calendar SYSTEM "modules/calendar.xml"> <!ENTITY mail SYSTEM "modules/mail.xml"> <!ENTITY ws SYSTEM "modules/ws.xml"> <!ENTITY logging SYSTEM "modules/logging.xml"> -<!ENTITY simulation SYSTEM "modules/simulation.xml"> <!ENTITY jpdl SYSTEM "modules/jpdl.xml"> <!ENTITY security SYSTEM "modules/security.xml"> <!ENTITY tdd SYSTEM "modules/tdd.xml"> @@ -51,14 +49,12 @@ &modelling; &context; &taskmgmt; - &docmgmt; &scheduler; &async; &calendar; &mail; &ws; &logging; - &simulation; &jpdl; &security; &tdd; Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/async.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/async.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/async.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -210,32 +210,4 @@ </para> </section> - <section id="jbpmforasyncarchitectures"> - <title>JMS for async architectures</title> - <para>The asynchronous continuations feature, opens up a new world of jBPM usage - scenarios. Where typically, jBPM is used for modelling business processes, - it can now be used from a more technical perspective. - </para> - <para>Imagine that you have - an application with quite some asynchronous processing. That typically requires - quite a bit if difficult set up to bind all the message producing and message - consuming pieces of software together. With jBPM it now becomes possible to - create a picture of the overall asynchronous architecture, have all your - code in POJO's and add transaction demarcation in the overall process file. - jBPM will now take care of binding the senders to the receivers without the - need for writing all the JMS or MDB code yourself. - </para> - </section> - - <section id="futuredirections"> - <title>Future directions</title> - <para>TODO's: add support for multiple queues. So that it becomes possible to - specify a queue for each node or action that is marked as asynchronous. Also it would - be great to produce message for a set of queues in a round-robin. Since all of - this should be configurable for both the JMS and the built-in messaging systems, - this will require some thought on how to do all this configurations. The process - definitions should not have to depend on any of the 2 possible implementations. - </para> - </section> - </chapter> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/calendar.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/calendar.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/calendar.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -45,7 +45,7 @@ <para>A duration is specified in absolute or in business hours. Let's look at the syntax:</para> - <para><literal>basedate ::= &lt;EL&gt; +/-</literal></para> + <para><literal>basedate ::= &lt;EL&gt;</literal></para> <para>Where <literal>&lt;EL&gt;</literal> is any JAVA Expression Language expression that resolves to a JAVA Date or Calendar object. Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/configuration.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/configuration.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/configuration.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -4,20 +4,21 @@ <para>The simplest way to configure jBPM is by putting the <literal>jbpm.cfg.xml</literal> configuration file in the root of the classpath. If that file is not found as a resource, the default minimal configuration will be used that is included in the - jbpm library. Note that the minimal configuration does not have any configurations - for persistence. + jbpm library (<literal>org/jbpm/default.jbpm.cfg.xml</literal>). If a jbpm configuration + file is provided, the values configured will be used as defaults. So you only + need to specify the parts that are different from the default configuration file. </para> <para>The jBPM configuration is represented by the java class <literal>org.jbpm.JbpmConfiguration</literal>. - Most easy way to get a hold of the JbpmConfiguration is to make use of the singleton - instance method <literal>JbpmConfiguration.getInstance()</literal>. + Most easy way to get a hold of the JbpmConfiguration is to make use of the singleton + instance method <literal>JbpmConfiguration.getInstance()</literal>. </para> - <para>If you want to load a configuraiton from another source, you can use the + <para>If you want to load a configuration from another source, you can use the <literal>JbpmConfiguration.parseXxxx</literal> methods. </para> - <programlisting>static JbpmConfinguration jbpmConfiguration = JbpmConfinguration.getInstance();</programlisting> + <programlisting>static JbpmConfinguration jbpmConfiguration = JbpmConfinguration.parseResource("my.jbpm.cfg.xml");</programlisting> <para>The JbpmConfiguration is threadsafe and hence can be kept in a static member. All threads can use the JbpmConfiguration as a factory for JbpmContext objects. A JbpmContext typically represents one @@ -40,8 +41,7 @@ jBPM to run in any Java environment and use whatever services are available in that environment. </para> - <para>Here's a typical configuration for the JbpmContext as you can find it in - <literal>src/config.files/jbpm.cfg.xml</literal>: + <para>Here's the default configuration for the JbpmContext: </para> <programlisting>&lt;jbpm-configuration&gt; @@ -56,6 +56,7 @@ &lt;!-- configuration resource files pointing to default configuration files in jbpm-{version}.jar --&gt; &lt;string name='resource.hibernate.cfg.xml' value='hibernate.cfg.xml' /&gt; + &lt;!-- &lt;string name='resource.hibernate.properties' value='hibernate.properties' /&gt; --&gt; &lt;string name='resource.business.calendar' value='org/jbpm/calendar/jbpm.business.calendar.properties' /&gt; &lt;string name='resource.default.modules' value='org/jbpm/graph/def/jbpm.default.modules.properties' /&gt; @@ -64,11 +65,27 @@ &lt;string name='resource.node.types' value='org/jbpm/graph/node/node.types.xml' /&gt; &lt;string name='resource.parsers' value='org/jbpm/jpdl/par/jbpm.parsers.xml' /&gt; &lt;string name='resource.varmapping' value='org/jbpm/context/exe/jbpm.varmapping.xml' /&gt; + &lt;string name='resource.mail.templates' value='jbpm.mail.templates.xml' /&gt; &lt;int name='jbpm.byte.block.size' value="1024" singleton="true" /&gt; &lt;bean name='jbpm.task.instance.factory' class='org.jbpm.taskmgmt.impl.DefaultTaskInstanceFactoryImpl' singleton='true' /&gt; &lt;bean name='jbpm.variable.resolver' class='org.jbpm.jpdl.el.impl.JbpmVariableResolver' singleton='true' /&gt; + &lt;string name='jbpm.mail.smtp.host' value='localhost' /&gt; + &lt;bean name='jbpm.mail.address.resolver' class='org.jbpm.identity.mail.IdentityAddressResolver' singleton='true' /&gt; + &lt;string name='jbpm.mail.from.address' value='jbpm@noreply' /&gt; + &lt;bean name='jbpm.job.executor' class='org.jbpm.job.executor.JobExecutor'&gt; + &lt;field name='jbpmConfiguration'&gt;&lt;ref bean='jbpmConfiguration' /&gt;&lt;/field&gt; + &lt;field name='name'&gt;&lt;string value='JbpmJobExecutor' /&gt;&lt;/field&gt; + &lt;field name='nbrOfThreads'&gt;&lt;int value='1' /&gt;&lt;/field&gt; + &lt;field name='idleInterval'&gt;&lt;int value='5000' /&gt;&lt;/field&gt; + &lt;field name='maxIdleInterval'&gt;&lt;int value='3600000' /&gt;&lt;/field&gt; &lt;!-- 1 hour --&gt; + &lt;field name='historyMaxSize'&gt;&lt;int value='20' /&gt;&lt;/field&gt; + &lt;field name='maxLockTime'&gt;&lt;int value='600000' /&gt;&lt;/field&gt; &lt;!-- 10 minutes --&gt; + &lt;field name='lockMonitorInterval'&gt;&lt;int value='60000' /&gt;&lt;/field&gt; &lt;!-- 1 minute --&gt; + &lt;field name='lockBufferTime'&gt;&lt;int value='5000' /&gt;&lt;/field&gt; &lt;!-- 5 seconds --&gt; + &lt;/bean&gt; + &lt;/jbpm-configuration&gt;</programlisting> <para>In this configuration file you can see 3 parts: @@ -254,15 +271,6 @@ </section> </section> - <section id="jbpmdebuglogsinjboss"> - <title>jBPM debug logs in JBoss</title> - <para>When running jPDL in JBoss and you want to see the debug logs of jBPM, replace the file - <literal>conf/log4j.xml</literal> in the jboss server configuration take with the file - <literal>deploy/log4j.xml</literal> in your jPDL distribution. In the suite, the full location - of the file to be replaced is <literal>[jpdl.home]/server/server/jbpm/conf/log4j.xml</literal>. - </para> - </section> - <section id="loggingofoptimisticconcurrencyexceptions"> <title>Logging of optimistic concurrency exceptions</title> <para>When running in a cluster, jBPM synchronizes on the database. By default with optimistic Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/database.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/database.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/database.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -16,19 +16,16 @@ this is the case you can have a look at files for one of the databases present in the DB project and mimic this using your own database.</para> - <para>For this document, we will use the JBoss jBPM Starter's Kit - distribution. We will assume that this starter's kit was extracted to a - location on your machine named ${JBPM_SDK_HOME}. You will find the DB - subproject of jBPM in the ${JBPM_SDK_HOME}/jbpm-db.</para> + <para>For this document, we will use the jBPM jPDL installer. + Download and install as described in <xref linkend="downloadingandinstallingjbpm"/>. + We will assume that this installation was done to a + location on your machine named ${jbpm-jpdl-home}. You will find the DB + subproject of jBPM in the ${jbpm-jpdl-home}/db.</para> - <para>After installing the database, you will have to run the database - creation scripts. These will create the jBPM tables in the database. To - make the default webapp running with this new database, we will have to - update some configuration files of the server included in the Starter's - Kit. For these configuration changes, we will not go into too much detail. - If you want to know more about the different configuration settings in the - server, we advise you to have a look at the JBoss documentation.</para> - + <para>After installing the of your choice database, you will have to run + the database creation scripts to create the jBPM tables. Note that in the + hsqldb inside jboss this is done automatically during installation. + </para> <section id="isolationlevel"> <title>Isolation level</title> <para>Whatever database that you use, make sure that the isolation level @@ -126,29 +123,21 @@ <title>Creating the JBoss jBPM Database with your new PostGreSQL or MySQL</title> - <para>In order to get the proper database script generated for your - database, you should use the scripts provided in the jBPM Starter's Kit. - In the Starter's Kit under the - ${JBPM_SSTARTERSKIT_HOME}/jbpm-db/build/${DATABASE_TYPE}/scripts you - will find create scripts for all the major databases. Using your + <para>In order to get the proper database scripts for your + database, you should look int the directory <literal>${jbpm-jpdl-home}/db</literal>. + Using your database admin console, navigate to the database and then open and execute the create script we just referenced. Below are screen shots doing this for PostGreSQL and MySQL under their respective admin consoles</para> - <figure> - <mediaobject> - <imageobject /> - </mediaobject> - </figure> - <section> <title>Creating the JBoss jBPM Database with PostGreSQL</title> <para>As already mentioned you will find the database scripts for a lot of the supported databases in the DB subproject. The database scripts for PostgreSQL are found in the folder - '${JBPM_SDK_HOME}/jbpm-db/build/mysql/scripts. The creation script is + '${jbpm-jpdl-home}/db. The creation script is called 'postgresql.create.sql'. Using DBVisualizer, you can load this script by switching to the 'SQL Commander' tab and then selecting 'File-&gt;Load...'. In the following dialog, navigate to the creation @@ -265,12 +254,16 @@ <para>Before we can really use our newly created database with the JBoss jBPM default webapp we will have to do some updates to the JBoss jBPM - configuration. The location of the server is - '${JBPM_SDK_HOME}/jbpm-server'. The first thing we will be doing to - update this configuration is create a new datasource that points to our - JbpmDB database. In a second step, we will make sure that the default - webapp is talking to this datasource and not to the HSQLDB datasource - anymore.</para> + configuration. The location of the jbpm server configuration is + <literal>${jboss-home}/server/default/deploy/jbpm</literal>. + </para> + <para>First we create a new datasource in JBoss that binds to our + database. In the default installation, this is the done in the file + <literal>jbpm-hsqldb-ds.xml</literal>. That hypersonic database + configuration file can be removed and should be replaced by + the a file that ends with -ds.xml like e.g. + <literal>jbpm-postgres-ds.xml</literal> + </para> <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; @@ -304,18 +297,16 @@ &lt;/local-tx-datasource&gt; &lt;/datasources&gt;</programlisting> - <para>In order to create a new datasource, you should create a file - named e.g. jbpm-ds.xml with the contents shown in the program listing - above. Of course it is possible that you have to change some of the + <para>Of course it is possible that you have to change some of the values in this file to accommodate for your particular situation. You then simply save this file in the - ${JBPM_SDK_HOME}/jbpm-server/server/jbpm/deploy folder. Congratulations, + <literal>${jboss-home}/server/default/deploy/jbpm</literal> folder. Congratulations, you just created a new DataSource for your JBoss jBPM server. Well, almost... To make things really work you will have to copy the correct - JDBC driver to the ${JBPM_SDK_HOME}/jbpm-server/server/jbpm/lib folder. + JDBC driver to the <literal>${jboss.home}/server/default/lib</literal> folder. We already used this JDBC driver above when we were installing it in DBVisualizer to be able to browse our newly created database. The file - is named 'postgresql-8.1-*.jdbc3.jar' and it can be found in the jdbc + is named <literal>postgresql-8.1-*.jdbc3.jar</literal> and it can be found in the jdbc subfolder of your PostgreSQL installation folder.</para> <para>For MySQL, copy the jdbc driver installed from the MySQL @@ -323,37 +314,11 @@ Connector/J 3.1 available from http://www.mysql.com/products/connector/j/</para> - <para>If you are not using PostgreSQL or MySQL and are wondering how to - create your own data source definition for your particular database, you - can find sample data source definitions in the JBoss Application Server - distribution under the 'docs/examples/jca' folder. if your database has - a JDBC driver available for it, you should have no problems using it - with jBPM.</para> - - <para>Making the default webapp talk to the correct datasource is again - not very difficult. The first step in doing this is simply locate the - 'jboss-service.xml' file in the folder - '${JBPM_SDK_HOME}/jbpm-server/server/jbpm/deploy/jbpm.sar/META-INF'. - Change the contents of this file with the contents of the listing below. - An attentive reader will notice that the only difference is an exchange - of the token 'DefaultDS' by 'JbpmDS'.</para> - - <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; - -&lt;server&gt; - &lt;mbean code="org.jbpm.db.jmx.JbpmService" - name="jboss.jbpm:name=DefaultJbpm,service=JbpmService" - description="Default jBPM Service"&gt; - &lt;attribute name="JndiName"&gt;java:/jbpm/JbpmConfiguration&lt;/attribute&gt; - &lt;depends&gt;jboss.jca:service=DataSourceBinding,name=JbpmDS&lt;/depends&gt; - &lt;/mbean&gt; -&lt;/server&gt;</programlisting> - - <para>The last thing we have to do to make everything run is a - manipulation of the 'jbpm.sar.cfg.jar' file in the - '${JBPM_SDK_HOME}/jbpm-server/server/jbpm/deploy/jbpm.sar' folder. You - have to extract this file somewhere and open the file named - 'hibernate.cfg.xml'. Then replace the section containing the jdbc + <para>The last thing we have to do to make everything run is to + update the hibernate configuration file <literal>hibernate.cfg.xml</literal>. + That file is located in directory + <literal>${jboss.home}/server/default/deploy/jbpm-service.sar</literal>. + Replace the section containing the jdbc connection properties. This section should look like shown in the listing below. There are two changes in this file : the hibernate.connection.datasource property should point to the JbpmDS @@ -405,144 +370,8 @@ <section id="databaseupgrades"> <title>Database upgrades</title> - <para>In the jbpm.db subproject, you can find:</para> - - <itemizedlist> - <listitem> - An SQL script to create the jBPM 3.0.2 schema (for Hypersonic) - </listitem> - - <listitem> - An SQL script to create the jBPM 3.1 schema (for Hypersonic) - </listitem> - - <listitem> - An SQL script to upgrade from a jBPM 3.0.2 schema to a jBPM 3.1 schema (for Hypersonic) - </listitem> - - <listitem> - The ant scripts to create the schema update - </listitem> - </itemizedlist> - - <para>The schema SQL scripts can be found in directory - <literal>hsqldb/upgrade.scripts</literal>.</para> - - <para>To run the schema update tool for your database, follow these - guidelines:</para> - - <itemizedlist> - <listitem> - Prerequisite: Make sure you installed the jbpm.db project right besides the jbpm project. In the starters-kit, this is automatically the case. If jbpm is installed in a different location, update the jbpm.3.location dir in build.properties accordingly. - </listitem> - - <listitem> - Prerequisite: You should have the proper JDBC driver jar for your database. - </listitem> - - <listitem> - Update the properties in the build.properties in the root of the jbpm.db project: - - <itemizedlist> - <listitem><emphasis - role="bold">upgrade.hibernate.properties</emphasis>: a properties - file that contains the connection properties to your database in - hibernate style.</listitem> - - <listitem><emphasis role="bold">upgrade.libdir</emphasis>: the - directory containing the jdbc driver jars for your - database.</listitem> - - <listitem><emphasis - role="bold">upgrade.old.schema.script</emphasis>: the schema - generation script to create the old database schema. (if it already - exists, you don't need this property.)</listitem> - </itemizedlist> - - - </listitem> - - <listitem> - For creating the old schema and then calculating the differences, run the ant script - - <emphasis role="bold"> - <literal>'ant upgrade.db.script'</literal> - </emphasis> - - - </listitem> - - <listitem> - For only calculating the update script without first loading the old db schema, run the ant script - - <emphasis role="bold"> - <literal>'ant upgrade.hibernate.schema.update'</literal> - </emphasis> - - - </listitem> - - <listitem> - After successfull completion, you'll find the upgrade script in - - <literal>build/database.upgrade.sql</literal> - - - </listitem> - </itemizedlist> - - <para>For upgrading from jBPM 3.0.2 to jBPM 3.1, the generated upgrade SQL - script (for HSQLDB) is illustrated in the listing below:</para> - - <programlisting># New JBPM_MESSAGE table -create table JBPM_MESSAGE ( - ID_ bigint generated by default as identity (start with 1), - CLASS_ char(1) not null, - DESTINATION_ varchar(255), - EXCEPTION_ varchar(255), - ISSUSPENDED_ bit, - TOKEN_ bigint, - TEXT_ varchar(255), - ACTION_ bigint, - NODE_ bigint, - TRANSITIONNAME_ varchar(255), - TASKINSTANCE_ bigint, - primary key (ID_) -); - -# Added columns -alter table JBPM_ACTION add column ACTIONEXPRESSION_ varchar(255); -alter table JBPM_ACTION add column ISASYNC_ bit; -alter table JBPM_COMMENT add column VERSION_ integer; -alter table JBPM_ID_GROUP add column PARENT_ bigint; -alter table JBPM_NODE add column ISASYNC_ bit; -alter table JBPM_NODE add column DECISIONEXPRESSION_ varchar(255); -alter table JBPM_NODE add column ENDTASKS_ bit; -alter table JBPM_PROCESSINSTANCE add column VERSION_ integer; -alter table JBPM_PROCESSINSTANCE add column ISSUSPENDED_ bit; -alter table JBPM_RUNTIMEACTION add column VERSION_ integer; -alter table JBPM_SWIMLANE add column ACTORIDEXPRESSION_ varchar(255); -alter table JBPM_SWIMLANE add column POOLEDACTORSEXPRESSION_ varchar(255); -alter table JBPM_TASK add column ISSIGNALLING_ bit; -alter table JBPM_TASK add column ACTORIDEXPRESSION_ varchar(255); -alter table JBPM_TASK add column POOLEDACTORSEXPRESSION_ varchar(255); -alter table JBPM_TASKINSTANCE add column CLASS_ char(1); -alter table JBPM_TASKINSTANCE add column ISSUSPENDED_ bit; -alter table JBPM_TASKINSTANCE add column ISOPEN_ bit; -alter table JBPM_TIMER add column ISSUSPENDED_ bit; -alter table JBPM_TOKEN add column VERSION_ integer; -alter table JBPM_TOKEN add column ISSUSPENDED_ bit; -alter table JBPM_TOKEN add column SUBPROCESSINSTANCE_ bigint; -alter table JBPM_VARIABLEINSTANCE add column TASKINSTANCE_ bigint; - -# Added constraints -alter table JBPM_ID_GROUP add constraint FK_ID_GRP_PARENT foreign key (PARENT_) references JBPM_ID_GROUP; -alter table JBPM_MESSAGE add constraint FK_MSG_TOKEN foreign key (TOKEN_) references JBPM_TOKEN; -alter table JBPM_MESSAGE add constraint FK_CMD_NODE foreign key (NODE_) references JBPM_NODE; -alter table JBPM_MESSAGE add constraint FK_CMD_ACTION foreign key (ACTION_) references JBPM_ACTION; -alter table JBPM_MESSAGE add constraint FK_CMD_TASKINST foreign key (TASKINSTANCE_) references JBPM_TASKINSTANCE; -alter table JBPM_TOKEN add constraint FK_TOKEN_SUBPI foreign key (SUBPROCESSINSTANCE_) references JBPM_PROCESSINSTANCE; -alter table JBPM_VARIABLEINSTANCE add constraint FK_VAR_TSKINST foreign key (TASKINSTANCE_) references JBPM_TASKINSTANCE;</programlisting> + <para>For database upgrades, please refer to the <literal>release.notes.html</literal> + in the root of your installation directory.</para> </section> <section> @@ -560,7 +389,7 @@ figure below.</para> <figure> - <title>The JBoss jBPM JMX Console</title> + <title>The JBoss JMX Console</title> <mediaobject> <imageobject> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -11,10 +11,10 @@ <section id="jbpmlibraries"> <title>jBPM libraries</title> - <para><emphasis role="bold">jbpm-jpdl.jar</emphasis> is the library + <para><emphasis role="bold">lib/jbpm-jpdl.jar</emphasis> is the library with the core jpdl functionality. </para> - <para><emphasis role="bold">jbpm-identity.jar</emphasis> is the + <para><emphasis role="bold">lib/jbpm-identity.jar</emphasis> is the (optional) library containing an identity component as described in <xref linkend="theidentitycomponent" />. </para> @@ -158,109 +158,30 @@ </table> </section> - <section id="webapplication"> - <title>Web application</title> - <para>As part of the installation, the JSF based web application is installed - in JBoss in this location: + <section id="deploymentinjboss"> + <title>Deployment in JBoss</title> + <para>The installer deploys jBPM into JBoss. This section walks you through the deployed components. </para> - <para><literal>jboss-4.2.2.GA\server\default\deploy\jbpm\jbpm-enterprise-bundle.ear\jsf-console.war</literal></para> - </section> - - <section id="theruntimeandsuite"> - <title>The jPDL Runtime and Suite</title> - - <section id="theruntime"> - <title>The runtime</title> - <para>The jPDL runtime is all you need to get started with jPDL: jpdl libraries, third party - libraries, examples and documentation. It doesn't include the graphcal designer and web console - tooling, which is added in the suite package. + <section id="thejbpmdirectory"> + <title>The jbpm directory</title> + <para>When jBPM is installed on a server configuration in JBoss, only the jbpm directory is + added to the deploy directory and all components will be deployed under that directory. + No other files of JBoss are changed or added outside that directory. </para> - - <table id="jpdlruntimedirectories"> - <title>jPDL runtime directories</title> - <tgroup cols="2" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> - <thead> - <row> - <entry align="center">Directory</entry> - <entry align="center">Content</entry> - </row> - </thead> - <tbody> - <row> - <entry>config</entry> - <entry>Contains all the configuration files. Note that for easy testing and development, - the current hibernate configuration points to the in-memory jbpm database. - </entry> - </row> - <row> - <entry>db</entry> - <entry>Contains the scripts to create the jPDL tables in your DB. It includes a copy of - the wiki page about database compatibility.</entry> - </row> - <row> - <entry>doc</entry> - <entry>Contains the userguide and the javadocs for the jpdl sources and identity - sources</entry> - </row> - <row> - <entry>examples</entry> - <entry>Each example is a separate project that you can compile and run with ant or eclipse.</entry> - </row> - <row> - <entry>lib</entry> - <entry>All the third party libs and their licenses.</entry> - </row> - <row> - <entry>src</entry> - <entry>The sources for jpdl and the identity components.</entry> - </row> - </tbody> - </tgroup> - </table> </section> - - <section id="thesuite"> - <title>The suite</title> - <para>The jPDL suite is an extension of the jPDL runtime with 2 tools: a graphical designer - plugin for eclipse and a JBoss server that is preconfigured with a deployed version of the - jPDL runtime and console webapp. The included tools are all preconfigured to work nicely - together out of the box. + <section id="theenterprisebundle"> + <title>The enterprise bundle</title> + <para>The enterprise bundle is a J2EE web application that contains the jBPM enterprise beans + and the JSF based console. The enterprise beans are located in + <literal>\deploy\jbpm\jbpm-enterprise-bundle.ear\jbpm-enterprise-beans.jar</literal> and the + JSF web application is located at + <literal>\deploy\jbpm\jbpm-enterprise-bundle.ear\jsf-console.war</literal> </para> - - <table id="jpdlsuitedirectories"> - <title>jPDL suite extra directories</title> - <tgroup cols="2" rowsep="1" colsep="1"> - <colspec colname="c1" colwidth="1*"/> - <colspec colname="c2" colwidth="2*"/> - <thead> - <row> - <entry align="center">Directory</entry> - <entry align="center">Content</entry> - </row> - </thead> - <tbody> - <row> - <entry>designer</entry> - <entry>The designer is the eclipse plugin that alows for graphical process editing - of jPDL process files. Look in the designer/readme.html for more instructions on - installing the designer.</entry> - </row> - <row> - <entry>server</entry> - <entry>The server is actually a JBoss application server which has the jPDL runtime - and the jPDL console web application deployed.</entry> - </row> - </tbody> - </tgroup> - </table> </section> - <section id="configuringthelogsinthesuiteserver"> <title>Configuring the logs in the suite server</title> <para>If you want to see debug logs in the suite server, update file - <literal>jpdl-suite-home/server/server/jbpm/config/log4j.xml</literal> + <literal>jboss-{version}/server/default/config/log4j.xml</literal> Look for </para> <programlisting> &lt;!-- ============================== --&gt; @@ -296,7 +217,7 @@ here are the 2 steps that you need to do: </para> <para>1) in - <literal>jpdl-suite-home/server/server/bin/run.bat</literal>, somewhere at the end, + <literal>jboss-{version}/server/bin/run.bat</literal>, somewhere at the end, there is a line like this:</para> <programlisting>rem set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%</programlisting> <para>For backup reasons, just start by making a copy of that line, then remove the first '<literal>rem</literal>' @@ -307,6 +228,8 @@ port 8787. Then you can start adding break points and run through the processes with the console until the breakpoint is hit. </para> + <para>For more info about configuring logging of optimistic locking failures, + see <xref linkend="loggingofoptimisticconcurrencyexceptions"/></para> </section> </section> </chapter> Deleted: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/docmgmt.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/docmgmt.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/docmgmt.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -1,64 +0,0 @@ -<chapter id="docmgmt"> - <title>Document management</title> - - <para>This is still an experimental feature. - </para> - - <para>To enable this feature, you need to - uncomment the following line in the hibernate.cfg.xml: - </para> - - <programlisting>&lt;mapping resource="org/jbpm/context/exe/variableinstance/JcrNodeInstance.hbm.xml"/&gt;</programlisting> - - <para>The document management support of jBPM is based on - <ulink url="http://www.jcp.org/en/jsr/detail?id=170">Java Content Repository</ulink>. - That is a standard java specification for integrating document management - systems into Java. The basic idea is that jBPM supports storage of JCR nodes - as process variables. - </para> - - <para>To store a node, the session, repository and path are extracted from the node - like this: - </para> - - <programlisting>Session session = node.getSession(); -Repository repo = session.getRepository(); -Workspace wspace = session.getWorkspace(); - -// THE NODE REPOSITORY AND WORKSPACE NAME GOT TO CORRESPOND WITH A JBPM SERVICE NAME -repository = repo.getDescriptor(Repository.REP_NAME_DESC); -workspace = wspace.getName(); -path = node.getPath(); - </programlisting> - - <para><emphasis role="bold">IMPORTANT NOTE:</emphasis> The name of the jbpm context service - MUST correspond with the name of the repository (repository.getDescriptor(Repository.REP_NAME_DESC)). - This is to make the match between the reference stored in the jbpm process variables and - the repository when a node-variable is being loaded from the jBPM DB. When the JCR node process - variable is retrieved, each service name in the jbpm context will be matched against the - repository and workspace name stored. The matching between jbpm context service and the - JCR session/repository names will go like this: - </para> - - <itemizedlist> - <listitem>if there is a jbpm context service named 'jcr' (lower case) that one will be - taken - </listitem> - <listitem>a service name that is equal to the repository name matches - </listitem> - <listitem>a service that starts with the repository name and ends with the workspace - name matches and takes preference over a service with the repository name - </listitem> - </itemizedlist> - - <para>The typical use case for this feature is a document approval process. A document - needs to be approved and updated. That document (e.g. a word document), can be - stored in a JCR-content-repository-node. The node contains all the versions of the - document. So that later in the process, people still can consult the historical - versions of the document. - </para> - - <para>This feature was only tested with Jackrabbit. Please refer to the JCR - implementation documentation for more information about library dependencies. - </para> -</chapter> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/jpdl.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/jpdl.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/jpdl.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -137,16 +137,6 @@ </para> </section> - <section id="processconversion"> - <title>Process conversion</title> - <para>A conversion class has been made available to assist you with converting - your jBPM 2.0 process archives into jBPM 3.0 compatible process archives. Create an output - directory to hold the converted process archives. Enter the following command line from the build - directory of the jBPM 3.0 distribution:</para> - <para>java -jar converter.jar indirectory outdirectory</para> - <para>Substitute the input directory where your jBPM 2.0 process archives reside for "indirectory". Substitute the output - directory for the one you created to hold the newly converted process archives for "outdirectory".</para> - </section> </section> <section id="delegation"> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/persistence.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/persistence.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/persistence.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -192,7 +192,7 @@ that is used by jbpm is: </para> - <programlisting>hibernate.connection.datasource= --datasource JNDI name-- like e.g. java:/DefaultDS</programlisting> + <programlisting>hibernate.connection.datasource= --datasource JNDI name-- like e.g. java:/JbpmDS</programlisting> <para>More information on how to configure jdbc connections in hibernate, see <ulink url="http://www.hibernate.org/hib_docs/reference/en/html/session-con... the hibernate reference manual, section 'Hibernate provided JDBC connections'</ulink> @@ -338,7 +338,7 @@ null and creation of JDBC connections will be delegated to hibernate. By specifying a datasource, jBPM will fetch a JDBC connection from the datasource and provide that to hibernate while opening a new session. For user provided JDBC connections, - see <xref linkend="userprovidedstuff" />. + see <xref linkend="injectingresourcesprogrammatically" />. </listitem> </itemizedlist> </section> @@ -554,21 +554,6 @@ </para> </section> - <section id="knownissues"> - <title>Known Issues</title> - <para> - This section highlights the known-issues in databases that have been tested with jBPM. - </para> - <section id="sybaseissues"> - <title>Sybase Issues</title> - <para> - Some Sybase distributions have a known issue with truncating binary files resulting in - misbehavior of the system. This limitation is resulting from the storage mechanism of - binaries into the Sybase database. - </para> - </section> - </section> - </section> <section> @@ -594,7 +579,7 @@ <para>The easiest way to integrate your persistent classes with the jBPM persistent classes is by creating one central hibernate.cfg.xml. You can take the jBPM - <literal>src/config.files/hibernate.cfg.xml</literal> as a starting point and + <literal>hibernate.cfg.xml</literal> as a starting point and add references to your own hibernate mapping files in there. </para> </section> @@ -606,11 +591,11 @@ </para> <itemizedlist> <listitem>copy the jBPM hibernate mapping file(s) you want to copy from the - sources (<literal>src/java.jbpm/...</literal>) or from inside of the - jbpm jar. + sources (<literal>src/jbpm-jpdl-sources.jar</literal>) </listitem> <listitem> - put the copy anywhere you want on the classpath + put the copy anywhere you want on the classpath, but make sure it is not + the exact same location as they were before. </listitem> <listitem> update the references to the customized mapping files in the hibernate.cfg.xml @@ -633,10 +618,12 @@ If it weren't for this cache, JBoss jBPM could have a serious drawback in comparison to the other techniques to implement a BPM engine. </para> - <para>The caching strategy is set to <literal>nonstrict-read-write</literal>. At - runtime, the caching strategy could be set to <literal>read-only</literal>. But in - that case, you would need a separate set of hibernate mapping files for - deploying a process. That is why we opted for the nonstrict-read-write. + <para>The default caching strategy is set to <literal>nonstrict-read-write</literal>. During + runtime execution of processes, the process definitions are static. This way, + we get the maximum caching during runtime execution of processes. In theory, + caching strategy <literal>read-only</literal> would be even better for runtime + execution. But in that case, deploying new process definitions would not be + possible as that operation is not read-only. </para> </section> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/scheduler.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/scheduler.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/scheduler.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -18,6 +18,7 @@ transition='time-out-transition' &gt; &lt;action class='the-remainder-action-class-name' /&gt; &lt;/timer&gt; + &lt;transition name='time-out-transition' to='...' /&gt; &lt;/state&gt;</programlisting> <para>A timer that is specified on a node, is not executed after the node @@ -58,15 +59,6 @@ <mediaobject><imageobject><imagedata align="center" fileref="images/scheduler.overview.gif"/></imageobject></mediaobject> </figure> - <para>The following class diagram shows the classes that are involved in the - scheduler deployment. The interfaces <literal>SchedulerService</literal> and - <literal>TimerExecutor</literal> are specified to make the timer execution mechanism - pluggable.</para> - - <figure id="scheduler.classes.image"> - <title>Scheduler classes overview</title> - <mediaobject><imageobject><imagedata align="center" fileref="images/scheduler.classes.gif"/></imageobject></mediaobject> - </figure> </section> - + </chapter> \ No newline at end of file Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/taskmgmt.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/taskmgmt.xml 2008-11-09 14:30:26 UTC (rev 2833) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/taskmgmt.xml 2008-11-09 15:08:15 UTC (rev 2834) @@ -247,7 +247,7 @@ <para>The actorId will always override the pooled actors. So a taskInstance that has an actorId and a list of pooledActorIds, will only show up in the actor's personal task list. Keeping the pooledActorIds around allows a user to put a task instance - back into the group by just erasing the actorId property of the taskInstance. + back into the group by just setting the actorId property of the taskInstance to <literal>null</literal>. </para> </section> </section>