Develop and execute WS-BPEL V2.0 business processes using the Eclipse BPEL plug-in

Combine Tomcat and the Eclipse BPEL plug-in to plan complex applications consisting of myriad components and Web services

Ilya Platonov (ill@isg.axmor.com), Software Engineer and Developer, Axmor

Ilya Platonov is a software engineer at Axmor Software, consulting at IBM Advanced Technology Solutions (ATS) Lab in Novosibirsk, Russia. He holds a master's degree in computer science from Novosibirsk State University. Recently, he has participated in more than five ATS projects as a system architect and software engineer.

Artem Papkov (artem@us.ibm.com), Solution architect, IBM, Software Group

Artem Papkov is currently a solution architect with IBM's Client Innovation Team, working with customers and Business Partners to adopt emerging technologies, such as SOA and Web services. After graduating from the Belarusian State University of Informatics and Radioelectronics in 1998 with a master's degree in computer science, he joined IBM in Research Triangle Park, N.C. in 2000. His experience includes software development of multitier solutions using emerging technologies, architecture design, and integration of Internet-based solutions. For the past three years he has been focused on working closely with customers to help them adopt Web services as IBM's strategic integration technology and SOA as the integration approach. You can contact Artem at artem@us.ibm.com.

Jim Smith (jamessmi@us.ibm.com), Manager, IBM, Software Group

Jim Smith has over 18 years of experience in software development. He started his career at Sandia National Labs in Livermore, California, designing high-speed data acquisition systems and distributed computing systems using a myriad of existing legacy code. With deep experience in Java language and customer-facing skills, Jim moved to the Emerging Internet Technologies team focusing on making Java solutions real for IBM customers. Jim was one of the founders of Advanced Technology Solutions (ATS), a global software services and development organization with a mission to develop, refine, and franchise advanced technologies and lightweight business processes for IBM, development labs, Business Partners, and customers, resulting in faster adoption and deployment of standard technologies and IBM products. Currently, Jim manages the organization.

Summary: BPEL V2.0 is a powerful language intended to help in development of huge, complex applications consisting of a lot of other components and Web services. BPEL allows you to describe long-running workflows using graphical editors to present workflows on human-friendly diagrams. This article describes how to combine the Eclipse BPEL plug-in for development of processes and Apache ODE for their execution.

Tag this!

Date: 25 Mar 2008
Level: Intermediate
Activity: 4184 views

The Apache Foundation calls its implementation of the Web Services Business Process Execution Language (WS-BPEL) V2.0 the Orchestration Director Engine (ODE). ODE executes WS-BPEL processes, which are capable of communicating with Web services, sending and receiving messages, etc. The Eclipse BPEL project is a related open source project that provides an Eclipse plug-in for the visual development of WS-BPEL V2.0 processes. (See "What is WS-BPEL" if you are new to this technology.)

What is WS-BPEL?

WS-BPEL is a vendor-neutral specification developed by OASIS to specify business processes as a set of interactions between Web services. OASIS defines WS-BPEL as follows: "Business processes can be described in two ways. Executable business processes model actual behavior of a participant in a business interaction. Abstract business processes are partially specified processes that are not intended to be executed. An Abstract Process may hide some of the required concrete operational details. Abstract Processes serve a descriptive role, with more than one possible use case, including observable behavior and process template. WS-BPEL is meant to be used to model the behavior of both Executable and Abstract Processes.

"WS-BPEL provides a language for the specification of Executable and Abstract business processes. By doing so, it extends the Web Services interaction model and enables it to support business transactions. WS-BPEL defines an interoperable integration model that should facilitate the expansion of automated process integration in both the intra-corporate and the business-to-business spaces."

When this article was written, ODE V1.1 and the Eclipse BPEL project milestone M3 were the current versions. This article examines these products and describes how to create your own BPEL process and integrate it into your application using Apache ODE and Eclipse BPEL project.

You may want to review the developerWorks article "Execute business processes with Eclipse" by Tyler Anderson if you are more familiar with BPMN and need a tutorial on using Eclipse STP BPMN Modeler for manipulating business processes (see Resources).

Software installation

Your operating system can be a modern version of Microsoft® Windows®, Linux®, or Mac OS X. This was written using Linux, so you may need to adjust file locations according to the customs of your operating system. Before installing ODE and BPEL for Eclipse, make sure the following is installed on your computer:

Java™ V5.0 or later
Tomcat V5.5 or later
Eclipse V3.3.x with the following plug-ins installed:

EMF V2.3.x
GEF V3.3.x
DTP STK V1.5.x
WTP (Web Tools Platform) V2.0.x

Please refer to the applications' installation guides to install them (see Resources).

Apache ODE installation

Download the ODE. Start your Apache Tomcat Web container and use the Tomcat Manager (which you should find on your computer at http://localhost:8080/manager/html) to deploy the ode.war module from the distribution archive. To check for success, visit http://localhost:8080/ode/, which will display the state of your computer's ODE Web services.

BPEL support for Eclipse

To set up the Eclipse BPEL project, run your Eclipse application, launch the Eclipse update manager (by clicking the menu Help > Software Update > Find & Install) and select the New feature to install an option. Click New Remote Site... and add the URL http://download.eclipse.org/technology/bpel/update-site/ to the New Update Site dialog, then name the site BPEL. Click Finish, select a nearby mirror, select BPEL Designer for Eclipse, agree to the license terms, Select All options, then click Next and Finish. Eclipse will alert you to any potential duplication conflicts, then warn you about BPEL being unsigned. Click Install if the provider is Eclipse.org. When installation complete, Eclipse will ask you to restart it.

Creation of a simple BPEL process

In this section, we create a simple BPEL process and try running it in ODE. The process merely performs simple string manipulation. Keep in mind that it is just a simple example, and you can create much more complex processes using the WS-BPEL V2.0 specification.

Eclipse BPEL editor

To create a simple BPEL process, run Eclipse and click File > New > Other menu item, select the BPEL 2.0 -> BPEL Project option and create a new BPEL project called HelloWorld. Once the project is created, you are ready to create your first BPEL process. Click File > New > Other menu item again and select the BPEL 2.0 > New BPEL Process File option to start with the BPEL process creation wizard,

Figure 1. Create a BPEL process file

Let's create a synchronous process also called HelloWorld. On the next page of the wizard, you should choose BPEL process files location — just choose the project created before and click Finish. The sample process will be created.

Figure 2. Creating a synchronous process

As shown, the newly created process has two internal BPEL variables — input and output — and a sequence with one receive and one reply element. The receive block is responsible for receiving input BPEL process data and for initialization of the variable input. Similarly, the reply block is aimed at outputting BPEL process data using the output variable.

Also during the BPEL process creation, the wizard created a WSDL file. This file describes input and output data types and a port type that represents the BPEL process. Both input and output data types simply contain single string fields.

We're ready to add some data manipulation into our process. To do so, drag and drop an Assign block right between the receiveInput and replyOutput blocks.

Figure 3. Drag and drop an Assign block

Once the assign block is placed, right-click the Assign block and choose the Show In Properties context menu item to show the Properties view and select the Details tab. The Assign block should initialize the output variable with an initial XML tags structure. It is the common procedure required by most of BPEL processing engines. Click the New button on the Detail tab to start creation of the first assign procedure. Select the Fixed Value element in the From select box and enter following lines into the text area:

>tns:HelloWorldResponse xmlns:tns="http://www.ibm.com/wd2/ode/HelloWorld">
     >tns:result/>
     >/tns:HelloWorldResponse>

Next, select the Variable element in the To select box and choose the output/payload variable in the variables tree, as shown below.

Figure 4. Initializing output variables

When the output variable is initialized, we can create a new assign procedure. For the sample process, this procedure gets a string value from the input variable, concatenates it with the "Hello" greeting and assigns the result to the output variable string field. For this click the New button and choose the Expression value in the From select box. In the text box displayed below, enter the following expression: concat("Hello ", $input.payload/tns:input). In the To section, select the output/payload/tns:result variable, as shown below.

Figure 5. Selecting output/payload/tns:result

The Assign block is ready. As you can see, the Eclipse BPEL plug-in provides XPath V1.0 highlighting and code completion features to simplify creation of XPath queries. (See Resources to learn more about XPath.)

WSDL file changes

The WSDL file for a BPEL process should describe the types used in the BPEL process as well as port types, bindings, and services for your process. The WSDL automatically created by the wizard already contains a port type and in order to make the process functional, we need to create binding and service for it.

Open the WSDL file in the respective editor and see the port type graphical definition.

Figure 6. See the port type graphical definition

To create a Web service binding, right-click any free area in the WSDL editor and choose the Add Binding option. In the Properties view rename the newly created binding to HelloWorldBinding and select HelloWorld as the port type for the new binding. Click the Generate Binding Content button to bring up the Binding Wizard dialog.

Figure 7. The Binding Wizard dialog

Select SOAP protocol in the Protocol select box, check the document-literal option in the SOAP Binding Options section and click Finish.

Figure 8. Binding options

After the binding is created, right-click a free area of the WSDL editor and choose the Add Service menu item to create a new one with the name HelloWorldService. Then specify HelloWorldPort for the binding's port name and the URL http://localhost:8080/ode/processes/HelloWorld for its address. Also select HelloWorldBinding as the binding for the newly created service.

Figure 9. HelloWorldBinding

Our WSDL file is ready to be deployed into ODE application.

Deployment descriptor

The last thing we need to do before our process is ready for deployment is create an ODE descriptor. The descriptor must have the name deploy.xml and must be placed in the same directory where the BPEL and WSDL files are stored. Just create a new deploy.xml text file and put the following content there.

Listing 1. Creating a deploy.xml text file

                
>?xml version="1.0" encoding="UTF-8"?>
>deploy xmlns="http://ode.fivesight.com/schemas/2006/06/27/dd"
    xmlns:pns="http://www.ibm.com/wd2/ode/HelloWorld" 
    xmlns:wns="http://www.ibm.com/wd2/ode/HelloWorld">
  >process name="pns:HelloWorld">
    >active>true>/active>
    >provide partnerLink="client">
      >service name="wns:HelloWorldService" port="HelloWorldPort"/>
    >/provide>
  >/process>
  >/deploy>

The descriptor specifies the list of process and services for a deployable unit.

Usage of BPEL process

Now, when the HelloWorld BPEL process is ready, we can deploy it into the ODE application and test it.

Deploy BPEL process into ODE

ODE supports hot-deployment of BPEL processes. To deploy the process created in previous sections, just copy the folder containing all the process's files into the webapps/ode/WEB-INF/processes directory of your Apache Tomcat where ODE was deployed. To monitor deployment process, you can look into the log file logs/catalina.out in the Tomcat root directory for any new entries.

An easy way to test the deployed process is to use the Eclipse Web Services Explorer tool. Right-click your HelloWorld WSDL file and select Web Services > Test with Web Services Explorer pop-up menu item. Eclipse will start the Web Services Explorer test tool. Using this tool, enter some text to the input parameter and invoke the Process operation. As shown in Figure 10, the Web service returns the greeting to the text you just entered.

Figure 10. Invoke a WSDL operation

Creation of a BPEL process client

When we have the Web service that executes the BPEL process, we can integrate this process into a client application. Let's use Eclipse WTP plug-in to generate an Axis-based Web services client. Before generating the client code, you need to add your Tomcat server in the list of Eclipse servers. Click File > New > Other menu item and select the Server option from the list. Then, go through the wizard steps to create a new Tomcat server for your Eclipse workspace.

Once the server is created, right-click the WSDL file and select Web Services > Generate Client pop-up menu item. This action starts the Web Service Client wizard, which generates a new project with classes required for work with your Web service.

Figure 11. Setting up the Web service client

To work with the generated files, use the code similar to the following.

Listing 2. Creating a Web service client

                
HelloWorldServiceLocator locator = new HelloWorldServiceLocator();
HelloWorldRequest hwRequest = new HelloWorldRequest();
hwRequest.setInput("developerWorks!");
				
HelloWorldResponse hwResponse = locator.getHelloWorldPort().process(hwRequest);
String output = hwResponse.getResult();

After the code is executed, the output variable should contain the result of the BPEL process work.

ODE Management API

ODE provides access through Web services to some of the applications management functionality. By using it, you can control processes deployed in ODE and their instances, which are currently executed on the server. All operations are described in the pmapi.wsdl file located in the folder webapps/ode/WEB-INF of your Tomcat application. Unfortunately, pmapi.wsdl uses the old RPC document style, and it is difficult to use it using the Eclipse Web Services Explorer test tool, for example.

The best way to access the Management API is to use the Axis2 libraries. In particular, use the ServiceClientUtil class, which is supplied by the ode-axis2 library. Axis2 depends on other libraries, including Xerces, Stax, etc. Most of them are included into the ode.war archive, so you can add it into your project dependencies.

The following code demonstrates how to extract information about the current process instances.

Listing 3. Extracting information about current process instances

                
ServiceClientUtil client = new ServiceClientUtil();
OMElement msg = client.
  buildMessage("listAllInstances", new String[] {}, new String[] {});
OMElement result = 
  client.send(msg, "http://localhost:8080/ode/processes/InstanceManagement");
			
List>ProcessInfo> processes = new ArrayList>ProcessInfo>();
Iterator>OMElement> i = result.getChildElements();
			
while (i.hasNext()) {
  OMElement omInstanceInfo = i.next();
  OMElement omProcessName = 
    omInstanceInfo.getFirstChildWithName(
      new QName("http://www.apache.org/ode/pmapi/types/2006/08/02/",
						"process-name"));
  OMElement omStatus = 
    omInstanceInfo.getFirstChildWithName(
      new QName("http://www.apache.org/ode/pmapi/types/2006/08/02/",
				"status"));
  OMElement omStarted = 
    omInstanceInfo.getFirstChildWithName(
      new  QName("http://www.apache.org/ode/pmapi/types/2006/08/02/",
				"dt-started"));
  OMElement omLastActive =
    omInstanceInfo.getFirstChildWithName(
      new QName("http://www.apache.org/ode/pmapi/types/2006/08/02/",
				"dt-last-active"));

  ProcessInfo process = new ProcessInfo();
  process.setProcessName(omProcessName.getText());
  process.setStatus(omStatus.getText());
  process.setStarted(omStarted.getText());
  process.setLastActive(omLastActive.getText());
  processes.add(process);
  }

The example uses the axiom library to retrieve information and store it as the list of ProcessInfo objects. They can be used from any other part of your application.

ODE event listener

ODE allows you to develop listeners for any action inside an ODE application, such as starting and stopping process instances. To create your own event listener, you need to implement the org.apache.ode.bpel.iapi.BpelEventListener interface defined in the ode-bpel-api.jar library. The following code demonstrates a simple implementation that prints to the standard output-stream incoming events and invocations of the startup() and shutdown() listener methods.

Listing 4. The startup() and shutdown() listener methods

                
/**
* {@inheritDoc}
*/
public void onEvent(BpelEvent event) {
  System.out.println(event);
}
	
/**
* {@inheritDoc}
*/
public void startup(Properties arg0) {
  System.out.println(this.getClass() + " startup");
}
	
/**
* {@inheritDoc}
*/
public void shutdown() {
  System.out.println(this.getClass() + " shutdown");
  }

Once a listener class is ready, you need to put it into the ODE classpath (you can put a JAR file with your listener class into the webapps/ode/WEB-INF/lib Tomcat directory). You also need to create the webapps/ode/WEB-INF/conf/ode-axis2.properties property file and add the following line there:

ode-axis2.event.listeners=com.ibm.wd2.bpel.eventlistener.WD2EventListener

The name of your listener class may differ from the one above.

Conclusion

BPEL V2.0 is a powerful language intended to help in development of complex applications consisting of a lot of other components and Web services. BPEL allows describing long-running workflows using graphical editors to present workflows on human-friendly diagrams. You can use open source products for the creation of applications using the BPEL V2.0 specification from Apache and Eclipse communities can be used together — Eclipse BPEL Project for the development of processes and Apache ODE for their execution. Both products successfully work at least on simple BPEL V2.0 processes, such as the one described above. However, we recommend you investigate the pros and cons of these open source tools on a more complex application before making the decision to use them for real business applications.

Resources

Learn

The definitive reference for the Web Services Business Process Execution Language V2.0 specification is at OASIS.
Read more about the Web Services Business Process Execution Language at OASIS.
Learn more about the Eclipse BPEL Project including its goals and the current status of its software.
See the developerWorks tutorial "Execute business processes with Eclipse" to learn both Business Process Modeling Notation (BPMN) and Business Process Execution Language (BPEL) XML formats using the Eclipse SOA Tools Platform BPMN Modeler to model a business process.
See the article "Developing Web applications with Tomcat and Eclipse" for background on working with Tomcat and Eclipse.
Learn more about Apache ODE in the Apache ODE User Guide.
To learn more about XPath, read the XML Path Language (XPath) V1.0 W3C recommendation.
Check out the "Recommended Eclipse reading list."
Browse all the Eclipse content on developerWorks.
New to Eclipse? Read the developerWorks article "Get started with Eclipse Platform" to learn its origin and architecture, and how to extend Eclipse with plug-ins.
Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
To listen to interesting interviews and discussions for software developers, check out developerWorks podcasts.
Stay current with developerWorks' Technical events and webcasts.
Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.

Get products and technologies

Download components for the Eclipse BPEL designer from the Eclipse BPEL Project.
Download Eclipse Web Tools Platform (WTP) from the Eclipse WTP Project.
Download Apache Orchestration Director Engine (ODE) from Apache ODE.
Download Eclipse Modeling Framework Project (EMF) from the Eclipse EMF Project.
Download Eclipse Graphical Editing Framework (GEF) from the Eclipse GEF Project.
Download Eclipse Data Tools Platform (DTP) from the Eclipse DTP Project.
Download Apache Tomcat V5.5 from the Apache Tomcat project.
Download Java technology from Sun's Java developer Web site.
Check out the latest Eclipse technology downloads at IBM alphaWorks.
Download Eclipse Platform and other projects from the Eclipse Foundation.
Download IBM product evaluation versions, and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
Innovate your next open source development project with IBM trial software, available for download or on DVD.

Discuss

The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
Participate in developerWorks blogs and get involved in the developerWorks community.

About the authors

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=Open source, SOA and Web services

ArticleID=296053

ArticleTitle=Develop and execute WS-BPEL V2.0 business processes using the Eclipse BPEL plug-in

publish-date=03252008

author1-email=ill@isg.axmor.com

author1-email-cc=

author2-email=artem@us.ibm.com

author2-email-cc=