Tuesday, August 25, 2009

Adding dll Files to Eclipse Projects

I had a project where I was using a dll file and Java JNI for generating some alert sounds based on some events in my java code. After developing in pain text java files for some time, I planned to move it to Eclipse IDE, to speed up my development. But where to place my dll file.

(dll files contain the implementation of the native method implementations for some java Native method calls. Hence they are like Library file, in other words, Native Libraries)

Issue here was that, dll files are searched for not in the CLASSPATH but in PATH. Where to place that the file gets to be in the path of the Project builder and also during runtime. (I was missing the ease of placing it in the invocation/current directory when I was working without the IDE)

Well finally got the link to add Path to native libraries to the project. Navigate to Project-->Properties-->Java Build Path-->Libraries Tab. Now expand JRE system Library. You can see an entry for "Native Library location". Click on the same and then on "Edit". Specify the path of the folder which contains your dll file and you are done.

But wait, this does not make your project portable. What if you want it to be part of the project and be bundled with the same. It should be placed some where within the project folder. This is what precisely i did.

Placed it in src folder of the project root folder. Modified the Native library location to point to Workspace\Project-folder\src. Done. Now application is portable along with the dll.

A picture of the option pane to guide you better:


Happy Native Coding :-)

Wednesday, February 18, 2009

Deploying JBoss JBPM on Pramati Server

Deploying JBoss JBPM on Pramati Server:

(Product Versions Used: Pramati Server 6.0, jdk 1.5.0_11, jbpm-jpdl-3.2.3, eclipse-jee-europa-win32)

The community product JBoss Business Process Management (JBPM) , from JBoss Community is one of the popular BPM suites in use. JBoss Provides the j2ee compliant app in two versions, WAR and EAR. The web archive can provide you a quick start and is quite straight forward to configure and deploy. In addition, its the only option you have when the server does not contain a EJB container. On the other hand, the Enterprise archive exploits all the available middleware from an application server to form a robust process management system. The enterprise archive uses Session Beans and Message Driven Beans complemented with container transactions. JDBC datasources are used in both WAR and EAR to leverage the advantage of connection pools.

Basic architecture of execution in JBPM

Every process consists of a set of steps to be completed. As the steps are executed one by one, optionally depending on some custom logic, the state of the Process changes. To simulate such a behavior, JBPM follows the philosophy as detailed below.

1. The process flow is defined in an XML descriptor(Process Definition).
2. A process flow consists for several "nodes"
3. The state of a process is maintained in terms of certain variables
3. The nodes are configured with one or more tasks which are carried out with or without manual intervention. These tasks in general change the Process variables causing the state of execution to move forward.
4. Execution begins from a standard node called "Start Node"
5. The flow from one node to another is through "transitions". Depending on the logic as defined in Process Definition appropriate transition is chosen and execution moves forward.
6. Eventually the Execution flow arrives at "End Node" which marks the completion of the execution.

A sample Process Flow might look like:

Fig. 1 : A sample Process Image from JBPM

All data like process definition, execution state, process variables, task state, task user list ...etc are persisted to a DB. The DB can be an in -memory HSQLDB or external standard DB like ORACLE or MySQL. JBPM uses the popular persistence and query service, Hibernate for this purpose. The DB details are configurable in hibernate.cfg.xml. Usability of hibernate enhances the usability of JBPM itself. In addition, we can configure hibernate to use datasource on an application server there by leveraging middleware services like connection pool and transactions.

Hence a prerequisite for deploying JBPM is to create the database to hold this data. jbpm-jpdl-suite-3.2.3.zip contains sql scripts to create this database (in jbpm-jpdl-suite-3.2.3.zip\jbpm-jpdl-3.2.3\db folder).

In my case i had to do a little modification to the supplied SQL script in terms of adding the ending ; symbols to all the lines. Otherwise mysql refused to execute the script!!

Another pre-requisite is to setup the eclipse plug-in for creating Process definitions and deploying them on JBPM. This is as direct as eclipse is. Just copy the content of jbpm-jpdl-suite-3.2.3.zip\jbpm-jpdl-3.2.3\designer\eclipse\features directory to eclipse\features directory (I used eclipse-jee-europa-win32 to work with). Also copy the content of jbpm-jpdl-suite-3.2.3.zip\jbpm-jpdl-3.2.3\designer\eclipse\plugins directory to eclipse\plugins directory. And you are done.

Now lets see how we can deploy the JBPM web archive on Pramati Server.

Steps to deploy JBPM Web Archive on Pramati Server:

The web archive deployment requires the following steps:
1. Create a datasource on pramati server pointing to the newly created database fro JBPM
2. Create a TransactionManagerLookup java class for use with Hibernate
3. Configure Hibernate for using the datasource and JTA
4. Create a realm with two groups user and admin on pramati server and assign "All Permissions" to them. (The default "system" realm can be used as well)
5. Open the Web archive in deploytool complete the mapping for Datasource and users
6. Deploy the web archive

Explanation of individual steps follows:

1. Creation of datasource on Pramati is straight forward. Place the jdbc driver jar in /server/lib/ext directory. On the management console of the node, go to Configure-resources-add datasource. Fill in the database connection parameters and you are done. Say the name of the datasource created here is jbpmDS.

2. The transaction manager lookup class has two methods to be implemented. To work with Pramati server the class could look like the following

//File Name:PramatiTransactionManagerLookup.java
package org.hibernate.transaction;

public final class PramatiTransactionManagerLookup extends JNDITransactionManagerLookup{
/**
* @see org.hibernate.transaction.JNDITransactionManagerLookup#getName()
*/
protected String getName() {
return "java:comp/TransactionManager";
}

public String getUserTransactionName() {
return "java:comp/UserTransaction";
}
}

Compile the class with hibernate jar in the classpath. This class can be placed in WEB-INF/classes directory to have it available in the classpath. In order to direct hibernate to use this class while using JTA, we will configure it in the hibernate.cfg.xml.

3. Configuring Hibernate to use Datasource and JTA:

The hibernate config file is located at jbpm-console.war\WEB-INF\classes\hibernate.cfg.xml

The default Setting of the config included is
org.hibernate.dialect.HSQLDialect
org.hibernate.cache.HashtableCacheProvider
java:comp/env/jdbc/JbpmDataSource
.......

Change dilect to the type of DB you are using. In my case it was MySQL
The datasource remains same.
The JTA transaction tag has to be enabled and replace the lookup class name with the one we created in the last step.
Finally the configuration looks like this:

org.hibernate.dialect.MySQLDialect
org.hibernate.cache.HashtableCacheProvider
java:comp/env/jdbc/JbpmDataSource

org.hibernate.transaction.JTATransactionFactory
org.hibernate.transaction.PramatiTransactionManagerLookup
.........

4. Create a realm named jbpmRealm on Pramati server using the management console. Create two groups named "user" and "admin" in the realm and few users to each of the groups. Basically the users belonging to the "user" group are the ones that access the application. admin group does not have access to all the web-resources as it is declared in the web.xml that is included by default in the JBPM web-archive. We shall need the "admin" group nevertheless fro deploying the JBPM WAR.

Additionally assign all permissions to these groups on the newly created realm. For detailed instructions on creating realms, groups, users and assigning permissions refer to Pramati Documentation at
Pramati Dev Portal.

5. Open the web archive in deploy tool and complete the mapping for datasource and the user gorups. Choose the data source "jbpmDS" in the Defined Resource drop down at Web Properties-->Resource tab. Click on tasks left button at the bottom of the window. That will take you to the user/group mapping page. Choose the jbpmRealm in the realm name drop down. For "user" role select the "user" group from the available list. Similarly choose "admin" group for admin role. Now tasks left should read "0" at the bottom of the deploytool window.
Completing these mappings could not be easier than this. Pramati Server deploytool literally guides you through all deploy-time mappings.

6. We are ready to save the archive and deploy. Click on save and then deploy to deploy the Web archive.

Please note that the WEB-INF/lib directory should contain the following library files:

asm.jar
bsh.jar
cglib.jar
commons-collections.jar
commons-fileupload.jar
commons-io.jar
dom4j.jar
gravel.jar
hibernate3.jar
jbpm-configs.jar
jbpm-identity.jar
jbpm-jpdl.jar
jbpm4jsf.jar
jsf-facelets.jar
log4j.jar

If any of these classes are not found to be in place, try looking for them in the jbpm-jpdl-suite-3.2.3.zip file. (in jbpm-jpdl-suite-3.2.3.zip\jbpm-jpdl-3.2.3\lib directory)

Once deployment is complete, you can deploy new process definitions from Eclipse directly just by click of a button. (The only parameter that might need change is the HTTP port of the server, in the URL that eclipse points to. Update the value to the current HTTP port of Pramati server).

To use the application access the following url in your browser:
http://localhost:/jbpm-console/

Provide user name and password for any of the user in the "user" group of the jbpmRealm and login. :-)