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

do-not-reply at jboss.org do-not-reply at jboss.org
Fri Jun 12 05:52:01 EDT 2009


Author: jbarrez
Date: 2009-06-12 05:52:01 -0400 (Fri, 12 Jun 2009)
New Revision: 5031

Added:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/images/jobexecutor.overview.png
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-JobExecutor.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml
Removed:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-SoftwareLogging.xml
   jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-History.xml
Modified:
   jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml
Log:
Added documentation for Jobexecutor to Devguide

Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/jobexecutor.overview.png
===================================================================
(Binary files differ)


Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/jobexecutor.overview.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml	2009-06-12 09:21:13 UTC (rev 5030)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/master.xml	2009-06-12 09:52:01 UTC (rev 5031)
@@ -10,8 +10,9 @@
   <!ENTITY ch07-ImplementingAdvancedActivities SYSTEM "modules/ch07-ImplementingAdvancedActivities.xml">
   <!ENTITY ch08-AdvancedJpdl                   SYSTEM "modules/ch08-AdvancedJpdl.xml">
   <!ENTITY ch09-Persistence                    SYSTEM "modules/ch09-Persistence.xml">
-  <!ENTITY ch10-SoftwareLogging                SYSTEM "modules/ch10-SoftwareLogging.xml">
-  <!ENTITY ch11-History                        SYSTEM "modules/ch11-History.xml">
+  <!ENTITY ch10-JobExecutor                    SYSTEM "modules/ch10-JobExecutor.xml">
+  <!ENTITY ch11-SoftwareLogging                SYSTEM "modules/ch11-SoftwareLogging.xml">
+  <!ENTITY ch12-History                        SYSTEM "modules/ch12-History.xml">
 ]>
 
 <book lang="en">
@@ -31,7 +32,8 @@
   &ch07-ImplementingAdvancedActivities;
   &ch08-AdvancedJpdl;
   &ch09-Persistence;
-  &ch10-SoftwareLogging;
-  &ch11-History;
+  &ch10-JobExecutor;
+  &ch11-SoftwareLogging;
+  &ch12-History;
 
 </book>
