<commit_before><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "../../../target/docbook-tool-1.0/docbook-xml/docbookx.dtd">

<chapter>
  <title>Configuration</title>
  
  <section id="configuration">
    <title>Creating a ProcessEngine</title>
    
    <para>
    The Activiti process engine is configured through an XML file called <literal>activiti.cfg.xml</literal>.
    Note that this is <emphasis role="bold">not</emphasis> applicable if you're 
    using <link linkend="springintegration">the Spring style of building a process engine</link>.
    </para>

    <para>
    The easiest way to obtain a <literal>ProcessEngine</literal>, is to use the 
    <literal>org.activiti.engine.ProcessEngines</literal> class:
    <programlisting>ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine()</programlisting>
    This will look for an <literal>activiti.cfg.xml</literal> file on the classpath and
    construct an engine based on the configuration in that file.
    The following snippet shows an example configuration. 
    The following sections will give a detailed overview of the configuration properties.
    <programlisting>&lt;beans xmlns=&quot;http://www.springframework.org/schema/beans&quot; 
       xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
       xsi:schemaLocation=&quot;http://www.springframework.org/schema/beans   http://www.springframework.org/schema/beans/spring-beans.xsd&quot;&gt;

  &lt;bean id=&quot;processEngineConfiguration&quot; class=&quot;org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration&quot;&gt;
  
    &lt;property name=&quot;jdbcUrl&quot; value=&quot;jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000&quot; /&gt;
    &lt;property name=&quot;jdbcDriver&quot; value=&quot;org.h2.Driver&quot; /&gt;
    &lt;property name=&quot;jdbcUsername&quot; value=&quot;sa&quot; /&gt;
    &lt;property name=&quot;jdbcPassword&quot; value=&quot;&quot; /&gt;
    
    &lt;property name=&quot;databaseSchemaUpdate&quot; value=&quot;true&quot; /&gt;
    
    &lt;property name=&quot;jobExecutorActivate&quot; value=&quot;false&quot; /&gt;
    
    &lt;property name=&quot;mailServerHost&quot; value=&quot;mail.my-corp.com&quot; /&gt; 
    &lt;property name=&quot;mailServerPort&quot; value=&quot;5025&quot; /&gt;    
  &lt;/bean&gt;

&lt;/beans&gt;</programlisting>
    </para> 
    
    <para>
      Note that the configuration XML is in fact a Spring configuration.
      <emphasis role="bold">This does not mean that Activiti can only be used in a Spring environment!</emphasis>
      We are simply leveraging the parsing and dependency injection capabilities of Spring
      internally for building up the engine.
    </para>
    
    <para>
      The ProcessEngineConfiguration object can also be created programmatically using the configuration file.
      It is also possible to use a different bean id (e.g. see line 3).
      <programlisting>
ProcessEngineConfiguration.createProcessEngineConfigurationFromResourceDefault();
ProcessEngineConfiguration.createProcessEngineConfigurationFromResource(String resource);
ProcessEngineConfiguration.createProcessEngineConfigurationFromResource(String resource, String beanName);
ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(InputStream inputStream);
ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(InputStream inputStream, String beanName);</programlisting>
   It is also possible not to use a configuration file, and create a configuration based on 
   defaults (see <link linkend="configurationClasses">the different supported classes</link> for more information).
   <programlisting>
ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration();
ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration();</programlisting>
   All these <literal>ProcessEngineConfiguration.createXXX()</literal> methods return a 
   <literal>ProcessEngineConfiguration</literal> that can further be tweaked if needed.
   After calling the <literal>buildProcessEngine()</literal> operation, a <literal>ProcessEngine</literal>
   is created:
   <programlisting>
ProcessEngine processEngine = ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration()
  .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_FALSE)
  .setJdbcUrl("jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000")
  .setJobExecutorActivate(true)
  .buildProcessEngine();</programlisting>
    </para>
     
  </section>  
    
  <section id="configurationRoot">
    <title>ProcessEngineConfiguration bean</title>
    <para>
      The <literal>activiti.cfg.xml</literal> must contain a bean that has the id <literal>'processEngineConfiguration'</literal>.
      <programlisting> &lt;bean id=&quot;processEngineConfiguration&quot; class=&quot;org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration&quot;&gt;</programlisting>
      This bean is then used to construct the <literal>ProcessEngine</literal>. There are multiple
      classes available that can be used to define the <literal>processEngineConfiguration</literal>.
      These classes represent different environments, and set defaults accordingly. It's a best 
      practice to select the class the matches (the most) your environment, to minimalise the
      number of properties needed to configure the engine. The following classes are currently available
      (more will follow in future releases):
      <itemizedlist id="configurationClasses">
        <listitem>
          <para>
            <emphasis role="bold">org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration</emphasis>:
            the process engine is used in a standalone way. Activiti will take care of the transactions.
            By default, the database will only be checked when the engine boots (and an exception is thrown if there
            is no Activiti schema or the schema version is incorrect). 
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration</emphasis>:
            this is a convenience class for unit testing purposes. Activiti will take care of the transactions.
            An H2 in-memory database is used by default. The database will be created and dropped when the engine boots and shuts down.
            When using this, probably no additional configuration is needed (except when using for example the job executor or mail capabilities).
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">org.activiti.spring.SpringProcessEngineConfiguration</emphasis>:
            To be used when the process engine is used in a Spring environment. 
            See <link linkend="springintegration">the Spring integration section</link> for more information. 
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">org.activiti.engine.impl.cfg.JtaProcessEngineConfiguration</emphasis>:
            To be used when the engine runs in standalone mode, with JTA transactions.
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </section>
    
  <section id="databaseConfiguration">
    <title>Database configuration</title>
    <para>
      There are two ways to configure the database that the Activiti engine will use.
      The first option is to define the JDBC properties of the database:
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">jdbcUrl</emphasis>: JDBC URL of the database.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcDriver</emphasis>: implementation of the driver for the specific database type.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcUsername</emphasis>: username to connect to the database.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcPassword</emphasis>: password to connect to the database.
          </para>
        </listitem>
      </itemizedlist>
    </para>
    
    <para>
      The data source that is constructed based on the provided JDBC properties
      will have the default <ulink url="http://www.mybatis.org/">MyBatis</ulink> connection pool
      settings. The following attributes can optionally be set to tweak that connection pool (taken from the MyBatis documentation):
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">jdbcMaxActiveConnections</emphasis>: The number of active connections
            that the connection pool at maximum at any time can contain. Default is 10.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcMaxIdleConnections</emphasis>: The number of idle connections
            that the connection pool at maximum at any time can contain.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcMaxCheckoutTime</emphasis>: The amount of time in milliseconds a connection
            can be 'checked out' from the connection pool before it is forcefully returned.
            Default is 20000 (20 seconds).
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcMaxWaitTime</emphasis>: This is a low level setting that gives the pool 
            a chance to print a log status and re-attempt the acquisition of a connection in the 
            case that it’s taking unusually long (to avoid failing silently forever if the pool is misconfigured)
            Default is 20000 (20 seconds).
          </para>
        </listitem>
      </itemizedlist>
    </para>
    
    <para>
      Example database configuration:
      <programlisting>
