Do you know what’s happening in middleware? Budget crunch keeping you from attending industry gatherings? Bring the conference to your desktop. Take a minute (or a few hours) and attend the JBoss Virtual Experience.

Wednesday, February 11th, 2009 LIVE online
(on-demand February 16th – May 11th, 2009)

Find out more or register now.

Join our executives, key developers, and your business peers. Attend keynote sessions for executive insight into the future of open source and the middleware roadmap for 2009 and beyond. Visit the Exhibit Hall and chat live with booth representatives. Come to the Networking Cafe for in-depth technical and business discussions, birds-of-a-feather chats, and live Q&A with our speakers.

Whether you’re a developer, enterprise architect, or senior IT manager, this one-day event will show you how JBoss can help you build, integrate, deploy, and manage mission-critical applications and services while lowering your costs without sacrificing performance, security, or functionality.

For updates, follow us on Twitter.

Here’s a few more details:

Keynotes with live Q&A:

• Business keynote by Jim Whitehurst (live event only) and Craig Muzilla
• technical keynote by Rob Cardwell and Sacha Labourey

Sessions with live Q&A:

• business, technical and government
• 2 panel discussions: Customer viewpoint and Developer panel

Exhibit Hall:
Red Hat booths, including:

• JBoss Enterprise Middleware
• JBoss Operations Network
• JBoss.org
• Customer Reference
• MRG (Messaging, Realtime, and Grid)
• Cloud Computing

Partner booths include:

• Alfresco
• Carahsoft
• CityTech
• Consilium1
• DLT
• Dell
• EnterpriseDB
• Exadel
• Freedom OSS
• Ingres
• Jaspersoft
• USolutions
• Vizuri

Media sponsor:

• DZone

Networking cafe:

• Birds-of-a-Feather sessions with JBoss Rock Stars

Find out more or register now.

JBoss Operations Network (JON) recently became available as an open source solution through the Jopr project. (That’s pronounced “jopper.”) We interviewed Chris Morgan from Red Hat’s JON group to learn more.

1. What does Jopr do?
Jopr is an open source project that provides an integrated management platform that simplifies the development, testing, deployment, and monitoring of your JBoss technologies. From a single console you can inventory and monitor resources from the operating system to deployed applications. It also lets users control and audit application configurations to standardize deployments. It’s a robust solution to manage, monitor, and tune your applications for improved visibility, performance, and availability.

2. What about Embedded Jopr?
Embedded Jopr provides many of the same features as Jopr, but only for a single instance or (in the near future) a cluster of JBoss technologies. It’s essentially an administration console to manage JBoss products–users don’t have to rely so much on command line and XML configuration to set up their JBoss environment and applications.

It doesn’t offer the extensive monitoring and historical auditing capabilities of Jopr, but it is perfect for an individual developer or administrator to use. In contrast, Jopr is what you use to manage the entire enterprise or multiple instances and clusters from one location.

3. How does Jopr fit in with JON and RHQ?
RHQ is the platform on which Jopr is written. RHQ provides a very extensible plug-in technology that allows for many other technologies to be managed. Jopr includes all of the existing RHQ plugins, plus JBoss-specific ones. In turn, Jopr is the true upstream to commercial JBoss Operations Network (JON).

So you could think of it this way: RHQ is upstream to Jopr, which is upstream to JBoss Operations Network.

4. How did the project get started?
The project has really been in the works for a while, starting when it was becoming clear that JBoss needed a tool to help enable solutions for “non-developers” as the JBoss footprint continued to grow.

Typically, the groups responsible for operations in an environment are not the developers, so they need a different set of tools. Most operations staff are concerned with uptime and making sure the environment is compliant and ready to use for the customers they support. Jopr is the open source solution to provide that for JBoss technologies.

5. Tell us about the name.
Well, the team actually went through what seemed like hundreds of names, but almost every one we were close to choosing had some sort of issue where it was taken, trademarked, or just not “sticky” enough. So legend has it that a 1983 Matthew Broderick and Ally Sheedy flick called War Games was the eventual inspiration.

The real star of the movie was an artificial intelligence computer the military used called W.O.P.R. (pronounced whopper). From this, Jopr was born (it’s not a acronym as in the movie–that would have opened an entire other set of issues for getting a trademark). So it met the criteria of not being taken, it could be trademarked. And it was definitely “sticky,” as there is really no project, especially not in the Java space, that is even close.

6. So how is Embedded Jopr different from the consoles that have shipped with JBoss Application Server in the past?
Previous consoles for the application server were designed with a “developer” in mind, so they required some JBoss and Java expertise to use. With Embedded Jopr (and really, Jopr, too), it’s all about enabling JBoss for operations by making administrative and management tasks easier. We hope that with the open source community helping us, we can continue to push that goal forward.

7. Can anyone contribute? How would they get involved?
Absolutely! Just go to http://www.jboss.org/jopr or http://www.jboss.org/embjopr and join us!

Related links
http://www.jboss.org/jopr
http://www.jboss.org/embjopr
http://www.jboss.org/feeds/
(scroll down to JBoss ON section for many of the development team blogs)
http://www.rhq-project.org

Guvnor is the business rules management system in Drools 5. When you deploy it out of the box, you get an unsecured web application that stores data in Jackrabbit’s embedded Derby database.

This two-part article explains how to tune Guvnor deployed on JBoss Application Server 4.2.3. (If you missed the first half of the series, catch up in our archives.)This means that we will use the container’s configuration files and security infrastructure. This installment covers enabling password validation based on an OpenLDAP server, moving from the default data repository, and enabling SSL for better security.

1. Use OpenLDAP as a user repository
2. Use MySQL as a data repository
3. Enable SSL
4. How to use a secured Guvnor package
5. Summary

Use OpenLDAP as a user repository

There are several reasons why you would want to use an LDAP directory instead of a clear text file — security, provisioning, and reuseability are just a few. First of all, we need a directory. OpenLDAP will do for this example. Download and extract the bits from the OpenLDAP home page. In this example, I’ve used openldap-2.3.39.tgz. Next, go to the directory where you’ve extracted the installation files and perform following steps:

$ mkdir -p /data/openldap-2.3.39
$ ./configure --prefix=/data/openldap-2.3.39
$ make depend
$ make
$ make install

For more detailed instructions, look at the INSTALL file or the OpenLDAP Administrator’s Guide.

The next instructions will configure our directory and create a tree which looks like this:

We need to initialize the LDAP server and provide data like the root suffix, directory manager, and password. We also want to enable SSL like so:

