This tutorial is intended to follow the Plan a PXE System tutorial and also uses the [GeoIp Example] packaged with the distribution in ./examples/GeoIp.

Add the PXE tools to your path. If you plan to work with PXE from the commandline, it's a good idea to add the PXE_HOME/bin directory to your path. In UNIX, it's easy to do this on a session-by-session basis, e.g., # cd /path/to/pxe # export PATH=$PATH:`pwd`/bin In Windows, you need to add the PXE bin directory to the PATH system variable via the Control Panel.

The Short Version – It's Easy.

Once the pieces are available, building a SAR file for the GeoIp example – or most other systems with a single BPEL process bound to concrete protocols – from the commandline only requires two commands (not counting the initial cd):

# cd ./examples/GeoIp
# bpelc -wsdl file:GeoIp.wsdl file:GeoIp.bpel
# sarcreate -sysd pxe-system.xml GeoIpProcess.cbp g.sar

And that's the only thing necessary to build a deployable g.sar. (You can compare the JAR-based deployment method used by the pxe command in the Quick Start.)

The rest of this tutorial goes through the longer version step-by-step with additional detail.

Step 1: Construct a Resource Repository

The first step is to construct the resource repository that will be used by the BPEL compiler and eventually added to the system deployment archive. The resource repository is intended to represent a snapsnot of the URL-world, including file:, http:, etc., that the system can use later to access resources without using the filesystem or network.

To create a ZIPRR called g.rr with the rradd command:

# cd ./examples/GeoIp
# rradd file:GeoIp.wsdl g.rr

Resource repositories work with [URL]s. Note that if you leave out the file: in the above call to rradd the command will (correctly) complain that the argument was not a URL.

The rrls lists the contents of the resource repository:

# rrls g.rr
1 resource:
1202   file:GeoIp.wsdl

So far, g.rr only contains the wrapper WSDL created earlier, instead of the imported WSDL as well, and the system expects to be able to resolve all imports within the resource repository. The -wsdl flag for rradd will have the desired effect:

# rradd -wsdl file:GeoIp.wsdl g.rr
rradd: Overwriting existing resource for file:GeoIp.wsdl
# rrls g.rr
3 resources:
1924   http://www.webservicex.net
1202   file:GeoIp.wsdl
8628   http://www.webservicex.com/geoipservice.asmx?WSDL

Use rralias to deal with badly behaved import locations. The rralias is intended as a helper when the URI to be used as a reference to a resource is different from the URL used to load it into the resource repository. For example, if the WSDL for the remote service was temporarily unavailable over the network but available in the local file geoipservice.wsdl, the following could be used to create g.rr: # rradd file:geoipservice.wsdl g.rr # rralias file:geoipservice.wsdl \ http://www.webservicex.com/geoipservice.asmx?WSDL g.rr # rradd -wsdl file:GeoIp.wsdl g.rr The rradd command defers to resources already in the repository when resolving imports, so the last rradd will succeed as long as the imported WSDL is already in the repository.

Step 2: Compile the BPEL Process

The BPEL process GeoIp.bpel can either be compiled using the WSDL cached in the resource repository:

# bpelc -rr g.rr -wsdl file:GeoIp.wsdl file:GeoIp.bpel

Or, the bpelc command can create a temporary resource repository:

# bpelc -wsdl file:GeoIp.wsdl file:GeoIp.bpel

In either case, the result will be a file called GeoIpProcess.cbp in the current directory. (The .cbp suffix stands for "compiled BPEL process".) Recall that this is the same value that was put into the compiledProcess property in the system descriptor in the prelude to this tutorial.

Compile multiple BPEL processes at once. Multiple BPEL processes that share the same WSDL can be passed to the compiler by specifying multiple BPEL URL arguments.

Step 3: Build the Deployment Archive

The last step is to actually build the SAR file with the sarcreate command:

# sarcreate -common g.rr -sysd pxe-system.xml GeoIpProcess.cbp g.sar

This will build a SAR file called g.sar with the common resource repository g.rr that we built above, the compiled BPEL process as a named resource GeoIpProcess.cbp, and the descriptor pxe-system.xml.

As with bpelc, sarcreate supports the shortcut syntax where the resource repository is automatically constructed:

# sarcreate -sysd pxe-system.xml GeoIpProcess.cbp g.sar

In this case, the URI for the root WSDL from the system descriptor is dereferenced as a URL, so the above command has the same effect as:

# rradd -wsdl URI /tmp/foo.rr
# sarcreate -rr /tmp/foo.rr -sysd pxe-system.xml GeoIpProcess.cbp g.sar

Next Steps

To see how to deploy a SAR from the commandline, see [Deploy a PXE System from the Commandline].