&lt;property name=&quot;jdbcUrl&quot; value=&quot;jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000&quot; /&gt;
&lt;property name=&quot;jdbcDriver&quot; value=&quot;org.h2.Driver&quot; /&gt;
&lt;property name=&quot;jdbcUsername&quot; value=&quot;sa&quot; /&gt;
&lt;property name=&quot;jdbcPassword&quot; value=&quot;&quot; /&gt;
      </programlisting>
    </para>
    
    <para>
      Alternatively, a <literal>javax.sql.DataSource</literal> implementation can be used 
      (e.g. DBCP from <ulink url="http://commons.apache.org/dbcp/">Apache Commons</ulink>):
      <programlisting>
&lt;bean id=&quot;dataSource&quot; class=&quot;org.apache.commons.dbcp.BasicDataSource&quot; &gt;
  &lt;property name=&quot;driverClassName&quot; value=&quot;com.mysql.jdbc.Driver&quot; /&gt;
  &lt;property name=&quot;url&quot; value=&quot;jdbc:mysql://localhost:3306/activiti&quot; /&gt;
  &lt;property name=&quot;username&quot; value=&quot;activiti&quot; /&gt;
  &lt;property name=&quot;password&quot; value=&quot;<PASSWORD>&quot; /&gt;
  &lt;property name=&quot;defaultAutoCommit&quot; value=&quot;false&quot; /&gt;
&lt;/bean&gt;      

