06.24.2010

Unit testing ALBPM and OBPM: Unravelling PUnit, CUnit and PAPI JUnit Testing

I have long been a fan of unit testing. Thus, I was full of joy when I found out that there were PUnit and CUnit objects were made available back in ALBPM version 6.
My good mood was quickly dashed when I found out that there was not much in documentation and examples. There is a paragraph or two in the manual. And the example included with the installation of Studio was equally terse.
But, over time I eventually learned the ins and outs of leveraging these objects to my benefit. While they aren't as comprehensive or as reliable as I would like, they are quite useful.
I will let everyone know what I have learned about these objects here, so others will not have to go through the pain I went through figuring this out.

PUnit and CUnit -- What they are and What they do.
First of all, let's introduce these objects to those who don't yet know them.
PUnit objects are a special kind of Business Object you can create in the Component Catalog in ALBPM 6, 6.5, or OBPM 10g Studio. They allow you to create automated tests of your processes in the style of JUnit tests. They will even allow you to specify how you want interactive activities to respond through the use of PUnit tasks.

CUnit objects are another special kind of business object that allow you to create automated tests of your business objects in the Catalog.

Creating a PUnit Test
Creating a PUnit object is easy. It's just a matter of choosing the right menu option off of the "New" menu when you right-click on a "Module" of the Catalog. See the Image below.

Creating a PUnit Object

Creating a PUnit Object

Now creating a test method in the PUnit object is a bit more tricky. Right-click the PUnit object in the Catalog, select "New" then "Method". Here is the tricky part. You have to begin the name of the test method with the word "test". Otherwise, OBPM will not recognize that method as a test method. So, name the method something like "testProcess" or "testBetterDocumentation" or something like that. After you have a test method (you will know because the method icon will be green instead of blue), you can put special PUnit test object calls into the method. You can find these easily by using Eclipse's Ctrl+Spacebar feature to tell you what you can do. The operations and objects are easy to understand, especially if you know PAPI. To get you started, I have written a sample test method in this project export you can download here.

Notice the built-in methods "setUp" and "tearDown". These should be familiar to JUnit veterans. They initiate a PAPI connection/session to the Studio engine before running a test, and shut it down gracefully afterwards. You shouldn't need to change the "tearDown" method which is written for you. But, you may want to change the participant specified in the "setUp" method. After all, the participant specified here will be the user context under which the test will be performed, and you probably won't have a participant "punit" in your Organization settings.
There is also a built-in attribute of type Fuego.Test.ProcessServiceSession named session included with the PUnit test object. This is your connection to the Studio engine, and the object from which most of your interactions with the engine will be done.

Writing and Running a PUnit Test
The example I have provided shows how you can do the following tasks in a PUnit test.

  • Create an instance of a process
  • Assign input arguments to a process instance
  • Assert that the instance is running
  • Get the current activity of a running process
  • Get the value of an instance variable (only works for simple data types)
  • Assert that a process instance arrives at a certain activity within a certain amount of time

You can do much more with the session object. But these are the activities I usually do in a Process test. The Fuego.Test.ProcessServiceSession has some similar methods to the PAPI ProcessServiceSession. But, the PUnit version is quite different. You don't have as much flexibility as do with PAPI.

But, you are able to interact with interactive activities. Here is how you do it. Right-click on the interactive activity you are including in your process test, select the "PUnit task" menu option.
Testing Interactive Activities

Testing Interactive Activities

Since PUnit tests are automated, and there is no actual user interaction, you specify how the interactive activity changes the process instance (when you are running the PUnit test) in the PUnit task. So if the interactive's output parameter set an instance variable, you would set the same instance variable in the PUnit task method.

Next, in the PUnit test method, when you are sure the process instance is waiting at the interactive activity, use the session.activityExecute method to execute the PUnit task specified.

To run the test method, first start the ALBPM or OBPM 10g engine. Then right-click the method in the Catalog, and choose "Run Test". The "Test Results" pane will pop-up and you can watch the test execute.
Test Results Pane
The Test Results Pane

If you are using objects in your Catalog which have been introspected from jar files as input or output parameters of processes, you will need to modify Studio/Eclipse's classpath. The test runner executes the tests in Eclipse's Java environment. So, while writing the test code, there are no errors (Eclipse knows what is in the Catalog), and the engine runs fine (in another Tomcat Java environment which has the jar files deployed with the BPM project), the test runner will report ClassNotFound. This is pretty tricky, I solved it by modifying the file %BEA_HOME%\albpm6.0\studio\eclipse\configuration\config.ini and changed the osgi.frameworkClassPath value to include my custom jar files in Eclipse's classpath.

