JBoss.orgCommunity Documentation

RiftSaw 2.0-M2

Getting Started Guide

by Gary Brown and Kurt Stam
1. Installation
1.1. Overview
1.2. Prerequisites
1.3. Installation Instructions
1.3.1. Available databases and how to configure them
2. Examples
2.1. Overview
2.2. Quickstart Examples - Hello World
2.3. ESB Examples - ESB Invocation of Hello World
2.4. Importing Examples into Eclipse
1.1. Overview
1.2. Prerequisites
1.3. Installation Instructions
1.3.1. Available databases and how to configure them

This chapter provides details of the pre-requisites for using the RiftSaw BPEL project, and how to install the engine into a JBossAS environment.

The examples distributed with RiftSaw are split into two categories, quickstarts that are pure BPEL that can run directly in the JBossAS server, and ESB based examples that require JBossESB. If you only want to use the pure BPEL examples, then JBossESB will not be required.

  1. JBossAS (version 5.1.GA or higher), available from http://www.jboss.org/jbossas
  2. JBossESB (version 4.6.GA or higher), should download the jbossesb-4.6.GA.zip, available from http://www.jboss.org/jbossesb. This is only required to run the ESB/BPEL example.
  3. RiftSaw (version 2.0-M2 or higher), available from http://www.jboss.org/riftsaw
  4. If using JBossAS 5.1.GA, then it will also be necessary to upgrade JBossWS (version 3.2.1.GA or higher), available from http://www.jboss.org/jbossws
  5. Ant, available from http://ant.apache.org

Note

If you have previously installed RiftSaw-2.0-M1, then you will need to undeploy this version using the ant undeploy command from the install folder of the M1 distribution. This is due to database schema changes.

  1. Install JBossAS

    Unpack the JBossAS installation into the required location.

  2. Install JBossESB

    This is only required if you want to run the ESB/BPEL examples.

    Unpack the JBossESB installation into a location alongside the JBossAS installation. Then follow the instructions in the JBossESB installation (install/readme.txt), to deploy JBossESB into the JBossAS environment.

  3. Upgrade JBossWS

    This is only required if you are using JBossAS 5.1.GA.

    Unpack the JBossWS installation into a location alongside the JBossAS installation. Then follow the instructions in the JBossWS installation (docs/Install.txt), to upgrade the JBossWS version in the JBossAS environment.

  4. Install the RiftSaw distribution

    Unpack the RiftSaw distribution into a location alongside the JBossAS installation.

    • Edit the install/deployment.properties file to update the JBossAS and JBossESB location settings.
    • From the install folder, run: ant deploy -Ddatabase=.... to deploy RiftSaw to JBossAS. The list of available databases, and how they should be configured, is explained in the following sub-section.
    • If JBossESB has been installed, then run: ant deploy-esb-examples to install the BPEL/ESB examples into the JBossESB samples/quickstart folder.

To de-install the RiftSaw distribution,

  1. Uninstall the RiftSaw distribution

    • From the install folder, run: ant undeploy -Ddatabase=.... to remove RiftSaw from JBossAS. The database option should specify the same value used during installation of RiftSaw.
    • If JBossESB has been installed, then run: ant undeploy-esb-examples to remove the BPEL/ESB examples from the JBossESB samples/quickstart folder.

The following "in-memory" databases are available. If just evaluating the capabilities of RiftSaw, it is recommended that one of these options is used to reduce the time taken to get RiftSaw up and running.

  1. derby
  2. hsql

Other databases available, that require further configuration details, include:

  1. mysql
  2. postgres

The configuration properties for these database options can be found in the ${RiftSaw}/db/jdbc folder. These properties need to be specified before executing the ant deploy -Ddatabase=... command.

2.1. Overview
2.2. Quickstart Examples - Hello World
2.3. ESB Examples - ESB Invocation of Hello World
2.4. Importing Examples into Eclipse

This chapter provides a getting started guide to the examples. Further information on the individual examples can be found in the samples folder. This guide will describe one example from each of the categories - quickstart (pure BPEL) and ESB.

Before deploying any of the examples, you need to start the JBossAS server and ensure that RiftSaw has been installed. This can be achieved by testing whether the BPEL Console (as discussed in the previous chapter) is available.

The BPEL example we are going to try out is the simple 'hello world' example. This is located in the ${RiftSaw}/samples/quickstarts/hello_world folder.

The first step is to deploy the example to the running JBossAS server. This is achieved using the following command:

ant deploy

When the ant script indicates that it has completed successfully, the next step is to invoke the BPEL process we have just deployed.

This can be achieved using either the supplied ant script,

ant sendhello

Or by using any SOAP client, such as SOAPUI (available from http://www.soapui.org/).

The WSDL definition is located in the bpel folder, and can be used to initialise the SOAPUI client. The service location is: http://localhost:8080/bpel/processes/helloWorld.

An example message can be found in the messages subfolder.

When the message is submitted to the BPEL process, the response received is:

If you then wish to modify the example and deploy a new version, you will need to either update the 'version' property within the build.xml, or specify the version when performing the command, e.g.

ant -Dversion=2 deploy

and similarly when undeploying,

ant -Dversion=2 undeploy

Note

When modifying a previously deployed BPEL deployment, it will be necessary to either undeploy the previous version, or increment the version number. If you attempt to deploy a BPEL deployment unit with the same name as an already deployed unit, then the server will generate an exception.

This quickstart example demonstrates how an ESB service can directly invoke a BPEL process running inside RiftSaw, as long as RiftSaw and the ESB are co-located in the same JVM, and the invoked BPEL process is deployed to the RiftSaw instance running co-located with the JBossESB.

If the ESB examples were deployed during the RiftSaw installation procedure, the example that we are going to try will be located in the ${JBossESB}/samples/quickstarts/bpel_helloworld folder.

Also note that the quickstart described in the preceding section, located in the ${RiftSaw}/samples/quickstarts/hello_world must still be deployed. If this example is not deployed, then please follow the instructions in the previous section to deploy the example.

The next step is to deploy the ESB service that will invoke this "hello world" BPEL process. This is achieved by performing the following command in the ${JBossESB}/samples/quickstarts/bpel_helloworld folder.

ant deploy

Once the ESB service has been successfully deployed, then run the following command:

ant runtest

This command will send the text "Hello World via ESB to BPEL" to the ESB service, which will invoke the BPEL process, which in turn will append "World" to the text and echo it back until it is received by the client application.

For more information on the ESB to RiftSaw integration, please see the User Guide.

The quickstart examples, provided with the RiftSaw distribution, can be imported into an Eclipse environment as BPEL2.0 projects. This enables the BPEL and WSDL to be viewed using Eclipse based editors. Please see the JBoss Tools project for access to appropriate versions of these tools that work with the RiftSaw runtime engine.

  1. Select the 'Import...' menu item, associated with the popup menu on the background of the left panal (Navigator or Package depending on perspective being viewed).

  2. When the import dialog appears, select the General->ExistingProject from Workspace option and press the 'Next' button.

  3. Ensuring that the 'Select root directory' radio button is selected, press the 'Browse' button and navigate to the ${RiftSaw}/samples folder, then press 'Ok'.

  4. All of the Eclipse projects contained within the samples directory structure will be listed. Press the 'Finish' button to import them all.

    Once imported, the Eclipse navigator will list the sample projects:

Once imported, the BPEL and WSDL artifacts can be viewed by double-clicking the appropriate files.