Using the Oracle Service Bus Tuxedo Transport

Set TUXDIR so that all applications will know how to run Tuxedo commands. This is set automatically for you when Tuxedo is installed, but may need a little tweak for the setting to take place in new DOS windows.

a. Right-click My Computer and select Properties.

b. In the System Properties dialog box, click the Advanced tab, and then click the Environment Variables button to display the Windows environment variable settings:

Add or edit TUXDIR within the System Variables box, delete the last character, and put it back to reset the variable. Click OK in all the subsequent dialog boxes.

Verify that TUXDIR is getting set properly by opening a DOS window and entering:

echo %TUXDIR%

If you have not already installed Microsoft Visual Studio 2005, then install it from the link provided in the Software Requirements section.

Note: As the versions of Visual Studio progress, it is not possible to find earlier versions of the software easily online. As a result, you will need to install using the installer included in this tutorial. The uBike Tuxedo application has been tested with Visual Studio 2005 successfully. Testing with Visual Studio 2008 was not successful and, therefore, is not supported at this time.

Extract the uBikeTux.zip contents to a location of your choice. For this example, it is assumed that it is installed to C:\, resulting in the application installing to C:\uBike.

In Windows Explorer, open the setenv.cmd file for editing in the uBike folder. Set the appropriate values for your environment using the following table for guidance. After you have finished editing the setenv.cmd file, save your changes and close the file.

Note: Tuxedo applications are written in C or C++, which use make files to build projects much like ant is used in the Java world.

a. In your uBike folder, double-click the uBikeTuxSvr1.dsw file to open the uBike project in Visual Studio.

b. If you see a message that says, "The project 'uBikeTuxSvr1.dsp' must be converted to the current Visual C++ project format....," click Yes to convert the project.

c. If you see a message box that says "A Visual C++ project of the name uBikeTuxSvr1.vcproj already exists...," click Yes to load the existing project.

d. If it is not expanded yet, expand the uBikeTuxSvr1 project in the window on the left.

There are a few Microsoft Windows library files that Tuxedo processes need in order to compile correctly. They are not included with Visual Studio 2005 and you have two choices for obtaining them. (Warning: Read both options completely before making a choice.)

1. Execute and install the Microsoft Platform SDK for Windows 2003 network installer. This is the proper way to obtain the libraries; however, it is a lengthy process to download and install. If you do not need a C++ compiler environment on your machine for more than this exercise, then you can complete this tutorial by using option two below to set up the missing libraries.

You need to configure Visual Studio to use these libraries. After the SDK is installed, go to the Visual Studio IDE and select Tools > Options > Projects and Solutions > VC++ Directories to open the configuration window for adding directory paths to the project. In the upper-right side of the window, select Library files in the drop-down list box . Next, click the Folder icon to add a new path entry. Browse to the location of the Lib folder where you installed the Microsoft Platform SDK. The default location is C:\Program Files\Microsoft SDKs\Windows\v6.1\Lib. Click OK when done.

2. Unzip the contents of msvclibs.zip to the lib folder of your Visual Studio installation. The default location is C:\Program Files\Microsoft Visual Studio 8\VC\lib.

a. Within Visual Studio, press the F7 key to build the project. Visual Studio will run the uBikeTuxSvr.mak file using the following command: (You can also run the uBikeTuxSvr.mak file from the command line if desired)

nmake -f uBikeTuxSvr.mak

b. Check the output window in the IDE to see if the build had any errors. A clean build should look like the image below, and you should see the following files in your uBike folder. The build process also creates other files that are covered later.

a. Within the command shell with the environment set, enter the following command:

tmboot -y

Run the ud32 command, which is an out-of-the-box (OOTB) Tuxedo client that uses search.ud32 as an input file to call the SEARCHINVENTORY Tuxedo service to return all bicycles in inventory with a SKU of RJ4500.

NOTE: The in-memory database that is created during the first initialization of the uBikeTuxSvr is generated with random values. As a result, your screen results may vary slightly with the screen shot below.

ud32 < search.ud32

Use the commands within the Tuxedo Administration command-line tool to monitor the activities within the uBike application. This will help you verify that your Tuxedo services were actually called. First run tmadmin at your command prompt to start the tool, and then try each of the following commands to get familiar with them to use later. Note that the short version of the command is listed within parenthesis.

