Activiti Enterprise Developer Series - Setting up an Extension Project

[gravitonian]

Table of Contents          

• Introduction
• Source Code
• Prerequisites
  • Java Development Kit (JDK)
  • Apache Maven
• Creating the Activiti Extension Project
• Building the Activiti Extension Project
• Installing the Activiti Extension JAR

Introduction

Most customizations developed for Alfresco Activiti will require an extension project that produces a JAR that can be added to the application server’s classpath. These are for example Java customizations such as service tasks, task and execution listeners, custom REST APIs etc.

All the artifacts (i.e. JAR files) that make up the Activiti Enterprise server and its extension points are available in Alfresco’s Nexus repo accessible at https://artifacts.alfresco.com. To bring them into the extension project Apache Maven’s dependency management is used.

The project structure that is used in the Activiti Extension project is based on maven’s standard directory layout. So, as you might have figured out, the Activiti Extension project is based completely on Maven and Java.

Source Code

Source code for the Activiti Developer Series can be found here.

Prerequisites

This section covers the tools needed to work with the Activiti Extension project.

Java Development Kit (JDK)

This section steps you through installing the JDK and verifying its installation. There are no prerequisites for this installation. To use the Activiti Extension project most effectively, and to align with what JDK is used by the Activiti Enterprise versions, you need to have Oracle JDK 1.8 installed. Note that Maven requires that the JDK be installed - the Java run-time alone is not sufficient.

Checking for the availability of the JDK:

1. Check if you have the JDK already installed. Go to your command line and type the following command:
   1. javac -version   
2. You will see a message such as the following, if you have the JDK installed:
   1. javac 1.8.0_91                   
3. Important: make sure you use javac when you test if JDK is installed and not java, which tests if the JRE is installed.
4. If you get "command not found" you need to install the JDK. Also if you have a version of the JDK prior to 1.8 you will need to install 1.8 or above. It is possible to have multiple versions of the JDK installed (and multiple Java run-times). You will later see how you can configure your JAVA_HOME variable so that Maven uses the correct version of the JDK.

Downloading the JDK:

1. Download the JDK from the Oracle JDK site.

Installing the JDK:

1. Carefully review the Oracle JDK 8 installation guide as appropriate for your system.
2. Install the JDK, following the Oracle instructions.

Verifying the JDK is successfully installed:

1. Go to your command line and type the following command:
   1. javac -version
2. This will display information such as the following:
   1. javac 1.8.0_91                   
3. To be extra sure you should also check your Java run-time by entering the following command:
   1. java -version                   
4. This will display information such as the following:
   1. java version "1.8.0_91"

Java(TM) SE Runtime Environment (build 1.8.0_91-b14)

Java HotSpot(TM) 64-Bit Server VM (build 25.91-b14, mixed mode)    

1. Double check that the version of Java installed is correct (1.8).

Setting JAVA_HOME:

Before using Maven and the Activiti Extension project, you need to set your JAVA_HOME environment variable to a suitable value, using the correct mechanism for your operating system.

Setting the JAVA_HOME environment variable ensures that the correct JDK is accessed. This is especially important where you have multiple JDKs installed on your system.

Mac OS X:

1. On Mac OS X you can edit your .bash_profile file and add something similar to the following (the exact version you are using may vary):
   1. export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_91.jdk/Contents/Home
2. Restart the terminal session or run source .bash_profile to activate the environment variable.
3. Important: Note that the actual value you specify here will depend on which JDK you have installed, and the associated directory name.

Linux:

1. On Linux you can edit your .bashrc file and add something similar to the following:
   1. export JAVA_HOME=/usr/lib/jvm/java-8-oracle
2. Restart the terminal session or run source .bashrc to activate the environment variable.
3. Important: Note that the actual value you specify here will depend on which JDK you have installed, and the associated directory name.

Windows:

1. On Windows, the exact procedure for setting environment variables varies depending on the version of Windows you are running. For example, the procedure for Windows XP can be found in the Microsoft Knowledgebase.

