Tutorials

Getting Started with the BEA AquaLogic Service Bus Tutorials

In this section, you learn how to set up your environment, configure your resources, and start BEA AquaLogic Service Bus so that you can create the solutions that implement the business cases presented in the tutorial. You must complete the steps in this section before you start the other tutorials.

The AquaLogic Service Bus tutorials guide you through designing and configuring AquaLogic Service Bus resources and deploying a configuration. These tutorials use the AquaLogic Service Bus example suite as a basis for instruction. (See the BEA AquaLogic Service Bus Examples Guide)

About the Scenarios

The tutorials describe a typical Mortgage broker scenario for a loan application request. A primary mortgage company uses AquaLogic Service Bus to route loan applications to appropriate business services. The loan applications are routed to different business services depending on certain qualifying criteria, such as the requested interest rate and the requested principal amount. The applicant's credit rating information is required in one of the scenarios to complete the loan request.

How to Use the Tutorials

The tutorials represent typical use case scenarios for AquaLogic Service Bus. You will learn how to configure and use AquaLogic Service Bus to resolve the business scenarios presented in the specified use cases.

Complete the first tutorial to become familiar with AquaLogic Service Bus. You can build on what you learn in the first tutorial by completing the subsequent tutorials. These tutorials explore the basic functionality of AquaLogic Service Bus, including message routing and enrichment.

The following tutorials are available:

Tutorial 1. Routing a Loan Application demonstrates how AquaLogic Service Bus facilitates routing of messages within an enterprise.
Tutorial 2. Transforming a Loan Application describes how a proxy service is configured with a routing node, transformations, and a Web service callout (Service Callout) to allow content based routing and message enrichment through AquaLogic Service Bus.
Tutorial 3. Validating a Loan Application describes how a BEA AquaLogic Service Bus proxy service can be configured to validate a message passing from a client to a business service.

Setting Up the Tutorials

The files (including pre-built business services) that support the building of the tutorial solutions are located in the following directory:

BEA_HOME\weblogic91\samples\servicebus\examples

The tutorial files contain properties that you must set to run the tutorials. Each business service also has a set of files associated with it. In the tutorial, you use four different business services. The files structure for each of the business services is the same—the directory structure for one of the business services, the normal service, is described in the following table. You can explore the other directories as an exercise.

Table 2-1 Sample Files Provided in Support of the Tutorials

Filename	Description
`/src/setEnv.cmd`	This file sets the environment properties.
`/src/`examples.properties	This file contains business service build and deployment properties.
For each business service:
`BEA_HOME/weblogic91/samples/servicebus/examples/src/examples/webservices/jws_basic/normal`	The files contained in this folder are those required by the normal business service. The same files structure exists for the other three business services used in this tutorial (`manager`, `large`, and `credit`).
`SimpleBean.java`	The jws-181 Web service definition.
`LoanStruct.java`	The message definition.
`build.xml`	The build script is used to build each of the services using `ant`.
`*.wsdl`	A Web Service Definition Language (WSDL) file defines each of the services.
`/client/Main.java`	The Java client with which each of the business services interacts.

You must execute the following steps to set up and run the tutorials:

Step 1: Install BEA AquaLogic Service Bus

Install AquaLogic Service Bus. For instructions on how to do this, see the BEA Products Installation Guide.

Create a new AquaLogic Service Bus domain in which to develop the tutorials. The Configuration Wizard guides you through the process of creating a new domain using the configuration templates.

For this tutorial, in the Configuration Wizard, make sure that you:

Select the AquaLogic Service Bus check box when you select the domain source.
Select Development Mode and the default PointBase database.
Create a domain named ServiceBusTutorial.

For instructions on how to use the configuration wizard, see Creating WebLogic Domains Using the Configuration Wizard.

Step 2: Change the Configuration Settings

To develop and run the AquaLogic Service Bus tutorials you must modify some of the configuration properties. The associated files are located in the following directory:

BEA_HOME\weblogic91\samples\servicebus\examples

There are two subdirectories: \build and \src. You make the configuration changes to the files in the \src directory.

Folder Name	Description
`\build`	This folder contains the files required to run the pre-configured AquaLogic Service Bus examples provided in the AquaLogic Service Bus Examples domain.
`\src`	This folder contains the files that support the development and running of the AquaLogic Service Bus tutorial. While developing the tutorial you will modify some of the files contained in this folder, such as `examples.properties`.

Edit the examples.properties File

To deploy the business services to your running tutorial domain, you must modify the properties responsible for specifying the WebLogic Server behavior. You do so in the WebLogic configuration section in the following file:

BEA_HOME\weblogic91\samples\servicebus\examples\src\examples.properties

To Modify the examples.properties File

Change the hostname to the name of the machine on which your ServiceBusTutorial domain is running.

Change the port number to the port number of the tutorial domain.

Enter the username you specified when creating the domain.

Enter the password you specified when setting up the domain.

Change the server name to the name you specified when you created the domain (if you specified a name other than the default name (AdminServer) assigned by the Configuration Wizard).

Listing 2-1 Fragment of examples.properties File

### WebLogic configuration ###

-- Configure per your WLS installation.

wls.hostname=localhost

wls.port=7001

wls.username=weblogic

wls.password=weblogic

wls.server.name=AdminServer

Edit and Run the setEnv.cmd File