$ mkdir /data/openldap-2.3.39/ssl
$ openssl req -newkey rsa:1024 -x509 -nodes -out /data/openldap-2.3.39/ssl/server.pem -keyout /data/openldap-2.3.39/ssl/server.pem -days 365
Generating a 1024 bit RSA private key
....++++++
................++++++
writing new private key to 'server.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:EU
State or Province Name (full name) [Berkshire]:Mazovia
Locality Name (eg, city) [Newbury]:Warsaw
Organization Name (eg, company) [My Company Ltd]:Kijanowski
Organizational Unit Name (eg, section) []:Guvnor
Common Name (eg, your name or your server's hostname) []:localhost
Email Address []:a@a.a

Since this is a self-signed certificate we will need to add it to the client’s (JBoss AS) truststore.

$ openssl
OpenSSL> x509 -inform PEM -outform DER -in /data/openldap-2.3.39/ssl/server.pem -out /data/openldap-2.3.39/ssl/server.der
OpenSSL> exit

$ keytool -import -file /data/openldap-2.3.39/ssl/server.der -keystore $JBOSS_SERVER/conf/ldap.truststore

Enter keystore password:  qwerty
Owner: EMAILADDRESS=a@a.a, CN=localhost, OU=Guvnor, O=Kijanowski, L=Warsaw, ST=Mazovia, C=EU
Issuer: EMAILADDRESS=a@a.a, CN=localhost, OU=Guvnor, O=Kijanowski, L=Warsaw, ST=Mazovia, C=EU
Serial number: d8537a079c5eed59
Valid from: Wed Jul 16 18:35:50 CEST 2008 until: Thu Jul 16 18:35:50 CEST 2009
Certificate fingerprints:
         MD5:  25:C5:88:7B:D4:88:02:46:F1:EF:0D:6B:D6:EE:1F:A7
         SHA1: 57:B8:F4:25:77:F0:12:BD:B2:2E:DD:7D:CE:09:D2:D4:96:56:BC:26
Trust this certificate? [no]:  yes
Certificate was added to keystore

To enable the new truststore, edit $JBOSS_SERVER/deploy/properties-service.xml and add following lines:

    javax.net.ssl.trustStore=/data/jboss-4.2.3.GA/server//conf/ldap.truststore
    javax.net.ssl.trustStorePassword=qwerty

Now edit the file /data/openldap-2.3.39/etc/openldap/slapd.conf:

include         /data/openldap-2.3.39/etc/openldap/schema/core.schema
include         /data/openldap-2.3.39/etc/openldap/schema/cosine.schema
include         /data/openldap-2.3.39/etc/openldap/schema/inetorgperson.schema

pidfile         /data/openldap-2.3.39/var/run/slapd.pid
argsfile        /data/openldap-2.3.39/var/run/slapd.args

database        bdb
suffix          "dc=kijanowski,dc=eu"
rootdn          "cn=DirManager,dc=kijanowski,dc=eu"
rootpw          secret
directory       /data/openldap-2.3.39/var/openldap-data
index   objectClass     eq

TLSCipherSuite HIGH:MEDIUM:-SSLv2
TLSCACertificateFile /data/openldap-2.3.39/ssl/server.pem
TLSCertificateFile /data/openldap-2.3.39/ssl/server.pem
TLSCertificateKeyFile /data/openldap-2.3.39/ssl/server.pem
TLSVerifyClient never

The rootpw attribute should be changed from ’secret’ to:

$ /data/openldap-2.3.39/sbin/slappasswd -s admin123

where ‘admin123′ is the new directory manager’s password. For better performance, you can create a config file for the backend database or copy the sample configuration file like so:

$ cp /data/openldap-2.3.39/var/openldap-data/DB_CONFIG.example /data/openldap-2.3.39/var/openldap-data/DB_CONFIG

To start the server with a customized listener, run:

$ /data/openldap-2.3.39/libexec/slapd -h ldaps://localhost:16636

You can make sure your LDAP server is up and running (listening) by running:

$ netstat -an|grep 16636
tcp        0      0 127.0.0.1:16636             0.0.0.0:*                   LISTEN

To create tree like the one shown above, we need to add the following myorg.ldif file:

dn: dc=kijanowski,dc=eu
objectclass: top
objectclass: dcObject
objectclass: organization
dc: kijanowski
o: kijanowski

dn: o=guvnor,dc=kijanowski,dc=eu
objectclass: top
objectclass: organization
o: guvnor

dn: ou=People,o=guvnor,dc=kijanowski,dc=eu
objectclass: top
objectclass: organizationalUnit
ou: People

dn: uid=admin,ou=People,o=guvnor,dc=kijanowski,dc=eu
objectclass: top
objectclass: uidObject
objectclass: person
objectClass: inetOrgPerson
uid: admin
cn: Guvnor Admin
sn: Administrator
userPassword: {SSHA}ZGUjbzh0wN0JoWxIAcZfFXpV5MIu/gZw

dn: uid=user1,ou=People,o=guvnor,dc=kijanowski,dc=eu
objectclass: top
objectclass: uidObject
objectclass: person
objectClass: inetOrgPerson
uid: user1
cn: Regular User
sn: Regular
userPassword: {SSHA}Gcif1SlGPu2vHrtoLGYlKXbKBytJiVVF

dn: ou=Roles,o=guvnor,dc=kijanowski,dc=eu
objectClass: top
objectClass: organizationalUnit
ou: Roles

dn: cn=admin,ou=Roles,o=guvnor,dc=kijanowski,dc=eu
objectClass: top
objectClass: groupOfNames
cn: admin
description: the GuvnorAdmin group
member: uid=admin,ou=People,o=guvnor,dc=kijanowski,dc=eu

dn: cn=regular,ou=Roles,o=guvnor,dc=kijanowski,dc=eu
objectClass: top
objectClass: groupOfNames
cn: regular
description: the Guvnor Regular group
member: uid=user1,ou=People,o=guvnor,dc=kijanowski,dc=eu

The passwords for admin and user1 are ‘9uvn04′ and ‘user1′ (respectively) and were generated with slappasswd. To add this ldif to our directory, we will use an ldap client application called ldapadd. First we need to update its configuration to be able to talk over SSL. Edit the file /data/openldap-2.3.39/etc/openldap/ldap.conf and add following line:

TLS_REQCERT allow

This will prevent us from getting errors like these:

client side:
ldap_initialize( ldaps://localhost:16636 )
ldap_bind: Can't contact LDAP server (-1)
        additional info: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

server side:
TLS trace: SSL3 alert read:fatal:unknown CA
TLS trace: SSL_accept:failed in SSLv3 read client certificate A
TLS: can't accept.
TLS: error:14094418:SSL routines:SSL3_READ_BYTES:tlsv1 alert unknown ca s3_pkt.c:1057
connection_read(11): TLS accept failure error=-1 id=4, closing
connection_closing: readying conn=4 sd=11 for close
connection_close: conn=4 sd=11

Now we can add the ldif file to our directory:

$ /data/openldap-2.3.39/bin/ldapadd -x -D "cn=DirManager,dc=kijanowski,dc=eu" -H ldaps://localhost:16636 -w admin123 -f myorg.ldif

adding new entry "dc=kijanowski,dc=eu"
adding new entry "o=guvnor,dc=kijanowski,dc=eu"
adding new entry "ou=People,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "uid=admin,ou=People,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "uid=user1,ou=People,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "ou=Roles,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "cn=admin,ou=Roles,o=guvnor,dc=kijanowski,dc=eu"
adding new entry "cn=regular,ou=Roles,o=guvnor,dc=kijanowski,dc=eu"

The last step is to configure JAAS in $JBOSS_SERVER/conf/login-config.xml. Replace the previous file based login module with this one:

            ldaps://localhost:16636
            ssl
            cn=DirManager,dc=kijanowski,dc=eu
            admin123

            ou=People,o=guvnor,dc=kijanowski,dc=eu
            (uid={0})

            ou=Roles,o=guvnor,dc=kijanowski,dc=eu
            (member={1})
            cn

            -1
            ONELEVEL_SCOPE

Now restart JBoss AS and try to login as admin with password 9uvn04. The application server will talk with the OpenLDAP server over SSL. If you want to shutdown the OpenLDAP server you need to determine its PID and interrupt it by sending the process a SIGINT signal:

$ kill -INT `cat /data/openldap-2.3.39/var/run/slapd.pid`

Use MySQL as a data repository

Jackrabbit has been chosen as a Java Content Repository (JCR) implementation. By default, it uses the Derby database as a backend. You may want to switch to a database you are more familiar with, and can regularly back up and properly tune. If you have already used the file-based repository and don’t want to loose all your assets, export them. After MySQL is up and running, import them back. To export your current repository, go to the ‘Administration’ menu on the left side, expand ‘Admin,’ choose ‘Import/Export,’ and click on ‘Export’:

Shut down the server and set up MySQL as your new repository. First, download MySQL and extract it. I will use the community server 5.0.51a standard, extracted to /data/mysql-5.0.51. As root, perform the following steps. (For more details, have a look at the INSTALL-BINARY file):

$ /usr/sbin/groupadd mysql5
$ /usr/sbin/useradd -g mysql5 mysql5
$ cd /data/mysql-5.0.51
$ chown -R mysql5 .
$ chgrp -R mysql5 .
$ /data/mysql-5.0.51/scripts/mysql_install_db --user=mysql5

$ chown -R root .
$ chown -R mysql5 data

# now start MySQL
$ /data/mysql-5.0.51/bin/mysqld_safe --user=mysql5 &

# and create a password for root
$ /data/mysql-5.0.51/bin/mysqladmin -u root password mysqladminpwd
To shutdown the MySQL server run:
$ /data/mysql-5.0.51/bin/mysqladmin -u root shutdown -p
Logout as root and log in to MySQL to create a user and database for Guvnor:
$ /data/mysql-5.0.51/bin/mysql -u root -p
mysql> create database guvnor;
Query OK, 1 row affected (0.00 sec)

mysql> grant all privileges on guvnor.* to 'guvnor-user'@'localhost' identified by 'guvnor-pwd';
Query OK, 0 rows affected (0.00 sec)

mysql> flush privileges;
Query OK, 0 rows affected (0.00 sec)

Now the DB side is complete.

Edit the $GUVNOR/WEB-INF/components.xml file and provide a path to where you would like to keep the repository configuration files. You can leave the default value–which is the JBoss Application Server’s bin directory–however it is recommended to provide a location that is regularly backed up. Under the ‘repositoryConfiguration’ component add:

/data/GuvnorRepo/

This last step creates a repository.xml file. It is created by default when running Guvnor the first time and is placed into the AS bin directory. This file configures the data repository. We would like to use MySQL, so we will create /data/GuvnorRepo/repository.xml:

As you see we’re using the com.mysql.jdbc.Driver, so we need to provide it. Download the mysql java connector from MySQL, unzip it, and copy the JAR file to $JBOSS_SERVER/lib. (I’m using mysql-connector-java-5.1.6.)

Now you can start the app server. If you have exported your assets, just go to the ‘Administration’ menu, expand ‘Admin,’ choose ‘Import/Export,’ and import your xml file. Please note that you have to unzip your exported xml file before you can upload it.

Enable SSL

The last tweak is enabling SSL. It not only provides security, but also ensures the transmitted data hasn’t been modified. This is strictly a server-side task.

First, we need a certificate. Please note that as the “first and last name” you have to provide the fully qualified domain name of the host. For testing purposes you can use localhost like so:

$ keytool -genkey -alias guvnor -keyalg RSA -keystore $JBOSS_SERVER/conf/guvnor.keystore -validity 365

Enter keystore password:  guvnorkspwd
What is your first and last name?
  [Unknown]:  localhost
What is the name of your organizational unit?
  [Unknown]:  My Department
What is the name of your organization?
  [Unknown]:  My Company
What is the name of your City or Locality?
  [Unknown]:  My City
What is the name of your State or Province?
  [Unknown]:  My State
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=My Name, OU=My Department, O=My Company, L=My City, ST=My State, C=US correct?
  [no]:  yes

Enter key password for
        (RETURN if same as keystore password):

Now we can enable an SSL connector. Edit the file $JBOSS_SERVER/deploy/jboss-web.deployer/server.xml like so:

Restart your JBoss Application Server. Guvnor should be available at https://localhost:8443/drools-guvnor.

How to use a secured Guvnor package

The last part of this article shows how you can access a drools package from Guvnor in a secure way. This is very straight forward if you use certificates signed by trusted authorities. In our test environment, it’s a little bit more complicated since we use self-signed certificates.

First create a package and deploy it. I’ll use the package we made during the quick introduction. This package is available under https://localhost:8443/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST. Replace the url attribute with the new value in Guvnor.properties:

url=https://localhost:8443/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST

One would expect that running the Drools application should end successfully, however this is not the case:

RuleAgent(default) INFO (Wed Jul 23 20:38:03 CEST 2008): Configuring with newInstance=false, secondsToRefresh=-1
RuleAgent(default) INFO (Wed Jul 23 20:38:03 CEST 2008): Configuring package provider : URLScanner monitoring URLs:  https://localhost:8443/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST
RuleAgent(default) WARNING (Wed Jul 23 20:38:04 CEST 2008): Was an error contacting https://localhost:8443/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST. Reponse header: {}
RuleAgent(default) EXCEPTION (Wed Jul 23 20:38:04 CEST 2008): Was unable to reach server.. Stack trace should follow.
java.io.IOException: Was unable to reach server.
        at org.drools.agent.URLScanner.hasChanged(URLScanner.java:149)
        at org.drools.agent.URLScanner.getChangeSet(URLScanner.java:113)
        at org.drools.agent.URLScanner.loadPackageChanges(URLScanner.java:90)
        at org.drools.agent.RuleAgent.checkForChanges(RuleAgent.java:341)
        at org.drools.agent.RuleAgent.refreshRuleBase(RuleAgent.java:300)
        at org.drools.agent.RuleAgent.configure(RuleAgent.java:285)
        at org.drools.agent.RuleAgent.init(RuleAgent.java:209)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:177)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:149)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:217)
        at kijanowski.eu.GuvnorTest.main(GuvnorTest.java:12)
