Developing Tuxedo SALT SCA Components

<Do not delete this text because it is a placeholder for the generated list of "main" topics when run in a browser>

Purpose

In this tutorial, you learn how to configure all the components required to call an Oracle Tuxedo SCA component, using the Oracle Service Architecture Leveraging Tuxedo (SALT) product.

After completing this course, you should be able to:

Time to Complete

Approximately 2 hours including product download and installation time.

Overview

Oracle SALT enables developers and administrators to expose Tuxedo services as Web services and SCA components.

This OBE guides you through constructing an application that demonstrates calling Tuxedo SCA components using the SALT SOAP server gateway. The back end for the uBike application is written in Tuxedo. Read the uBike Tuxedo Overview page for detailed information about the back -end services offered on the Tuxedo side of this application. This example only uses the SEARCHINVENTORY service of the uBike application.

Scenario

In this tutorial, you begin by configuring the SALT environment to expose uBike C++ services as Web services that can be called by any SCA-compliant code, and test that your Web services are working using soapUI to enter a color as input to the service call, which returns the bike inventory available that matches that color.

Here are the differnt sections of this hands-on exercise:

Your company has a pre-existing application, called uBike, that is implemented using C++. The company is investigating how to leverage this IT investment to work within their overall SOA strategy without making major and expensive changes. The company has decided to use Oracle SALT to expose their existing uBike C++ services as Web services in an SCA container that can be easily consumed by SCA-compliant applications. This strategy integrates existing technologies to enable the application server tier to freely use C++ services with very little change.

The diagram below displays the high-level architecture of the solution:

 

Software Requirements

The following is a list of software requirements:

Prerequisites

Before starting this tutorial, you should have performed the following in the order specified:

. Installed GNU 4.1.2 Compiler
. Installed Oracle Tuxedo 11gR1 (instructions): Installed to /home/vmuser/tuxedo/tuxedo11g
. Installed Oracle SALT 11gR1 (instructions): Installed to /home/vmuser/tuxedo/tuxedo11g
. Installed soapUI

Develop and Run Tuxedo SALT SCA Component


To set the lab environment up, perform the following steps. For our environment, we created a user called vmuser, and this user's home directory was used to install the products and lab files. You can either create a user called vmuser as well, and reuse the same paths as the exercise uses, or you can go your own route and be sure to modify the paths and environment touch points in your system. This tutorial will not specify where these changes need to take place as it assumes you are following the instructions verbatim.

Set up Lab Files


. Extract installation files:

  • Unzip the uBikeSCA.zip file to /home/vmuser/handson/uBikeSCA, which will create the folder structure for the lab files.

The uBikeSCA folder contains all the files needed to perform this exercise.

The table below describes the purpose of each file:

File
Purpose
uBikeSCA
Main directory ($APPDIR): /home/vmuser/handson/uBikeSCA. This contains all
the Tuxedo related files.
ubb
This file contains the Tuxedo configuration to run the SCA component and SALT servers.
uBike.composite
 This file is the root SCA composite configuration for the uBike SCA component.
setenv.sh
 The file that sets the environment to develop and run this exercise.
$APPDIR/uBike.server
Folder that contains the Bike store application components. This will contain the SCA composite and components you will develop.
uBike.server.composite
Service Component Definition Language (SCDL) source for this composite.
uBikeServiceImpl.cpp
This file contains the actual Tuxedo C++ code that provides the SEARCHINVENTORY service that is exposed as an SCA-based Web Service.

 
.

 Modify and Run setenv.sh:
  • Edit the setenv.sh file and make sure the variable settings are correct. If you installed everything to the same directory structure this example uses, then it should be correct by default.
  • Open a new terminal. Click the K menu button, and then select the System/Terminal menu choice.
  • Navigate to the lab directory:

    cd handson/uBikeSCA

  • Set up the environment using the setenv.sh script:

       . ./setenv.sh

You are now ready to perform the steps outlined in this lab guide.

Desigining the Interface for a Bike Inventory Component

In these steps we will see how to write a C++ interface for our component.

. Open Text Editor :

  • Open the Kate editor by selecting K Menu>Utilities>Editors>Kate:

 

.

Enter Code for C++ Interface :

  • Select File>New to create a new text file.
  • Copy and paste this code into the file.

Your code should resemble the following:

 

.

Save File in Correct Location :

  • Select the File>Save as… menu option.
  • Navigate to /home/vmuser/handson/uBikeSCA/uBike.server
  • Save the file as uBikeService.h. The case is important.

You may keep the source editor open for the next tasks in this lab.

 

Developing the Bike Inventory Component

With these steps, you will see what it takes to develop actual business code for the SALT SCA container.

. Examine and Repair uBike Implementation Code:

  • The component source implementation needs to be provided in a source file that follows a
    convention based on the contents of the SCDL.

From the following SCDL snippet found in $APPDIR/uBike.server/uBike.server.composite the implementation source code is written in a file named uBikeServiceImpl.cpp:

For convenience this file and the related code is already provided in the /home/vmuser/handson/uBikeSCA/uBike.server directory:

  • Open the uBikeServiceImpl.cpp source file in Kate:

  • Examine the code. This component sets up an in-memory list of bicycles at boot time, which represent a fictitious inventory. Find the searchBike() method of this component, which is designed to search this inventory according to a search criteria, in this case, bike color.
  • There is an error in this code that prevents it from returning any results. Spot the error and fix it. You may comapre your code at any time with the solution to see where this error exists.