While this worked for me, occasionally I still received ClassNotFound errors. But these went away when I restarted ALBPM Studio.

Limitations of PUnit Tests
You can get the values of instance variables returned to the test method. However, this only works reliably for simple or native data types. Complex datatypes (business objects, and introspected objects) can be viewed as XML if they are serializable. Otherwise, their values can't be inspected in the test.
Testing processes which use subprocesses and Split/Join activites can be difficult. You can't get a subprocess' Id from the parent process. And targeting a specific thread in a Split/Join group can be difficult.

Those limitations aside, testing Processes with PUnit is a pretty useful feature. One of the more welcome features is the ability to change the PUnit test method and run it without having to stop the engine or redeploy the process.

Writing and Running CUnit Tests
As mentioned earlier CUnit tests can be used in the traditional fashion to test code written in Business Objects to insure they work as expected. You create and write CUnit tests in the same way as you do PUnit tests. You also have to start the names of CUnit test methods with the word "test".

CUnit tests can also be used to verify or proove that External Systems (Web Services or Databases, etc.) are returning the expected responses to your inputs. Or, they can be used to do ad-hoc testing of Business Object code.
The advantage of CUnit tests to PUnit tests is that you don't need to have an engine running or a process deployed to run them. But if you are using introspected jar's in the test code, you will need to change Eclipse's classpath as shown earlier.

Using a PAPI JUnit Java Test Environment
Sometimes you need to test your BPM project in a J2EE container because the process just does not behave the same way in Tomcat as it does in WebLogic Server. To do this, simply write JUnit test cases using PAPI. Doing this has some advantages and disadvantages to using the PUnit test cases.

  • If your subprocess activity has the "Generate Events" option turned on, the PAPI JUnit test case can pick up a process' subprocess id and continue testing. You can't do this with PUnit tests.
  • You can get the vales of instance variables of complex data types.
  • PAPI JUnit test methods can not execute interactive activites in a process. PUnit tasks are not available ouside of ALBPM / OBPM Studio.

Once written PAPI JUnit tests can be run on both the J2EE engines as well as ALBPM / OBPM Studio engines.
You can download this example to get you started creating a PAPI JUnit test suite.

05.19.2010

Maximizing Instance Memory Efficiency in OBPM / ALBPM

When you get to the point where you have hundreds of thousands of active instances in your engines, minimizing the amount of memory each instance uses is essential. Insuring you have a good process design at the beginning will save you problems trying to scale your servers to support them. This article will give you some ideas how this can be done.

Most of us software developers are familiar with the venerable Model/View/Control (MVC) methodology which has greatly increased memory efficiency, performance, and maintainability in our projects. I have developed a similar methodolgy for developing BPM projects in OBPM / ALBPM which has proven to be successful.

Three Kinds of Business Objects

The BPM Component Catalog allows you to introspect many kinds of objects from disparate resources. While this is very convenient, don't get into the trap of using those objects as they are imported. This will usually get you using objects which consume much more memory than you need. It is better to create new objects which just accomplish what BPM needs to do, and have methods or helper objects to transfer the appropriate information between concerned objects.

Sample Business Model Object
Sample Business Model Object

If you start to segregating your object, you will end up having three kinds of objects: Business Model Objects, Process Flow Objects, and Process View Objects. I will explain what I mean below.

Separating the Object Into Useful Portions
Separating the Object Into Useful Portions

Business Model Objects

These are usually the objects which are introspected into the Component Catalog. They are very detailed an complex. They probably have relationships with other objects. They represent the knowledge of a business concept, or at least how those concepts interact with the business' systems.

Business Model Objects are very useful for interacting with web services, databases, and other external systems. But for processes because of their memory requirements. And, they are cumbersome to use for user interfaces because the data is optimized for retrieval and storage, not for data entry or display to a human.

Process Flow Objects

The Process Flow Objects contain a subset of the information stored in the Business Model Objects. The idea is to only have information in these objects which the process flow will need for decisions and supporting the process flow.

Process View Objects

These objects also contain a subset of the Business Model Objects. The focus of the Process View Objects are supporting Screenflows or Presentations. The data and object structure of these objects is optimized for easy presentation of user interfaces.

Using Business Model Objects in the Process Flow

So if you take the bait, and use your Business Model Objects as instance variables in your process flows, here is what happens. First, there is a big splash as the object is filled in by your back-end systems. Information is shared between activities by putting in or changing data in the object's attributes. As the process goes through its life-cycle, the object grows in memory usage. And, the object is using memory for the full duration of the lifespan of the process.

Using Business Model Objects in the Process Flow
Using Business Model Objects in the Process Flow

Using the Three Object Types Method in the Process Flow

