Resolving Sample Project Java Library Dependencies
Introduction
ActiveBPEL on Tomcat
ActiveBPEL on JBoss, WebLogic or WebSphere
Remote Deployment

How to Resolve ActiveBPEL Sample Project Java Library Dependencies

Introduction

Many of the ActiveBPEL Sample projects describe how to build client applications, custom invoke handlers, custom functions and other components using the Java Programming Language. These Java-based components depend on one or more jar files at compile- and run-time, and it is best to resolve these dependencies using the jars that are deployed with the version of ActiveBPEL and/or the server platform where you'll be running the sample applications. This document describes how to resolve these dependencies with the specific combination of development environment, version of ActiveBPEL and type of application server platform you're using.

Most of the jar files required during compilation and execution are supplied as part of your ActiveBPEL product distribution. Any additional required jars are provided with the sample archive. When building and running samples with ActiveBPEL on the Tomcat platform (e.g., ActiveBPEL^® Designer's Development Engine or ActiveBPEL^® Enterprise for Apache Tomcat) your build path can refer to these jars directly. When using the JBoss, WebLogic and WebSphere platforms, however, the jar files are shipped in an EAR file, and must be extracted to a location on the file system so they are accessible during the build process.

Note that these instructions assume you are building your sample components on the same host computer where you run your ActiveBPEL engine or Enterprise instance. If you are running the samples on ActiveBPEL deployed to a remote computer, please read through the appropriate section and then see the Remote Deployment section for additional information.

-- Please read ALL applicable instructions before performing any steps! ---

ActiveBPEL on the Tomcat Platform

If you using JBoss, WebLogic or WebSphere, skip ahead to the next section.

If you're running samples on the ActiveBPEL^® engine that ships with the free ActiveBPEL Designer, or you're using ActiveBPEL Enterprise for Apache Tomcat, then setting up dependency resolution is fairly simple. You will use a slightly different method depending on whether you prefer using the Ant build.xml script or the Eclipse IDE .classpath and.project files that are provided with each of the samples.

Using the Ant build.xml Script

Each sample with Java components includes an Ant build script: build.xml. Internally, this script is designed to resolve jar dependencies using an environment variable named AESAMPLES_LIB. You can instruct the build script to use a specific set of jar files by setting this environment variable to the directory containing those jars. For example, if you are running your samples with ActiveBPEL Enterprise for Apache Tomcat, and the Tomcat instance is installed in c:\jakarta-tomcat-5.0.28, you should already have an environment variable defined, named CATALINA_HOME, which points to the Tomcat install directory. If so, then set AESAMPLES_LIB as follows:

set AESAMPLES_LIB=%CATALINA_HOME%\shared\lib

You can do this on the command line immediately before executing the build script, or set this environment variable globally using the Windows dialog: right-click on My Computer (on the desktop), select Properties..., then the Advanced tab and then select the Environment Variables button to display the editor dialog.

If you don't have a CATALINA_HOME environment variable defined, you can either create one or simply set AESAMPLES_LIB to the full path of the jar file location, e.g.,

set AESAMPLES_LIB=c:\jakarta-tomcat-5.0.28\shared\lib

Once AESAMPLES_LIB is correctly defined, you can build and/or run any of the Java-based sample components using the appropriate ant [arg] command, as described in the documentation for that sample.

Using the Eclipse IDE .classpath and .project Files

Each sample includes an Eclipse IDE classpath and project definition files: .classpath and .project. If you examine the contents of the .classpath file, you'll notice that classpath entries are defined using a path Variable: AESAMPLES_LIB (note: this is an Eclipse-specific, internal Variable definition, NOT an operating system environment variable). To set this Variable in Eclipse, select Window / Preferences... from the main menu and navigate the tree on the left to Java / Build Path / Classpath Variables. Click New... and define the AESAMPLES_LIB Variable using the full path to the location of your jar files. For example, if you're using the ActiveBPEL engine that ships with ActiveBPEL Designer (installed in the default location), click the Folder... button and navigate to:

C:\Program Files\Active Endpoints\ActiveBPEL Designer\Server\ActiveBPEL_Tomcat\shared\lib

Set the Variable as follows:

When asked to do a full build, respond "Yes". You can now work with all ActiveBPEL samples using the Eclipse .classpath and .project files provided with each sample.

If you are not using JBoss, WebLogic or WebSphere, and you're building and running the samples on the same computer where ActiveBPEL is running, then you can skip the rest of this document.

If you have ActiveBPEL deployed to a remote server, then read and follow the additional instructions in the last section.

ActiveBPEL on the JBoss, WebLogic or WebSphere Platforms

As mentioned previously, the jar files required by the Java-based sample components are shipped in your ActiveBPEL Enterprise product inside an EAR on these three platforms. The jars can't be referenced there during the build process and must therefore be extracted and made accessible in a folder on your file system.

Getting Started

If you are viewing this web page on the Active Endpoints web site, click here (or here for the gzip-ed tar file) to download the archive for this How-to. Extract the archive to the root directory of your file system. It contains this documentation and an Ant build script that will perform the jar file extraction: build.xml. You will need Apache Ant 1.6.2 or greater to use this extraction script.

If you're setting up to work with ActiveBPEL Enterprise for JBoss, note that an environment variable - JBOSS_HOME - is created during JBoss installation to identify the location where JBoss is installed, and the jar extraction script will use this environment variable. However, if you're setting up for ActiveBPEL deployed to the WebLogic or WebSphere platform, the ActiveBPEL Enterprise EAR for must be located prior to extracting the jar files. You must identify this location by setting the WEBLOGIC_EAR or WEBSPHERE_EAR environment variable, as appropriate, to point to the fully-qualified path of the ActiveBPEL EAR before running the extraction script. For example, if you have installed ActiveBPEL Enterprise for WebLogic to the default location, you will set WEBLOGIC_EAR as:

set WEBLOGIC_EAR=C:\Program Files\Active Endpoints\...

...ActiveBPEL Enterprise for WebLogic\deploy\abe_weblogic90.ear

Extracting the Sample Library Dependencies

The extraction script provides a number of targets that will extract the necessary jar files from the EAR in your ActiveBPEL product install directory to the directory in which you run the script. These targets are:

JBoss - creates a copy of the jars installed with the ActiveBPEL Enterprise for JBoss product.

WebLogic - creates a copy of the jars installed with the ActiveBPEL Enterprise for WebLogic product.

WebSphere - creates a copy of the jars installed with the ActiveBPEL Enterprise for WebSphere product.

To create the working library of jar files, navigate to the AB_lib directory and execute the following:

ant [target]

Where [target] is one of the targets listed above. This will cause the script to delete any old jars in the AB_lib directory and copy those used by the product indicated.

Use ant clean to remove all jars from the AB_lib directory when you no longer need them.

Using the Ant build.xml Scripts

Each sample with Java components includes an Ant build script: build.xml. Internally, this script is designed to resolve jar dependencies using an environment variable named AESAMPLES_LIB. Once you have extracted the jars as described above, you can instruct the build script for each sample to use them by setting this environment variable to the directory containing the extracted jars. For example, if you extracted the jars into c:\AB_lib, then set AESAMPLES_LIB as follows:

set AESAMPLES_LIB=c:\AB_lib

Once AESAMPLES_LIB is correctly defined, you can build and/or run any of the Java-based sample components using the appropriate ant [arg] command, as described in the documentation for that sample.

Using the Eclipse IDE .classpath and .project Files

Each sample includes Eclipse IDE classpath and project definition files: .classpath and .project. If you examine the contents of the .classpath file, you'll notice that classpath entries are defined using a path Variable: AESAMPLES_LIB (note: this is an Eclipse-specific, internal Variable definition, NOT an operating system environment variable). To set this Variable in Eclipse, select Window / Preferences... from the main menu and navigate the tree on the left to Java / Build Path / Classpath Variables. Click New... and define the AESAMPLES_LIB Variable using the full path to the location where you just extracted your jar files. For example, if you extracted to c:\AB_lib, click the Folder... button and navigate to:

c:\AB_lib

Set the Variable as follows:

When asked to do a full build, respond "Yes". You can now work with all ActiveBPEL samples using the Eclipse .classpath and .project files provided with each sample.

If you'll be building and running your samples on the same computer where ActiveBPEL is running, you can skip the rest of this document.

If you have ActiveBPEL deployed to a remote server, then read and follow the additional instructions in the next section.

Remote Deployment

If you'll be deploying your Java-based sample components to a remote installation of ActiveBPEL, or using client components to invoke services on a remote ActiveBPEL Server, then you'll need to get copies of the jar and EAR files locally before performing any of the steps above.

ActiveBPEL Enterprise for Apache Tomcat

Perform a network copy or FTP all files in the server's %CATALINA_HOME%/shared/lib directory to a temporary directory on your development computer (the computer where you'll be building, and possibly running your sample Java components). If using the Ant build scripts, set the AESAMPLES_LIB envvar to point to this temporary directory. If using the Eclipse IDE, set the AESAMPLES_LIB Variable to point to this directory.