&lt;bean id=&quot;processEngineConfiguration&quot; class=&quot;org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration&quot;&gt;
  
    &lt;property name=&quot;dataSource&quot; ref=&quot;dataSource&quot; /&gt;
    ...
      </programlisting>
      Note that Activiti does not ship with a library that allows to define such a data source.
      So you have to make sure that the libraries (e.g. from DBCP) are on your classpath.
    </para>
    
    <para>
      The following properties can be set, regardless of whether you are using the JDBC or data source approach:
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">databaseType</emphasis>: it's normally not necessary to 
            specify this property as it is automatically analyzed from the database connection meta data.  
            Should only be specified in case automatic detection fails.
            Possible values: {h2, mysql, oracle, postgres, mssql, db2}.
            <emphasis role="bold">This property is required when not using the default H2 database</emphasis>.
            This setting will determine which create/drop scripts and queries will be used. See 
            <link linkend="supporteddatabases">the 'supported databases' section</link> for 
            an overview of which types are supported.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">databaseSchemaUpdate</emphasis>: allows to set the strategy to handle
            the database schema on process engine boot and shutdown.
            <itemizedlist>
              <listitem>
                <para>
                  <literal>false</literal> (default): Checks the version of the DB schema against the
                  library when the process engine is being created and throws an exception if the 
                  versions don't match.
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>true</literal>: Upon building the process engine, a check is performed and 
                  an update of the schema is performed if it is necessary. If the schema doesn't exist,
                  it is created.
                </para>
              </listitem>
               <listitem>
                <para>
                  <literal>create-drop</literal>: Creates the schema when the process engine is being created and 
                  drops the schema when the process engine is being closed.
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="supporteddatabases">
    <title>Supported databases</title>
    <para>Listed below are the types (case sensitive!) that Activiti uses to refer to databases.</para>
    <table id="databaseTypes">
      <title>Supported databases</title>
      <tgroup cols='3'>
        <thead>
          <row>
            <entry>Activiti database type</entry>
            <entry>Versions tested</entry>
            <entry>Example JDBC URL</entry>
            <entry>Notes</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>h2</entry>
            <entry>1.3.168</entry>
            <entry>jdbc:h2:tcp://localhost/activiti</entry>
            <entry>Default configured database</entry>
          </row>
          <row>
            <entry>mysql</entry>
            <entry>5.1.21</entry>
            <entry>jdbc:mysql://localhost:3306/activiti?autoReconnect=true</entry>
            <entry>Tested using mysql-connector-java database driver</entry>
          </row>
          <row>
            <entry>oracle</entry>
            <entry>172.16.31.10.0</entry>
            <entry>jdbc:oracle:thin:@localhost:1521:xe</entry>
            <entry></entry>
          </row>
          <row>
            <entry>postgres</entry>
            <entry>8.1</entry>
            <entry>jdbc:postgresql://localhost:5432/activiti</entry>
            <entry></entry>
          </row>
          <row>
            <entry>db2</entry>
            <entry>DB2 10.1 using db2jcc4</entry>
            <entry>jdbc:db2://localhost:50000/activiti</entry>
            <entry></entry>
          </row>
          <row>
            <entry>mssql</entry>
            <entry>2008 using sqljdbc4</entry>
            <entry>jdbc:sqlserver://localhost:1433/activiti</entry>
            <entry></entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </section>
  
  <section id="creatingDatabaseTable">
  
    <title>Creating the database tables</title>
    
    <para>
      The easiest way to create the database tables for your database is to:
      <itemizedlist>
        <listitem>
          <para>Add the activiti-engine jars to your classpath</para>
        </listitem>
        <listitem>
          <para>Add a suitable database driver</para>
        </listitem>
        <listitem>
          <para>Add an Activiti configuration file (<emphasis>activiti.cfg.xml</emphasis>) to your classpath, 
          pointing to your database (see <link linkend="databaseConfiguration">database configuration section</link>)</para>
        </listitem>
        <listitem>
          <para>Execute the main method of the <emphasis>DbSchemaCreate</emphasis> class</para>
        </listitem>
      </itemizedlist>
    </para>
    
    <para>
      However, often only database administrators can execute DDL statements on a database.
      The SQL DDL statements can be found on the Activiti downloads page or inside the Activiti distribution folder, in the <literal>database</literal> subdirectory. The scripts are also in 
      the engine jar (<emphasis>activiti-engine-x.jar</emphasis>), in 
      the package <emphasis>org/activiti/db/create</emphasis> (the <emphasis>drop</emphasis> folder contains the drop statements).
      The SQL files are of the form
      <programlisting>activiti.{db}.{create|drop}.{type}.sql</programlisting>
      Where <emphasis>db</emphasis> is any of the <link linkend="supporteddatabases">supported databases</link>
      and <emphasis>type</emphasis> is 
      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">engine:</emphasis> the tables needed for engine execution. Required.</para>
        </listitem>
        <listitem>
          <para><emphasis role="bold">identity:</emphasis> the tables containing users, groups and memberships of users to groups. These tables are optional and should be used when using 
          the default identity management as shipped with the engine.</para>
        </listitem>
        <listitem>
          <para><emphasis role="bold">history:</emphasis> the tables that contain the history and audit information. Optional: not needed when history level is set to <emphasis>none</emphasis>
          Note that this will also disable some features (such as commenting on tasks) which store the data in the history database.</para>
        </listitem>
      </itemizedlist>
    </para>
  
  </section>
  
  <section id="database.tables.explained">
    <title>Database table names explained</title>
    <para>
      The database names of Activiti all start with <emphasis role="bold">ACT_</emphasis>. The 
      second part is a two-character identification of the use case of the table. This use case 
      will also roughly match the service API.
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">ACT_RE_*</emphasis>: 'RE' stands for <literal>repository</literal>. 
            Tables with this prefix contain 'static' information such as process definitions and
            process resources (images, rules, etc.).
          </para>
        </listitem>
         <listitem>
          <para>
            <emphasis role="bold">ACT_RU_*</emphasis>: 'RU' stands for <literal>runtime</literal>.
            These are the runtime tables, that contain the runtime data of process instances,
            user tasks, variables, jobs, etc. Activiti only stores the runtime data during process instance
            execution, and removes the records when a process instance ends. This keeps 
            the runtime tables small and fast.
          </para>
        </listitem>
         <listitem>
          <para>
            <emphasis role="bold">ACT_ID_*</emphasis>: 'ID' stands for <literal>identity</literal>.
            These tables contain identity information, such as users, groups, etc.
          </para>
        </listitem>
         <listitem>
          <para>
            <emphasis role="bold">ACT_HI_*</emphasis>: 'HI' stands for <literal>history</literal>.
            These are the tables that contain historic data, such as past process instances,
            variables, tasks, etc.
          </para>
        </listitem>
         <listitem>
          <para>
            <emphasis role="bold">ACT_GE_*</emphasis>: <literal>general</literal> data, which is used
            in various use cases.
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </section>
    
  <section id="databaseUpgrade">
     <title>Database upgrade</title>
     <para>Make sure you make a backup of your database 
     (using your database backup capabilities) before you run an upgrade.
     </para>
     <para>By default, a version check will be performed each time a process engine is created.
     This typically happens once at boot time of your application or of the Activiti webapps.
     If the Activiti library notices a difference between the library version and the version  
     of the Activiti database tables, then an exception is thrown.
     </para> 
     <para>To upgrade, you have to start with putting the following configuration property in your 
     activiti.cfg.xml configuration file:
     </para>
    <programlisting>&lt;beans ... &gt;

  &lt;bean id=&quot;processEngineConfiguration&quot; class=&quot;org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration&quot;&gt;
    &lt;!-- ... --&gt;
    &lt;property name=&quot;databaseSchemaUpdate&quot; value=&quot;true&quot; /&gt;    
    &lt;!-- ... --&gt;
  &lt;/bean&gt;