Example of printserver: Notice how the uBikeTuxSvr server has performed one request since you ran the SEARCHINVENTORY service.

Example of printservice: See that the SEARCHINVENTORY service has executed once.

Now the Tuxedo uBike application is built, configured, and running.

Configure OSB domain using the Configuration Wizard:

Start the WebLogic Server Configuration Wizard using Start > Programs > Oracle WebLogic > WebLogic Server 10gR3 > Tools > Configuration Wizard.

NOTE: Your screen may vary slightly from what is shown in the screen shot below. As long as you have the options that are selected below, and have them selected, this exercise will function properly.

In the next section, you will log in to the WebLogic Administration console, which shows that the server is working correctly.

The uBike application has a /DOMAINs gateway already configured and running on the Tuxedo side. You will use this file as the basis for configuring the WLS WTC side of the gateway. Open and examine the uBike.dom file contained within your uBike folder. Look at the screen shot below and take a few minutes to become familiar with the parameters. You will need some of these parameters to configure the WTC side within the WebLogic Server Administration console.

Note: The Tuxedo Universal Bulletin Board (UBB) configuration file is called uBike.ubb for your application. Open it to examine how it relates to the /DOMAINs configuration file below. Pay close attention to the DOMAINID parameter, and the GWADM, DMADM, and GWTDOMAIN /DOMAINs servers that belong to the SYS_GRP group, which are the settings that directly relate to configuring the domain gateway on the Tuxedo side.

Enter the following values and click OK:

Enter the following values and click OK:

This completes the basic configuration for setting up WTC to work with your remote Tuxedo domain. Now you need to configure a user within WLS that matches the Tuxedo ACCESSPOINTID parameter so the domains can establish a trusted connection.

Now you have configured WTC and are ready to begin configuring OSB services to use your WTC gateway to Tuxedo.

Open and examine the uBike.meta file located in your C:\uBike folder. Use the image below to identify the purpose of the various settings. This file is provided for you to learn by using a working example.

See http://download.oracle.com/docs/cd/E13161_01/tuxedo/docs10gr3/ads/admrp.html for more information about the Tuxedo service metadata repository.

Tuxedo provides the tmloadrepos tool to take a service metadata file as input to store in binary format within a Tuxedo metadata repository file. You need to store this data in the repository so you can run a tool to extract the WSDL form of this definition from the repository. The tmloadrepos tool does not generate WSDL directly.

See http://download.oracle.com/docs/cd/E13161_01/tuxedo/docs10gr3/rfcm/rfcmd.html#wp1789066 for more information about the Tuxedo tmloadrepos tool.

Note: Oracle provides a product called SALT that enables you to expose Tuxedo services as Web services. SALT has other tools that can perform similar functions; however, it is a separate download and this tutorial is focused on providing a solution using only the out-of-the-box capabilities of Tuxedo and OSB. You can read more about SALT at http://download.oracle.com/docs/cd/E13161_01/salt/docs10gr3/index.html.

Enter the following to run the tmloadrepos command:

cd c:\uBike

tmloadrepos -e -i uBike.meta -y metarepo

Tuxedo provides the tmunloadrepos tool to generate WSDL from a service contract stored in a metadata repository.

See http://download.oracle.com/docs/cd/E13161_01/tuxedo/docs10gr3/rfcm/rfcmd.html#wp1791154 for more information about the Tuxedo tmunloadrepos tool.

You run tmunloadrepos and redirect the output to create a WSDL file within the uBikeClient folder by executing the following command:

tmunloadrepos -w metarepo > uBikeClient\uBike.wsdl

The WSDL that is generated results in a message payload that is not compatible with the OSB Tuxedo Transport. As a result, a few changes need to be made to the WSDL to make it work properly.

Additionally, the response payload from the OSB Tuxedo Transport business service is not structured in a way that is meaningful to OSB Web service clients, so you will need to create an XML schema that represents how the response should be returned and include it in your WSDL file. You will then need to transform the response payload from the business service to your XML schema type using an XQuery function.

This section will guide you through examining and setting up these constructs, and the next section will take you through applying them to your OSB configuration.

