Communicating with the ActiveBPEL Server Administration Interface via Web Services

Introduction

The ActiveBPEL^® Server provides an administration interface that is accessible via WSDL-defined web service invocations. 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 administration client application using the ActiveBPEL Server's web service (WSDL) definition, wsdl2java and a running copy of the ActiveBPEL Server deployed to a Tomcat environment. This methodology may be used as a guide for administration interface construction using other server platforms and configurations.

Objectives

• Acquire the WSDL for the web service running on the ActiveBPEL Server you are currently using.
• Generate a set of administrative interface classes from this WSDL using wsdl2java or (preferably) the Eclipse Web Service Client wizard.
• Create an administration client application Java class that you can use to communicate with a running ActiveBPEL Server.

Getting Set Up

The files provided for this sample are contained in the downloadable sample archive (accessible via the links at the bottom of the menu to the left when viewed online). You may extract this archive into a directory of your choosing (e.g., c:\, \, etc.). The archive contains numerous directories with an Eclipse Java .project file and various other support files. There is also an Ant build script - build.xml - that can be used if you are not working with the Eclipse development IDE. The Eclipse IDE is preferred.

Both the Eclipse project and the Ant script presently assume that you have a copy of Axis 1.4 extracted to the root of the current drive, e.g., c:\axis-1_4 .  If you're using a different version of Axis, or it's in a different location, you'll either have to move it or change the Ant script and/or Eclipse .classpath file accordingly. Symbols and variables are provided to make this easier.

If you're using Eclipse for your client application development, run Eclipse, select File / Import... / General / Existing Projects into workspace and navigate to the following directory, wherever you extracted it:

/ActiveBpelAdmin_API

Select and import the Eclipse project in this directory. This will create a new Java project in your workspace / Navigator view called ActiveBpelAdmin_API, with several supporting directories. The project is complete, and the test client can be run as-is if you have a running instance of ActiveBPEL Server on localhost at port 8080 (which uses Version 4.2 of the Admin Web Service API - see below).

In Eclipse, note that you may need to create a new Build Path / Classpath Variable: AXIS-1_4_LIB. Link this variable to the lib directory of your Axis installation, e.g., c:\axis-1_4\lib.
 

If you're not using Eclipse, you can still use the files in this sample. There is a build.xml Ant script in the ActiveBpelAdmin_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.

Note that under the src/org/activebpel/samples directory are the directory hierarchy and *.java files for the Admin Web Service client framework as generated by Eclipse (org.activebpel.samples.wizard.*) and also generated by wsdl2java via the build.xml Ant script (org.activebpel.samples.script.*).

The files in package org.activebpel.samples.wizard.* were generated by Eclipse's Web Service Client wizard. The files in package org.activebpel.samples.script.* were generated by the Ant script, using wsdl2java. Both package sets are provided for comparison, but you should select and work with one set or the other, not both.

Both packages shipped in this archive are derived from a running instance of ActiveBPEL Server Professional Edition (Tomcat) Version 5.0. To create the web service client framework for a different edition of ActiveBPEL Server - or the CE (Community Edition) Engine - use the following instructions. These have been verified with ActiveBPEL Server PE (Professional Edition).

From the Eclipse IDE

If you haven't done so already, you'll need to install the Web Tools Platform plug-in for Eclipse, which is discussed here.

To begin, import the project into Eclipse as describe above, then right-click on the ActiveBpelAdmin_API project and select New / Other... from the pop-up menu. A dialog appears, displaying the various wizards supported by the plug-ins currently installed. Navigate to and select Web Services / Web Services Client, then click Next.

The Web Services Client wizard appears, open to the Web Services page. The first step is to define the WSDL from which you'll build your client. The WSDL definition for the Admin API is accessible via the following URL, by default (note - if your server is on a different hostname or port, you'll need to adjust this):

http://localhost:8080/active-bpel/services/ActiveBpelAdmin?wsdl

If your ActiveBPEL Admin Console is secured (i.e., requires a Basic Auth Username and Password), then you should use the following URL form, replacing user with the login ID and pass with the login password:

http://user:pass@localhost:8080/active-bpel/services/ActiveBpelAdmin?wsdl

Ensure that your instance of ActiveBPEL Server - or CE (Community Edition) Engine - is running. Enter this URL into the Service definition text entry box, set the slider below Client type to Assemble client and click Next.

The Web Service Proxy Page appears. Accept the default Output folder (or edit if desired). Note that using this default location will overwrite the files currently stored there unless you change the package names from those described below. Check the box next to Define custom mapping... and click Next.