Verify JAVA_HOME setting:

1. Ensure that the JAVA_HOME environment variable is set correctly, using a method suitable for your system. For example, on Mac OS X and Linux you can enter the following command:
   1. $ env |grep JAVA_HOME
      JAVA_HOME=/usr/lib/jvm/java-8-oracle                  
2. You will see the value that JAVA_HOME has been set to.
3. Ensure that the result matches the value you specified in your shell configuration file (such as .bashrc).
4. If you are on Windows you can use a command such as SET J to display environment variables starting with 'J'.

Apache Maven

The Activiti Extension project is based on Apache Maven. To use it you need to have Maven installed. To be able to use Maven you need to have a suitable JDK installed. For this version of the extension project you should have JDK 1.8 installed. Maven version 3.2.5 or above is required.

Check for the availability of Maven:

1. First, check to see if you already have the correct version of Maven installed. On your command line enter the following command:
   1. mvn --version          
2. If you get "command not found", or you have a version of Maven prior to 3.2.5, you will need to install Maven or upgrade to 3.2.5 or above. In this case it is recommended you download the latest version of Maven from the official Maven website.

Downloading Maven:

1. Download Maven from the Apache Maven project web site.

Installing Maven:

1. Carefully review the platform-specific installation instructions in the Installing Maven Sonatype documentation.
2. Install Maven using the platform-specific instructions provided in the Maven documentation.

Verifying Maven is correctly installed:

1. Run the following command to verify Maven is correctly installed:
   1. mvn --version                  
2. This will display information such as the following:
   1. Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T12:57:37+01:00)

Maven home: /home/martin/apps/apache-maven-3.3.3

Java version: 1.8.0_91, vendor: Oracle Corporation

Java home: /usr/lib/jvm/java-8-oracle/jre

Default locale: en_GB, platform encoding: UTF-8

OS name: "linux", version: "4.2.0-42-generic", arch: "amd64", family: "unix"

1. Check that the correct versions of Maven and the JDK are being used. If Maven is not using the correct version of the JDK, make sure you have set your JAVA_HOME environment variable as described in the previous tutorial.

Setting MAVEN_OPTS and M2:

The MAVEN_OPTS and M2_HOME environment variables also need to be set to suitable values using the correct mechanism for your operating system. Setting M2_HOME specifies the home of Maven and is used by the script mvn (or mvn.bat on Windows). MAVEN_OPTS is used to configure a bit of extra memory for Maven when needed and it is also used to set up any Java Agents (e.g. JRebel) for things like class reloading.

Mac OS X:

1. On Mac OS X you can edit your .bash_profile file and add the following:
   1. export M2_HOME=/home/martin/apps/apache-maven-3.3.3
      export MAVEN_OPTS="-Xms1024m -Xmx1G"
2. Important: refer to previous installation sections for in what directory Maven was installed.
3. Restart the terminal session or run source .bash_profile to activate the environment variables.

Linux:

1. On Linux you can edit your .bashrc file and add the following:
2. See step 1 for Mac OS, do the same thing for Linux.
3. Restart the terminal session or run source .bashrc to activate the environment variable.

Windows:

1. On Windows, the exact procedure for setting environment variables varies depending on the version of Windows you are running. For example, the procedure for Windows XP can be found in the Microsoft Knowledgebase.
   1. set M2_HOME=C:\Tools\apache-maven-3.3.1
      set MAVEN_OPTS=-Xms256m -Xmx1G
2. Important: refer to previous installation sections for in what directory Maven was installed.
3. Restart the Windows terminal/console session.

Verifying Variables:

1. Ensure that the MAVEN_OPTS and M2_HOME environment variables are set correctly, using a method suitable for your system. For example, on Mac OS X and Linux you can enter the following command:
   1. $ env|egrep "M2|MAV"
      MAVEN_OPTS=-Xms256m -Xmx1G

M2_HOME=/home/martin/apps/apache-maven-3.3.3

