Communicating with the ActiveBPEL Server Engine Administration Interface via Web Services

Introduction

The ActiveBPEL™ engine provides an administration interface that is accessible via standard Web Service calls. The engine can be remotely administered and controlled or integrated into a larger application through the use of these Web Services.

This sample demonstrates a Java-based remote engine administration client application using the ActiveBPEL engineAdmin.wsdl Web Service definition, wsdl2java and a running copy of the ActiveBPEL Engine deployed to a Tomcat environment. This methodology may be used as a guide for administration interface construction using other products and configurations.

Objectives

• Generate a set of administrative interface classes from engineAdmin.wsdl using wsdl2java.
• Construct an administration client application used to communicate with a running ActiveBPEL Engine.

Getting Set Up

The files provided with this sample are contained in the archive you downloaded. You may extract this archive into a directory of your choosing. The archive contains numerous directories with an Eclipse Java Project and various support files.

If you're using Eclipse for your client application development, run Eclipse, select File / Import / Existing project into workspace and navigate to the following Eclipse project directory

/admin_api

This will open a Java project called admin_api, with various supporting directories. The project is self-sufficient and, in addition to the necessary scripts and WSDL, contains pre-built copies of all of the source files that are created by running the build.xml script (see below).

One manual step you may need to perform is to create an AESAMPLES_LIB variable for the project's Java Build Path (i.e., you may see "Unbound classpath variable"; errors for the project). Create the variable by right-clicking on the project in the Package Explorer and selecting Properties. Next, select Java Build Path, select the Libraries tab, and click the Add Variable... button. Click the Configure Variables... button in the dialog that appears, and then New... Create a AESAMPLES_LIB variable that points to the \AESamples\lib directory (or wherever you've put it) that you get when you extract the samples library archive (click here for more information). Click OK to exit the dialogs and answer Yes if asked to do a full rebuild of the project.

If you're not using Eclipse, you can still use the files in this sample. There is a build.xml Ant script in the admin_api root that contains build targets for creating the Java source from WSDL, compiling all source, and running the client application - all described in detail below. Here's the archive's directory structure.

WSDL Definition for the Administration Interface

We'll start with the Web Services definition for the engine's administration interface, which is contained in engineAdmin.wsdl.  A version of this WSDL is included in this sample, but be aware that this interface will change over time (albeit less often than the underlying implementation code), so you should be sure that the WSDL you're using matches the version of the ActiveBPEL Engine with which you plan to communicate.  The WSDL is contained in the source distribution archive for your engine version, found here.  engineAdmin.wsdl is located in the /projects/org.activebpel.rt.bpel.server/support directory in that archive.  The archive also contains source code for several classes you may want to use in constructing your administration client application.

Generating the Java Classes

To create our Web Service based Administration Interface client, we'll need a set of classes that can communicate with the engine through web service calls.  We could certainly code this by hand, but wsdl2java is designed to create this interface layer given the associated WSDL, so we'll use that.  An Ant build script - build.xml - is included in the root directory for this purpose.

Before generating the Java classes, be sure your environment meets the following requirements:

• You'll need Ant ver. 1.6.1 or later, freely available here.
• build.xml depends upon an AESAMPLES_LIB environment variable, which should point to the \AESamples\lib directory created by extracting the samples library archive.

To generate the WS interface classes for engine administration, run ant wsdl2java. This target creates the associated Java source files in src/*. When the build script completes, you should see something similar to the following output:

Examine the contents of the src directory at this point, and it now contains an AeAdminServices subdirectory, as well as a new rt code subdirectory under src/org/activebpel, alongside samples.

Java Test Client Application

With the generation of our web service interface layer completed, development of a client application for administration is fairly straightforward.  The TestClient.java application included in this sample demonstrates invocation of a few of the methods exposed by the RemoteDebugSoapBindingStub class. This class is named to indicate how the administration interface is used in the commercial ActiveBPEL Enterprise product. The TestClient application will connect to the ActiveBPEL engine (running at localhost:8080), retrieve the list of active processes, and display the process log for the process whose PID is 1. If it bugs you, you can rename the instances of "RemoteDebugSoapBinding" in engineAdmin.wsdl to something more meaningful to your application, or simply rename references to the generated RemoteDebugSoapBindingStub class.

The remote stub generated by wsdl2java exposes an interface with methods that follow the same structure as org.activebpel.rt.bpel.server.admin.rdebug.server.IAeBpelAdmin.java. So the documentation associated with that class provides a good reference for the functionality available via the remote stub.  You'll need to view the source for this class because the javadoc is not currently published as part of the documentation set.  Note that in order to manipulate values and objects like AeDefaultEngineConfiguration, as is shown in the test client example, the source (again) comes in handy.  You'll also need access to ae_rt.jar and ae_rtbpel.jar in the classpath for your client project.  These references are defined using the AESAMPLES_LIB variable in the Eclipse project provided with this sample.

A final note on programmatic configuration changes using AeDefaultEngineConfiguration with the ActiveBPEL engine: changes to the engine's configuration from your test client will modify the aeEngineConfig.xml file located in CATALINA_HOME/bpr.  Be sure to make a backup of this file if you're testing configuration changes but don't want to lose your original deployed configuration.

Possible run-time error using Eclipse

If you're running the Java Test Client using the Eclipse development platform, and you have any custom functions deployed to your BPEL Server, you may observe a NoSuchMethodError for method org.activebpel.rt.AeException.logError(). This is normal. The version of AeException extracted from the WSDL will be missing the logError method, which is used to report runtime errors. You can work around this by refactoring the org.activebpel.rt.AeException class by renaming it to anything else and rebuilding the project.   Renaming the WSDL-generated class in this way will cause the system to use the version of AeException found in ae_rt.jar, which has the method.  You can then safely ignore any error messages you see regarding missing custom functions.

Copyright © 2004–2006 Active Endpoints, Inc. - All Rights Reserved