This guide is intended for developers who wish to learn how to integrate a BPEL enactment environment into the Eclipse BPEL Designer using org.eclipse.bpel.runtimes.

If you are a computational scientist interested in using BPEL Designer to model your workflows, go here instead.

This guide gives a quick overview of how users can use the ActiveBPEL server integration in ActiveBPEL, provides an overview of the steps required to integrate any other third-party BPEL runtime and provides downloads of source code and other components.

We suggest you use version 1.5.1 of WTP instead of the official prerequisite (1.5M6) as 1.5.1 resolves a bug affecting starting a server from within BPEL Designer.

The relevant source code is contained in two plugins: org.eclipse.bpel.runtimes (which you can get from Eclipse CVS) and uk.ac.ucl.sse.omii.bpel.abr.

If you want to try out how the integration of ActiveBPEL works from a user's perspective you also need to install the following components.

• Eclipse 3.2.1
• WTP-1.5.1
• The other prerequisites are as listed at http://www.eclipse.org/bpel/install.php
• ActiveBPEL plug-in source code
• ActiveBPEL 2.1
• Tomcat-5.0.25

Once Eclipse and its prerequisites have been installed, unzip the plug-ins source code and import the plug-ins as projects into your workspace. Select a class (e.g., RuntimesPlugin) and select Run As. Configure it as an Eclipse application and make sure you select clearing the config area of the runtime workbench.

In order to integrate your BPEL engine into BPEL Designer, just create a new plug-in for your runtime and let it define the following items.

• Defining Your Server Definition

We need to supply a server definition to WTP's generic server framework in the form of a .serverdef file. This file contains information such as the name of the server, properties for the user to configure during setup, how to start and stop the server and libraries required on the classpath (e.g., Bootstrap.jar).

The ActiveBPEL engine runs as a web application inside Tomcat and so we can simply modify exisiting server definitions for Tomcat.

The activebpel2.serverdef file (in abr plug-in) serves as an example. Here we will just briefly discuss the one common element needed in order to integrate your server with the runtime framework. For information on how to complete the remainder of your serverdef file, please consult this article on the WTP documentation pages.

You need to specify the kinds of modules that can be published to it as well as the class reponsible for publishing:

1<module>

2 <type>bpel.module</type>

3 <publishDir>${abHome}\bpr</publishDir>

4 <publisherReference>uk.ac.ucl.sse.omii.bpel.abr.abpublisher</publisherReference>

5<module>

In line 2 we specify that our server accepts modules of type bpel.module. Line 3 denotes the directory used by our server to deploy modules. In line 4 we specify the GenericPublisher we wish to use for actually deploying modules to our server. This id will be defined and linked to a specific class in your runtime's plugin.xml (will look at later).

• Defining Your Plugin.xml

A quick walkthrough of what you need to define in your plugin.xml. We use plugin.xml in uk.ac.ucl.sse.omii.bpel.abr as our example and you can consult the WTP documentation pages for more info.

Define org.eclipse.wst.server.core.runtimeTypes supplying your runtime with an id and some descriptive strings. We want to use GenericServerRuntime as the class and make sure you replicate the moduleType element as it is in the example plugin.xml.

Next, define org.eclipse.wst.server.core.serverTypes to specify the actual server linked to the runtime type. The attributes should be self-explanatory.

Define org.eclipse.wst.server.ui.wizardFragments to plug into the runtime and server setup wizards of the Generic Server Framework. GenericRuntime/ServerWizardFragment will take care of displaying the properties from your serverdef.

We use org.eclipse.wst.server.ui.serverImages to specify some icons for server and runtime.

Next, org.eclipse.jst.server.core.runtimeClasspathProviders to specify a classpath provider for the runtime (to provide any jar files engine might need).

org.eclipse.jst.server.generic.core.serverdefinition allows us to state where the serverdef file is to be found.

In org.eclipse.jst.server.generic.core.genericpublisher we specify the id of the publisher (the one we use in serverdef in the publisherReference element) and the class actually responsible for publishing. In the example, ActiveBPELPublisher sub-classes GenericBPELPublisher.

Next, org.eclipse.wst.common.project.facet.core.runtimes. Make sure that you associate the runtime-component you define here to version 2.0 of bpel.facet.core as shown in the example plugin.xml. This associates your runtime with projects that have the BPEL 2.0 facet installed.

The final three extension points we need to use are org.eclipse.wst.common.project.facet.ui.images, org.eclipse.wst.common.project.facet.core.runtimes, org.eclipse.jst.server.core.runtimeFacetMappings, which should be self-explanatory from consulting the example plugin.xml.

• Implementing GenericBPELPublisher

The last step is to implement GenericBPELPublisher. The idea behind GenericBPELPublisher is to i) denote a particular type of publisher and ii) over time evolve it into a nice abstract base class that provides value to runtime providers (you). For now, it just provides subclasses with access to the default or user-configured host name and port number.

The example provided in uk.ac.ucl.sse.omii.bpel.abr is called ActiveBPELPublisher. This class is responsible for driving the deployment process by generating deployment descriptors and archives, etc. Your implementation should implement the publish() and unpublish() methods, but other than that you are free to implement the behaviour needed by your engine (each BPEL engine may have its own requirements on how to deploy a BPEL process). However, there is one noteworthy item in the implementation of the publish method; to get hold of the modules a user has selected for deployment, we cannot rely on the publish's arguments, but rather resort to the following as a fix:

1IModule[] modules = super.getModule();

2 resources = new IModuleArtifact[modules.length];

3for (int i=0; i<modules.length; i++) {

4 IModule module = modules[i];

5 String moduleId = module.getId();

6 String bpelFileRelativePathString = moduleId.split(">>")[1];

7 IPath path = new Path(bpelFileRelativePathString);

8 IFile bpelFile = module.getProject().getFile(path);

9 BPELModuleArtifact moduleArtifact = new BPELModuleArtifact(module, bpelFile);

10 resources[i] = moduleArtifact;

11}

In line 1 we get all BPEL modules that have been added to the server. From that we generate BPELModuleArtifacts in the for-loop by first getting the unique id of each module (line 5) and then extracting the project relative path of the corresponding BPEL file (line 6). This provides us with the data required to construct a bunch of BPELModuleArtifacts which can then be further processed (i.e. deploy) in the publish method.

It is also the responsibility of your publisher code to actually copy any required files (e.g., deployment archive) onto the server using whatever means are employed by your engine. The example code, in its current form, simply stores a copy of the generated archive in its corresponding BPEL project. In addition, you may want to make any engine-specific deployment messages available to a user (let me know if that's the case... we should display such messages in the Problems view).

This concludes the overview on how to integrate your BPEL engine into BPEL Designer. Please don't be shy with any feedback you may have that could help make this guide more useful.