Exception in thread "main" java.lang.NullPointerException
        at org.drools.agent.RuleAgent.refreshRuleBase(RuleAgent.java:301)
        at org.drools.agent.RuleAgent.configure(RuleAgent.java:285)
        at org.drools.agent.RuleAgent.init(RuleAgent.java:209)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:177)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:149)
        at org.drools.agent.RuleAgent.newRuleAgent(RuleAgent.java:217)
        at kijanowski.eu.GuvnorTest.main(GuvnorTest.java:12)

If you navigate with your browser to this URL, you will be asked to accept the non-signed certificate. In case of our test application, we need to trust the server by importing its public key to our (temporary) local keystore:

$ mkdir /data/ssl

# export the public key
$ keytool -export -alias guvnor -keystore $JBOSS_SERVER/conf/guvnor.keystore -file /data/ssl/out.cert

# you don't have to provide a password
Enter keystore password:

*****************  WARNING WARNING WARNING  *****************
* The integrity of the information stored in your keystore  *
* has NOT been verified!  In order to verify its integrity, *
* you must provide your keystore password.                  *
*****************  WARNING WARNING WARNING  *****************

Certificate stored in file 

# import this key to a local truststore
$ keytool -import -alias guvnor -file /data/ssl/out.cert -keystore /data/ssl/myKS

Enter keystore password:  qwerty
Owner: CN=localhost, OU=My Department, O=My Company, L=My City, ST=My State, C=US
Issuer: CN=localhost, OU=My Department, O=My Company, L=My City, ST=My State, C=US
Serial number: 48862cb6
Valid from: Tue Jul 22 20:53:42 CEST 2008 until: Wed Jul 22 20:53:42 CEST 2009
Certificate fingerprints:
         MD5:  81:FD:97:97:12:E7:2B:94:DA:62:35:11:2C:2B:4E:2B
         SHA1: 7E:B1:36:F4:C9:F9:45:5A:98:F2:F1:46:F6:58:E6:0D:81:46:EC:B5
Trust this certificate? [no]:  yes
Certificate was added to keystore

Now we have a keystore with a server’s key that we trust. To use this keystore, just start the drools application with the following property:

-Djavax.net.ssl.trustStore=/data/ssl/myKS

In Eclipse, click on GuvnorTest.java. From the menu Run -> Open Run Dialog and then add this property to the VM arguments:

Now your Drools application runs in a secure environment.

Summary

This article has shown how you can upgrade your BRMS, which should only be deployed out-of-the-box for testing purposes. For a multiuser environment with mission-critical applications, Guvnor should be tuned. Have a look at this blog post, the JSSE Reference Guide or the key tool docs page for more details about the tools we used. For LDAP browsing I recommend this user-friendly and light-weight tool.

Guvnor is the business rules management system in Drools 5. When you deploy it out of the box, you get an unsecured web application that stores data in Jackrabbit’s embedded Derby database.

The first half of this series explains how to tune Guvnor deployed on JBoss Application Server 4.2.3. This means that we will use the container’s configuration files and security infrastructure. We will cover enabling password validation based on an OpenLDAP server, moving from the default data repository, and enabling SSL for better security in part 2.

1. Installation
2. Quick introduction
3. Enable user/password validation

Installation

We will deploy Guvnor as an exploded archive on the JBoss Application Server.

1. Download JBoss AS 4.2.3.GA and extract it to:

    /data/jboss-4.2.3.GA
   

2. Download Guvnor M1 and extract it to the deploy directory under:

    /data/jboss-4.2.3.GA/server//deploy/drools-guvnor.war
   

3. From now on we’ll use:

   $JBOSS_SERVER as /data/jboss-4.2.3.GA/server/
   $GUVNOR as /data/jboss-4.2.3.GA/server//deploy/drools-guvnor.war
   

4. To verify a successful deployment, start the server:

   $ /data/jboss-4.2.3.GA/bin/run.sh -c
   

   You should see the response below:

   JBoss Bootstrap Environment
   
   JBOSS_HOME: /data/jboss-4.2.3.GA
   
   JAVA: /usr/local/jdk1.5.0_11/bin/java
   
   JAVA_OPTS: -Dprogram.name=run.sh -server -Xms128m -Xmx512m -Dsun.rmi.dgc.client.gcInterval=3600000-Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv4Stack=true
   
   CLASSPATH: /data/jboss-4.2.3.GA/bin/run.jar:/usr/local/jdk1.5.0_11/lib/tools.jar
   
   =========================================================================
   
   17:13:53,732 INFO  [Server] Starting JBoss (MX MicroKernel)...
   17:13:53,734 INFO  [Server] Release ID: JBoss [Trinity] 4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200807181417)
   17:13:53,736 INFO  [Server] Home Dir: /data/jboss-4.2.3.GA
   .
   .
   .
   17:14:38,366 INFO  [TomcatDeployer] deploy, ctxPath=/drools-guvnor, warUrl=.../deploy/drools-guvnor.war/.
   .
   .
   

Navigate to http://localhost:8080/drools-guvnor and login as ‘admin’ without any password.

Guvnor is now up and running. Let’s see how we can get started quickly.

Quick introduction

Before you can start using Guvnor for rule authoring, you need to perform some basic setup. We will need to create a category, make a package, and upload your facts. Let’s log in.

Categories
You will need to create at least one category, under which you will store your rules. Categories are for classification purposes. You will normally want to provide meaningful names like ‘Insurance’ or ‘Discount,’ but for this test instance, we’ll just create ‘MyNewCategory.’ On the left side click on the ‘Administration’ tab, expand the ‘Admin’ list, and then click on ‘Categories’:

Create a category by clicking on ‘New category’ and providing a name.

Packages
A package is a place where rules are stored. It also includes globals and imports of all the facts and other classes we would like to use in our rules–for example, ArrayLists or Iterators. To create a package, expand the ‘Package’ tab and click on ‘Create New’ -> ‘New Package’

You can create a new package by providing its name (our example is myNewPackage) or by importing one from a drl file. In either case, you will need to provide the facts you’re going to use in your rules.

Facts
Next, you will create classes you would like to use in your rules. For this example, I’ll use a Driver and a Car class:

Driver.java
package kijanowski.eu;

public class Driver {

        private String name;
        private int age;
        private Car car;

        public Driver() {}

        public Driver(String name, int age, Car car) {
                this.name = name;
                this.age = age;
                this.car = car;
        }

        public String getName() {
                return name;
        }

        public void setName(String name) {
                this.name = name;
        }

        public int getAge() {
                return age;
        }

        public void setAge(int age) {
                this.age = age;
        }

        public Car getCar() {
                return car;
        }

        public void setCar(Car car) {
                this.car = car;
        }

}

