Thursday, August 14, 2014

Top 3 Ways Developers Build Projects Against JBoss BPM Suite

In this weeks tips & tricks series we introduce some of the more technical aspects of working with JBoss BRMS and JBoss BPM Suite products by showing you the top three ways that you as a developer can build your projects against  projects that the business users create with JBoss BPM Suite (or JBoss BRMS).

The developer in all of us is not always interested in staying within the confines of the beautiful Business Central web dashboard as provided, but is working from our favorite IDE to build the applications that leverage the work from our business user.

We expect to clone the project the business user created and build it from scratch, or we want to embed this a project dependency and run our project against the product artifacts available to us in the JBoss central maven repositories.

We also might not trust our business users and want to create, run, and analyse some unit tests to confirm that this stuff we depend on is working properly.

All these actions rely on us understanding what product artifacts we need, how the business user projects build within their product dashboard, and how to build them outside of the product when we clone these projects.

For this article, we will be using the Customer Evaluation Demo project as our running example, where you can find the various aspects of this in the project hosted on github.com.

1. Depending on Business Central projects

When business users login and create a project with rules, event, and/or processes it results in a Knowledge JAR (KJAR) after they build it. This KJAR is just a Maven artifact JAR file that is put into the local repository by default but can be configured to point to any valid Maven repository.

As a developer you want to use this as a dependency in your project, so how does this work?

We need to point to our development project's pom.xml file at the proper business user project that will be built from the JBoss BPM Suite, using the Customer Evaluation demo project. If you look into that project you will find a pom.xml that does just that: bpms-customer-evaluation-demo/projects/customer-evaluation-demo/pom.xml.

Locate the code snippet from the pom.xml below to see how the project is added to your development projects dependencies.

# Add this to your development projects pom.xml file as shown to depend on the 
# customer evaluation project build version 1.0.
#
<!-- KJar file from project. -->
<dependency>
  <groupId>customer</groupId>
  <artifactId>evaluation</artifactId>
  <version>1.0</version>
  <scope>compile</scope>
</dependency>

Next up we look at how you can add the central JBoss maven repository and make use of the latest JBoss BPM Suite product dependencies.

2. JBoss BPM Suite Maven dependencies

The JBoss maven repository is used as shown below which will point to the latest product version we want to use, at the time of this writing it was JBoss BPM Suite 6.0.2:

# Add this to your pom.xml as shown, or modify (exercise left to the reader)
# to add into your .m2/settings.xml file. 
#
<repositories>
  <repository>
    <id>jboss-maven-repository</id>
    <name>JBoss Maven Repository</name>
    <url>http://maven.repository.redhat.com/techpreview/all/</url>
    <layout>default</layout>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>never</updatePolicy>
    </releases>
    <snapshots>
      <enabled>false</enabled>
      <updatePolicy>never</updatePolicy>
    </snapshots>
  </repository>
</repositories>

Next we want to setup a unit test that will exercise our rules, events, and process project.

You can find this in the Customer Evaluation demo project setup with maven dependencies using a central pom.xml property to point to the artifact version we are currently using. Next we need a product dependency to unit test our code.

# Add this to your development projects pom.xml as shown to make use of the
# product base artifacts to create unit tests.
#
<properties>
  <bpm-suite-version>6.0.0-redhat-5</bpm-suite-version>
</properties>

<dependencies>
  <!-- Test dependencies. -->
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.10</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-test</artifactId>
    <version>${bpm-suite-version}</version>
    <scope>test</scope>
  </dependency>

  <!-- Backwards compatible BRMS 5 API -->
  <dependency>
    <groupId>org.drools</groupId>
    <artifactId>knowledge-api</artifactId>
    <version>${bpm-suite-version}</version>
    <scope>compile</scope>
  </dependency>

  <!-- KJar file from project. -->
  <dependency>
    <groupId>customer</groupId>
    <artifactId>evaluation</artifactId>
    <version>1.0</version>
    <scope>compile</scope>
  </dependency>
</dependencies>

Business Central project pom file.
Next up and the final section, how to build business user projects as they are cloned directly from the JBoss BPM Suite product's internal git repository.

3. Building projects outside Business Central

Once you have a business user project completed as shown above with the Customer Evaluation demo, you want to clone this over SSH following this previous article (link).

# Cloning the business users customer evaluation demo project from the 
# command line.
#
$ git clone ssh://erics@localhost:8001/customer
Cloning into 'customer'...
The authenticity of host '[localhost]:8001 ([127.0.0.1]:8001)' can't be established.
DSA key fingerprint is ef:51:d6:ec:7f:ce:8b:e1:b6:a1:96:5e:6a:cf:d3:f8.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[localhost]:8001' (DSA) to the list of known hosts.
Password authentication
Password: 

remote: Counting objects: 602, done
remote: Finding sources: 100% (602/602)
remote: Getting sizes: 100% (466/466)
remote: Compressing objects: 100% (118792/118792)
remote: Total 602 (delta 24), reused 72 (delta 21)
Receiving objects: 100% (602/602), 60.23 KiB, done.
Resolving deltas: 100% (344/344), done.