Edit the setEnv script (setEnv.cmd on Windows or setEnv.sh on UNIX systems) in the following directory to replace the default path with the path to your tutorial domain's setDomainEnv script.

BEA_HOME\weblogic91\samples\servicebus\examples\src

The new path is:

BEA_HOME\user_projects\domains\ServiceBusTutorial\bin\setDomainEnv.cmd.

where BEA_HOME\user_projects represents the default directory in which you created your ServiceBusTutorial domain. (Use setDomainEnv.cmd or setDomainEnv.sh, as appropriate for your operating system.)

To Run the setEnv Script

Windows:

Open a Command window.

Change to the following directory:

BEA_HOME\weblogic91\samples\servicebus\examples\src\examples

In the examples directory, on the command line, run the following command:

..\setEnv.cmd

UNIX:

% cd BEA_HOME/weblogic91/samples/servicebus/examples/src/examples

% ../setEnv

where BEA_HOME represents the directory in which you installed AquaLogic Service Bus.

Edit the setDomainEnv.cmd File—Windows 2000 Users Only

This step is only for Windows 2000 users. On Windows 2000 machines, a classpath length problem prevents you from running ant tasks and executing the tutorial. The workaround uses the subst command to shorten the classpath passed by ant. Follow these steps to shorten the classpath:

Edit the setDomainEnv.cmd file located in the Service Bus domain installation location, BEA_HOME\user_projects\domains\ServiceBusTutorial\bin\

In the setDomainEnv.cmd file search for the instruction that sets the PRE_CLASSPATH. The instruction looks like:

set PRE_CLASSPATH=%PRE_CLASSPATH%;%WL_HOME%\servicebus\lib\sb-public.jar;%

Identify three unused drive letters (for example, X, Y, and Z) and add the following code to the beginning of the file:

subst X: %WL_HOME%\servicebus\lib
subst Y: %WL_HOME%\integration\common\lib
subst Z: %WL_HOME%\server\lib

Edit the PRE_CLASSPATH entry, replacing the path with the appropriate drive letter. For the example:

set PRE_CLASSPATH=%PRE_CLASSPATH%;X:\sb-public.jar;X:\sb-internal.jar;Y:\wlicommon.jar;Y:\qs_p13n_system.jar;X:\xbus-core.jar;Z:\wlxbean.jar;Z:\xquery.jar;Z:\apache_xbean.jar;Z:\binxml.jar

Save the changes and close setDomainEnv.cmd.

Run the setDomainEnv.cmd.

cd to BEA_HOME\user_projects\domains\ServiceBusTutorial\bin\

Run setDomainEnv.cmd

Step 3: Start BEA AquaLogic Service Bus

Start AquaLogic Service Bus using one of the following methods:

From the Windows Start menu, select

Start —>Programs—>BEA Products —>User Projects —>domain_name —>Start Server for AquaLogic Service Bus Domain
Where domain_name represents the name you assigned your AquaLogic Service Bus domain when you created it.

On Windows systems, invoke startWebLogic.cmd from the root of the AquaLogic Service Bus domain.
On UNIX systems, invoke startWebLogic.sh from the root of the AquaLogic Service Bus domain.

A server command console window, which shows status information about Weblogic Server is displayed.

Note: If you created a production mode domain, you are required to enter a valid username and password to start the server. For more information about domains, see Creating WebLogic Domains Using the Configuration Wizard.

Step 4: Build and Deploy the Business Services

You must start the server before building the Web services. See Step 3: Start BEA AquaLogic Service Bus. After the server is started, you must run a build script to:

Build and deploy the Web services
Create a Java client to test the Web services
Exercise the Java client using ant run

To Build and Deploy the Business Services

In the Command window, ensure that you have run the setEnv script, as described in To Run the setEnv Script.

Change to the webservices\jws_basic directory.

cd BEA_HOME\weblogic91\samples\servicebus\examples\src\examples\webservices\jws_basic

Four business service folders exist in this directory. The following steps describe how to build and run each of the business services.

Change to the normal directory: cd normal.

To build the other business services (credit, large, and manager), change to the appropriate business service folder.

To deploy the Web service, enter ant, then press Enter.

A message indicating whether the command was successfully executed is displayed on the console.

To test the deployed Web service, Enter ant run, then press Enter.

A message from the business service is output to the command line. The message indicates whether the Web service was run successfully.

To build the remaining Web services (credit, large, and manager) that you will use in this tutorial, repeat step 3 through step 5 of these build and deploy instructions for each of the folders listed in the \jws_basic directory.

Step 5: Log in to the AquaLogic Service Bus Console

To log in to the AquaLogic Service Bus Console, open a browser window and enter the following URL in your browser:

http://host:port/sbconsole

where host:port represents the name and port number of the machine on which WebLogic Server is running. For example, if WebLogic Server is running on your local machine using the default port configuration, enter the following URL in your browser:

http://localhost:7001/sbconsole

The AquaLogic Service Bus Console login page is displayed. Enter the username and password you specified when you created the AquaLogic Service Bus domain.

Where to Go from Here

After you complete the steps required to set up the tutorials, you are ready to proceed to Tutorial 1. Routing a Loan Application, which describes how to configure BEA AquaLogic Service Bus with the resources required for the routing scenario.

Each of the tutorials include instructions for designing and configuring the AquaLogic Service Bus resources, followed by test sections that you can use to test the configurations you complete.