Car.java
package kijanowski.eu;

public class Car {

        private String color;
        private double value;

        public Car() {}

        public Car(String color, double value) {
                this.color = color;
                this.value = value;
        }

        public String getColor() {
                return color;
        }

        public void setColor(String color) {
                this.color = color;
        }

        public double getValue() {
                return value;
        }

        public void setValue(double value) {
                this.value = value;
        }

}

Compile these java files (if not already done by your IDE) and create an java archive:

$ javac -d . *.java
$ jar cf model.jar kijanowski

Import the new model to your package. From the ‘Packages’ tab click on ‘Create New’ -> ‘Upload new Model jar’:

Provide a name and select myNewPackage as the destination package. Provide a path (or click on Browse and navigate) to your facts archive. Finally, click on Upload.

When you choose myNewPackage from the ‘Packages’ tab, you should see the imported facts:

Before these facts are available in rules, you need to save this package. Click on ‘Save and validate configuration’.

Rules
Now you can create rules. From the ‘Package’ tab select ‘Create New’ -> ‘New Rule’. Provide a name, choose a category, and select your favorite rule format with myNewPakage as the destination package:

A simple example is shown below:

Validate and save your rule by first choosing ‘Validate’ and–if all is ok–then ‘Save changes’. Now you can make this package and all its rules available to your applications.
Choose your package and click on ‘Save and validate configuration.’ Before building it, click on ‘Show package source’ to have a look at the whole package. When you’re done looking at the source, choose ‘Build package’. You should be able to access the package under http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST and in drl format at http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST.drl.

Now let’s create a simple Drools application that will use a package served by Guvnor.

Open Eclipse and create a new Drools project (as described in Introduction into Rule Engines) or use your favorite IDE (don’t forget to add drools-core.jar and mvel.jar to your classpath). Add model.jar to your classpath and create a test class:

package kijanowski.eu;

import org.drools.RuleBase;
import org.drools.WorkingMemory;
import org.drools.agent.RuleAgent;
import java.util.Iterator;

public class GuvnorTest {

        public static final void main(String[] args) {

                RuleAgent agent = RuleAgent.newRuleAgent("/Guvnor.properties");
                RuleBase ruleBase = agent.getRuleBase();

                WorkingMemory workingMemory = ruleBase.newStatefulSession();

                Driver d = new Driver("Jarek", 20, null);
                workingMemory.insert(d);

                workingMemory.fireAllRules();

                for (Iterator i = workingMemory.iterateObjects(); i.hasNext();) {
                        System.out.println(i.next().getClass().getCanonicalName());
                }
        }

}

This time we don’t read a package from the filesystem, but are configuring our rule agent with a properties file. One fact is inserted, rules are fired, and, in the end, we iterate over all facts in the working memory to make sure a Car fact has been inserted. We expect this will happen, don’t we? Check the rule if you’re in doubt. Let’s have a look at the properties file:

url=http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST

We provide the url that points to our package. There are a lot more attributes you can provide (read the Guvnor docs for details). When the application is run, you should get following output:

RuleAgent(default) INFO (Wed Jul 23 20:31:28 CEST 2008): Configuring with newInstance=false, secondsToRefresh=-1
RuleAgent(default) INFO (Wed Jul 23 20:31:28 CEST 2008): Configuring package provider : URLScanner monitoring URLs:  http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/package/myNewPackage/LATEST
RuleAgent(default) INFO (Wed Jul 23 20:31:29 CEST 2008): Applying changes to the rulebase.
RuleAgent(default) INFO (Wed Jul 23 20:31:29 CEST 2008): Adding package called myNewPackage
kijanowski.eu.Driver
kijanowski.eu.Car

This was just a quick introduction into Guvnor. A much more exhaustive description can be found in the Guvnor documentation.

Enable user/password validation

When deploying Guvnor, everyone can access it using the admin username–a password isn’t verified. However, Guvnor is designed to allow access to different users, who may have different skills and rights. Controlling access may be critical. To enable username/password validation, we need to edit Guvnor’s security configuration. This is located in:

$GUVNOR/WEB-INF/components.xml

We will want to set JAAS as the new authorization and authentication service. Comment out:

and add:

That’s all from the apps side. To configure JBoss AS, add the following to $JBOSS_SERVER/conf/login-config.xml:

          <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag = "required">
           props/guvnor-users.properties
           props/guvnor-roles.properties

We have chosen the file-based login module. We now need to create two files, where we will provide the admin username, password, and role:

$JBOSS_SERVER/conf/props/guvnor-users.properties
admin=admin123
$JBOSS_SERVER/conf/props/guvnor-roles.properties
admin=admin

We have now created an ‘admin’ user with the password ‘admin123′ and its role is ‘admin’.

You may want to have all your users in a database or directory. For all available login modules, have a look at this wiki.

In the current Drools 5M1 release, only the admin role is supported. You may want to have a look at drools-guvnor/src/main/java/org/drools/guvnor/server/security/RoleTypes.java for other roles implemented in future releases.

It’s been a good few weeks for stories and information about JBoss Rules and Drools, the open source project upstream of the JBoss subscription offering. Here is a quick summary of the recent stories. Post a comment if you know of any others we all should pay attention to.

• Pierre Fricke, JBoss product manager, writes about Daiwa Securities America Improves Performance and Reduces Costs with JBoss Enterprise Portal Platform. The Red Hat press release says, “In addition to the (JBoss) Portal Platform, Daiwa also uses the JBoss Rules framework to embed alerts into portal applications.”
• Two articles on Drools were published in Red Hat Magazine, Introduction to Drools: Rules fall from your eyes and JBoss Drools meets Hibernate. Both pieces are a good introduction to working with Drools.
• Drools continues to grow its library of widgets for the Guv’nor, which is the web tool and rules repository of Drools, formerly known just as the “Drools BRMS.” This new widget, rolodex, adds a flipping slideshow of photos pulled using Google Web Toolkit.
• A beta implementation of WordNet for Drools is being talked up by project lead Mark Proctor; they are seeking comments from users/testers in the Drools mailing list.
• Mark Proctor also writes, “We often get asked about Drools scalability in complex apps, so I thought I would link to this posting just done, where someone has Drools scaling to 900K facts on a 64bit JVM with reasonable performance.”
• More tools and features are being included in Drools all the time, such as adding Smooks as a data loader.

Jaroslaw is a JBoss QA Engineer based in Poland, and recently published an introduction to Drools that he kindly shared with us. This second piece covers Drools (or JBoss Rules), the open source business rules engine… in this case combining it with Hibernate.

This article is presented here in its entirety (with a trackback). The original can be found on Jaroslaw’s site. This article is also available in German and Polish.

Justification:

Drools evaluates facts which are present in the working memory. But could it also reason over data stored in a relational database? This feature would extend Drools’ range of applicability and since this is an often asked question in the mailing list, it’s worth to know the answer which sounds: “of course Drools can!”

Abstract:

Hibernate, one of the most favorite ORM tools, allows to handle data stored in a relational database. This article will describe how one can access a Hibernate session from inside the rule engine. I will use PostgreSQL as a data source. Besides that I will create two classes, Game and Player, having a many-to-many relationship.

1. Creating a new Drools project
2. Class files
3. Hibernate
4. Drools
5. How does it work?
6. Results
7. Summary

Creating a new Drools project

You still don’t have installed the Drools 4.0.7 Eclipse Workbench? Just have a look at this article: “Rules fall from your eyes”.

Menu File -> New -> Project -> Drools – > Rule Project -> Next. Provide the project’s name, drools-hibernate-demo, and click on Next, to uncheck the example files

Class files

Create a package “eu.kijanowski.drools.hibernate” in the src/main/java directory. We will use two class files, Player.java and Game.java. They have a many-to-many relationship, since one player can own many games and one game can be owned by many players

Class Game.java

package eu.kijanowski.drools.hibernate;

import java.io.Serializable;
import java.util.HashSet;
import java.util.Set;

public class Game implements Serializable {
	private static final long serialVersionUID = 1L;
	private Long id = null;
	private String name;
	private double price;
	private int levels;
	private Set players = new HashSet();

	public Game() {
	}

	public Game(String name, double price, int levels) {
		this.name = name;
		this.price = price;
		this.levels = levels;
	}

	public Long getId() {
		return id;
	}

	@SuppressWarnings("unused")
	private void setId(Long id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public double getPrice() {
		return price;
	}

	public void setPrice(double price) {
		this.price = price;
	}

	public int getLevels() {
		return levels;
	}

	public void setLevels(int levels) {
		this.levels = levels;
	}

	public Set getPlayers() {
		return players;
	}

	public void setPlayers(Set players) {
		this.players = players;
	}

	public String toString() {
		return name + " with " + levels + " levels for " + price;
	}
}

Class Player.java

package eu.kijanowski.drools.hibernate;

import java.io.Serializable;
import java.util.HashSet;
import java.util.Set;

public class Player implements Serializable {
	private static final long serialVersionUID = 1L;
	private Long id;
	private String name;
	private int age;
	private Set games = new HashSet();

	public Player() {
	}