Business Objects are used in automatic activities to provide data to the Process Flow and Process View objects. They are then unloaded from memory.The objects with the smallest footprint (the Process Flow objects) are in memory the longest.

Using the Three Object Types
Using the Three Object Types

Process View objects are loaded with data in order to support interactive activities. They are only in instance memory long enough to complete the interactive activity, and send the results to the other objects. Since these objects are optimized for the screenflows, their memory usage is reduced.

Object Type Relationships
Object Type Relationships

Well That's Nice, But...

Yeah, sometimes you just need to keep large chunks of data around to avoid performance problems caused by excess chatter (from continually loading the Business Model Objects). This is when you would use "separated" instance variables. These are then stored in a database table and not in direct instance memory.

How to Segment Business Model Objects

First, Business Model Objects can have methods to load and save to database/webservice/etc. This keeps the complexity of the persistence method out of the process flows completely.

Segmenting the Objects
Segmenting the Objects

Next, Process Flow Objects can have methods for loading their information from the Business Model Objects.

Then, Process View Objects can have methods for loading and saving their information back to the appropriate objects.

04.21.2010

JMS Techniques in OBPM

Background
I have had several clients now desire to dump their current Web Service integrations in favor of using JMS in their BPM orchestrations. The reasons are many, but the main ones have to do with message persistence and scalability. Messages sent with JMS are queued up and persisted until the consumer is ready. And, JMS is a little more efficient than Web Services due to the lack of the SOAP envelope. Whatever your reasons for wanting to use JMS instead of Web Services in OBPM/ALBPM, this article should help you a bit.

Not as Simple as it Sounds
OBPM makes it seriously easy to implement Web Service integrations. Just introspect the WSDL into the catalog and then drag a method from the catalog to a code-block. The response is usually returned immediately in the typical HTTP request/response cycle. Plus, all of the objects involved are usually embedded in the WSDL so everybody knows what they are talking about.
With JMS, the BPM process has to listen to a JMS Queue with a Global Automatic activity and manually wait for a response using a Notification Wait activity for an asynchronous response. Also, if you are doing more than just simple text JMS messages, all the objects being used will need to be manually introspected into the catalog, and kept up to date with what the other side of the JMS conversation is using. The following diagram shows the differences.

Web Services vs. JMS

The Message Router
You may be asking why you need two processes for this to work. Well, if you just have one JMS conversation going on, then you will only need one process. Something like the following diagram will certainly do the trick.

Simple JMS Response

But, if you have several conversations going on with numerous processes, you won’t want to have a single JMS queue built for each conversation in each process. You will probably want to use just a few JMS queues and route messages to the processes based upon what is in the messages (such as by object type). Thus you will end up with something like the following message router process (MRP).

Message Router Process


Note: I don’t like using the Process Notification activity to notify processes. If the process instance to be notified is not found, the instance of the MRP is aborted. If an error handler is present in the MRP, this can be avoided, but the engine still logs a Warning error in the log. Get enough of these, and it can really clutter up the log. I prefer to use the PBL Notification.Send method in an Automatic Activity. Then, you have more control over what happens in these scenarios.

Processing the Notification
A Correlation Set has to be created and initialized by the process receiving the notification from the message router process (MRP) before it receives the notification. This is so that the MRP can find the appropriate process instance by the unique business Id. The MRP does not need to know about the Correlation Set, it just needs to set the appropriate unique business Id argument before sending the notification.
The receiving process also needs to handle unexpected problems with the messaging conversation. Here are a couple of examples. First, to handle the case where the JMS sender never sends a response, an activity with a due transition needs to be present to time-out the conversation. Next, when the sender responds with a message that it couldn’t perform the desired action, a conditional path is created.
So our simple example from earlier now looks like this.

Not So Simple JMS Response


Whew! That’s a lot of infrastructure to build up just to replace a simple Web Service request/response. Yeah, JMS may be more efficient, but its implementation here is much more verbose.
Now that you have a better idea of how to do it, I have a few implementation patterns you may want to consider in implementing JMS in OBPM/ALBPM.

JMS Process Pattern 1: Interrupting Interactive Activities
This is a case where a process instance is waiting at an Interactive Activity, and it needs to move on to the next activity when it receives a JMS message. Essentially, the process flow is blocked by an Interactive instead of a Notification Wait activity. This pattern works well when you want the process instance to appear in the Workspace inbox even though it is actually waiting for a JMS notification. The user can then have the opportunity to interact with the process without having to search for it and use a Grab.

I like this pattern because it increases the visibility of the process instance in the Workspace. Plus, it gives the user more information and influence over the instance. The user can have their view set to sort by instance creation date, and easily see which instances have been stuck too long waiting on a notification. If we used Notification Wait’s to block the process, a custom view would need to be created to cause the instances to be visible.