The Web Service Client Namespace to Package Mapping page appears. Click the Add button to add the first mapping. A default mapping appears in the list. Replace http://default.namespace with the target namespace for the API's WSDL definitions:

http://docs.active-endpoints/wsdl/activebpeladmin/2007/01/activebpeladmin.wsdl

Replace default.javapackage with the following package, or one of your choosing (note: 'wizard' is used to differentiate this package from the one that is automatically generated by the Ant build script, which replaces this package element with 'script'):

org.activebpel.samples.wizard.wsdl

Add another mapping with the following namespace and package:

http://schemas.active-endpoints.com/activebpeladmin/2007/01/activebpeladmin.xsd

org.activebpel.samples.wizard.schema

Click Finish to generate the Admin web service client framework classes. Once generated, the new packages and Java files will appear under the src folder in your project. Also, a number of required jar files will be added to your build path. Right-click on the project name, select Build Path / Configure Build Path... and select the Libraries tab to view them.

Note that among the Eclipse generated files there is an IAeActiveBpelAdminProxy.java file, which contains a handy encapsulation of the functionality required to locate and instantiate a remote interface to the administration web service. A simple, non-generated demo class included in this project - TestClient.java - makes use of IAeActiveBpelAdminProxy.java. Now that you've generated the necessary support classes, you may run TestClient to exercise some simple Admin API functionality.

Also note that Eclipse may report errors (i.e., in the Problems view) on files in the org.activebpel.samples.script.wsdl package. This package is not part of the wizard-generated, Eclipse web service client build. You can safely ignore these errors.

From the Command Line using Ant

For those who prefer a non-IDE approach, generating the web service client framework classes and running the test client using the Ant script is very simple, but this method will not generate a proxy class. A JUnit test case class (ActiveBpelAdminTestCase.java) is generated, however, and you can examine this class to understand how to construct an instance of the remote interface and call its methods.

Also, to simplify understanding of this interface, the IAeActiveBpelAdminProxy.java class has been copied from the Eclipse-generated framework, renamed to ActiveBpelAdminProxy.java, and included in the org.activebpel.samples.script.wsdl package in this archive as a sample proxy. Although this file won't be overwritten if you regenerate the framework classes using the script, just remember that it was generated using the WSDL for version 5.0 of ActiveBPEL Server PE.

First, you will need a copy of Axis, which is available here. ActiveBPEL supports Axis 1.4 as of this writing. To determine which version of Axis your installation is using, run the engine and access the Admin API's WSDL definition using your web browser with the following URL:

http://localhost:8080/active-bpel/services/ActiveBpelAdmin?wsdl

If your ActiveBPEL Admin Console is secured (i.e., requires a Basic Auth Username and Password), then you should use the following URL form, replacing user with the login ID and pass with the login password:

http://user:pass@localhost:8080/active-bpel/services/ActiveBpelAdmin?wsdl

The version will be displayed at approximately the third line of the WSDL data, e.g., "WSDL created by Apache Axis version: 1.4."

To generate the framework classes using the Ant script provided, first open a command window and navigate to the project root directory (wherever you extracted it). Open the build.xml file in a text editor and ensure that the api_wsdl_url, lib and various jar reference values are accurate for your configuration. Also ensure that the Basic Auth credentials in the above URL are set correctly if required, otherwise simply delete that portion of the URL.

Ensure that your instance of ActiveBPEL Server - or CE Engine - is running. Execute ant and watch the console output for errors or warnings. The default script target is client, which gets the WSDL definition from the running engine, generates the framework classes, compiles them and runs TestClient.java - the sample client application.

If successful, the Ant script will output the API Version, followed by an XML representation of the current engine configuration, followed by a list of the currently active processes (if any), followed by information on the first active process (if there is one). Note that any warnings about disabled attachment support can be ignored for API functions.

WSDL Definition for the Administration Interface

The WSDL definition for the Admin API's web service interface may be found in the source distribution archive of the open source engine, found here.  ActiveBpelAdmin.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. Use of those classes is beyond the scope of this sample, as you can access the Javadoc for these in the full distribution.

If you plan to write a client that reads and/or remotely modifies the engine configuration, you may wish to pay careful attention to org.activebpel.rt.bpel.config.AeDefaultEngineConfiguration and supporting classes. This is the Java encapsulation of the XML data returned by TestClient.getConfiguration().

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 operations exposed by the Admin API web service.

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.  See /projects/org.activebpel.rt.bpel.server/doc/index.html in the full open source distribution archive for more information.

Copyright © 2004–2008 Active Endpoints, Inc.