	public Player(String name, int age, HashSet games) {
		this.name = name;
		this.age = age;
		this.games = games;
	}

	public Long getId() {
		return id;
	}

	@SuppressWarnings("unused")
	private void setId(Long id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

	public Set getGames() {
		return games;
	}

	public void setGames(Set games) {
		this.games = games;
	}

	public String toString() {
		return name;
	}
}

Hibernate

Without going into details, download the binaries, Hibernate Core 3.2.6 and extract the archive.

In our project create a directory called lib and copy over following files:

• hibernate-3.2.6.GA/lib/antlr-2.7.6.jar
• hibernate-3.2.6.GA/lib/asm.jar
• hibernate-3.2.6.GA/lib/cglib-2.1.3.jar
• hibernate-3.2.6.GA/lib/commons-collections-2.1.1.jar
• hibernate-3.2.6.GA/lib/commons-logging-1.0.4.jar
• hibernate-3.2.6.GA/lib/dom4j-1.6.1.jar
• hibernate-3.2.6.GA/hibernate3.jar
• hibernate-3.2.6.GA/lib/jta.jar

Now we have to add these libraries to the “build path”: from the menu choose Project -> Properties -> Java Build Path -> Libraries and then Add External JARs and navigate to the project’s lib directory. Mark all files and click OK.

It’s time to configure Hibernate. In the src/main/java directory create a file called hibernate.cfg.xml:

         org.postgresql.Driver
         jdbc:postgresql://localhost/droolsdb
         droolsuser

         1
         org.hibernate.dialect.PostgreSQLDialect
         org.hibernate.transaction.JDBCTransactionFactory

         thread
         org.hibernate.cache.NoCacheProvider
         true
         create

As you see, we’re going to use the org.postgresql.Driver class, hence we need to add another library to our project. From the PostgreSQL home page we can download the required driver. I’m using 8.2-508 JDBC 3. Don’t forget to add it to the Java Build Path, like we did with the hibernate library.

It’s time to download and start PostgreSQL and create a user and schema.

/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data>logfile 2>&1 &
/usr/local/pgsql/bin/createuser -h 127.0.0.1 -p 5432 -U postgres -s -d -R droolsuser
/usr/local/pgsql/bin/createdb -h 127.0.0.1 -p 5432 -U postgres -O droolsuser droolsdb

The last step is mapping – this is connecting the world of Java objects with the world of relations (tabels). Create model.hbm.xml in the eu.kijanowski.drools.hibernate package:

				player_id_seq

				game_id_seq

Drools

We’re almost there. We olny have to create the rule file and a testing class which will start our example. But how are we going to use Hibernate in our application? Well, in our testing class we will create a Hibernate session and provide it to the rule engine’s working memory as a constant global value. This allows us to access the database from inside the rule file. Next we will create a query and access the result’s objects using the keyword “from”. Let’s do this:

Class DroolsHibernateTest.java

package eu.kijanowski.drools.hibernate;

import java.io.InputStreamReader;
import java.io.Reader;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import org.drools.RuleBase;
import org.drools.RuleBaseFactory;
import org.drools.WorkingMemory;
import org.drools.compiler.PackageBuilder;
import org.drools.rule.Package;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.cfg.Configuration;

public class DroolsHibernateTest {

	private final static SessionFactory factory;
	static {
		Configuration cfg = new Configuration().configure();
		factory = cfg.buildSessionFactory();
	}

	public static final void main(String[] args) {
		try {

			Game g1 = new Game("BF2", 39.99, 5);
			Game g2 = new Game("AoE3", 129.99, 45);
			Game g3 = new Game("BF3", 139.99, 15);

			HashSet games1 = new HashSet();
			games1.add(g1);
			games1.add(g2);
			games1.add(g3);
			HashSet games2 = new HashSet();
			games2.add(g1);
			games2.add(g3);

			Player p1 = new Player("jarek", 26, games1);
			Player p2 = new Player("ewelina", 25, games2);

			System.out.println(p1.getGames());
			System.out.println(p2.getGames());

			/* open a Hibernate session and persist data */
			Session session = factory.openSession();
			Transaction tx = session.beginTransaction();
			session.save(p1);
			session.save(p2);
			tx.commit();
			session.close();

			/* Let's verify the persisted data */
			session = factory.openSession();
			tx = session.beginTransaction();

			List players = session.createCriteria(Player.class).list();
			System.out.println(players.size() + " player(s) found:");
			for (Iterator iter = players.iterator(); iter.hasNext();) {
				Player player = (Player) iter.next();
				System.out.println(player.getName() + " has following games: "
						+ player.getGames());
			}
			tx.commit();
			session.close();

			// load up the rulebase
			RuleBase ruleBase = readRule();
			WorkingMemory workingMemory = ruleBase.newStatefulSession();

			/* pass a hibernate session to the working memory as a global */
			session = factory.openSession();
			workingMemory.setGlobal("hibernateSession", session);

			workingMemory.fireAllRules();
			session.close();

		} catch (Throwable t) {
			t.printStackTrace();
		}
	}