1. Ensure that the result matches the value you specified in your shell configuration file (such as .bashrc).
2. If you are on Windows you can use a command such as set M to display environment variables starting with 'M'.
   1. C:\Users\mbergljung>set M
      M2_HOME=C:\Tools\apache-maven-3.3.1
      MAVEN_OPTS=-Xms256m -Xmx1G

Your MAVEN_OPTS and M2_HOME environment variables are now set. Feel free to increase the specified memory settings if required, for example, if you get "out of memory" errors when building your projects.

Creating the Activiti Extension Project

We are now ready to create the actual Activiti Extension project. Create a directory to hold your project, for example activiti-extension-jar. Then create a Maven pom.xml file in this directory with the following content:

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

       xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>com.activiti.extension</groupId>

  <artifactId>activiti-extension-jar</artifactId>

  <version>1.0-SNAPSHOT</version>

  <name>Activiti Extension Module</name>

  <description>Activiti Extension Module that produces a JAR file with Java extensions such as service task delegates.</description>

  <packaging>jar</packaging>

  <properties>

      <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

      <!-- Properties used in dependency declarations -->

      <activiti.groupId>com.activiti</activiti.groupId>

      <activiti.version>1.5.1</activiti.version>

      <activiti.engine.version>5.21.0.2</activiti.engine.version>

      <!-- Compile with Java 8, default is 5 -->

      <maven.compiler.source>1.8</maven.compiler.source>

      <maven.compiler.target>1.8</maven.compiler.target>

  </properties>

  <dependencies>

      <!-- The main Activiti Enterprise application dependency that brings in all

           needed classes to compile your customizations -->

      <dependency>

          <groupId>${activiti.groupId}</groupId>

          <artifactId>activiti-app-logic</artifactId>

          <version>${activiti.version}</version>

      </dependency>

      <!-- Testing -->

      <dependency>

          <groupId>junit</groupId>

          <artifactId>junit</artifactId>

          <version>4.11</version>

          <scope>test</scope>

      </dependency>

  </dependencies>

  <build>

      <resources>

          <!-- Filter the resource files in this project and

do property substitutions -->

          <resource>

              <directory>src/main/resources</directory>

              <filtering>true</filtering>

          </resource>

      </resources>

      <testResources>

          <!-- Filter the test resource files in this project and

do property substitutions -->

          <testResource>

              <directory>src/test/resources</directory>

              <filtering>true</filtering>

          </testResource>

      </testResources>

  </build>

  <!--

      Alfresco Maven Repositories

      -->

  <repositories>

      <!-- Activiti Enterprise Edition Artifacts,

put username/pwd for server in settings.xml -->

      <repository>

          <id>activiti-private-repository</id>

<url>https://artifacts.alfresco.com/nexus/content/repositories/activiti-enterprise-releases</url>

      </repository>

  </repositories>

</project>

Then create the following project directory structure:

src/activiti-extension-jar$ tree

.

├── pom.xml

└── src

   ├── main

   │   ├── java

   │   │   └── com

   │   │       └── activiti

   │   │           └── extension

   │   │               ├── bean

   │   │               └── conf

   │   └── resources

   └── test

       └── java

           └── com

               └── activiti

                   └── extension

                       └── bean

The different packages that we use for Java classes are important as only some packages are scanned by Activiti, such as the com.activiti.extension.bean package, which is scanned for Spring beans implementing things like service tasks and task listeners. And the com.activiti.extension.conf package, which is scanned for new Spring context configurations. So it is good practice to use these packages as a starting point.

Building the Activiti Extension Project

We now have an Activiti extension project based on Apache Maven. To build it we would execute the following command:

~/src/activiti-extension-jar$ mvn clean install

[INFO] Scanning for projects...

[INFO]                                                                         

[INFO] ------------------------------------------------------------------------

[INFO] Building Activiti Extension Module 1.0-SNAPSHOT

[INFO] ------------------------------------------------------------------------

Downloading:

...

[INFO]

