ProcessEngine Configuration in Activiti

1. Overview

In our previous Activiti with Java intro article, we saw the importance of the ProcessEngine, and created one via the default static API provided by the framework.

Beyond the default, there are other ways of creating a ProcessEngine – which we’ll explore here.

2. Obtaining a ProcessEngine Instance

There are two ways of getting an instance of ProcessEngine :

1. using the ProcessEngines class
2. programmatically, via the ProcessEngineConfiguration

Let’s take a closer look at examples for both of these approaches.

3. Get ProcessEngine using ProcessEngines class

Typically, the ProcessEngine is configured using an XML file called activiti.cfg.xml, with is what the default creation process will use as well.

Here’s a quick example of what this configuration can look like:

<beans xmlns="...">
    <bean id="processEngineConfiguration" class=
      "org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration">
        <property name="jdbcUrl"
          vasentence you have mentioned and also changed thelue="jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000" />
        <property name="jdbcDriver" value="org.h2.Driver" />
        <property name="jdbcUsername" value="root" />
        <property name="jdbcPassword" value="" />
        <property name="databaseSchemaUpdate" value="true" />
    </bean>
</beans>

Notice how the persistence aspect of the engine is configured here.

And now, we can obtain the ProcessEngine:

ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();

4. Get ProcessEngine using ProcessEngineConfiguration

Moving past the default route of obtaining the engine – there are two ways of creating the ProcessEngineConfiguration:

1. Using XML Config
2. Using Java Config

Let’s start with XML configuration.

As mentioned in section 2.1. – we can define the ProcessEngineConfiguration programmatically, and build the ProcessEngine using that instance:

@Test 
void whenCreateDefaultConfiguration_thenGotProcessEngine() {
    ProcessEngineConfiguration processEngineConfiguration 
      = ProcessEngineConfiguration
        .createProcessEngineConfigurationFromResourceDefault();
    ProcessEngine processEngine 
      = processEngineConfiguration.buildProcessEngine();
    
    assertNotNull(processEngine);
}

The method createProcessEngineConfigurationFromResourceDefault() will also look for the activiti.cfg.xml file, and now we only need to call the buildProcessEngine() API.

In this case, the default bean name it looks for is processEngineConfiguration. If we want to change the config file name or the bean name, we can use other available methods for creating the ProcessEngineConfiguration.

Let’s have a look at a few examples.

First, we’ll change the configuration file name and ask the API to use our custom file:

@Test 
void whenGetProcessEngineConfig_thenGotResult() {
    ProcessEngineConfiguration processEngineConfiguration 
      = ProcessEngineConfiguration
        .createProcessEngineConfigurationFromResource(
          "my.activiti.cfg.xml");
    ProcessEngine processEngine = processEngineConfiguration
      .buildProcessEngine();
    
    assertNotNull(processEngine);
}

Now, let’s also change the bean name:

@Test 
void whenGetProcessEngineConfig_thenGotResult() {
    ProcessEngineConfiguration processEngineConfiguration 
      = ProcessEngineConfiguration
        .createProcessEngineConfigurationFromResource(
          "my.activiti.cfg.xml", 
          "myProcessEngineConfiguration");
    ProcessEngine processEngine = processEngineConfiguration
      .buildProcessEngine();
    
    assertNotNull(processEngine);
    assertEquals("root", processEngine.getProcessEngineConfiguration()
      .getJdbcUsername());
}

Of course, now that the configuration is expecting different names, we need to change the filename (and the bean name) to match – before running the test.

Other available options to create the engine are createProcessEngineConfigurationFromInputStream(InputStream inputStream),
createProcessEngineConfigurationFromInputStream(InputStream inputStream, String beanName).

If we don’t want to use XML config, we can also set things up using Java config only.

We’re going to work with four different classes; each of these represents a different environment:

1. org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration – the ProcessEngine is used in a standalone way, backed by the DB
2. org.activiti.engine.impl.cfg.StandaloneInMemProcessEngineConfiguration – by default, an H2 in-memory database is used. The DB is created and dropped when the engine starts and shuts down – hence, this configuration style can be used for testing
3. org.activiti.spring.SpringProcessEngineConfiguration – to be used in Spring environment
4. org.activiti.engine.impl.cfg.JtaProcessEngineConfiguration – the engine runs in standalone mode, with JTA transactions

Let’s take a look at a few examples.

Here is a JUnit test for creating a standalone process engine configuration:

@Test 
void whenCreateProcessEngineConfig_thenCreated() {
    ProcessEngineConfiguration processEngineConfiguration 
      = ProcessEngineConfiguration
        .createStandaloneProcessEngineConfiguration();
    ProcessEngine processEngine = processEngineConfiguration
      .setDatabaseSchemaUpdate(ProcessEngineConfiguration
        .DB_SCHEMA_UPDATE_TRUE)
      .setJdbcUrl("jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000")
      .buildProcessEngine();
    
    assertNotNull(processEngine);
    assertEquals("sa", processEngine.getProcessEngineConfiguration()
      .getJdbcUsername());
}

Similarly, we’ll write a JUnit test case for creating the standalone process engine configuration using the in-memory database:

@Test 
void whenCreateInMemProcessEngineConfig_thenCreated() {
    ProcessEngineConfiguration processEngineConfiguration 
      = ProcessEngineConfiguration
      .createStandaloneInMemProcessEngineConfiguration();
    ProcessEngine processEngine = processEngineConfiguration
      .buildProcessEngine();
    
    assertNotNull(processEngine);
    assertEquals("sa", processEngine.getProcessEngineConfiguration()
      .getJdbcUsername());
}

5. Database Setup

By default, Activiti API will use the H2 in-memory database, with database name “activiti” and username “sa”.

If we need to use any other database, we’ll have to set things up explicitly – using two main properties.

databaseType – valid values are h2, mysql, oracle, postgres, mssql, db2. This can also be figured out from the DB configuration but will be useful if automatic detection fails.

databaseSchemaUpdate – this property allows us to define what happens to the database when the engine boots up or shuts down. It can have these three values:

1. false (default) – this option validates the version of database schema against the library. The engine will throw an exception if they do not match
2. true – when the process engine configuration is built, a check is performed on the database. The database will be created/updated create-drop accordingly
3. “–” – this will create the DB schema when the process engine is created and will drop it when the process engine shuts down.

We can define the DB configuration as JDBC properties:

<property name="jdbcUrl" value="jdbc:h2:mem:activiti;DB_CLOSE_DELAY=1000" />
<property name="jdbcDriver" value="org.h2.Driver" />
<property name="jdbcUsername" value="sa" />
<property name="jdbcPassword" value="" />
<property name="databaseType" value="mysql" />

Alternatively, if we are using DataSource:

<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" >
    <property name="driverClassName" value="com.mysql.jdbc.Driver" />
    <property name="url" value="jdbc:mysql://localhost:3306/activiti" />
    <property name="username" value="activiti" />
    <property name="password" value="activiti" />
    <property name="defaultAutoCommit" value="false" />
    <property name="databaseType" value="mysql" />
</bean>

6. Conclusion

In this quick tutorial, we focused on several different ways of creating ProcessEngine in Activiti.

We also saw different properties and approaches to handle database configuration.

As always, the code for examples we saw can be found over on GitHub.