	private static RuleBase readRule() throws Exception {
		// read in the source
		Reader source = new InputStreamReader(DroolsHibernateTest.class
				.getResourceAsStream("/Demo.drl"));

		PackageBuilder builder = new PackageBuilder();

		// this will parse and compile in one step
		builder.addPackageFromDrl(source);

		// get the compiled package (which is serializable)
		Package pkg = builder.getPackage();

		// add the package to a rulebase (deploy the rule package).
		RuleBase ruleBase = RuleBaseFactory.newRuleBase();
		ruleBase.addPackage(pkg);
		return ruleBase;
	}

}

The rule file can be created using the drools plug-in. Just click on the src/main/rules directory and from the menu File -> New -> Other… click Drools -> Rule Resource:

Demo.drl

package eu.kijanowski.drools.hibernate

global org.hibernate.Session hibernateSession;

rule "hibernate_from"
	when
		game:Game() from hibernateSession.createQuery("select games from Player p where p.age >= :age").setProperties( {"age" : 18 }).list()
	then
		System.out.println("The game "+game.getName() +"is owned by "+game.getPlayers());
end

How does it work?

Let’s have a look at the global keyword in the rule file. This allows us to provide the rule engine with constants and variables from outside. Potential usecases are:

• return results back to the application
• access services, like Hibernate, JMS, file writers, email senders, etc.

What’s worth to know is that you should never change a global, when you use it in the condition part (LHS) of a rule. Moreover globals are not designed to share any data between rules, this can be done via facts living in the working memory.

The condition element from allows to access data from other sources than the working memory. These can be Collectins, Maps and results coming from called methods. In our scenario we’ve created a query and received a list of games.

Results

After running our example (Run as -> Java Application) the console will show:

Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Environment 

INFO: Hibernate 3.2.6
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Environment
INFO: hibernate.properties not found
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Environment buildBytecodeProvider
INFO: Bytecode provider name : cglib
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Environment 

INFO: using JDK 1.4 java.sql.Timestamp handling
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Configuration configure
INFO: configuring from resource: /hibernate.cfg.xml
Jun 14, 2008 8:58:11 AM org.hibernate.cfg.Configuration getConfigurationInputStream
INFO: Configuration resource: /hibernate.cfg.xml
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.Configuration addResource
INFO: Reading mappings from resource : eu/kijanowski/drools/hibernate/model.hbm.xml
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.HbmBinder bindRootPersistentClassCommonValues
INFO: Mapping class: eu.kijanowski.drools.hibernate.Player -> PLAYERS
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.HbmBinder bindCollection
INFO: Mapping collection: eu.kijanowski.drools.hibernate.Player.games -> PLAYERS_GAMES
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.HbmBinder bindRootPersistentClassCommonValues
INFO: Mapping class: eu.kijanowski.drools.hibernate.Game -> GAMES
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.HbmBinder bindCollection
INFO: Mapping collection: eu.kijanowski.drools.hibernate.Game.players -> PLAYERS_GAMES
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.Configuration doConfigure
INFO: Configured SessionFactory: null
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: Using Hibernate built-in connection pool (not for production use!)
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: Hibernate connection pool size: 1
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: autocommit mode: false
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: using driver: org.postgresql.Driver at URL: jdbc:postgresql://localhost/droolsdb
Jun 14, 2008 8:58:12 AM org.hibernate.connection.DriverManagerConnectionProvider configure
INFO: connection properties: {user=droolsuser, password=****}
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: RDBMS: PostgreSQL, version: 8.2.5
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JDBC driver: PostgreSQL Native Driver, version: PostgreSQL 8.2 JDBC3 with SSL (build 508)
Jun 14, 2008 8:58:12 AM org.hibernate.dialect.Dialect 

INFO: Using dialect: org.hibernate.dialect.PostgreSQLDialect
Jun 14, 2008 8:58:12 AM org.hibernate.transaction.TransactionFactoryFactory buildTransactionFactory
INFO: Transaction strategy: org.hibernate.transaction.JDBCTransactionFactory
Jun 14, 2008 8:58:12 AM org.hibernate.transaction.TransactionManagerLookupFactory getTransactionManagerLookup
INFO: No TransactionManagerLookup configured (in JTA environment, use of read-write or transactional second-level cache is not recommended)
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Automatic flush during beforeCompletion(): disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Automatic session close at end of transaction: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JDBC batch size: 15
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JDBC batch updates for versioned data: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Scrollable result sets: enabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JDBC3 getGeneratedKeys(): disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Connection release mode: auto
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Default batch fetch size: 1
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Generate SQL with comments: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Order SQL updates by primary key: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Order SQL inserts for batching: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory createQueryTranslatorFactory
INFO: Query translator: org.hibernate.hql.ast.ASTQueryTranslatorFactory
Jun 14, 2008 8:58:12 AM org.hibernate.hql.ast.ASTQueryTranslatorFactory
INFO: Using ASTQueryTranslatorFactory
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Query language substitutions: {}
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: JPA-QL strict compliance: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Second-level cache: enabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Query cache: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory createCacheProvider
INFO: Cache provider: org.hibernate.cache.NoCacheProvider
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Optimize cache for minimal puts: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Structured second-level cache entries: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Echoing all SQL to stdout
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Statistics: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Deleted entity synthetic identifier rollback: disabled
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Default entity-mode: pojo
Jun 14, 2008 8:58:12 AM org.hibernate.cfg.SettingsFactory buildSettings
INFO: Named query checking : enabled
Jun 14, 2008 8:58:12 AM org.hibernate.impl.SessionFactoryImpl
INFO: building session factory
Jun 14, 2008 8:58:12 AM org.hibernate.impl.SessionFactoryObjectFactory addInstance
INFO: Not binding factory to JNDI, no JNDI name configured
Jun 14, 2008 8:58:12 AM org.hibernate.tool.hbm2ddl.SchemaExport execute
INFO: Running hbm2ddl schema export
Jun 14, 2008 8:58:12 AM org.hibernate.tool.hbm2ddl.SchemaExport execute
INFO: exporting generated schema to database
Jun 14, 2008 8:58:13 AM org.hibernate.tool.hbm2ddl.SchemaExport execute
INFO: schema export complete
[BF3 with 15 levels for 139.99, BF2 with 5 levels for 39.99, AoE3 with 45 levels for 129.99]
[BF3 with 15 levels for 139.99, BF2 with 5 levels for 39.99]
Hibernate: select nextval ('player_id_seq')
Hibernate: select nextval ('game_id_seq')
Hibernate: select nextval ('game_id_seq')
Hibernate: select nextval ('game_id_seq')
Hibernate: select nextval ('player_id_seq')
Hibernate: insert into PLAYERS (NAME, AGE, PLAYER_ID) values (?, ?, ?)
Hibernate: insert into GAMES (NAME, PRICE, LEVELS, GAME_ID) values (?, ?, ?, ?)
Hibernate: insert into GAMES (NAME, PRICE, LEVELS, GAME_ID) values (?, ?, ?, ?)
Hibernate: insert into GAMES (NAME, PRICE, LEVELS, GAME_ID) values (?, ?, ?, ?)
Hibernate: insert into PLAYERS (NAME, AGE, PLAYER_ID) values (?, ?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: insert into PLAYERS_GAMES (PLAYER_ID, GAME_ID) values (?, ?)
Hibernate: select this_.PLAYER_ID as PLAYER1_0_0_, this_.NAME as NAME0_0_, this_.AGE as AGE0_0_ from PLAYERS this_
2 player(s) found:
Hibernate: select games0_.PLAYER_ID as PLAYER1_1_, games0_.GAME_ID as GAME2_1_, game1_.GAME_ID as GAME1_2_0_, game1_.NAME as NAME2_0_, game1_.PRICE as PRICE2_0_, game1_.LEVELS as LEVELS2_0_ from PLAYERS_GAMES games0_ left outer join GAMES game1_ on games0_.GAME_ID=game1_.GAME_ID where games0_.PLAYER_ID=?
jarek has following games: [AoE3 with 45 levels for 129.99, BF3 with 15 levels for 139.99, BF2 with 5 levels for 39.99]
Hibernate: select games0_.PLAYER_ID as PLAYER1_1_, games0_.GAME_ID as GAME2_1_, game1_.GAME_ID as GAME1_2_0_, game1_.NAME as NAME2_0_, game1_.PRICE as PRICE2_0_, game1_.LEVELS as LEVELS2_0_ from PLAYERS_GAMES games0_ left outer join GAMES game1_ on games0_.GAME_ID=game1_.GAME_ID where games0_.PLAYER_ID=?
ewelina has following games: [BF3 with 15 levels for 139.99, BF2 with 5 levels for 39.99]
Hibernate: select game2_.GAME_ID as GAME1_2_, game2_.NAME as NAME2_, game2_.PRICE as PRICE2_, game2_.LEVELS as LEVELS2_ from PLAYERS player0_ inner join PLAYERS_GAMES games1_ on player0_.PLAYER_ID=games1_.PLAYER_ID inner join GAMES game2_ on games1_.GAME_ID=game2_.GAME_ID where player0_.AGE>=?
Hibernate: select players0_.GAME_ID as GAME2_1_, players0_.PLAYER_ID as PLAYER1_1_, player1_.PLAYER_ID as PLAYER1_0_0_, player1_.NAME as NAME0_0_, player1_.AGE as AGE0_0_ from PLAYERS_GAMES players0_ left outer join PLAYERS player1_ on players0_.PLAYER_ID=player1_.PLAYER_ID where players0_.GAME_ID=?
The game BF2is owned by [jarek, ewelina]
Hibernate: select players0_.GAME_ID as GAME2_1_, players0_.PLAYER_ID as PLAYER1_1_, player1_.PLAYER_ID as PLAYER1_0_0_, player1_.NAME as NAME0_0_, player1_.AGE as AGE0_0_ from PLAYERS_GAMES players0_ left outer join PLAYERS player1_ on players0_.PLAYER_ID=player1_.PLAYER_ID where players0_.GAME_ID=?
The game BF3is owned by [jarek, ewelina]
Hibernate: select players0_.GAME_ID as GAME2_1_, players0_.PLAYER_ID as PLAYER1_1_, player1_.PLAYER_ID as PLAYER1_0_0_, player1_.NAME as NAME0_0_, player1_.AGE as AGE0_0_ from PLAYERS_GAMES players0_ left outer join PLAYERS player1_ on players0_.PLAYER_ID=player1_.PLAYER_ID where players0_.GAME_ID=?
The game AoE3is owned by [jarek]
The game BF2is owned by [jarek, ewelina]
The game BF3is owned by [jarek, ewelina]

Summary

This article shows how you can easily integrate Hibernate with the Drools rule engine. This allows you to reason over data, which does not only live in the working memory, but also in an external database.

Related articles

• Video: Mark Proctor and JBoss Drools
• Video: Mark Proctor, part 2: Origins and uses of JBoss Drools

One of our long-time writers introduced us to Jaroslaw, a JBoss QA Engineer based in Poland, and mentioned that he’d been working on some documentation we might find interesting. And, boy, do we! This first piece de-mystifies the complex world of rules engines. Whether you call it Drools, or JBoss Rules, or JBoss Drools… you still might want to know what it does and how it functions in your technical environment. (Not to mention that it’s just all kinds of logical and interesting–if you like brainteaser word puzzles or abstract math questions, this qualifies as pleasure reading.)

This article is presented here in its entirety (with a trackback). The original can be found on Jaroslaw’s site. This article is also available in German and Polish.

Justification:

Either you’re a developer, architect or a business analyst, it’s worth to get familiar at least with the first chapter of this article. It contains an introduction into the world of rule engines, which increase the readability of certain applications and make them easier to manage and to maintain. It applies to apps that take decisions, which depend on events or a state of some objects.

Abstract:

This article contains an introduction to rule engines, a description of an installation of Eclipse IDE and a guide how to configure Eclipse with the Drools Workbench plug-in.

1. A Rule Engine
2. Drools
3. Advantages of the Drools rule engine
4. BRMS
5. Production rules vs. events
6. Let’s get started!
7. What happened?
8. Summary

A Rule Engine

A rule engine is a piece of software, which having some knowledge is able to perform conclusions. Knowledge and inferences are stored in rules, which are called production rules. In other words, production rules consist of conditions and actions, which are executed when their conditions are true. Besides that there’s a working memory, which stores all objects we may want to use while making a decision. The state of this memory can vary, because actions can add, delete or change existing objects. Moreover rules can get into a conflict. This happens when there are more than one rule which are true, at the same time. Then conflict resolution is provided by the agenda. It arranges the order of actions, which has been selected to be run. The agenda is an important part of a rule engine, because the execution of an action may invalidate a rule and in consequence cancel another action. To sum it up, a rule engine can be presented as follows:

Rule engines perfectly fits to:

• calculate a discount of orders based on the amount or price
• determine an insurance policy dependent on the age of the driver and the value of the car
• make a diagnosis
• detect imminence of failure
• solve riddles

Drools

One of the open source implementations of a rule engine is Drools. It’s a Java library distributed under the Apache license. It’s available as as a binary and a source download. You can get it and use in your applications for free.

The heart of a rule engine is an inference engine. Its job is to match facts and rules (pattern matching) to make conclusions which ends in running actions. This matching is done by the RETE algorithm, which has been extended by object oriented concepts.

As I already mentioned, knowledge is presented in form of production rules. Knowledge representation, which is a way to provide the rule engine with data, is based on FOL – first order logic. FOL allows to evaluate expressions like 2 + 3 == 5 or customer.age > 17.

The two main parts of a production rule are its condition(s) and action(s):

when
	Customer (age > 17)
	then
	System.out.println("Customer is full age");

The rule above is going to evaluated as true for all those facts, which represents full age customers. A similar sql query would look as follows:

SELECT * from Customers c WHERE c.age > 17

There are two ways to determine the truth of a rule (condition) and run its action in consequence. Forward chaining is driven with facts. Rules are checked, which conditions are true for facts being in the working memory. The process of pattern matching finishes, when there are no more rules left, whose conditions are true. Backward chaining on the other hand is a goal
driven approach. Only those rules are checked, whose actions can be matched with a goal. If that is the case, conditions of that rule are evaluated.

Advantages of the Drools rule engine

• separates your application from conditions which control the flow
  • rules are stored in separate files
  • rules can be modified by different groups of people
  • changing rules does not require to recompile or to redeploy the whole application
  • putting all rules into one place makes it easier to control or manage the flow of the application
• rules can replace complex if – then statements in an easy and readable way
  • the rule language is not very difficult to learn
  • a plug-in for Eclipse IDE makes it easier to write rules and allows to have a look at the RETE tree
• problems are not solved using a complicated algorithm, but via rules, which are easier to read and understand than
  code
  • with declarative programming you are focused on WHAT you are solving, and not HOW
  • a group of problems can be easily solved with rules, where the algorithmic approach may be unusable (too complex, too time consuming, etc)
• access to the reasoning process allows you to understand why a particular decisions has been made

Summing up a rule engine should be considered when the solution of a problem seems complex or simply the algorithm contains a lot of it – then or switch statements. Rules should be also taken into account, when logic that drives your application often changes or has to be managed by people who don’t (or shouldn’t) have access to the application itself (to recompile/redeploy it).

BRMS

Drools is not just a rule engine. It provides also an application for managing rules, called Business Rules Management System. It allows to create, modify, delete, branch and persist rules. Moreover it’s possible to assign roles to users and a login mechanism and LDAP integration makes it easy to introduce security. So for example, a business analyst may have access to modify a rule, a developer on the other hand may be able only to read it. A BRMS is a single point of truth.

Production rules vs. events

Production rules consists mainly of conditions (when) and actions (then), e.g. when there’s a customer, who has a driving license for less than 5 years, then offer her an expensive insurance. Other type of rules are events (event condition action). In that case a rule engine looks for event patterns to match registered events. An event may be selling the last item or a breakdown of traffic lights. Another difference is the moment, when actions are executed. In the production rules environment, it’s the developer, who decides, when the rule engine is going to fire all actions. However, when working with events, an action is fired, when the associated event did happen.

Let’s get started!

… and install an IDE. I’ve chosen Eclipse, because it’s good enough and Drools provides a plug-in for writing rules.

Eclipse IDE, Eclipse IDE for Java EE Developers (eclipse-jee-europa-winter-linux-gtk.tar.gz)

After you’ve downloaded it, extract and start Eclipse. From the menu click on Help -> Software Updates -> Find and install… -> Search for new features to install -> New Remote Site…

You can find the URL on the Drools downloads page under “Drools IDE Update Site”. It’s a link to the plug-in. For Drools 4.0.7 Eclipse Workbench for Europa 3.3 it is http://downloads.jboss.com/drools/updatesite3.3/

We choose OK and Finish. Eclipse will show the search results:

Click on Next, accept the license and choose Finish, to start to download the plug-in. After that Eclipse will show another window, where we click on “Install all”. When asked for a restart we click on “Yes”. To verify a successful installation of the plug-in, make sure a new Drools icon showed up in the toolbar.

Let’s have a look at our first Drools application. Click on the Drools “head” and choose “New Rule Project”.

Type a name for the project and click Finish. The Drools plug-in creates a standard layout and provides all the necessary libraries to get started. To run this application click on com.sample.DroolsTest and press “Shift + Alt + X” and then “J”. The console will show th following:

Hello World
	Goodbye cruel world

What happened?

This example has been described in the Drools documentation. I’m not going into detail what’s happening in DroolsTest.java, where the rule engine is initialized and rules are read. The more interesting part is the rule file itself, Sample.drl.

This file has two rules. At the beginning, the working memory contains one object of the class Message, whose fields message and status are set to “Hello World” and “0″. When fireAllRules() is called, all actions are going to be executed. It’s worth to note that conditions of rules are evaluated when an object is added into the working memory. The condition of the rule called “Hello World” is true, because there is an object in the working memory, which is a Message and has a status equal to “0″. Hence actions of this rule are going to be run. As a result, the status and message fields of that Message object are going to be modified. The update() command forces the rule engine to evaluate its rules again. This time the second rule’s condition is true and appropriate actions are executed.

Summary

This short introduction into the world of rule engines and the chosen implementation Drools showed their main characteristics and some potential fields of use. To get more familiar with this software I would suggest to read the Drools documentation.

Related articles

• Video: Mark Proctor and JBoss Drools
• Video: Mark Proctor, part 2: Origins and uses of JBoss Drools

The first candidate release (CR1) for JBoss Application Server 5 has been released. There is a lot of good background from Sacha Labourey and feature details from project lead Dimitris Andreadis. Now that version 5 of the new application server has been through alpha and beta stages, this candidate release is a great opportunity for developers to get knowledge and practice on the next gen app server.

(Tip of the hat for Ales Justin’s post about the CR1. Ales also posts new information about SpringDeployer and VFS .)

One of the joys of software development is the ease with which you can create complex stuff out of thin air–or your own imagination. Creating new software may fulfill a need that could not otherwise be met. However, you can take advantage of a standardized way of doing things, so that you don’t have to start from scratch every single time. In the case of infrastructure software, using an established standard enables you to concentrate on your specific business needs, and not the supporting systems.

The seed of this article is actually a comment on the first article^[1] in this series. In that first article, I described middleware as though it were plumbing. I chose to use this analogy as the term “middleware” is often misunderstood. My rationale for the plumbing analogy was that plumbing and middleware share these characteristics:

First, it’s mostly invisible. Second, it provides a standard way of doing things. Third, it ties together parts of complex systems. Fourth, and finally, it lets you worry about other things.

What I was getting at with the fourth characteristic is this: With middleware, application developers don’t have to re-invent the software infrastructure needed to support their applications. Instead, they can concentrate on the business logic of the application. In the article, I said, “When you put an addition onto a house, what do you worry about? Bathroom fixtures, kitchen appliances, flooring, colors, and how to pay for it all. It’s a very stressful process. The last thing you want to worry about is whether you want 3/4-inch or half-inch pipe, copper or PVC connectors, #9 or #17 solder, etc. With middleware taking care of all the invisible functions, you (as a software developer or a business owner) can concentrate on building software to solve your business problems and fulfill your customers’ needs.”

That article has received several responses from readers. One response included this comment:

“…Except that when you do build your addition, you will need to worry about those exact issues. You’ll need adapters for attaching new metric pipes to old Imperial sizes; you’ll probably have couplers that are designed to connect plastic to copper; and you’ll also need to know the current regulations about when to use copper, plastic, or (heaven forbid) steel. In this sense, your analogy that middleware is like plumbing is surprisingly accurate. Just when you aquire all the materials and expertise in working with one standard, a new standard replaces it, and you start all over again, with the added headache of making the two work together during the transition period…At least that has been my experience over the past twenty years as a developer.”

Now, I hadn’t planned on writing a series of articles on middleware, but that reader’s comment got me thinking about adapters. Not the kind of adapter that you use to tie together different generations of water pipes in your house, but the kind of connections that the adapters in an ESB make possible.

JBoss ESB

Just like “middleware,” the term “ESB” can cause confusion.

An Enterprise Service Bus (ESB) is not a single program or technology. It’s really a matter of software architecture or design. Let’s take a step back from all the jargon and keep it simple. In hardware terms, a “bus” is a physical connector that ties together multiple systems or subsystems. Instead of having a large number of point-to-point connectors between pairs of systems, you connect each system to the bus once.

An ESB does the same thing, logically, in software. Instead of passing electric current or data over the bus to and from the connections (or “endpoints”) on the ESB, the ESB logically sits in the architectural layer above a messaging system. The messaging system allows for asynchronous communications between services over the ESB. In fact, when you are working with an ESB, everything is either a service (which in this context is your application software) or a message being sent between services. It’s important to note that a “service” is not automatically a web service. Other types of applications, using transports such as FTP or JMS, can also be services.

Is an ESB the same thing as SOA? (Service Oriented Architecture)

Not exactly. An ESB does not provide a Service Oriented Architecture, but it does provide the tools than can be used to build one–especially loose-coupling and asynchronous message passing. SOA is a series of principles, patterns, and best practices. The key initial “A” is for “architecture.” In this article, we’ll discuss JBossESB^[2].

Raising Your (ESB) Awareness

We just talked about considering everything in an ESB as either a message or a service. That’s fine for inside the ESB. How does a client or service–especially legacy applications–connect to an ESB?

To answer that question, we have to think about awareness.

No, I’m not talking about getting in touch with your inner child. I’m talking about whether or not your application clients and services are “ESB-aware” or, in other words, whether they can understand the message formats and transport protocols used by the ESB. If you (as a programmer) are ESB-aware, then you can simply code any new clients and services that you write to also be ESB-aware. ESB-aware clients and services communicate with each other using messages. ESB-aware services are identified using Endpoint References (EPRs). The messages take the form defined by the org.jboss.soa.esb.message interface. As the javadocs^[4] for message says:

A message consists of the following components:

• Header: the header information contains information such as the destination EPR, the sender EPR, and where the reply goes–general message-level functional information.
• Context: additional information that further explains the message; for example, transaction or security data, the identity of the ultimate receiver, or HTTP-cookie-like information.
• Body: the actual payload of the message.
• Fault: any error information associated with the message.
• Attachment: any attachments (additional files) associated with the message.
• Properties: any message-specific properties (for example the jbossesb.message.id property is a unique value for each message.

What about cases where legacy clients and services that are not ESB-aware need to be able to communicate over the ESB? What about cases where legacy clients and services need to be able to communicate with newer ESB-aware clients and services? Oh, and how about ESB-aware clients that we need to be able to use with ESB-unaware services?

This is suddenly getting complicated. It sounds like you will have to build lots of custom plumbing adapters to get all these combinations of clients and services to talk to each other. But don’t panic and don’t start building home-grown infrastructure. Supporting interoperability between different clients and services is one of the goals of JbossESB.

Interoperability through ESB adapters

One of the ways that JBossESB makes this interoperability possible is though gateway adapters.

Remember how I said that in an ESB, everything is either a message or a service? Well, a gateway (org.jboss.soa.esb.listeners.gateway) is a service that acts as a bridge between an ESB-aware and an ESB-unaware client and service. Gateways translate information between ESB and non-ESB message formats and EPRs. (And EPR stands for endpoint reference.) Gateways are listener processes in that they “listen” for incoming communications. They are different from ESB-aware listeners in that they accept data in different formats such as objects in files or SQL tables. ESB-aware listeners can only accept messages in the org.jboss.soa.esb.message format.

JBossESB supports these gateways:

• file gateways: local filesystem, ftp, sftp and ftps
• JMS
• HTTP/HTTPS
• email (POP3)
• SQL table
• Hibernate

When a gateway listener hears something, it converts the non-JBossESB messages that it receives to the org.jboss.soa.esb.message format. How this conversion happens depends on the gateway type. For example, the file gateway takes the contents of the file and puts it into the location named BytesBody.BYTES_LOCATION within the message body.

Let’s look at an example.

A quick start (with a quickstart)

One of the helpful features included in JBossESB is the set of “quickstart” sample applications. The quickstarts demonstrate JBossESB functions and integrations. The goals of the quickstarts are to serve as learning tools and as a starting point for your own application coding. We’ll examine one of these quickstarts to view the operation of a gateway.

Let’s assume that you have a legacy application that stores data in text files. What you want to do is to create an ESB-aware service to read these files and process them as they are created. You could write infrastructure code that periodically polls a target directory to determine when a new file is deposited there. With JBossESB, however, you can simply use a file gateway.

First, let’s install and start up a JBossESB server. Before you start, you will need to install Java (1.4 or 1.5) and ant (1.6.5 or later).

Next, download the JBossESB server from http://www.jboss.org/jbossesb/downloads/. For this illustration, download the JBossESB 4.2.1 GA Binary and unzip it:

unzip jbossesb-server-4.2.1GA.zip

Then, configure the quickstarts to know about the install directory for the JBossESb server by editing jbossesb-server-4.2.1GA/samples/quickstarts/conf, and setting org.jboss.esb.server.home to the directory into which you installed the JBossESB server

Now start the server:

sh jbossesb-server-4.2.1GA/bin/run.sh -c default

The quickstarts are distributed under the samples/quickstarts directory. Let’s take a look at helloworld_file_action.

cd jbossesb-server-4.2.1GA/samples/quickstartshelloworld_file_action

Deploy the test to the server and run it with these simple commands:

ant deploy
ant runtest

The server output should look something like this:

16:42:22,744 INFO [STDOUT] Message structure:
16:42:22,744 INFO [STDOUT] [Hello World In A File].
16:42:22,746 INFO [STDOUT]
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
16:42:22,746 INFO [STDOUT] Body: Hello World In A File
16:42:22,746 INFO [STDOUT] &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
16:42:22,747 INFO [STDOUT] Message structure:
16:42:22,747 INFO [STDOUT] [ message: [ JBOSS_XML ]

What just happened here? Let’s take a look. The “runtest” and target invokes CreateTestFile.java program. As its name implies, this program creates a test file. The file contains this text: Hello World In A File

For what happens next, we need to look at how the test application is configured in the ESB. A JBossESB application’s primary configuration file is named jboss-esb.xml. In the case of this quickstart, that file is generated at run time so that the JBossESB install directory can be determined. So, we need to look at the source of the generated file, jboss-esb-unfiltered.xml.

The first part of the file that we’re interested in looks like this:

This is the definition of the file gateway that we’ll use. Note the directory names. In this example, they are filled in at run time from values determined by the directory in which you installed JBossESB.

Now, remember how we said that everything in the ESB is either a message or a service? Scroll down in the file and we’ll see our service.

Let’s look at this service description.

First, the listeners. Note the definition of the file system (fs) listener. This is our gateway. The “busidref” field references the “fs-provider” that we discussed a minute ago. Did you notice a second listener? This is an ESB-aware JMS listener. It is there because JBossESB requires that each gateway have a corresponding ESB listener defined.

Let’s look at the actions. The “mep” definition of “OneWay” refers to the action pipeline (the sequence of actions) explicitly not sending a response. (You can find more detail about these definitions in the ESB Programmers’ Guide ^[7].)

The actions named “testAction” and “dump” write the message to the server log. The action that we’re most interested in is “action1.” The methods (displayMessage, playWithMessage) in the class referred to by this action (org.jboss.soa.esb.samples.quickstart.helloworldfileaction.MyAction) receive the data in the input file as an ESB-Aware message, extract that information, and process it. In the case of your application, you would replace “MyAction” with your own business logic code.

So, in summary, what happens when this quickstart is run?

1. The file system gateway is initialized.
2. A file is created in the input directory defined in its fs-provider definition.
3. The gateway reads the file, transforms it into an ESB-aware message, and passes the message to the methods in the action class defined in the action definition.
4. These methods process the message (in the case of the quickstart, they write the message contents to the server log).5. The gateway moves the file to the output directory defined in its fs-provider definition.

It’s important to note that the only new code that had to be written is the action class. The infrastructure code to listen for and transform the file into a message in the format that the ESB can process is all part of the gateway.

From the perspective of an application developer, this is a plus as you can concentrate on writing code to fulfill the business process requirements of your application.

From the perspective of a QE engineer, this is a real plus as it means that less code has to be written. And, the less code, the fewer opportunities for bugs!

What’s next?

In the next article in this series, we’ll take a look at the counterpart to listeners: the notifiers. The listeners enable you to get information into the ESB. Notifiers provide one way to get information out.

Resources

^[1] Read the first article in this series – What is middleware? (In plain english, please.)
^[2] JBossESB – http://labs.jboss.com/jbossesb/
^[3] JBossESB Connectors and Adapters Guide
^[4] JBossESB javadoc: jboss/soa/esb/message/Message.html
^[5] JBossESB quick start
^[6] JBossESB getting started guide (4.2.1GA)
^[7] JBossESB Programmers Guide

Acknowledgments

The author would like to thank the members of the JBossESB project and community (especially Burr Sutter and Mark Little) and the SOA Platform project for their help and timely review comments. This article relies heavily on the excellent JBossESB user documents and the quickstarts.

About the author

Len DiMaggio is a senior QE engineer for JBoss middleware at Red Hat. When he’s not building tests and generally breaking things, he likes writing, photography, and chauffeuring the kids to their many sports activities. Len is a frequent contributor to Red Hat Magazine (this is Len’s 10th article in the magazine), and has also written for Dr. Dobbs’ Journal, STQE, Software Development, IBM DeveloperWorks, and other publications. Len also recently launched a blog dedicated to software testing.

A previous post, How to get OpenJDK 6 for Red Hat Enterprise Linux 5, covered how to install OpenJDK for Fedora Extra Packages for Enterprise Linux (EPEL) 5. Now these instructions are at an even easier URL to remember:

http://openjdk.java.net/install/#fedora

These instructions cover installing OpenJDK 6 for Fedora 9 and EPEL 5, as well as IcedTea 7 for Fedora 8. IcedTea 7 provides the OpenJDK 7 development branch with IcedTea components to make it build under Fedora using entirely open source components. The package name remains the same in the repository, despite the trademark agreement allowing the OpenJDK mark to be used by Fedora, because it is considered too disruptive to rename it now.