ActiveBPEL Enterprise for WebLogic or WebSphere

Perform a network copy or FTP the abe_weblogic90.ear or abe_websphere.ear file (as appropriate) to a temporary location on your local file system. Set the WEBLOGIC_EAR or WEBSPHERE_EAR envvar to point to the EAR file in this temporary directory. Now you can run the extraction script as described above to create a local copy of the jar files.

ActiveBPEL Enterprise for JBoss

In the case of JBoss, create a temporary directory named jbossLibTemp (in the file system root or %TEMP% - doesn't matter). Beneath that directory, create subdirectories client, lib and server. Under lib, create a subdirectory endorsed and under server create a subdirectory awf. Under awf, create deploy. The resulting temporary directory hierarchy should look like this:

jbossLibTemp
├─ client
├─ lib
│ └─ endorsed
└─ server
└─ awf
└─ deploy

Next, perform a network copy or FTP the files from the corresponding directories on your remote JBoss installation to your local file system:

//remoteServer/%JBOSS_HOME%/client/*.jar ==> jbossLibTemp/client

//remoteServer/%JBOSS_HOME%/lib/endorsed/*.jar ==> jbossLibTemp/lib/endorsed

//remoteServer/%JBOSS_HOME%/awf/deploy/abe_jboss.ear ==> jbossLibTemp/awf/deploy

On your local computer, open a command window and set the JBOSS_HOME directory to jbossLibTemp (wherever you created it), e.g.,

set JBOSS_HOME=c:\jbossLibTemp

Now you can run the extraction script to create local copies of the jar files needed. After extracting the jar files, you can delete jbossLibTemp and all its subdirectories and files.

In each of these cases, don't forget to set the AESAMPLES_LIB envvar or the Eclipse AESAMPLES_LIB Variable, as described above.