\ No newline at end of file

Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-JobExecutor.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-JobExecutor.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-JobExecutor.xml	2009-06-12 09:52:01 UTC (rev 5031)
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="jobexecutor">
+  <title>JobExecutor</title>
+  
+  <para>
+	For jPDL features like asynchronous continuations and timers, jBPM
+	relies on transactional asynchronous messaging and transactional
+	timers. Those are not available on the standard Java platform.
+	Therefore, jBPM includes the JobExecutor component, which executes
+	asynchronous messages and timers in any (potentially clustered)
+	environment. 
+  </para>
+
+  <section id="overview">
+    <title>Overview</title>
+    <para>
+		By default, when calling a jBPM service operation (eg. TaskService,
+		ExecutionService, etc.), the jBPM logic is executed on the same thread
+		as where the call came from. In most cases, this is sufficient since
+		most steps in a process don't take much time. This means that
+		signalling a process instance from one wait state to another, passing
+		by several other steps in the business process, can be done in one
+		transaction.
+    </para>
+    <para>
+		However, in some occasions business processes can be made more efficient by
+		introducing asynchronous continuations. By marking an activity as
+		asynchronous, the jBPM engine will take care that the logic
+		encapsulated in the activity isn't executed on the thread of the
+		caller, but on a separate dedicated thread. The same mechanism is used
+		for timers and asynchronous mailing (which means mails will be sent
+		later, in a separate thread). The following picture shows which components
+		come into play when using this mechanism.
+    </para>
+    <figure id="jobexecutor.overview.image">
+      <title>JobExecutor components overview</title>
+      <mediaobject><imageobject><imagedata align="center" fileref="images/jobexecutor.overview.png"/></imageobject></mediaobject>
+    </figure>
+    <para>
+		When using timers or asynchronous continuations in a business process, the
+		jBPM engine will store a 'job' into the database (a job contains mainly a 
+		duedate and continuation logic). Do note that this mechanism is
+		pluggable, which means that in the future other destinations could be
+		used (JMS, JCR, etc).
+    </para>
+    <para>
+		Now the JobExecutor comes in to play, which is in fact a manager
+		for several subcomponents:
+		
+		<itemizedlist>
+			<listitem>
+				A <emphasis role="bold">shared BlockingQueue</emphasis>, 
+				which is used to temporary store job identifiers of jobs which 
+				are executable (eg duedate is passed).
+			</listitem>
+			<listitem>
+				Every JobExecutor has one <emphasis role="bold">DispatcherThread.</emphasis> 
+				This thread	will query the database for 'acquirable jobs' (eg timers 
+				which duedate is passed), using a dedicated command through the CommandService.
+				Since the dispatcher uses the CommandService, the command is
+				automatically made transactional and wrapped by the configured
+				interceptors. As long as jobs are available the dispatcher will put
+				job identifiers on the shared queue, until the queue is either full
+				(the thread will automatically be blocked by the JVM until a slot is
+				free) or until no new jobs can be found in the database. If the latter
+				case, the dispatcher will wait for a configured time (ie the 'idle
+				time').
+      		</listitem>
+			<listitem>
+				The JobExecutor also maintains a pool of 
+				<emphasis role="bold">JobExecutorThreads</emphasis>. The number of
+				JobExecutorThreads can be configured and influences the size of the
+				shared queue. Every one of the JobExecutorThreads will try to take a
+				jobId from the queue. The shared queue implementation is guaranteed to
+				block the JobexecutorThread until a queue slot is filled and the new
+				job id will be passed to exactly one waiting JobexecutorThread.
+				After taking a job id from the queue, the job is transactionally
+				executed using a dedicated command through the CommandService. This
+				means that the job logic will completely be executed on the
+				JobExecutorThread, instead of the default calling thread. This also
+				means that the order in which the jobs are executed is unknown since
+				there could be multiple competing JobExecutorThreads, but it
+				is certain that only one job per transaction will be done (unless using
+				'exclusive jobs' - in this case all exclusive jobs are sequentially
+				executed).
+			</listitem>
+		</itemizedlist>
+    </para>
+   
+  </section>
+  
+  <section id="configuration">
+    <title>Configuration</title>
+    <para>
+      Enabling the jobExecutor is very easy by adding the following line to the 
+      jbpm.cfg.xml file (using default settings):
+    </para>
+    <programlisting>
+	  &lt;import resource=&quot;jbpm.jobexecutor.cfg.xml&quot; /&gt;
+	</programlisting>
+	<para>
+	  Additional attributes can be set to fine-tune the JobExecutor:
+	  <itemizedlist>
+	    <listitem>
+	      <emphasis role="bold">threads:</emphasis> defines the number of 
+	      JobexecutorThreads (default 3 threads)
+	    </listitem>
+	    <listitem>
+	      <emphasis role="bold">idle:</emphasis> number of milliseconds the dispatcher
+	      component waits after no new jobs were found in the database (default 5 seconds) 
+	    </listitem>
+	    <listitem>
+	      <emphasis role="bold">idle-max:</emphasis> each time an exception occurs, 
+	      the idle period will be doubled until the 'idle-max' is reached 
+	      (back-off mechanism used to avoid a constant load on a failing database)
+	    </listitem> 
+	    <listitem>
+	      <emphasis role="bold">lock-millis:</emphasis> Number of milliseconds 
+	      that a job will be locked after being acquired by the dispatcher. 
+	      This prevents starvation in case one of more JobExecutorThreads would die
+	      (eg when used in a cluster).
+	    </listitem>
+	  </itemizedlist>
+	  <programlisting>
+		
+		&lt;process-engine-context&gt;
+		  
+		    &lt;job-executor threads=&quot;4&quot; idle=&quot;15000&quot; idle-max=&quot;60000&quot; lock-millis=&quot;3600000&quot; /&gt;
+		
+		&lt;/process-engine-context&gt;
+	  </programlisting>
+	</para>
+  </section>
+  
+</chapter>

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-SoftwareLogging.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-SoftwareLogging.xml	2009-06-12 09:21:13 UTC (rev 5030)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-SoftwareLogging.xml	2009-06-12 09:52:01 UTC (rev 5031)
@@ -1,99 +0,0 @@
-<chapter id="softwarelogging">
-  <title>Software logging</title>
-
-  <section>
-    <title>Configuration</title>
-    <para>PVM can use JDK logging (java.util.logging) or log4j. When the first message is 
-    logged, PVM logging will make the selection with following procedure:
-    <orderedlist>
-      <listitem>If a <literal>logging.properties</literal> resource is found 
-      on the classpath (using the context classloader), then JDK logging will 
-      be used and that file will be used to initialize the JDK logging.
-      </listitem>
-      <listitem>If log4j is found on the classpath, then log4j will be used.
-      The check for log4j will be done by checking availability of class 
-      <literal>org.apache.log4j.LogManager</literal> with the context classloader.
-      </listitem>
-      <listitem>If none of the above, JDK logging will be used.</listitem>
-    </orderedlist>
-    </para>
-  </section>
-
-  <section>
-    <title>Categories</title>
-    <para>The PVM classes use their class name as the category for the logger.
-    </para>
-    <para>To have a basic understanding of what the PVM classes are doing, 
-    turning on the <literal>debug</literal> level is great.  Level 
-    <literal>trace</literal> might be spitting out too much for that 
-    purpose. 
-    </para>
-  </section>
-  
-  <section>
-    <title>JDK logging</title>
-    <para>In JDK logging, <literal>debug</literal>maps to <literal>fine</literal> 
-    and <literal>trace</literal> maps to <literal>finest</literal>. 
-    Level <literal>finer</literal> is not used.
-    </para>
-    <para><literal>org.jbpm.pvm.internal.log.LogFormatter</literal> is part of 
-    the pvm library and it can create a nice one-line output for log messages.
-    It also has a neat feature that creates a unique indentation per thread.
-    To configure it, this is a typical <literal>logging.properties</literal>
-    </para>
-    <programlisting>handlers = java.util.logging.ConsoleHandler
-java.util.logging.ConsoleHandler.level = FINEST
-java.util.logging.ConsoleHandler.formatter = org.jbpm.pvm.internal.log.LogFormatter
-
-# For example, set the com.xyz.foo logger to only log SEVERE messages:
-# com.xyz.foo.level = SEVERE
-
-.level = SEVERE
-org.jbpm.level=FINE
-org.jbpm.tx.level=FINE
-org.jbpm.pvm.internal.wire.level=FINE</programlisting>
-
-<!-- 
-    <para>For production usage, jBPM also includes an error triggered log handler.  This is 
-    a log handler that will only keep the most recent log messages in 
-    memory and these will only be flushed to a file in case an error occurs.
-    </para>
-    <para>to configure it, add <literal>org.jbpm.util.ErrorTriggeredFileHandler</literal>
-    to the handlers in the logging properties like this:
-    </para>
-    <programlisting>handlers = java.util.logging.ConsoleHandler org.jbpm.util.ErrorTriggeredFileHandler</programlisting>
-    <para>Next snippet shows how in the same logging.properties, the error 
-    triggered file handler can be configured.  The given values are the default 
-    values.
-    </para>
-    <programlisting>org.jbpm.util.ErrorTriggeredFileHandler.size = 500
-org.jbpm.util.ErrorTriggeredFileHandler.push = SEVERE
-org.jbpm.util.ErrorTriggeredFileHandler.pattern = %h/jbpm%u.log</programlisting>
-    <para>Alternatively to using the org.jbpm.util.ErrorTriggeredFileHandler, the 
-    JDK handlers FileHandler and MemoryHandler can used in combination to get 
-    similar results with a bit more configuration.
-    </para>
-
--->    
-  </section>
-
-  <section>
-    <title>Debugging persistence</title>
-    <para>When testing the persistence, following logging configurations can be 
-    valuable.  Category <literal>org.hibernate.SQL</literal> shows the SQL statement that is executed 
-    and category <literal>org.hibernate.type</literal> shows the values of the parameters that are 
-    set in the queries. 
-    </para>
-    <programlisting>org.hibernate.SQL.level=FINEST
-org.hibernate.type.level=FINEST</programlisting>
-    <para>And in case you get a failed batch as a cause in a hibernate exception,
-    you might want to set the batch size to 0 like this in the hibernate properties:
-    </para>
-    <programlisting>hibernate.jdbc.batch_size = 0</programlisting>
-    <para>Also in the hibernate properties, the following properties allow for 
-    detailed logs of the SQL that hibernate spits out:</para>
-    <programlisting>hibernate.show_sql = true
-hibernate.format_sql = true
-hibernate.use_sql_comments = true</programlisting>
-  </section>
-</chapter>  
\ No newline at end of file

Deleted: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-History.xml
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-History.xml	2009-06-12 09:21:13 UTC (rev 5030)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-History.xml	2009-06-12 09:52:01 UTC (rev 5031)
@@ -1,42 +0,0 @@
-<chapter id="history">
-  <title>History</title>
-
-  <section id="overview">
-    <title>Overview</title>
-    
-    <para>HistoryEvents are fired during process execution.
-    </para>
-
-    <para>We maintain history information on 2 levels: process instance and activity instance.
-    </para>
-
-    <para>Process instance start and process instance end generate history events are fired directly 
-    from within the implementation.
-    </para>
-
-    <para>ActivityBehaviour implementations are responsible for calling the historyXxx methods that 
-    are exposed on the ActivityExecution
-    </para>
-
-    <para>All the HistoryEvents are delegated to a HistorySession.  The default HistorySessionImpl 
-    will invoke the process() method on the history events themselves.
-    </para>
-
-    <para>The HistoryEvents are temporary events.  In the process method, they build up the information 
-    in the history model.  There is a HistoryProcessInstance and there is a whole class hierarchy starting with HistoryActivityInstance.   
-    </para>
-
-    <para>In the HistoryEvent.process methods, the history events create model entities or merge 
-    information into the model entities.  For instance, a ProcessInstanceStart history event will 
-    create a HistoryProcessInstance entity/record.  And the ProcessInstanceEnd will set the endTime 
-    property in the existing HistoryProcessInstance entity/record.  
-    </para>
-
-    <para>Similar pattern for the activities.  But for automatic activities, there is an optimisation 
-    so that only 1 event is created and all the information is stored in one single insert (as all 
-    this happens inside 1 transaction).
-    </para>
-
-  </section>
-
-</chapter>
\ No newline at end of file

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml (from rev 5027, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch10-SoftwareLogging.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-SoftwareLogging.xml	2009-06-12 09:52:01 UTC (rev 5031)
@@ -0,0 +1,99 @@
+<chapter id="softwarelogging">
+  <title>Software logging</title>
+
+  <section>
+    <title>Configuration</title>
+    <para>PVM can use JDK logging (java.util.logging) or log4j. When the first message is 
+    logged, PVM logging will make the selection with following procedure:
+    <orderedlist>
+      <listitem>If a <literal>logging.properties</literal> resource is found 
+      on the classpath (using the context classloader), then JDK logging will 
+      be used and that file will be used to initialize the JDK logging.
+      </listitem>
+      <listitem>If log4j is found on the classpath, then log4j will be used.
+      The check for log4j will be done by checking availability of class 
+      <literal>org.apache.log4j.LogManager</literal> with the context classloader.
+      </listitem>
+      <listitem>If none of the above, JDK logging will be used.</listitem>
+    </orderedlist>
+    </para>
+  </section>
+
+  <section>
+    <title>Categories</title>
+    <para>The PVM classes use their class name as the category for the logger.
+    </para>
+    <para>To have a basic understanding of what the PVM classes are doing, 
+    turning on the <literal>debug</literal> level is great.  Level 
+    <literal>trace</literal> might be spitting out too much for that 
+    purpose. 
+    </para>
+  </section>
+  
+  <section>
+    <title>JDK logging</title>
+    <para>In JDK logging, <literal>debug</literal>maps to <literal>fine</literal> 
+    and <literal>trace</literal> maps to <literal>finest</literal>. 
+    Level <literal>finer</literal> is not used.
+    </para>
+    <para><literal>org.jbpm.pvm.internal.log.LogFormatter</literal> is part of 
+    the pvm library and it can create a nice one-line output for log messages.
+    It also has a neat feature that creates a unique indentation per thread.
+    To configure it, this is a typical <literal>logging.properties</literal>
+    </para>
+    <programlisting>handlers = java.util.logging.ConsoleHandler
+java.util.logging.ConsoleHandler.level = FINEST
+java.util.logging.ConsoleHandler.formatter = org.jbpm.pvm.internal.log.LogFormatter
+
+# For example, set the com.xyz.foo logger to only log SEVERE messages:
+# com.xyz.foo.level = SEVERE
+
+.level = SEVERE
+org.jbpm.level=FINE
+org.jbpm.tx.level=FINE
+org.jbpm.pvm.internal.wire.level=FINE</programlisting>
+
+<!-- 
+    <para>For production usage, jBPM also includes an error triggered log handler.  This is 
+    a log handler that will only keep the most recent log messages in 
+    memory and these will only be flushed to a file in case an error occurs.
+    </para>
+    <para>to configure it, add <literal>org.jbpm.util.ErrorTriggeredFileHandler</literal>
+    to the handlers in the logging properties like this:
+    </para>
+    <programlisting>handlers = java.util.logging.ConsoleHandler org.jbpm.util.ErrorTriggeredFileHandler</programlisting>
+    <para>Next snippet shows how in the same logging.properties, the error 
+    triggered file handler can be configured.  The given values are the default 
+    values.
+    </para>
+    <programlisting>org.jbpm.util.ErrorTriggeredFileHandler.size = 500
+org.jbpm.util.ErrorTriggeredFileHandler.push = SEVERE
+org.jbpm.util.ErrorTriggeredFileHandler.pattern = %h/jbpm%u.log</programlisting>
+    <para>Alternatively to using the org.jbpm.util.ErrorTriggeredFileHandler, the 
+    JDK handlers FileHandler and MemoryHandler can used in combination to get 
+    similar results with a bit more configuration.
+    </para>
+
+-->    
+  </section>
+
+  <section>
+    <title>Debugging persistence</title>
+    <para>When testing the persistence, following logging configurations can be 
+    valuable.  Category <literal>org.hibernate.SQL</literal> shows the SQL statement that is executed 
+    and category <literal>org.hibernate.type</literal> shows the values of the parameters that are 
+    set in the queries. 
+    </para>
+    <programlisting>org.hibernate.SQL.level=FINEST
+org.hibernate.type.level=FINEST</programlisting>
+    <para>And in case you get a failed batch as a cause in a hibernate exception,
+    you might want to set the batch size to 0 like this in the hibernate properties:
+    </para>
+    <programlisting>hibernate.jdbc.batch_size = 0</programlisting>
+    <para>Also in the hibernate properties, the following properties allow for 
+    detailed logs of the SQL that hibernate spits out:</para>
+    <programlisting>hibernate.show_sql = true
+hibernate.format_sql = true
+hibernate.use_sql_comments = true</programlisting>
+  </section>
+</chapter>  
\ No newline at end of file

Copied: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml (from rev 5027, jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch11-History.xml)
===================================================================
--- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml	                        (rev 0)
+++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch12-History.xml	2009-06-12 09:52:01 UTC (rev 5031)
@@ -0,0 +1,42 @@
+<chapter id="history">
+  <title>History</title>
+
+  <section id="overview">
+    <title>Overview</title>
+    
+    <para>HistoryEvents are fired during process execution.
+    </para>
+
+    <para>We maintain history information on 2 levels: process instance and activity instance.
+    </para>
+
+    <para>Process instance start and process instance end generate history events are fired directly 
+    from within the implementation.
+    </para>
+
+    <para>ActivityBehaviour implementations are responsible for calling the historyXxx methods that 
+    are exposed on the ActivityExecution
+    </para>
+
+    <para>All the HistoryEvents are delegated to a HistorySession.  The default HistorySessionImpl 
+    will invoke the process() method on the history events themselves.
+    </para>
+
+    <para>The HistoryEvents are temporary events.  In the process method, they build up the information 
+    in the history model.  There is a HistoryProcessInstance and there is a whole class hierarchy starting with HistoryActivityInstance.   
+    </para>
+
+    <para>In the HistoryEvent.process methods, the history events create model entities or merge 
+    information into the model entities.  For instance, a ProcessInstanceStart history event will 
+    create a HistoryProcessInstance entity/record.  And the ProcessInstanceEnd will set the endTime 
+    property in the existing HistoryProcessInstance entity/record.  
+    </para>
+
+    <para>Similar pattern for the activities.  But for automatic activities, there is an optimisation 
+    so that only 1 event is created and all the information is stored in one single insert (as all 
+    this happens inside 1 transaction).
+    </para>
+
+  </section>
+
+</chapter>
\ No newline at end of file




More information about the jbpm-commits mailing list