Chapter 3. Getting started

3.1. Getting JBoss jBPM BPEL

The releases of JBoss jBPM BPEL can be found in the jBPM download page. The jBPM BPEL package contains the software sources and binaries, plus the third-party libraries it depends on.

The BPEL Runtime builds on jBPM 3. Downloading the jBPM jPDL distribution separately is strongly recommended but strictly optional, as the BPEL package already contains the required jBPM binaries.

Once you download the package, unzip it to a suitable location in your machine. It should all unzip into a single directory named jbpm-bpel-<version>. Make sure you don't use a directory which has any spaces in the path (such as the Program Files directory on Windows) as this may cause problems.

Alternatively, you can get the software from CVS with the following parameters. Once you have access, look for module jbpm.3/bpel.

Table 3.1. CVS parameters

ParameterValue
Connection typepserver
Useranonymous
Password(when prompted for a password, just press enter)
Hostanoncvs.forge.jboss.com
Port2401 (the default)
Repository path/cvsroot/jbpm

3.2. Getting JBoss Application Server

The jBPM BPEL software builds on J2EE 1.4 APIs and a number of open source projects. While no binary dependency on JBoss AS exists, this guide provides deployment instructions for JBoss AS only. Even if you use a different application server in production, we still encourage you to try it along with JBoss AS in a development machine. If you like it and decide to take it to production, we can help you through the forum or our support services.

For instructions on getting JBoss AS, see Downloading and Installing JBoss.

Note

Please make sure you select a JBoss AS version and server profile compatible with J2EE 1.4. jBPM BPEL has been tested with versions 4.0.3.SP1, 4.0.5.GA, 4.2.0.GA and 4.2.2.GA using the default profile.

On version 4.0.3.SP1, the purchase and loan examples do not work because they have multiple partner links where attribute myRole is set. Conversely, 4.0.4.GA does not work at all, as the SAAJ implementation was unstable at that time.

3.3. Getting Apache Ant

Ant scripts dramatically simplify the development and deployment of BPEL proceses. The tutorial assumes you have installed Ant and are able to execute targets. Furthermore, you need Ant to build the jBPM BPEL enterprise application. For directions on getting Ant, see Installing Ant.

Note

In order to run junit tasks, Ant requires the JUnit library. You can find this library under lib/junit. Remember to copy it to Ant's lib directory.

3.4. Enterprise application setup

The jBPM BPEL enterprise application (jbpm-bpel.ear) contains the libraries and configuration files required to execute BPEL processes. The following sections describe how to configure, package and deploy the application to JBoss AS.

3.4.1. Application configuration

The configuration files reside in the config directory.

3.4.1.1. Hibernate configuration

Starting from version 1.0 alpha 3, the BPEL Runtime incorporates the jBPM persistence model, described in the chapter on persistence of the jBPM user guide. jBPM uses Hibernate as its object-relational mapping solution. The next table describes the Hibernate configuration files.

Table 3.2. Hibernate configuration files

FileLocationNotes
jbpm.hibernate.cfg.xmlconfig

Contains database connection properties and references to object-relational mapping files.

Since the jBPM BPEL service runs inside the application server, you should configure Hibernate to obtain connections from a data source registered in JNDI. Refer to the Configuration chapter of the Hibernate manual for instructions.

Among the properties in jbpm.hibernate.cfg.xml, hibernate.connection.datasource is of particular interest. This property specifies the name of a data source in the JNDI registry. The preset value, java:/DefaultDS, references a predeployed data source in JBoss AS.

3.4.1.2. jBPM settings

The file jbpm.cfg.xml contains the jBPM configuration. The following table summarizes the most relevant jBPM settings.

Table 3.3. Most relevant jBPM settings

SettingNotes
jbpm-contextConfigures the jBPM context with a set of services. The persistence , tx, scheduler and integration services are required. Other services are not used by the BPEL Runtime and may be disabled.
resource.hibernate.cfg.xmlSpecifies the classpath resource used to configure Hibernate.

3.4.2. Application packaging

Once you have set the configuration, building the enterprise archive is easy. Go to directory config and open the build.properties file. Specify the JBoss AS installation path. Also indicate your preferred server configuration.

# property software.installation.dir is used to define jboss.home and jwsdp.home 
software.installation.dir=c:/dev

# jboss.home is used for deployment targets 
# this property is based on jboss.version to keep them in sync
jboss.version=4.2.2.GA
jboss.home=${software.installation.dir}/jboss-${jboss.version}
jboss.server=default

3.4.3. Deployment

Before deploying the service, start JBoss in the server configuration of your choice (see Server Configurations). Afterward, change to the deploy directory and run the following target. This builds a file named jbpm-bpel.ear which is then copied to the JBoss deploy directory.

ant deploy.ear

The next log entries confirm the deployment of the jBPM BPEL enterprise application. JBoss is now ready to enact BPEL processes.

00:48:31,140 INFO  [EARDeployer] Init J2EE application: .../jbpm-bpel.ear
00:48:32,859 INFO  [EjbModule] Deploying CommandServiceBean
00:48:32,906 INFO  [EjbModule] Deploying SchedulerControlBean
00:48:32,921 INFO  [EjbModule] Deploying CommandListenerBean
00:48:32,937 INFO  [EjbModule] Deploying JobListenerBean
...
00:48:33,171 INFO  [EJBDeployer] Deployed: .../jbpm-bpel-enterprise.jar
00:48:33,218 INFO  [TomcatDeployer] deploy, ctxPath=/jbpm-bpel, warUrl=.../jbpm-bpel-exp.war/
00:48:33,343 INFO  [EARDeployer] Started J2EE application: .../jbpm-bpel.ear

3.4.4. Web console

The jBPM BPEL application includes a web console you can access to manage the product and to verify the application is up and running. The screen shot below shows the console home page.

Console home page

Figure 3.1. Console home page