&lt;/beans&gt;</programlisting>
     <para> <emphasis role="bold">Also, include a suitable database driver for your database to the classpath.</emphasis>
     Upgrade the Activiti libraries in your application. Or start up a new version 
     of Activiti and point it to a database that contains an older version.  With <literal>databaseSchemaUpdate</literal>
     set to <literal>true</literal>, Activiti will automatically upgrade the DB schema to the newer version
     the first time when it notices that libraries and DB schema are out of sync.
     </para>
     <para> <emphasis role="bold">As an alternative you can also run the upgrade DDL statements.</emphasis>
     It's also possible to run the upgrade database scripts, available on the Activiti downloads page.
     </para>
   </section>
  
  <section id="jobExecutorConfiguration">
    <title>Job executor activation</title>
    <para>The <literal>JobExecutor</literal> is a component that manages a couple of threads to fire timers (and later also asynchronous messages).
    For unit testing scenarios, it is cumbersome to work with multiple threads. Therefore the API allows to query for 
    (<literal>ManagementService.createJobQuery</literal>) and execute jobs (<literal>ManagementService.executeJob</literal>) through 
    the API so that job execution can be controlled from within a unit test.  To avoid interference by the job executor, it can be turned off. 
    </para>
    <para> 
    By default, the <literal>JobExecutor</literal> is activated when the process engine boots. Specify
    <programlisting>&lt;property name=&quot;jobExecutorActivate&quot; value=&quot;false&quot; /></programlisting>
    when you don't want the <literal>JobExecutor</literal> to be activated upon booting the process engine.
    </para>
  </section>
  
  <section id="mailServerConfiguration">
    <title>Mail server configuration</title>
    <para>
      Configuring a mail server is optional. Activiti supports sending e-mails in business processes. To actually send an e-mail, a valid
      SMTP mail server configuration is required. See the 
      <link linkend="bpmnEmailTaskServerConfiguration">e-mail task</link> for the configuration options.
    </para>
  </section>
  
  <section id="historyConfiguration">
    <title>History configuration</title>
    <para>
      Customizing the configuration of history storage is optional. This allows you to tweak settings that influence the <link linkend="history">history capabilities</link>
      of the engine. See <link linkend="historyConfig">history configuration</link> for more details.
      <programlisting>&lt;property name=&quot;history&quot; value=&quot;audit&quot; /&gt;</programlisting>
    </para>
  </section>
  
  <section id="exposingConfigurationBeans">
    <title>Exposing configuration beans in expressions and scripts</title>
    <para>By default, all beans that you specify in the <literal>activiti.cfg.xml</literal> configuration 
    or in your own Spring configuration file are available to expressions and in the scripts.
    If you want to limit the visibility of beans in your configuration file, you can 
    configure a property called <literal>beans</literal> in your process engine configuration.
    The beans property in <literal>ProcessEngineConfiguration</literal> is a map. When you specify that property,
    only beans specified in that map will be visible to expressions and scripts.  The exposed beans 
    will be exposed with the names as you specify in that map.  
    </para>
  </section>
  <section id="processDefinitionCacheConfiguration">
    <title>Deployment cache configuration</title>
    <para>All process definition are cached (after they're parsed) to avoid hitting
    the database every time a process definition is needed and because process definition data doesn't change.
    By default, there is no limit on this cache. To limit the process definition cache, add following property
    <programlisting>&lt;property name=&quot;processDefinitionCacheLimit&quot; value=&quot;10&quot; /&gt;</programlisting>
    Setting this property will swap the default hashmap cache with a LRU cache that has the provided hard limit.
    Of course, the 'best' value of this property depends on the total amount of process definitions stored and the number of
    process definitions actually used at runtime by all the runtime process instances.</para>
    <para>You can also inject your own cache implementation. This must be a bean that implements the
    org.activiti.engine.impl.persistence.deploy.DeploymentCache interface:
    <programlisting>
&lt;property name=&quot;processDefinitionCache&quot;&gt;
  &lt;bean class=&quot;org.activiti.MyCache&quot; />
&lt;/property&gt;</programlisting></para>
     <para>There is a similar property called <literal>knowledgeBaseCacheLimit</literal> and <literal>knowledgeBaseCache</literal> for configuring the rules cache.
     This is only needed when you use the rules task in your processes.</para>
    </section>
  
  <section id="loggingConfiguration">
    <title>Logging</title>
    <para>As of Activiti 5.12, SLF4J is used as logging framework, replacing the 
    previous used java.util.logging. All logging (activiti, spring, mybatis, ...) is routed through SLF4J and allows for
    selecting the logging-implementation of your choice.</para>
    <para><emphasis role="bold">By default no SFL4J-binding jar is present in the activiti-engine dependencies, this should be added
    in your project in order to use the logging framework of your choice.</emphasis> If no implementation jar is added, SLF4J will use a NOP-logger,
     not logging anything at all, other than a warning that nothing will be logged. For more info on these bindings <ulink url="http://www.slf4j.org/codes.html#StaticLoggerBinder">http://www.slf4j.org/codes.html#StaticLoggerBinder</ulink>.</para>

    <para>With Maven, add for example a dependency like this (here using log4j), note that you still need to add a version:
    <programlisting>
&lt;dependency&gt;
  &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
  &lt;artifactId&gt;slf4j-log4j12&lt;/artifactId&gt;
&lt;/dependency&gt;</programlisting></para>
    
    <para>The activiti-explorer and activiti-rest webapps are configured to use Log4j-binding. Log4j is also used when running the tests for all the activiti-* modules.</para>
  
    <para>
      <emphasis role="bold">Important note when using a container with commons-logging in the classpath:</emphasis>
      In order to route the spring-logging through SLF4J, a bridge is used (see <ulink url="http://www.slf4j.org/legacy.html#jclOverSLF4J">http://www.slf4j.org/legacy.html#jclOverSLF4J</ulink>). If your container provides a commons-logging implementation,
      please follow directions on this page: <ulink url="http://www.slf4j.org/codes.html#release">http://www.slf4j.org/codes.html#release</ulink> to ensure stability.
    </para>
    <para>
      Example when using Maven (version omitted):
      <programlisting>
&lt;dependency&gt;
  &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
  &lt;artifactId&gt;jcl-over-slf4j&lt;/artifactId&gt;
&lt;/dependency&gt;</programlisting>
    </para>
	<para> As of version 5.13, activiti supports Mapped Diagnostic Contexts feature of sl4j. These basic information are passed to the underlying logger along with what is going to be logged:
      <itemizedlist>
        <listitem>
			processDefinition Id as mdcProcessDefinitionID		   
		</listitem>
		  
        <listitem>
			processInstance Id as mdcProcessInstanceID
		</listitem>
		   
        <listitem>
			execution Id as mdcexecutionId
		</listitem>
      </itemizedlist>
	  None of these information are logged by default. The logger can be configured to show them in desired format, extra to the usual logged messages.
	  For example in log4j the following sample layout definition  causes the logger to show the above mentioned information:
	 <programlisting>
	   log4j.appender.consoleAppender.layout.ConversionPattern =ProcessDefinitionId=%X{mdcProcessDefinitionID}
 executionId=%X{mdcExecutionId} mdcProcessInstanceID=%X{mdcProcessInstanceID} mdcBusinessKey=%X{mdcBusinessKey} %m%n"
	  </programlisting>
	  This is useful where the systems are mission critical and logges should be seriously checked,  by means of a log analyzer for example.
	
	</para>
	
  </section>

</chapter>
<commit_msg>Fixing error in building docs<commit_after><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "../../../target/docbook-tool-1.0/docbook-xml/docbookx.dtd">

<chapter>
  <title>Configuration</title>
  
  <section id="configuration">
    <title>Creating a ProcessEngine</title>
    
    <para>
    The Activiti process engine is configured through an XML file called <literal>activiti.cfg.xml</literal>.
    Note that this is <emphasis role="bold">not</emphasis> applicable if you're 
    using <link linkend="springintegration">the Spring style of building a process engine</link>.
    </para>

    <para>
    The easiest way to obtain a <literal>ProcessEngine</literal>, is to use the 
    <literal>org.activiti.engine.ProcessEngines</literal> class:
    <programlisting>ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine()</programlisting>
    This will look for an <literal>activiti.cfg.xml</literal> file on the classpath and
    construct an engine based on the configuration in that file.
    The following snippet shows an example configuration. 
    The following sections will give a detailed overview of the configuration properties.
    <programlisting>&lt;beans xmlns=&quot;http://www.springframework.org/schema/beans&quot; 
       xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
       xsi:schemaLocation=&quot;http://www.springframework.org/schema/beans   http://www.springframework.org/schema/beans/spring-beans.xsd&quot;&gt;

  &lt;bean id=&quot;processEngineConfiguration&quot; class=&quot;org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration&quot;&gt;
  
    &lt;property name=&quot;jdbcUrl&quot; value=&quot;jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000&quot; /&gt;
    &lt;property name=&quot;jdbcDriver&quot; value=&quot;org.h2.Driver&quot; /&gt;
    &lt;property name=&quot;jdbcUsername&quot; value=&quot;sa&quot; /&gt;
    &lt;property name=&quot;jdbcPassword&quot; value=&quot;&quot; /&gt;
    
    &lt;property name=&quot;databaseSchemaUpdate&quot; value=&quot;true&quot; /&gt;
    
    &lt;property name=&quot;jobExecutorActivate&quot; value=&quot;false&quot; /&gt;
    
    &lt;property name=&quot;mailServerHost&quot; value=&quot;mail.my-corp.com&quot; /&gt; 
    &lt;property name=&quot;mailServerPort&quot; value=&quot;5025&quot; /&gt;    
  &lt;/bean&gt;

&lt;/beans&gt;</programlisting>
    </para> 
    
    <para>
      Note that the configuration XML is in fact a Spring configuration.
      <emphasis role="bold">This does not mean that Activiti can only be used in a Spring environment!</emphasis>
      We are simply leveraging the parsing and dependency injection capabilities of Spring
      internally for building up the engine.
    </para>
    
    <para>
      The ProcessEngineConfiguration object can also be created programmatically using the configuration file.
      It is also possible to use a different bean id (e.g. see line 3).
      <programlisting>
ProcessEngineConfiguration.createProcessEngineConfigurationFromResourceDefault();
ProcessEngineConfiguration.createProcessEngineConfigurationFromResource(String resource);
ProcessEngineConfiguration.createProcessEngineConfigurationFromResource(String resource, String beanName);
ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(InputStream inputStream);
ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(InputStream inputStream, String beanName);</programlisting>
   It is also possible not to use a configuration file, and create a configuration based on 
   defaults (see <link linkend="configurationClasses">the different supported classes</link> for more information).
   <programlisting>
ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration();
ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration();</programlisting>
   All these <literal>ProcessEngineConfiguration.createXXX()</literal> methods return a 
   <literal>ProcessEngineConfiguration</literal> that can further be tweaked if needed.
   After calling the <literal>buildProcessEngine()</literal> operation, a <literal>ProcessEngine</literal>
   is created:
   <programlisting>
ProcessEngine processEngine = ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration()
  .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_FALSE)
  .setJdbcUrl("jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000")
  .setJobExecutorActivate(true)
  .buildProcessEngine();</programlisting>
    </para>
     
  </section>  
    
  <section id="configurationRoot">
    <title>ProcessEngineConfiguration bean</title>
    <para>
      The <literal>activiti.cfg.xml</literal> must contain a bean that has the id <literal>'processEngineConfiguration'</literal>.
      <programlisting> &lt;bean id=&quot;processEngineConfiguration&quot; class=&quot;org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration&quot;&gt;</programlisting>
      This bean is then used to construct the <literal>ProcessEngine</literal>. There are multiple
      classes available that can be used to define the <literal>processEngineConfiguration</literal>.
      These classes represent different environments, and set defaults accordingly. It's a best 
      practice to select the class the matches (the most) your environment, to minimalise the
      number of properties needed to configure the engine. The following classes are currently available
      (more will follow in future releases):
      <itemizedlist id="configurationClasses">
        <listitem>
          <para>
            <emphasis role="bold">org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration</emphasis>:
            the process engine is used in a standalone way. Activiti will take care of the transactions.
            By default, the database will only be checked when the engine boots (and an exception is thrown if there
            is no Activiti schema or the schema version is incorrect). 
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration</emphasis>:
            this is a convenience class for unit testing purposes. Activiti will take care of the transactions.
            An H2 in-memory database is used by default. The database will be created and dropped when the engine boots and shuts down.
            When using this, probably no additional configuration is needed (except when using for example the job executor or mail capabilities).
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">org.activiti.spring.SpringProcessEngineConfiguration</emphasis>:
            To be used when the process engine is used in a Spring environment. 
            See <link linkend="springintegration">the Spring integration section</link> for more information. 
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">org.activiti.engine.impl.cfg.JtaProcessEngineConfiguration</emphasis>:
            To be used when the engine runs in standalone mode, with JTA transactions.
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </section>
    
  <section id="databaseConfiguration">
    <title>Database configuration</title>
    <para>
      There are two ways to configure the database that the Activiti engine will use.
      The first option is to define the JDBC properties of the database:
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">jdbcUrl</emphasis>: JDBC URL of the database.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcDriver</emphasis>: implementation of the driver for the specific database type.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcUsername</emphasis>: username to connect to the database.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcPassword</emphasis>: password to connect to the database.
          </para>
        </listitem>
      </itemizedlist>
    </para>
    
    <para>
      The data source that is constructed based on the provided JDBC properties
      will have the default <ulink url="http://www.mybatis.org/">MyBatis</ulink> connection pool
      settings. The following attributes can optionally be set to tweak that connection pool (taken from the MyBatis documentation):
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">jdbcMaxActiveConnections</emphasis>: The number of active connections
            that the connection pool at maximum at any time can contain. Default is 10.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcMaxIdleConnections</emphasis>: The number of idle connections
            that the connection pool at maximum at any time can contain.
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcMaxCheckoutTime</emphasis>: The amount of time in milliseconds a connection
            can be 'checked out' from the connection pool before it is forcefully returned.
            Default is 20000 (20 seconds).
          </para>
        </listitem>
        <listitem>
           <para>
            <emphasis role="bold">jdbcMaxWaitTime</emphasis>: This is a low level setting that gives the pool 
            a chance to print a log status and re-attempt the acquisition of a connection in the 
            case that it’s taking unusually long (to avoid failing silently forever if the pool is misconfigured)
            Default is 20000 (20 seconds).
          </para>
        </listitem>
      </itemizedlist>
    </para>
    
    <para>
      Example database configuration:
      <programlisting>
&lt;property name=&quot;jdbcUrl&quot; value=&quot;jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000&quot; /&gt;
&lt;property name=&quot;jdbcDriver&quot; value=&quot;org.h2.Driver&quot; /&gt;
&lt;property name=&quot;jdbcUsername&quot; value=&quot;sa&quot; /&gt;
&lt;property name=&quot;jdbcPassword&quot; value=&quot;&quot; /&gt;
      </programlisting>
    </para>
    
    <para>
      Alternatively, a <literal>javax.sql.DataSource</literal> implementation can be used 
      (e.g. DBCP from <ulink url="http://commons.apache.org/dbcp/">Apache Commons</ulink>):
      <programlisting>
&lt;bean id=&quot;dataSource&quot; class=&quot;org.apache.commons.dbcp.BasicDataSource&quot; &gt;
  &lt;property name=&quot;driverClassName&quot; value=&quot;com.mysql.jdbc.Driver&quot; /&gt;
  &lt;property name=&quot;url&quot; value=&quot;jdbc:mysql://localhost:3306/activiti&quot; /&gt;
  &lt;property name=&quot;username&quot; value=&quot;activiti&quot; /&gt;
  &lt;property name=&quot;password&quot; value=&quot;<PASSWORD>&quot; /&gt;
  &lt;property name=&quot;defaultAutoCommit&quot; value=&quot;false&quot; /&gt;
&lt;/bean&gt;      

&lt;bean id=&quot;processEngineConfiguration&quot; class=&quot;org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration&quot;&gt;
  
    &lt;property name=&quot;dataSource&quot; ref=&quot;dataSource&quot; /&gt;
    ...
      </programlisting>
      Note that Activiti does not ship with a library that allows to define such a data source.
      So you have to make sure that the libraries (e.g. from DBCP) are on your classpath.
    </para>
    
    <para>
      The following properties can be set, regardless of whether you are using the JDBC or data source approach:
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">databaseType</emphasis>: it's normally not necessary to 
            specify this property as it is automatically analyzed from the database connection meta data.  
            Should only be specified in case automatic detection fails.
            Possible values: {h2, mysql, oracle, postgres, mssql, db2}.
            <emphasis role="bold">This property is required when not using the default H2 database</emphasis>.
            This setting will determine which create/drop scripts and queries will be used. See 
            <link linkend="supporteddatabases">the 'supported databases' section</link> for 
            an overview of which types are supported.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">databaseSchemaUpdate</emphasis>: allows to set the strategy to handle
            the database schema on process engine boot and shutdown.
            <itemizedlist>
              <listitem>
                <para>
                  <literal>false</literal> (default): Checks the version of the DB schema against the
                  library when the process engine is being created and throws an exception if the 
                  versions don't match.
                </para>
              </listitem>
              <listitem>
                <para>
                  <literal>true</literal>: Upon building the process engine, a check is performed and 
                  an update of the schema is performed if it is necessary. If the schema doesn't exist,
                  it is created.
                </para>
              </listitem>
               <listitem>
                <para>
                  <literal>create-drop</literal>: Creates the schema when the process engine is being created and 
                  drops the schema when the process engine is being closed.
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="supporteddatabases">
    <title>Supported databases</title>
    <para>Listed below are the types (case sensitive!) that Activiti uses to refer to databases.</para>
    <table id="databaseTypes">
      <title>Supported databases</title>
      <tgroup cols='3'>
        <thead>
          <row>
            <entry>Activiti database type</entry>
            <entry>Versions tested</entry>
            <entry>Example JDBC URL</entry>
            <entry>Notes</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>h2</entry>
            <entry>1.3.168</entry>
            <entry>jdbc:h2:tcp://localhost/activiti</entry>
            <entry>Default configured database</entry>
          </row>
          <row>
            <entry>mysql</entry>
            <entry>5.1.21</entry>
            <entry>jdbc:mysql://localhost:3306/activiti?autoReconnect=true</entry>
            <entry>Tested using mysql-connector-java database driver</entry>
          </row>
          <row>
            <entry>oracle</entry>
            <entry>11.2.0.1.0</entry>
            <entry>jdbc:oracle:thin:@localhost:1521:xe</entry>
            <entry></entry>
          </row>
          <row>
            <entry>postgres</entry>
            <entry>8.1</entry>
            <entry>jdbc:postgresql://localhost:5432/activiti</entry>
            <entry></entry>
          </row>
          <row>
            <entry>db2</entry>
            <entry>DB2 10.1 using db2jcc4</entry>
            <entry>jdbc:db2://localhost:50000/activiti</entry>
            <entry></entry>
          </row>
          <row>
            <entry>mssql</entry>
            <entry>2008 using sqljdbc4</entry>
            <entry>jdbc:sqlserver://localhost:1433/activiti</entry>
            <entry></entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </section>
  
  <section id="creatingDatabaseTable">
  
    <title>Creating the database tables</title>
    
    <para>
      The easiest way to create the database tables for your database is to:
      <itemizedlist>
        <listitem>
          <para>Add the activiti-engine jars to your classpath</para>
        </listitem>
        <listitem>
          <para>Add a suitable database driver</para>
        </listitem>
        <listitem>
          <para>Add an Activiti configuration file (<emphasis>activiti.cfg.xml</emphasis>) to your classpath, 
          pointing to your database (see <link linkend="databaseConfiguration">database configuration section</link>)</para>
        </listitem>
        <listitem>
          <para>Execute the main method of the <emphasis>DbSchemaCreate</emphasis> class</para>
        </listitem>
      </itemizedlist>
    </para>
    
    <para>
      However, often only database administrators can execute DDL statements on a database.
      The SQL DDL statements can be found on the Activiti downloads page or inside the Activiti distribution folder, in the <literal>database</literal> subdirectory. The scripts are also in 
      the engine jar (<emphasis>activiti-engine-x.jar</emphasis>), in 
      the package <emphasis>org/activiti/db/create</emphasis> (the <emphasis>drop</emphasis> folder contains the drop statements).
      The SQL files are of the form
      <programlisting>activiti.{db}.{create|drop}.{type}.sql</programlisting>
      Where <emphasis>db</emphasis> is any of the <link linkend="supporteddatabases">supported databases</link>
      and <emphasis>type</emphasis> is 
      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">engine:</emphasis> the tables needed for engine execution. Required.</para>
        </listitem>
        <listitem>
          <para><emphasis role="bold">identity:</emphasis> the tables containing users, groups and memberships of users to groups. These tables are optional and should be used when using 
          the default identity management as shipped with the engine.</para>
        </listitem>
        <listitem>
          <para><emphasis role="bold">history:</emphasis> the tables that contain the history and audit information. Optional: not needed when history level is set to <emphasis>none</emphasis>
          Note that this will also disable some features (such as commenting on tasks) which store the data in the history database.</para>
        </listitem>
      </itemizedlist>
    </para>
  
  </section>
  
  <section id="database.tables.explained">
    <title>Database table names explained</title>
    <para>
      The database names of Activiti all start with <emphasis role="bold">ACT_</emphasis>. The 
      second part is a two-character identification of the use case of the table. This use case 
      will also roughly match the service API.
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">ACT_RE_*</emphasis>: 'RE' stands for <literal>repository</literal>. 
            Tables with this prefix contain 'static' information such as process definitions and
            process resources (images, rules, etc.).
          </para>
        </listitem>
         <listitem>
          <para>
            <emphasis role="bold">ACT_RU_*</emphasis>: 'RU' stands for <literal>runtime</literal>.
            These are the runtime tables, that contain the runtime data of process instances,
            user tasks, variables, jobs, etc. Activiti only stores the runtime data during process instance
            execution, and removes the records when a process instance ends. This keeps 
            the runtime tables small and fast.
          </para>
        </listitem>
         <listitem>
          <para>
            <emphasis role="bold">ACT_ID_*</emphasis>: 'ID' stands for <literal>identity</literal>.
            These tables contain identity information, such as users, groups, etc.
          </para>
        </listitem>
         <listitem>
          <para>
            <emphasis role="bold">ACT_HI_*</emphasis>: 'HI' stands for <literal>history</literal>.
            These are the tables that contain historic data, such as past process instances,
            variables, tasks, etc.
          </para>
        </listitem>
         <listitem>
          <para>
            <emphasis role="bold">ACT_GE_*</emphasis>: <literal>general</literal> data, which is used
            in various use cases.
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </section>
    
  <section id="databaseUpgrade">
     <title>Database upgrade</title>
     <para>Make sure you make a backup of your database 
     (using your database backup capabilities) before you run an upgrade.
     </para>
     <para>By default, a version check will be performed each time a process engine is created.
     This typically happens once at boot time of your application or of the Activiti webapps.
     If the Activiti library notices a difference between the library version and the version  
     of the Activiti database tables, then an exception is thrown.
     </para> 
     <para>To upgrade, you have to start with putting the following configuration property in your 
     activiti.cfg.xml configuration file:
     </para>
    <programlisting>&lt;beans ... &gt;

  &lt;bean id=&quot;processEngineConfiguration&quot; class=&quot;org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration&quot;&gt;
    &lt;!-- ... --&gt;
    &lt;property name=&quot;databaseSchemaUpdate&quot; value=&quot;true&quot; /&gt;    
    &lt;!-- ... --&gt;
  &lt;/bean&gt;

&lt;/beans&gt;</programlisting>
     <para> <emphasis role="bold">Also, include a suitable database driver for your database to the classpath.</emphasis>
     Upgrade the Activiti libraries in your application. Or start up a new version 
     of Activiti and point it to a database that contains an older version.  With <literal>databaseSchemaUpdate</literal>
     set to <literal>true</literal>, Activiti will automatically upgrade the DB schema to the newer version
     the first time when it notices that libraries and DB schema are out of sync.
     </para>
     <para> <emphasis role="bold">As an alternative you can also run the upgrade DDL statements.</emphasis>
     It's also possible to run the upgrade database scripts, available on the Activiti downloads page.
     </para>
   </section>
  
  <section id="jobExecutorConfiguration">
    <title>Job executor activation</title>
    <para>The <literal>JobExecutor</literal> is a component that manages a couple of threads to fire timers (and later also asynchronous messages).
    For unit testing scenarios, it is cumbersome to work with multiple threads. Therefore the API allows to query for 
    (<literal>ManagementService.createJobQuery</literal>) and execute jobs (<literal>ManagementService.executeJob</literal>) through 
    the API so that job execution can be controlled from within a unit test.  To avoid interference by the job executor, it can be turned off. 
    </para>
    <para> 
    By default, the <literal>JobExecutor</literal> is activated when the process engine boots. Specify
    <programlisting>&lt;property name=&quot;jobExecutorActivate&quot; value=&quot;false&quot; /></programlisting>
    when you don't want the <literal>JobExecutor</literal> to be activated upon booting the process engine.
    </para>
  </section>
  
  <section id="mailServerConfiguration">
    <title>Mail server configuration</title>
    <para>
      Configuring a mail server is optional. Activiti supports sending e-mails in business processes. To actually send an e-mail, a valid
      SMTP mail server configuration is required. See the 
      <link linkend="bpmnEmailTaskServerConfiguration">e-mail task</link> for the configuration options.
    </para>
  </section>
  
  <section id="historyConfiguration">
    <title>History configuration</title>
    <para>
      Customizing the configuration of history storage is optional. This allows you to tweak settings that influence the <link linkend="history">history capabilities</link>
      of the engine. See <link linkend="historyConfig">history configuration</link> for more details.
      <programlisting>&lt;property name=&quot;history&quot; value=&quot;audit&quot; /&gt;</programlisting>
    </para>
  </section>
  
  <section id="exposingConfigurationBeans">
    <title>Exposing configuration beans in expressions and scripts</title>
    <para>By default, all beans that you specify in the <literal>activiti.cfg.xml</literal> configuration 
    or in your own Spring configuration file are available to expressions and in the scripts.
    If you want to limit the visibility of beans in your configuration file, you can 
    configure a property called <literal>beans</literal> in your process engine configuration.
    The beans property in <literal>ProcessEngineConfiguration</literal> is a map. When you specify that property,
    only beans specified in that map will be visible to expressions and scripts.  The exposed beans 
    will be exposed with the names as you specify in that map.  
    </para>
  </section>
  <section id="processDefinitionCacheConfiguration">
    <title>Deployment cache configuration</title>
    <para>All process definition are cached (after they're parsed) to avoid hitting
    the database every time a process definition is needed and because process definition data doesn't change.
    By default, there is no limit on this cache. To limit the process definition cache, add following property
    <programlisting>&lt;property name=&quot;processDefinitionCacheLimit&quot; value=&quot;10&quot; /&gt;</programlisting>
    Setting this property will swap the default hashmap cache with a LRU cache that has the provided hard limit.
    Of course, the 'best' value of this property depends on the total amount of process definitions stored and the number of
    process definitions actually used at runtime by all the runtime process instances.</para>
    <para>You can also inject your own cache implementation. This must be a bean that implements the
    org.activiti.engine.impl.persistence.deploy.DeploymentCache interface:
    <programlisting>
&lt;property name=&quot;processDefinitionCache&quot;&gt;
  &lt;bean class=&quot;org.activiti.MyCache&quot; />
&lt;/property&gt;</programlisting></para>
     <para>There is a similar property called <literal>knowledgeBaseCacheLimit</literal> and <literal>knowledgeBaseCache</literal> for configuring the rules cache.
     This is only needed when you use the rules task in your processes.</para>
    </section>
  
  <section id="loggingConfiguration">
    <title>Logging</title>
    <para>As of Activiti 5.12, SLF4J is used as logging framework, replacing the 
    previous used java.util.logging. All logging (activiti, spring, mybatis, ...) is routed through SLF4J and allows for
    selecting the logging-implementation of your choice.</para>
    <para><emphasis role="bold">By default no SFL4J-binding jar is present in the activiti-engine dependencies, this should be added
    in your project in order to use the logging framework of your choice.</emphasis> If no implementation jar is added, SLF4J will use a NOP-logger,
     not logging anything at all, other than a warning that nothing will be logged. For more info on these bindings <ulink url="http://www.slf4j.org/codes.html#StaticLoggerBinder">http://www.slf4j.org/codes.html#StaticLoggerBinder</ulink>.</para>

    <para>With Maven, add for example a dependency like this (here using log4j), note that you still need to add a version:
    <programlisting>
&lt;dependency&gt;
  &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
  &lt;artifactId&gt;slf4j-log4j12&lt;/artifactId&gt;
&lt;/dependency&gt;</programlisting></para>
    
    <para>The activiti-explorer and activiti-rest webapps are configured to use Log4j-binding. Log4j is also used when running the tests for all the activiti-* modules.</para>
  
    <para>
      <emphasis role="bold">Important note when using a container with commons-logging in the classpath:</emphasis>
      In order to route the spring-logging through SLF4J, a bridge is used (see <ulink url="http://www.slf4j.org/legacy.html#jclOverSLF4J">http://www.slf4j.org/legacy.html#jclOverSLF4J</ulink>). If your container provides a commons-logging implementation,
      please follow directions on this page: <ulink url="http://www.slf4j.org/codes.html#release">http://www.slf4j.org/codes.html#release</ulink> to ensure stability.
    </para>
    <para>
      Example when using Maven (version omitted):
      <programlisting>
&lt;dependency&gt;
  &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
  &lt;artifactId&gt;jcl-over-slf4j&lt;/artifactId&gt;
&lt;/dependency&gt;</programlisting>
    </para>
  </section>
  
    <section id="MDC">
  
  <title>Mapped Diagnostic Contexts</title>
    
    <para> 
        As of version 5.13, activiti supports Mapped Diagnostic Contexts feature of sl4j.
        These basic information are passed to the underlying logger along with what is going to be logged:
      <itemizedlist>
        <listitem>
            <para>
            processDefinition Id as mdcProcessDefinitionID
            </para>        
        </listitem>
          
        <listitem>
        <para>
            processInstance Id as mdcProcessInstanceID
            </para>
        </listitem>
           
        <listitem>
        <para>
            execution Id as mdcexecutionId
        </para>
        </listitem>
      </itemizedlist>
      
      
      None of these information are logged by default. The logger can be configured to show them in desired format, extra to the usual logged messages.
      For example in log4j the following sample layout definition  causes the logger to show the above mentioned information:
     <programlisting>
 log4j.appender.consoleAppender.layout.ConversionPattern =ProcessDefinitionId=%X{mdcProcessDefinitionID}
executionId=%X{mdcExecutionId} mdcProcessInstanceID=%X{mdcProcessInstanceID} mdcBusinessKey=%X{mdcBusinessKey} %m%n"
      </programlisting>
      This is useful where the systems are mission critical and logges should be seriously checked,  by means of a log analyzer for example.
    
    </para>
  </section>  

</chapter>
{'fraction_non_alphanumeric': 0.09597559155653572, 'fraction_numerical': 0.004908219609663886, 'mean_word_length': 2.9676315789473686, 'pattern_counts': {'":': 0, '<': 1119, '<?xml version=': 2, '>': 1123, 'https://': 0, 'lorem ipsum': 0, 'www.': 22, 'xml': 20}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6123681', 'n_tokens_mistral': 16397, 'n_tokens_neox': 15506, 'n_words': 5322}