Examine BikeSchema.xsd

Right-click and save the BikeSchema.xsd file to c:\uBike\uBikeClient. This file contains the schema definition of the Java data types that the calling Web service client will use as the operation's return type. Examine the BikeSchema.xsd file to become familiar with its definitions:

A Tuxedo FML buffer is an allocated memory space that contains a set a field arrays. Each field is stored in the buffer as an array of occurrences, starting at an index of 0. Typically, a Tuxedo service returns a buffer with multiple instances (or occurrences) of multiple fields. The index number of the occurrence is used to correlate related fields into a single data record. While this model works in cases where the calling client and the service are tightly coupled, it is not suitable for an SOA application because the calling client has no way of knowing how the data is structured and how to make sense of the data. The data is meaningless without some structure.

The BikeSchema.xsd file defines an element, called bikeList, that contains a list of bike elements and a single STATUS element. The bike element defines the proper grouping of the particular data fields that comprise a bicycle record that represents what the Tuxedo service thinks is a bicycle record.

Examine FMLtoHierarchy.xq

Right-click and save the FMLtoHierarchy.xq file to c:\uBike\uBikeClient. This file contains the XQuery function that transforms the response payload of the uBike Business service into the BikeList data type defined in the BikeSchema.xsd file. Examine the FMLtoHierarchy.xq file to become familiar with how it performs the transformation:

Now that the BikeSchema.xsd file defines the desired data structure of the uBike SEARCHINVENTORY service return type, something needs to transform the <FML32>...</FML32> into <bikeList><bike>...</bike><bike>...</bike><bike>...</bike>...</bikeList>. The FMLtoHierarchy XQuery function defined here will take the <FML32>...</FML32> payload as input, iterate through each of its elements, and create the bikeList XML payload using the data contained within $fmlout at each iteration count using $count as the index into the FML32 element list. The FMLtoHierarchy file specifies that the FML32 element is defined externally, which in fact is defined within the uBike.wsdl file. Actually, it isn't defined yet. You will make those modifications next.

Examine and Modify uBike.wsdl

Open the c:\uBike\uBikeClient\uBike.wsdl file to edit its contents:

• Replace the following line

    <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified"     targetNamespace="http://example.org/tuxedo/typedef">

         with

    <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified">

• Do a search on tuxtype: and delete all occurrences within the file. This removes the namespace data associated with the element names. Removing namespace information is required because the Tuxedo Transport XML to FML conversion process strips out namespace information during the request process. This is because Tuxedo FML buffers do not have the concept of a namespace, and would not have any way of knowing how to reconstruct the payload with the proper namespace data. As a result, the Web service client code cannot marshal the response payload properly into Java bindings. The easiest way to deal with this is to remove the namespace data from the WSDL file so that the generated classes and payloads are all compatible.
• Include the BikeSchema XML schema in your WSDL so the clientgen Web service task can properly generate the necessary client classes required to marshal the response XML payload into the proper Java data types for the calling Web service client. To include the BikeSchema.xsd schema place the following line

    <xsd:include schemaLocation="BikeSchema.xsd"/>

         right before the following line

    <xsd:element name="SEARCHINVENTORY">

• The WSDL that is generated by the tmunloadrepos command creates request and response data types that are not compatible with the Tuxedo Transport. The Tuxedo Transport assumes that the first element in the payload it receives is a wrapping element, and that all elements contained within that element are FML fields. The WSDL that is generated creates a payload of <SEARCHINVENTORY><inbuf><FMLFIELDS></inbuf></SEARCHINVENTORY>. You need to simplify your WSDL to eliminate the inbuf element so the payload is <SEARCHINVENTORY><FMLFIELDS></SEARCHINVENTORY>. You do this by mapping the fml32_SEARCHINVENTORY_In type directly to the SEARCHINVENTORY element. Modify the SEARCHINVENTORY element by changing its definition from

    <xsd:element name="SEARCHINVENTORY">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element name="inbuf" type="fml32_SEARCHINVENTORY_In"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>

          to

    <xsd:element name="SEARCHINVENTORY" type="fml32_SEARCHINVENTORY_In"/>