.

Build Component :

  • Once the code is complete, the component is build using the buildscacomponent command, as follows:

    buildscacomponent -c uBike.server

The resulting file is a libuBike.so shared library. The buildscacomponent command will look at the SCDL code and build all C++ components it finds. Individual components may also be built by qualifying them with command-line options.

 

Exposing the Bike Inventory Component as a Web Service and Testing the SCA component

With these steps, we will see how to create a WSDL interface from a C++ interface, and then expose the component as a Web Service. The steps detailed here can easily be combined in scripts and automated, but are shown here for convenience, and to demonstrate how they can be performed separately in case some customization is needed.

. Generate Metadata Repository Interface:

  • Enter t he following commands to generate a Tuxedo Metadata Interface File (.mif) from the C++ interface:

    cd uBike.server

    scatuxgen -D FML32/BikeInventory -c uBike.server.composite
              -s uBikeService -w -a "http://localhost:112345" -n "http://uBike.com"

  • The –w option generates SALT wsdf definitions that are required for the next step.
  • The .mif file then needs to be loaded into the Tuxedo Metadata Repository using the following command:

    tmloadrepos -i uBike.server/uBikeService.mif meta.repos

 

.

Generate WSDL :

The following command generates a WSDL interface for the service we just developed. Change directory to $APPDIR, ensure that the tuxconfig file is created by running the tmloadcf command as shown below, then also perform the steps shown:

tmloadcf -y ubb

tmboot -A -s TMMETADATA

tmwsdlgen -c uBike.server/uBikeService.wsdf -y -o uBike.server/uBikeService.wsdl

tmshutdown -y

Take a moment and look at the generated WSDL file.

 

.

Build Server :

The buildscaserver command takes the SCDL, parses C++ interface(s) and generates an appropriate bootstrap server that will host SCA components in a Tuxedo environment. The command needs to be executed as follows:

buildscaserver -w -c uBike.server -o uBikeSCASvr

This generates a number of files in $APPDIR:

  • uBikeService_1.xsd
  • uBikeService.fml32
  • uBikeService.mif (this one is recreated, but is the same as the one generated by scatuxgen)
  • uBikeService.wsdf

These files are necessary for the operation of the SALT GWWS SOAP gateway.

 

.

Post-Build Set up:

Important:
The uBikeService.fml32 file generated in the step above needs to be edited, and its base number changed to a positive number. This is done to enforce users to double-check that that field numbers do not collide throughout enterprise applications.

Edit the uBikeService.fml32 file, replace “-10000” with “10000”:

  • Next, the generated service definition needs to be re-loaded into the Tuxedo Service Metadata Repository. This step is necessary so the correct field definitions generated above are taken into account.
  • Finally, the SALT deploy configuration need to be generated.

Run the following commands to accomplish this:

tmloadrepos -i uBike.server/uBikeService.mif meta.repos

wsloadcf -y GWWS.dep

 

Testing the SCA Component using soapUI


.

Boot the Application :

Run the following command to boot the Tuxedo application:

tmboot -y

 
. Test GWWS server WSDL and XSD configuration:

  • Enter the following into a Web browser address bar to see if the SALT GWWS server serves the component's WSDL:

    http://localhost:12345/wsdl

Your output should resemble the following:

  • Enter the following into a Web browser address bar to see if the SALT GWWS server serves the related service schema:

    http://localhost:12345/xsd/uBikeService_1.xsd

Your output should resemble the following:

Now that you have a valid WSDL and related schema, you can use soapUI to test the services.

 

. Run soapUI:

Start soapUI to test the SCA service.

 
. Create soapUI project:

Right-click the default workspace node in the left-hand pane, and select New soapUI Project.

Enter uBikeService for the project name and /home/vmuser/handson/uBikeSCA/uBike.server/uBikeService.wsdl for the Initial WSDL property, and click the OK button.


. Test the searchBike Service:

Expand the uBikeServiceSOAP node in the uBikeService project and double-click the Request1 node to open the SOAP request and response payload window.

Modify the payload contents to send a request to the searchBike service with a COLOR element of ORANGE. Note that colors need to be entered in uppercase. You can also try to test using other colors such as BLACK, WHITE, GREEN, RED, BLUE, YELLOW, and SILVER.

Your payload should look similar to the payload in the image below:

Click the icon to submit the request to the searchBike service. You should see a list of bicycles returned in the response window as shown in the image below. If you get an error, make sure you found the issue within the uBikeServiceImpl.cpp file and completed all of the previous steps successfully.

Congratulations, you have validated that the searchBike service is working properly!

NOTE: If you like, you can open the Tuxedo administration client, tmadmin, to monitor that your Tuxedo services are actually being called. The tmadmin command used to monitor Tuxedo services is called printservice, or psc for short.

 

Summary

Congratulations! You have successfully completed this OBE tutorial.

Oracle SALT exposes Tuxedo services as Web services and SCA components, and is a bidirectional gateway to and from Tuxedo applications. This enables SCA-compliant applications to call Tuxedo SCA components as part of an Enterprise SOA application. Now you can implement your own solutions that use these technologies together.

In this tutorial, you should have learned how to:

Check back on OTN for more OBE tutorials that build on this example to demonstrate other Tuxedo product integration examples.

Resources