Chapter 5. Deployment

jPDL is an embeddable BPM engine, which means that you can take the jPDL libraries and embed it into your own Java project, rather then installing a separate product and integrate with it. One of the key aspects that make this possible is minimizing the dependencies. This chapter discusses the jbpm libraries and their dependencies.

5.1. jBPM libraries

jbpm-jpdl.jar is the library with the core jpdl functionality.

jbpm-identity.jar is the (optional) library containing an identity component as described in Section 12.11, “The identity component”.

5.2. Java runtime environment

jBPM 3 requires J2SE 1.4.2+

5.3. Third party libraries

All the libraries on which jPDL might have a dependency, are located in the lib directory.

In a minimal deployment, you can create and run processes with jBPM by putting only the commons-logging and dom4j library in your classpath. Beware that persisting processes to a database is not supported. The dom4j library can be removed if you don't use the process xml parsing, but instead build your object graph programatically.

Table 5.1. 

LibraryUsageDescription
commons-logging.jarlogging in jbpm and hibernateThe jBPM code logs to commons logging. The commons logging library can be configured to dispatch the logs to e.g. java 1.4 logging, log4j, ... See the apache commons user guide for more information on how to configure commons logging. if you're used to log4j, the easiest way is to put the log4j lib and a log4j.properties in the classpath. commons logging will automatically detect this and use that configuration.
dom4j.jarprocess definitions and hibernate persistencexml parsing

A typical deployment for jBPM will include persistent storage of process definitions and process executions. In that case, jBPM does not have any dependencies outside hibernate and its dependent libraries.

Of course, hibernate's required libraries depend on the environment and what features you use. For details refer to the hibernate documentation. The next table gives an indication for a plain standalone POJO development environment.

Table 5.2. 

LibraryUsageDescription
hibernate3.jarhibernate persistencethe best O/R mapper
antlr-2.7.6rc1.jarused in query parsing by hibernate persistenceparser library
cglib.jarhibernate persistencereflection library used for hibernate proxies
commons-collections.jarhibernate persistence 
asm.jarhibernate persistenceasm byte code library

The beanshell library is optional. If you don't include it, you won't be able to use the beanshell integration in the jBPM process language and you'll get a log message saying that jbpm couldn't load the Script class and hence, the script element won't be available.

Table 5.3. 

LibraryUsageDescription
bsh.jarbeanshell script interpreterOnly used in the script's and decision's. When you don't use these process elements, the beanshell lib can be removed, but then you have to comment out the Script.hbm.xml mapping line in the hibernate.cfg.xml

5.4. Web application

In the deploy directory of the downloads, you can find jbpm-console.war. That web console contains the jPDL libraries, configuration files and the required libraries to run this web application on JBoss.

This war file does NOT include the hibernate libraries. That is because JBoss already includes the hibernate libraries. To run this webapplication on other servers like Tomcat, all you have to do is get the hibernate libraries in the WEB-INF/lib directory in the war file. Simplest way to do that is to use the ant build script in this directory.

Also, this war file can give you a good indication of how you could deploy jbpm libraries and configuration files into your own web application.

In the web.xml of this web application, the JobExecutorServlet is configured. This will start the JobExecutor when the jbpm-console.war is deployed. The JobExecutor serves as the basis for executing timers and asynchronous messages on the standard java platform.

5.5. Enterprise archive

In the deploy directory of the downloads, you can find jbpm-enterprise.ear. That J2EE 1.4 compliant enterprise archive includes: jPDL libraries, jBPM configuration files, the jBPM web console, and a couple of enterprise beans. In this package, jBPM is configured for usage in an application server like JBoss. The asynchronous messaging service is here bound to JMS and the scheduler service is bound to the EJB Timer Service. So here in this .ear file, no JobExecutor is started. The persistence service is configured to participate in the overall JTA transaction.