• Likewise, the generated response type is not compatible with the Tuxedo Transport's response payload, which is <FML32><FMLFIELDS></FML32>. You need to simplify the SEARCHINVENTORYResponse element by removing the outbuf element and mapping the fml32_SEARCHINVENTORY_Out type directly to the SEARCHINVENTORYResponse element. You also need to change the name of the element from SEARCHINVENTORYResponse to FML32 so the data type will match the payload, and so you have properly defined the FML32 element which is used by the FMLtoHierarchy XQuery function. Modify the SEARCHINVENTORYResponse element by changing its definition from

    <xsd:element name="SEARCHINVENTORYResponse">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element name="outbuf" type="fml32_SEARCHINVENTORY_Out"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>

         to

    <xsd:element name="FML32" type="fml32_SEARCHINVENTORY_Out"/>

• Now that you are changing the return type of the Web service operation to bikeList, you must change the operation's return type in the WSDL file so the calling Web service client can receive the data as a bikeList object. Change the tuxedo_portType output SEARCHINVENTORYOutput type to bikeList by changing

    <wsdl:part element="SEARCHINVENTORYResponse" name="FML32"/>

         to

    <wsdl:part element="bikeList" name="bikeList"/>

Click uBike.wsdl to compare your WSDL file with the solution to make sure it is correct.

Save the file with your changes when done.

Part of the configuration of the OSB business service that will use the Tuxedo Transport requires you to provide a Java class that represents the Tuxedo FML fields that are used for the Tuxedo service call. This class is generated as part of the Tuxedo make process you ran earlier. You may not have noticed this as the last part of the build process.

Let's examine the picture below that shows the commands used to build this class:

• The uBikeFML file is the FML field definition dictionary for all of the fields used by the uBike Tuxedo application. This file is used by weblogic.wtc.jatmi.mkfldclass32 to generate the uBikeFML.java file
• The uBikeFML.java file is then compiled into uBikeFML.class.

Package the uBikeFML.class file into a jar file called uBikeFML.jar by entering the command below in your command window:

jar cvf uBikeFML.jar uBikeFML.class

• Open a Web browser window and go to http://localhost:7001/sbconsole to open the OSB Administration Console. Log in using the credentials you set when you created your domain: weblogic/weblogic.
• Click the Project Explorer tab at the lower-left side of the screen to display the Projects page.

• Click the Create button in the upper-left side of the page to start an edit session in the OB Admin Console.

Note: The remainder of this tutorial will assume that you are properly using the change management mechanism of OSB. All configuration changes made using the OSB Administration Console involve clicking the Create button, making changes, and then either clicking the Discard button to roll back your changes, or clicking the Activate button to commit and label your changes.

Troubleshooting Tip: if you receive an error at any time using the OSB Administration Console or the Workshop IDE that says the WLS edit lock is currently held by another user, it usually means that either you have inactivated changes in the WebLogic Administration Console that need to be activated, or you need to click Undo All Changes if there are no changes to activate and click the Log Out link on the top of the page because the auto lock and edit feature of WLS always has the edit lock held when it is logged in. Logging out releases the lock.

• Enter a new project name called Tuxedo uBike and click the Add Project button.
• Click your newly created Tuxedo uBike project to display its configuration page.

• Enter a new folder name called WSDL and click the Add Folder button.
• Enter a new folder name called JAR and click the Add Folder button.
• Enter a new folder name called Proxy Services and click the Add Folder button.
• Enter a new folder name called Business Services and click the Add Folder button.

Your screen should look similar to the following:

Click the Activate button, enter a description of changes you made, and then click the Submit button to commit your changes.

Click the WSDL folder under the Tuxedo uBike project on the left of the page.

In the Resources section, click the Create Resource list box and select XML Schema under Interface.

Enter the values as follows, and click the Save button.

After saving your changes you should see an entry for this resource similar to the following:

Click the WSDL folder under the Tuxedo uBike project on the left of the page.

In the Resources section, click the Create Resource list box and select XQuery under Transformation.

Enter the values as follows, and click the Save button.

After saving your changes you should see an entry for this resource similar to the following:

Click the WSDL folder under the Tuxedo uBike project on the left of the page.

In the Resources section, click the Create Resource list box and select WSDL under Interface.