Example 1: Using Interactives to Block the Flow


A Correlation Set is initiated in the Begin activity, and used in the Notification Wait activity. The latter has the “Allows Interruptions” option turned on so that when the notification occurs, it will interrupt the running instance in a way similar to the error handling flows. In the automatic activity, the PBL sets the predefined variable “action” to SKIP. Thus, when the notification flow reaches the Compensation Activity, the process instance will skip the processing of the current activity (the interactive) and proceed on to the next activity down the unconditional path towards the “Finalize” activity. The Grab Activity is there so participants in a more administrative role can easily move the instance along the path should the notification never arrive.

JMS Process Pattern 2: Manually Moving a Process Instance
The “action=SKIP” strategy only works if the next activity in the process flow is where you want the instance after the notification arrives. What do you do if you need more control over where the process instance goes? That is the question that the following pattern answers.

The diagram of this pattern is exactly like the previous one, except for the addition is the “Exception Grab” activity. This is a From All/To All Grab. I call these “Exception Grab’s” because they are usually used as a method of last resort to fix a process instance that has gone down the wrong path.

Example 2: Destination Control

In the notification flow, the Automatic Activity uses a round-about way to automatically execute the Exception Grab to send the instance to the activity of choice.

Because you can’t execute a grab while in a notification or error flow, a simple process is created to connect to the engine, find the process, and execute the grab.
All of the code and the processes are included in the sample project export that can be downloaded below. Also, this example (in the export) shows how to manually initiate and finalize the Correlation Set in PBL.

JMS Process Pattern 3: Handling Multiple Asynchronous JMS Responses
This pattern addresses the case where a single request can cause multiple JMS responses. And, these responses can arrive in any order. But the process must wait for all of the messages to be received and so something with the responses as they arrive.

Example 3: Asynchronous JMS Responses


To achieve this, a business object is created in the catalog to keep a record of the messages that have arrived. The business object is implemented as an instance variable. The flow is blocked by an Interactive Activity only if a message has not been received.
This example shows how to use activity.source to determine where in the process the instance was at when the notification arrives. It also shows how instance state can be preserved when multiple asynchronous events are occurring, and they can occur at any time of the life of the instance. Boolean flags are used in the business object instance to insure that the process instance only reacts once to a certain type of message.
Note: In the process export all four Automatic Activities utilize the same process method.

Process Project Export
All three of these patterns are included in the following Process Project Export. Also included is the “GrabAndRedirect” process and demonstrations on how to send a JMS message in PBL. Here is the download.

04.15.2010

FindClass -- A Simple Utility To Find A Java Class in a Folder of Jars.

A long time ago, when I was supporting various Java applications I didn't write, I was freqently encountering the dreaded ClassNotFound exception. (Haven't we all.)

I had just finished playing with FWZipLib.dll wrapper around the Info Zip libraries. So, I quickly wrote this utility to scan a folder of jar's (which are just zip files anyway) for a class provided on the command line. It proved so useful that I still use it occasionally.

It is a simple C# console application. To use it, here is the syntax:

FindClass ClassNameToFind c:\SomeFolder\SomeJavaApp\lib


The utility will then list all of the jar files in the folder. Then, it will tell you when it finds the class file in one of the jar's.

However useful it may be, I never really updated it with any fancy features. There are other utilities which other jar-heads use for this feature. But if you like a simple, and free, utility to find those elusive classes, you can download it here.

04.15.2010

FWZipLib.dll: A C++.NET Zip Compression Library Wrapper Around Info Zip

Had enough with the portal tools? Well, here is a simple tool I made a long time ago someone may find useful.

The FWZipLib is a C++ DLL wrapper around the venerable Info Zip library for Windows. This makes this library accesible to .NET applications. It can do all of the standard operations on zip files: compression, decompression, listing of zip file contents, password protection, etc. Basically, just about anything the Info Zip library can do.

Hold On a Minute
There are a couple of things you must know before using this library. First, there are much better libraries out there for .NET. (Particularly the SharpZipLib.)
Second, I really don't think that it is all that thread-safe. (I haven't really tested it.) If you need it for small one-off utility programs, console or forms applications it will probably work fine.

Usage
To use it in your average C# program, just reference the FWZipLib.dll. Then, make sure you copy the Zip.dll and UnZip.dll files into your bin folder. These are the Info Zip libraries which actually do the work. The FWZipLib.dll provides the interface to the Info Zip dll's.

The Download
The download includes the source code and the compiled binary for the FWZipLib.dll. It also contains a VB.NET test client to show you how the syntax works.

:: Next >>