[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ activiti-extension-jar ---

[INFO]

[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ activiti-extension-jar ---

[INFO] Using 'UTF-8' encoding to copy filtered resources.

[INFO] Copying 0 resource

[INFO]

[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ activiti-extension-jar ---

[INFO] Nothing to compile - all classes are up to date

[INFO]

[INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ activiti-extension-jar ---

[INFO] Using 'UTF-8' encoding to copy filtered resources.

[INFO] skip non existing resourceDirectory /home/martin/src/activiti-extension-jar/src/test/resources

[INFO]

[INFO] --- maven-compiler-plugin:3.1:testCompile (default-testCompile) @ activiti-extension-jar ---

[INFO] Nothing to compile - all classes are up to date

[INFO]

[INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ activiti-extension-jar ---

[INFO] No tests to run.

[INFO]

[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ activiti-extension-jar ---

[INFO] Building jar: /home/martin/src/activiti-extension-jar/target/activiti-extension-jar-1.0-SNAPSHOT.jar

[INFO]

[INFO] --- maven-install-plugin:2.4:install (default-install) @ activiti-extension-jar ---

[INFO] Installing /home/martin/src/activiti-extension-jar/target/activiti-extension-jar-1.0-SNAPSHOT.jar to /home/martin/.m2/repository/com/activiti/extension/activiti-extension-jar/1.0-SNAPSHOT/activiti-extension-jar-1.0-SNAPSHOT.jar

[INFO] Installing /home/martin/src/activiti-extension-jar/pom.xml to /home/martin/.m2/repository/com/activiti/extension/activiti-extension-jar/1.0-SNAPSHOT/activiti-extension-jar-1.0-SNAPSHOT.pom

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 3.159 s

[INFO] Finished at: 2016-10-27T09:24:40+01:00

[INFO] Final Memory: 23M/381M

[INFO] ------------------------------------------------------------------------

This builds the project, creates the JAR, and installs the JAR into the local Maven repo at the following location:

martin@gravitonian:~/.m2/repository/com/activiti/extension/activiti-extension-jar/1.0-SNAPSHOT$ ls -l

total 16

-rw-rw-r-- 1 martin martin 2291 Oct 27 09:24 activiti-extension-jar-1.0-SNAPSHOT.jar

-rw-rw-r-- 1 martin martin 2718 Oct 27 09:21 activiti-extension-jar-1.0-SNAPSHOT.pom

-rw-rw-r-- 1 martin martin  724 Oct 27 09:24 maven-metadata-local.xml

-rw-rw-r-- 1 martin martin  217 Oct 27 09:24 _remote.repositories

The JAR is also available in the project’s target directory:

martin@gravitonian:~/src/activiti-extension-jar/target$ ls -l

total 16

-rw-rw-r-- 1 martin martin 2291 Oct 27 09:24 activiti-extension-jar-1.0-SNAPSHOT.jar

You can copy the JAR from any of these locations into the classpath of your Activiti Enterprise server installation.

Installing the Activiti Extension JAR

Now that we got an Activiti Extension JAR, how do we get the Activiti Enterprise server to know about it. We put it on the server’s classpath. Let’s say that our Activiti Enterprise server is installed into the /opt/activiti15 directory. Then we need to put the extension JAR into the /opt/activiti15/tomcat/webapps/activiti-app/WEB-INF/lib (important: it does not work to put the JAR into tomcat/lib):

martin@gravitonian:/opt/activiti15/tomcat/webapps/activiti-app/WEB-INF/lib$ cp ~/src/activiti-extension-jar/target/activiti-extension-jar-1.0-SNAPSHOT.jar .

After we have copied the file into the classpath we need to restart the Activiti server so it has a chance to read the new JAR:

martin@gravitonian:/opt/activiti15$ /opt/activiti15/tomcat/bin/catalina.sh stop

martin@gravitonian:/opt/activiti15$ /opt/activiti15/h2/stop-h2.sh

martin@gravitonian:/opt/activiti15$ ./start-activiti.sh

The server is now aware of the new classes in the extension JAR and we can start using them in our process definitions.