[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>
+ <import resource="jbpm.jobexecutor.cfg.xml" />
+ </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>
+
+ <process-engine-context>
+
+ <job-executor threads="4" idle="15000" idle-max="60000" lock-millis="3600000" />
+
+ </process-engine-context>
+ </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