Enter the values as follows, and click the Save button.

After saving your changes you should see an entry for this resource similar to the following:

Click the JAR folder under the Tuxedo uBike project on the left of the page.

In the Resources section, click the Create Resource list box and select JAR under Utility.

Enter the values as follows, and click the Save button.

After saving your changes, you should see an entry for this resource similar to the following:

Click the Business Services folder under the Tuxedo uBike project on the left of the page.

In the Resources section, click the Create Resource list box and select Business Service under Service.

Enter the values as follows, and click the Next button.

On the Transport Configuration page, enter the following values, leave the rest of the options at their default values, and click the Next button.

On the Tuxedo Transport Configuration page, enter the following values, leave the rest of the options at their default values, and click the Next button.

Note: You will have to select the uBikeFML.jar in the Classes Jar property prior to setting the Field Table Classes property.

On the Business Service Configuration Summary page, review your settings to make sure that they match the screen below, and then click the Save button.

Test your business service to verify that you have a connection to Tuxedo and can call the SEARCHINVENTORY service:

• Select the Business Service link of your Tuxedo uBike project on the left of the page.
• Locate your uBike Business service and click the Test icon to open the test console window.
• In the test console window, enter the following text as the payload:

<FML32>
<SKU>RJ4500</SKU>
</FML32>

• Verify that your screen looks like the screen below and click the Execute button to run the test:

• You should see results similar to the following:

Note: If you get an error that the system could not get a TuxedoConnection or a TuxedoSession, you may have to restart WLS and/or Tuxedo for the servers to properly establish their connection. If this does not work, then you may have to perform the following to force it into working: tmshutdown -y, del BDMCONFIG, dmloadcf -y uBike.dom, tmboot -y. Make sure that all of the Tuxedo server processes shut down before running dmloadcf. If this does not work, contact Mark Lindros.

Now that the business service is configured and working, you can set up the OSB proxy service that will route requests to it.

Click the Proxy Services folder under the Tuxedo uBike project on the left of the page.

In the Resources section, click the Create Resource list box and select Proxy Service under Service.

Enter the values as follows, and click the Next button.

On the Transport Configuration page, enter the following values, leave the rest of the options at their default values, and click the Last button.

On the Proxy Service Configuration Summary page, review your settings to make sure that they match the screen below, and then click the Save button.

Now that the proxy service is configured, you need to pair it up with your Tuxedo business service. The next section guides you through adding a route between your services.

Click the Proxy Services folder under the Tuxedo uBike project on the left of the page.

Click the icon for the uBike Proxy service under Actions to open the message flow editor.

• Click the Edit button to start an edit session.

Note: The OSB Administration Console does not display the Change Center on this screen. Clicking the Edit button starts an edit session. To commit your changes, you will need to ensure that you click the Save button on each page until you see the Change Center again, and then click the Activate button.

• Click the uBike Proxy node and select the Add Route option.

• This creates a new node on the screen called RouteNode1.

On the page that appears, click Add an Action > Communication > Routing to bring up the Route to service page..

Click the <Service> link to open the Select Service window.

Select the uBike Business service and click the Submit button.

Your screen should now look similar to the following:

Under Response Actions click Add an Action > Message Processing > Replace to add a replace node transformation. This is where you will configure the proxy service to transform the uBike Business service response into the bikeList schema defined in BikeSchema.xsd.

Within the Replace configuration form, select the Replace node contents option, leave the <XPath> entry as it is, type in body as the variable where the replace takes place, and click on <Expression> to configure this action to use our FMLtoHierarchy XQuery function that transforms the response payload into a list of bike records.

On the XQuery/XSLT Expression Editor page, select the XQuery Resources link to open the XQuery Resources configuration page.

Click the Browse button to open the file select window.

Select the FMLtoHierarchy option and click the Submit button.

Enter $body/FML32 in the Binding text box within the Bind Variables section. This will assign the fmlout variable that gets passed to the XQuery function defined in FMLtoHierarchy to the node contents contained within the FML32 element of the response body. This effectively passes the uBike Business service's response payload of <FML32>...</FML32> to the XQuery function. Click the Save button, and any subsequent Save buttons, and Activate your changes.

