Eric D. Schabell: March 2010

Wednesday, March 24, 2010

jBPM migration strategies - Introduction

For some time now I have been looking to put together my views and experience on how to position your current jBPM v3.2.x implementations for migration to a newer version. This article will outline some of the best practices within the four layers identified in general jBPM projects.

These ideas will be put forth based on the simple diagram provided here which outlines a typical enterprise business process implementation. It is not necessary to have all the various components in an implementation to be able to make use of the guidelines detailed in this article. The extensive list of components is provided to allow for discussion on the typical interactions I have encountered in my jBPM travels. In this introduction these layers will be outlined and future articles will cover them in more detail.

The idea behind each layer will be to identify best practices and ways to keep your implementations as jBPM version agnostic as possible. I believe this can be achieved, to a point, with proper knowledge and design time application of this knowledge. Each section will dive deeper into that specific area and try to provide you with the knowledge to design and implement your jBPM projects in such a way as to future proof them. You will be as ready as you can be to migrate to the next version.

The choice to focus on jBPM v3.2.x is due to the fact that this is currently the supported enterprise version provided in the JBoss SOA-P product. This is what many enterprises are currently using, throughout the world.

Process initialization layer
The first layer covers the details of providing flexible initialization of your processes within enterprises where you might have serious performance wishes, many different processes that can be initiated and allow for prioritising which process will be started when.

Process definition layer
This layer contains the process definition itself, a narrow layer that simply needs to be migrated to some future version of jBPM. Will this layer be jPDL, XPDL or some form of BPMN?

Process implementation layer
Here we dive into the underlying code layer that is best known as Handlers. The actual Java implementation that you may extended with abstraction layers, business logic and helper utilities. There is much to be cautious of here when looking to migrate your processes to a future version of jBPM, but there are some simple practices that will make migration less work than you think!

Process interaction layer
There is much to be won with a good strategy for accessing business logic, back-end systems, back-office systems, user interfaces, other applications or whatever your business processes need to use to get their jobs done. Here you will find a series of components passing review with suggestions for each one on the best way to position your projects for easy migration. A bit of prevention will go a long way in your IT budget!

General best practices
For as far as they have not been covered, I will provide some best practices with regards to any jBPM project. These will zoom in to a lower level than the above layers and can be applied across them all. If you get nothing out of these articles, I hope you will be able to make use of these gems of knowledge learned through harsh lessons in the trenches of jBPM projects.

Please feel free to provide feedback and suggestions for areas that might be missing. I am not trying to cover all possible use cases for jBPM projects, but to provide a reference architecture that is recognisable for the majority of enterprise jBPM users.

The next article in this series examines the process definition layer...

Tuesday, March 16, 2010

jBPM 3 hints - finding a process instance in your deep dark jBPMContext

While writing some unit testing of the jBPM exception framework I needed to deal with two separately deployed process instances, one for the unit test and one for dealing with the exception I was causing.

My problem was how to obtain the exception process instance when all I know is the process name? I also had it easy from the unit testing point of view, I do not need to worry about multiple running instances of the exception framework as this is under my unit test control (at least I feel like I have some control over it!).

Below you see how you can locate your process instance and context within that instance. I will show you some helper methods that might come in handy for you (all logging done with log4j and assumes you understand what you see below):
/** Used to get the process id of the specific process I want. */
public long getExceptionProcId () {
  JbpmConfiguration jbpmConf = JbpmConfiguration.getInstance();
  long procId;
  
  // Open the transaction.
  JbpmContext jbpmCtx = jbpmConf.createJbpmContext();

  try {
    // Get our process instance back.
    GraphSession graphSession = jbpmCtx.getGraphSession();
    ProcessDefinition processDefinition = 
      GraphSession.findLatestProcessDefinition("Exception Framework");
    assertThat("No process definition found.", 
      processDefinition, is(not(nullValue())));

    // Now, we search for all process instances of this process definition.
    List processInstances = 
      graphSession.findProcessInstances(processDefinition.getId());
    ProcessInstance procInst = (ProcessInstance) processInstances.get(0);
    procId = procInst.getId();
  } finally {
    // Close context.
    jbpmCtx.close();
  }   

  return procId;
}
With the above you can make use of the processId to recall your process instance as follows:
JbpmConfiguration jbpmConf = JbpmConfiguration.getInstance(); 
JbpmContext jbpmCtx = jbpmConf.createJbpmContext();
  try {
    long processInstanceId = getExceptionProcId();
    ProcessInstance procInst = jbpmCtx.getProcessInstance(processInstanceId);
    assertThat("No exception process instance returned.", 
      procInst, is(not(nullValue())));
    assertThat("Exception process in unexpected state.", 
      procInst.hasEnded(), is(true));
  } finally {
    // Close context.
    jbpmCtx.close();
  } 
Another nice one to help you find what processes have been deployed in your current jBPMContext:
// find all our processes that have been deployed and log them.
JbpmConfiguration jbpmConf = JbpmConfiguration.getInstance();
JbpmContext jbpmCtx = jbpmConf.createJbpmContext();

  try {
    List listProcs = 
      jbpmCtx.getGraphSession().findAllProcessDefinitions();
    if (getLogger().isDebugEnabled()) {
      for (ProcessDefinition processDefinition : listProcs) {
 getLogger().debug("Process definition is: " 
          + processDefinition 
          + " with version: " 
          + processDefinition.getVersion() 
          + ".");
      }
    }
  } finally {
    jbpmCtx.close();
  }

Sunday, March 14, 2010

JBoss BRMS install example repository gives OutOfMemoryError: PermGen space

When setting up a demo of JBoss BRMS 5.0.1 (don't think it will really matter which BRMS 5.x you use) in a JBoss EAP 4.3 product I was confronted with an error.

After server start-up you login to http://localhost:8080/jboss-brms which asks you if you want to install the sample repository in your new system. When I said yes, it would run a bit and then give me an error like this:
22:05:00,094 ERROR [STDERR] Exception in thread "http-127.0.0.1-8080-5" 
22:05:00,094 ERROR [STDERR] java.lang.OutOfMemoryError: PermGen space
22:05:00,152 ERROR [ContainerBase] Servlet.service() for servlet guvnorService threw exception
java.lang.OutOfMemoryError: PermGen space
 at java.lang.Throwable.getStackTraceElement(Native Method)
        etc.........

To fix this you need to tweak the jboss-as/bin/run.sh by adding near the top of the file the following line:
# Set a sane PermSize.
JAVA_OPTS="$JAVA_OPTS -XX:MaxPermSize=256m"

Restart EAP 4.3 and the installation of your sample repository will run fine.

Friday, March 12, 2010

Tweaking the log4j BasicConfigurator

This is not magic that I am posting, but something I don't want to sort out again in the future. My current project was involving some extensive debugging of my unit tests, with long log lines on the console causing me to have to full-screen or scroll too much (forced to work on windows and lots of mouse clicks really get my goat).

By digging into the log4j BasicConfigurator.class (with my buddy Maurice, credit to the mastermind!) it has a default setup as follows:

root.addAppender(new ConsoleAppender(new PatternLayout("%r [%t] %p %c %x - %m%n")));

This will generate logging output like this:
4513 [main] DEBUG org.jbpm.graph.def.GraphElement  - event 'process-start' on ProcessDefinition(Exception Handling) for Token(/)
4654 [main] DEBUG org.jbpm.graph.def.GraphElement  -  event 'process-start' on ProcessDefinition(Exception Framework) for Token(/)

I adjusted this in my unit tests as follows:
((PatternLayout) ((Appender) Logger.getRootLogger().getAllAppenders()
  .nextElement()).getLayout())
  .setConversionPattern("%r [%t] %p %c %x -%n%n  %m%n%n");

This will give you output like this:
4513 [main] DEBUG org.jbpm.graph.def.GraphElement  -

  event 'process-start' on ProcessDefinition(Exception Handling) for Token(/)

4654 [main] DEBUG org.jbpm.graph.def.GraphElement  -

  event 'process-start' on ProcessDefinition(Exception Framework) for Token(/)

Monday, March 8, 2010

Fedora 12 NetworkManager update breaking GSM connection

My latest Fedora 12 update broke my Mobile Broadband GSM connection. I kept seeing this in my message log:


6516 Mar  8 12:22:49 localhost NetworkManager:   (hso0): device state change: 3 -> 4 (reason 0)
6517 Mar  8 12:22:49 localhost NetworkManager:   Activation (hso0) Stage 1 of 5 (Device Prepare) scheduled...
6518 Mar  8 12:22:49 localhost NetworkManager:   Activation (hso0) Stage 1 of 5 (Device Prepare) started...
6519 Mar  8 12:22:49 localhost NetworkManager:   (hso0): device state change: 4 -> 6 (reason 0)
6520 Mar  8 12:22:49 localhost NetworkManager:   Activation (hso0) Stage 1 of 5 (Device Prepare) complete.
6521 Mar  8 12:22:49 localhost NetworkManager:   Activation (hso0) Stage 1 of 5 (Device Prepare) scheduled...
6522 Mar  8 12:22:49 localhost NetworkManager:   Activation (hso0) Stage 1 of 5 (Device Prepare) started...
6523 Mar  8 12:22:49 localhost NetworkManager:   (hso0): device state change: 6 -> 4 (reason 0)
6524 Mar  8 12:22:49 localhost NetworkManager:   Activation (hso0) Stage 1 of 5 (Device Prepare) complete.
6525 Mar  8 12:22:49 localhost modem-manager: (ttyHS2) opening serial device...
6526 Mar  8 12:22:49 localhost modem-manager: Modem /org/freedesktop/ModemManager/Modems/0: state changed (disabled -> enabling)
6527 Mar  8 12:22:50 localhost modem-manager: Modem /org/freedesktop/ModemManager/Modems/0: state changed (enabling -> enabled)
6528 Mar  8 12:22:50 localhost modem-manager: Modem /org/freedesktop/ModemManager/Modems/0: state changed (enabled -> disabled)
6529 Mar  8 12:22:50 localhost NetworkManager:   (hso0): device state change: 4 -> 3 (reason 0)
6530 Mar  8 12:22:50 localhost NetworkManager:   (hso0): deactivating device (reason: 0).
6531 Mar  8 12:22:50 localhost NetworkManager:   stage1_enable_done(): GSM modem enable failed: (32) SIM PIN required
6532 Mar  8 12:22:50 localhost NetworkManager:   (hso0): device state change: 3 -> 9 (reason 0)
6533 Mar  8 12:22:50 localhost NetworkManager:   Activation (hso0) failed.
6534 Mar  8 12:22:50 localhost NetworkManager:   (hso0): device state change: 9 -> 3 (reason 0)
6535 Mar  8 12:22:50 localhost NetworkManager:   (hso0): deactivating device (reason: 0).

The key here was the line:
  stage1_enable_done(): GSM modem enable failed: (32) SIM PIN required

Some looking around and it appears that the last update to NetworkManager broke it:

Name : NetworkManager
Arch : x86_64
Epoch : 1
Version : 0.7.998
Release : 2.git20100106.fc12

A simple downgrade will fix this to back you up to the previous version, here is mine:

Name : NetworkManager
Arch : x86_64
Epoch : 1
Version : 0.7.996
Release : 6.git20091021.fc12

To do this you use the following command:

$ sudo yum downgrade NetworkManager

Restarted and the GSM card worked as advertised!

============== UPDATE 02 April 2010 =========================
See Bugzilla on this for solution of upgrading the NetworkManager and ModemManager packages
to the versions found in the test repo:

https://bugzilla.redhat.com/show_bug.cgi?id=560742
http://download.fedora.redhat.com/pub/fedora/linux/updates/testing/12/