Within the enterprise archive there are the following files:

  • jbpm-console.war: the console web application, adapted for J2EE integration
  • jbpm-enterprise.jar: the supporting enterprise beans
  • lib/jbpm-configs.jar: configuration files
  • lib/jbpm-identity.jar: identity component classes
  • lib/jbpm-jpdl.jar: standard jPDL classes
  • meta-inf/application.xml: J2EE app descriptor

jbpm-enterprise.jar contains the following EJB components:

  • CommandServiceBean
  • CommandListenerBean
  • JobListenerBean
  • TimerEntityBean

These beans are J2EE 1.4 / EJB 2.1 compliant, to allow them to be deployed on a variety of application servers. Note however that jBPM only provides deployment descriptors for JBoss Application Server. All beans are deployed with the transaction-attribute Required. The source for the EJB classes and interfaces is in src/enterprise and the javadocs in doc/javadoc-enterprise. A detailed description can be found in Section 9.1, “Enterprise Beans”.

jbpm-configs.jar contains the following files:

  • jbpm.cfg.xml: the jBPM configuration
  • hibernate.cfg.xml: the Hibernate configuration
  • jbpm.mail.templates.xml: the e-mail templates

Sections Section 9.2, “jBPM Enterprise Configuration” and Section 9.3, “Hibernate Enterprise Configuration” examine the enterprise-specific settings in the first two files. The last file is described in Section 17.4, “Mail templates”.

5.6. The jPDL Runtime and Suite

5.6.1. The runtime

The jPDL runtime is all you need to get started with jPDL: jpdl libraries, third party libraries, examples and documentation. It doesn't include the graphcal designer and web console tooling, which is added in the suite package.

Table 5.4. jPDL runtime directories

DirectoryContent
configContains all the configuration files. Note that for easy testing and development, the current hibernate configuration points to the in-memory jbpm database.
dbContains the scripts to create the jPDL tables in your DB. It includes a copy of the wiki page about database compatibility.
docContains the userguide and the javadocs for the jpdl sources and identity sources
examplesEach example is a separate project that you can compile and run with ant or eclipse.
libAll the third party libs and their licenses.
srcThe sources for jpdl and the identity components.

5.6.2. The suite

The jPDL suite is an extension of the jPDL runtime with 2 tools: a graphical designer plugin for eclipse and a JBoss server that is preconfigured with a deployed version of the jPDL runtime and console webapp. The included tools are all preconfigured to work nicely together out of the box.

Table 5.5. jPDL suite extra directories

DirectoryContent
designerThe designer is the eclipse plugin that alows for graphical process editing of jPDL process files. Look in the designer/readme.html for more instructions on installing the designer.
serverThe server is actually a JBoss application server which has the jPDL runtime and the jPDL console web application deployed.

5.6.3. Configuring the logs in the suite server

If you want to see debug logs in the suite server, update file jpdl-suite-home/server/server/jbpm/config/log4j.xml Look for

   <!-- ============================== -->
   <!-- Append messages to the console -->
   <!-- ============================== -->

   <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
      <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
      <param name="Target" value="System.out"/>
      <param name="Threshold" value="INFO"/>

And in param Threshold, change INFO to DEBUG.

Then you'll get debug logs of all the components. To limit the number of debug logs, look a bit further down that file until you see 'Limit categories'. You might want to add tresholds there for specific packages like e.g.

   <category name="org.hibernate">
      <priority value="INFO"/>
   </category>

   <category name="org.jboss">
      <priority value="INFO"/>
   </category>

5.6.4. Debugging a process in the suite

First of all, in case you're just starting to develop a new process, it is much easier to use plain JUnit tests and run the process in memory like explained in Chapter 3, Tutorial.

But if you want to run the process in the console and debug it there here are the 2 steps that you need to do:

1) in jpdl-suite-home/server/server/bin/run.bat, somewhere at the end, there is a line like this:

rem set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%

For backup reasons, just start by making a copy of that line, then remove the first 'rem' and change suspend=y to suspend=n. Then you get something like

rem set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%
set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n %JAVA_OPTS%

2) In your IDE debug by connecting to a remote Java application on localhost on port 8787. Then you can start adding break points and run through the processes with the console until the breakpoint is hit.