Click the icon to open the test console for the uBike Proxy service. Enter the following as the payload and click the Execute button.

<SEARCHINVENTORY>
<SKU>RJ4500</SKU>
</SEARCHINVENTORY>

You should see a response similar to the following:

Now that you have successfully configured OSB to communicate with Tuxedo via the Tuxedo Transport; you need to build, deploy, and test the Web service client code that calls the service.

• Select Start>All Programs>Oracle WebLogic>Workshop for WebLogic 10gR3 to open Workshop
• A dialog window opens to prompt for the location of an Eclipse workspace. Choose a location of your choice. If there is no workspace in that location one is created for you
• Be sure to close the Welcome screen so you can view the IDE properly

Within Workshop, select File > Import to import the uBike front end application, select General > Existing Projects into Workspace, and click the Next button.

Click the Browse button and locate the root folder where you extracted the uBikeFrontEnd.zip contents, click Ok, ensure that both the uBikeEar and uBikeWeb project check boxes are selected and click the Finish button.

In Workshop, click the Servers tab, right-click inside the Servers window and select New > Server to display the New Server dialog window. Ensure that Oracle WebLogic Server v10.3 is selected and click the Next button.

Click the Browse button and browse to the location where you created your OSB/WLS domain to select it as the domain for your server configuration, and click the Next button.

On the Add or Remove Projects dialog window, add the uBikeEar project to Configured Projects and click the Finish button.

Open a command window, set your environment as specified previously, and cd to the C:\uBike\uBikeClient folder so you can use it to create the Web service client classes needed to call your OSB proxy service.

From your command window, run ant to perform the build.

You should see a jar file called uBikeClient.jar in your base folder. Copy the uBikeClient.jar file to the APP-INF\lib folder of your EAR, so your code can make calls to your proxy Web service. Open the uBikeClient.jar file to examine its contents to see how clientgen generated classes that reflect the BikeSchema.xsd file and other schema types defined in the uBike.wsdl file.

Hint: You may have to right-click the APP-INF\lib folder and refresh the project within Workshop for it to recognize that the jar file is there.

All compilation errors should be cleared and you are now ready to test your end to end integrated application.

Click the index.jsp and searchForm.jsp links to view the source code for the uBike Web application to understand how it works. Pay particular attention to how index.jsp obtains the bikeList from the request and iterates through the list to display the uBike Web page. Also look at how searchForm.jsp simply passes the SKU parameter to the Search servlet so it can pass it in as a search parameter when calling the uBike Proxy Web service.

index.jsp:

searchForm.jsp:

Click the Search.java link to view the source code for the uBike Web application to understand how it works. Pay particular attention to the doPost() method where the actual Web service call is made to the OSB uBike Proxy Web service. Once the bikeList data has been returned by the Web service, it is placed in the request and the Search servlet redirects back to the index.jsp page to display the results.

In your uBike Tuxedo command shell, run tmadmin and run the psc command. Take note of the #Done for the SEARCHINVENTORY service.

Within Workshop, expand the uBikeWeb project to locate WebContent\index.jsp. Right-click index.jsp and select Run As > Run on Server. If you see a Run on Server dialog window, check the Always use this server when running this project box and click the Finish button.

When the uBike Web application runs the first time, the bikeList variable is not populated, so the index.jsp page redirects to the Search servlet to call the Tuxedo SEARCHINVENTORY service with no parameters, which returns a list of all bicycles in the inventory. Enter the psc command in your tmadmin command shell again to see that the #Done for the SEARCHINVENTORY service has incremented by 1.

You should see a screen similar to the following:

Select a SKU from the drop down list box on the index.jsp page that is displayed in your browser and click the Search button.

This causes the SKU to be passed to the Search servlet to pass as a parameter to the OSB Proxy service using a payload similar to the following:

<SEARCHINVENTORY>
<SKU>RJ4500</SKU>
</SEARCHINVENTORY>

This is sent to the uBike Business service and translated to an FML32 buffer by the Tuxedo Transport which sends the FML32 buffer with the SKU as input to the Tuxedo SEARCHINVENTORY service. The service will return a list of all bicycle records that match the SKU, and the response is sent back to the Search servlet as a bikeList data type. Your screen should look similar to the following: