Page Operations

In this section we describe the procedure for starting a PXE server and deploying some example systems that incorporate BPEL processes. While PXE is designed primarily for embedded deployment into J2EE environments, it can run "out-of-the-box" as a stand-alone server started from the command-line. The stand-alone server uses popular open source components to supply needed functionality:

the Hibernate ORM layer and HypersonicSQL database for persistence;
the Jetty servlet container for inbound HTTP communications;
the Jakarta Commons HTTPClient for outbound HTTP communications;
and ObjectWeb JOTM for transaction management.

In the interest of simplicity we will limit our description to the stand-alone server (in its default configuration), and describe tasks that can be performed on the command-line (either Windows or UNIX will work, however we will stick to UNIX notation).

Starting

The stand-alone PXE server can be started using the pxe shell script found in the PXE ./bin directory.
To start the PXE server, make sure that the JAVA_HOME environment variable is set, change into the PXE installation directory, and execute bin/pxe:

# ./bin/pxe

Ports 8080 and 2099 must be free.
The pxe executable uses port 8080 (HTTP communications) and 2099 (RMI) by default, but these may be reconfigured by edit ./etc/pxe-config.xml. See the reference page for the pxe command for instructions on which properties to change.

The above will result in the display of various log messages on the console. For the curious, more extensive logging can be found in the logs/pxe.log file in the current (PXE installation) directory. After a few seconds the PXE server will be ready.

Deploying

Once the PXE server is up and running, we are ready to deploy PXE systems. PXE systems are units of deployment comprising of one or more interconnected PXE services. PXE systems take the form of PXE system archives, (a.k.a. SAR files) which consist of a system deployment descriptor (an XML file named pxe-system.xml) describing the system and its services, as well as any number of resources that may be required by the constituent services.

To deploy a PXE system typically requires that one create and deploy a PXE system archive. This requires compiling the BPEL process (typically with the bpelc command), writing a PXE system deployment descriptor (pxe-system.xml), creating a resource repository (with the rradd command), creating a system archive (with the sarcreate command), and deploying said system archive (with the pxe-deploy command).

The stand-alone PXE server provides a short-cut that automates the above procedure, by allowing us to deploy systems simply by placing a JAR containing all the relevant (unprocessed) artifacts in a special auto-deployment directory (./etc/deploy). We will adopt this procedure as it involves significantly fewer steps. Example systems that may be deployed using this technique are found in sub-directories of the ./examples directory. To deploy, simply copy the JAR file into the auto-deployment directory; for example:

# cp examples/HelloWorld/HelloWorld.jar etc/deploy

If the above should produce any errors on the stand-alone server's console, simply edit the offending file, re-JAR, and re-copy to the deployment directory:

# cd ./examples/HelloWorld
# rm HelloWorld.jar
# edit pxe-system.xml
# jar cf HelloWorld.jar *
# cd ../..
# cp examples/HelloWorld/HelloWorld.jar etc/deploy

Examples

Included with the installation are several example PXE systems featuring BPEL processes. They are found in the sub-directories of the ./examples directory. To deploy any of these systems, simply copy the JAR file within the specific example directory into the ./etc/deploy directory. If the system is already deployed, the system will automatically undeploy and redeploy with the new system.

Test SOAP messages are included with the examples to test the deployed process. A SOAP client utility is also included to invoke the process using "SOAP-over-HTTP".

HelloWorld Example

The HelloWorld example consists of a simple BPEL process that receives an input message with a string part, appends "World" to the string and replies with the result.

To deploy the Hello World example:

# cp examples/HelloWorld/HelloWorld.jar etc/deploy

To send a SOAP "Hello" message to the process, invoke the following command (the result should contain the string "HelloWorld"):

# bin/sendsoap http://localhost:8080/pxe/soap/helloWorld examples/HelloWorld/testRequest.soap

To see that the system is deployed (without necessarily looking at the logs or console output), the pxe-status command can be used:

# ./bin/pxe-status -v
Domain: StandaloneDomain (1 system, 1 active)
0:  +  HelloWorld [SYS0ZQ0a5Gb55Rx3u0]
  0:: helloWorld.BpelService [uri:bpelProvider]
  1:: HelloService [uri:protocoladapter.soap.inbound]

GeoIP Example

The GeoIP example sends an IP address as content over HTTP-SOAP to a BPEL processes which in turns relays the request to a remote Web Service. Once the response is collected, the client is returned the geographic location of the IP address. Because this example involves the invocation of a remote Web Service, you may need to relax your firewall.

To deploy the GeoIP example:

# cp examples/GeoIp/GeoIp.jar etc/deploy

To send a SOAP request to the process, invoke the following command:

# bin/sendsoap http://localhost:8080/pxe/soap/geoIp examples/GeoIp/testRequest.soap

Note that the pxe-status command will show both the HelloWorld and GeoIp systems deployed at this point:

# ./bin/pxe-status -v
Domain: StandaloneDomain (2 systems, 2 active)
 0:  +  HelloWorld [SYS0ZQ0a5Gb55Rx3u0]
   0:: helloWorld.BpelService [uri:bpelProvider]
   1:: HelloService [uri:protocoladapter.soap.inbound]

 1:  +  GeoIp [SYS0ZQ0a5Gb55Rx383]
   0:: HttpOutbound [uri:protocoladapter.soap.outbound]
   1:: HttpInbound [uri:protocoladapter.soap.inbound]
   2:: BpelProcess [uri:bpelProvider]

Undeploying the HelloWorld system can be accomplished with the pxe-undeploy command:

# ./bin/pxe-undeploy HelloWorld
# ./bin/pxe-status -v
Domain: StandaloneDomain (1 system, 1 active)
0:  +  GeoIp [SYS0ZQ0a5Gb55Rx383]
  0:: HttpOutbound [uri:protocoladapter.soap.outbound]
  1:: HttpInbound [uri:protocoladapter.soap.inbound]
  2:: BpelProcess [uri:bpelProvider]

Asynchronous Process Example

The Asynchronous Process example features a fairly complex process that demonstrates multiple invokes, asynchronous callbacks, and correlations. Please refer to the BPEL process definition for details.

To deploy the Asynchronous Process example:

# cp examples/AsyncProcess/AsyncProcess.jar etc/deploy

To send a SOAP request to the process, invoke the following command:

# bin/sendsoap http://localhost:8080/pxe/soap/async/invoke examples/AsyncProcess/message.soap

Spexercizer (Bpel Unit Tests)

Included with the distribution is a set of bpel scripts to exercize the various activities and features of the bpel engine. The wsdl, bpel, xml schemas, and other configuration files can be found in the examples/spexercizer.

To run all 72 tests:

# bin/bpeltests

To run a specific test (or set of tests), include the name(s) of the bpel file(s) to run:

# bin/bpeltests Pick1.bpel Pick4.bpel

Page Operations

Starting Points

Community

Reference