$ cd customer/evaluation/
$ ls -l
total 16
drwxr-xr-x  32 erics  501  1088 Aug 13 17:36 global
-rw-r--r--   1 erics  501   990 Aug 13 17:36 pom.xml
-rw-r--r--   1 erics  501    97 Aug 13 17:36 project.imports
drwxr-xr-x   4 erics  501   136 Aug 13 17:36 src

# When we try to build it breaks on the strange kie-maven-plugin
# found in the pom.xml.
#
$ mvn install
[INFO] Scanning for projects...
Downloading: http://repo.maven.apache.org/maven2/org/kie/kie-maven-plugin/6.0.3-redhat-4/kie-maven-plugin-6.0.3-redhat-4.pom
[WARNING] The POM for org.kie:kie-maven-plugin:jar:6.0.3-redhat-4 is missing, no dependency information available
Downloading: http://repo.maven.apache.org/maven2/org/kie/kie-maven-plugin/6.0.3-redhat-4/kie-maven-plugin-6.0.3-redhat-4.jar
Downloading: http://repo.maven.apache.org/maven2/org/codehaus/plexus/plexus-utils/1.1/plexus-utils-1.1.jar
Downloaded: http://repo.maven.apache.org/maven2/org/codehaus/plexus/plexus-utils/1.1/plexus-utils-1.1.jar (165 KB at 148.8 KB/sec)
[ERROR] The build could not read 1 project -> [Help 1]
[ERROR]   
[ERROR]   The project customer:evaluation:1.0 (/Users/erics/demo-projects/bpms6/bpms-customer-evaluation-demo/support/customer/evaluation/pom.xml) has 2 errors
[ERROR]     Unresolveable build extension: Plugin org.kie:kie-maven-plugin:6.0.3-redhat-4 or one of its dependencies could not be resolved: Could not find artifact org.kie:kie-maven-plugin:jar:6.0.3-redhat-4 in central (http://repo.maven.apache.org/maven2) -> [Help 2]
[ERROR]     Unknown packaging: kjar @ line 8, column 14
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/ProjectBuildingException
[ERROR] [Help 2] http://cwiki.apache.org/confluence/display/MAVEN/PluginResolutionException

Once cloned you will notice that the project will not build locally due to missing dependencies that the kie-maven-plugin needs. If you add them locally to the pom.xml it will build locally but these are managed internally to the product when the business user builds from within business central.

It is suggested to not push these changes back into the repository, but to only use them externally. Once you do this and add the JBoss maven repository, it will build outside of the business central GUI tooling.

# Add repositories and plugins for maven central to the pom.xml.
#
<repositories>
  <repository>
    <id>jboss-maven-repository</id>
    <name>JBoss Maven Repository</name>
    <url>http://maven.repository.redhat.com/techpreview/all/</url>
    <layout>default</layout>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>never</updatePolicy>
    </releases>
    <snapshots>
      <enabled>false</enabled>
      <updatePolicy>never</updatePolicy>
    </snapshots>
  </repository>
</repositories>
<pluginRepositories>
  <pluginRepository>
    <id>jboss-maven-repository</id>
    <name>JBoss Maven Repository</name>
    <url>http://maven.repository.redhat.com/techpreview/all/</url>
    <layout>default</layout>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>never</updatePolicy>
    </releases>
    <snapshots>
      <enabled>false</enabled>
      <updatePolicy>never</updatePolicy>
    </snapshots>
  </pluginRepository>
</pluginRepositories>

# Add the dependencies needed.
#
<dependencies>
  <dependency>
    <groupId>org.kie</groupId>
    <artifactId>kie-api</artifactId>
    <version>6.0.3-redhat-4</version>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>org.jbpm</groupId>
    <artifactId>jbpm-bpmn2</artifactId>
    <version>6.0.3-redhat-4</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

# Now you can build it in your IDE.
#
$ mvn package
[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building customer-evaluation 1.0
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ evaluation ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 11 resources
[INFO] 
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ evaluation ---
[INFO] Changes detected - recompiling the module!
[WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
[INFO] Compiling 2 source files to /Users/erics/demo-projects/bpms6/bpms-customer-evaluation-demo/support/customer/evaluation/target/classes
[INFO] 
[INFO] --- kie-maven-plugin:6.0.3-redhat-4:build (default-build) @ evaluation ---
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
[INFO] KieModule successfully built!
[INFO] 
[INFO] --- maven-compiler-plugin:3.1:testCompile (default-testCompile) @ evaluation ---
[INFO] Nothing to compile - all classes are up to date
[INFO] 
[INFO] --- maven-surefire-plugin:2.17:test (default-test) @ evaluation ---
[INFO] No tests to run.
[INFO] 
[INFO] --- maven-jar-plugin:2.5:jar (default-jar) @ evaluation ---
[INFO] Building jar: /Users/erics/demo-projects/bpms6/bpms-customer-evaluation-demo/support/customer/evaluation/target/evaluation-1.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7.086s
[INFO] Finished at: Wed Aug 13 17:56:33 CEST 2014
[INFO] Final Memory: 36M/447M
[INFO] ------------------------------------------------------------------------

Hopefully this will get you started when you are attempting to integrate your development project with the various possibilities offered by the JBoss BPM Suite (and JBoss BRMS) product.