Tuesday, August 01, 2006

Using ANT in a BPEL environment


Updated: Sep 2007, for, download code here.

Oracle’s scalable application architecture in combination with the BPEL architecture combines the best elements to create a high available and high performance environment. Using tools to develop BPEL applications can be very complex when multiple environments exist.
In general there are the following environments;
  • Development
  • Test
  • Acceptance
  • Production
Depending on the customer requirements more or less environments exists.
This paper describes a solution to develop applications based on BPEL for multiple environments.


In general development of BPEL processes is done via an IDE tools. These tools are:
The first two products are graphical tools to design and develop BPEL processes. These tools can also be used for compilation and deployment of a BPEL process. The obant tool is part of the BPEL software stack and can be used to compile and deploy a BPEL process.
Combining these tools make is in general enough for designing and implementing BPEL applications.
It will be more complex if design and development must be done for various environments; developing new BPEL applications in development environment and fixing BPEL processes in a production environment.

The obant tool can compile from a current directory an ANT build.xml file. It will read the XML tags from this and interpret them. Oracle Jdeveloper generates this build.xml file when a new BPEL process is created.

It is possible to extend this “build.xml” file with other ANT tasks. But this is not logical. When developing BPEL applications, it will result in many BPEL processes, each having it’s own “build.xml” file.

A solution could be to have a general “build.xml” that is able to compile the BPEL processes.

A feature of the current obant tool, is that is only possible to use the core ANT tasks. It is not possible to use the optional tasks or even extend it with other tasks without changing the obant script.

The solution described in the next paragraphs will take this into account. The solution will cover the following features and can be easily change and extended to customer requirements:
  • Using full ANT tasks features
  • Multiple environments
  • Compiling multiple BPEL processes
  • Deployment to cluster environment
See also the white paper “Deploying BPEL processes in a High Available Application Cluster”

Directory Structure
Apart of using a version control tool to maintain all the files in a central repository, the files must be downloaded from this repository onto the hard drive. As source control tools as Oracle Source Control Management, SubVersion, CVS and ClearCase can be used.

The directory structure for this solution is as follows:


The meaning of the directory names is mentioned in the next table.

Directory Description
/home/mkelderm/projects/bpel The base directory of the BPEL application
ant The location of the ANT scripts.
ant/doc The location of the documentation that you are reading.
ant/properties The location of the properties files that the ANT build script is reading. For each environment an separate property file is created.
ant/templates In this directory the BPEL templates are located. By default an empty, asynchronous and a synchronous BPEL process are located here.
source In this directory all the source code that is related to the BPEL application is located beneath here.
source/default The BPEL domain.
source/default/dev The environment that is valid for the BPEL application. By default ‘dev’ is used. This could also be ‘test’, ‘prod’ or even version number.
source/default/dev/custom Any addition code, non-BPEL processes, related to the BPEL application is located here. For example custom Java code.
source/default/dev/HelloWorld As example a BPEL process is located beneath the ‘dev’ directory. In this case the BPEL process HelloWorld. Each BPEL process has its own sub directory.
derived Any file that is not source code related but can be derived from the source code is located here. For example compiled BPEL processes (JARS), java classes, java documentation
derived/default BPEL domain
derived/default/dev Environment
derived/default/dev/custom Custom derived code; for example classes
derived/default/dev/HelloWorld The BPEL process HelloWorld containing the jar file.
derived/default/dev/ear The derived EAR file, used form deployment
derived/default/dev/war The derived WAR file, used form deployment

Based on the previous directory structure a script is made that takes control over these directories and fulfill the appropriate actions onto it. The script is made generic so that any other structure can be implemented.

Build Script: OBBUILD.SH - Configure
Based on the obant tool, as part of the Oracle BPEL PM 10g. A script is made that is able to full-fill the same functions. There are some differences. The script will use the full version of ANT, it will not use the tool obant.
The script expects that a full-version of ANT is downloaded and installed on the machine on the script executed. ANT and an additional library are found on the following locations:
The script is also expecting the Oracle BPEL PM is installed and configured on the server on which the script is executed.

The “obbuild.sh” will use the above ANT versions and reference to the Oracle BPEL environment. Within the three environment settings must be checked before this script can be executed. The settings are:


Build Script: OBBUILD.SH – Options
The script has a help function to show the possible options.

obbuild.sh -h
obbuild.sh [-[hvtV] [-e environment] [-f build-file]
[-r replace-file] [task] [arg1] [arg2] .. [arg6]]

-h Shows this help
-v Show the version of this program
-t Show all the tasks in the build file
-e Select envirnonment property file, default 'dev', reading dev.properties
-f Read a specific build file, default is build.xml in current directory
-r Read a specific replacement file,
use for promoting BPEL process to other environments.
-V Show verbose output
task The task to be executed, default is main
arg1..6 Optional arguments passed to the build file
as properties ANT.ARG1..ANT.ARG6

The script is reading a “build.xml” file to perform all the ANT tasks. By default it look in the current directory for the “build.xml”. With the option –f another build file can be mentioned. The –e option set the environment. In this file settings for a specific environment can be set; development, system test, production etc. By default it tries to read the “dev” environment; ./properties/dev.properties. The task is the task that ANT will be executed. By default it looks for the “main” task. Depending on the task, additional arguments can de given.

Build Script: OBBUILD.SH – Examples

Start the script with no arguments. It searches for the ./properties/dev/properties file and ./build.xml file and execute the “main” task of this file.

obbuild.sh –t

List all the tasks from the default build.xml file.

obbuild.sh –f /home/user/bpel/build.xml
It reads the build.xml from another location.

obbuild.sh –e systemtest
It reads the properties file named systemtest from ./properties/systemtest.properties.

obbuild.sh –f /home/user/bpel/build.xml –e systemtest CompileBPEL
Compile all the BPEL processes for the systemtest environment using a specific build file.

Build Script: build.xml
The build.xml file contains all the functions to maintain BPEL processes. Currently the following tasks are available

obbuild.sh -t
obbuild.sh: Tasks in ./build.xml
_Init - Internal: Initialize environment
_CleanSVN - Internal: remove svn files
_CheckoutLatest - Internal: Checkout the latest sourcecode from SVN
_CheckoutVersion - Internal: Checkout the particular version from SVN
CreateDirs - Create directory structure
CreateNewProcess - Create a new BPEL process, based on a template
[arg1=bpel-process-template_name, arg2=bpel-process-name].
Compile - Compile one or all BPEL processes (
DeployLocal - Deploy one or all BPEL processes to a domain
on the local server
[arg1=[Bpel-process|all]], [arg2=[domain-name|default]]
, [arg3=version|1.0]
Download - Download latest source code
CreateWar - Create WAR file, containing all the BPEL processes
CreateEar - Create BPEL ear file
main - Default task
Promote - Find/Replace on one or more BPEL processes,
see replace.properties
DeploySCP - Deploy one or all BPEL processes to a domain
on a remote server [arg1=[Bpel-process|all]]

This task creates an initial directory structure as mentioned previously.

Example: For the prod environment create a new structure

obbuild.sh –e prod CreateDirs

Create a new BPEL process based on a template.

Post a Comment