Programming Guide

Oracle SALT SCA Programming

This chapter contains the following topics:

Overview

One important aspect of Service Component Architecture (SCA) is the introduction of a new programming model. As part of the Tuxedo architecture, SCA allows you to better blend high-output, high-availability and scalable applications in an SOA environment.

SCA components run on top of the Tuxedo infrastructure using ATMI binding. The ATMI binding implementation provides native Tuxedo communications between SCA components, as well as SCA components and Tuxedo programs (clients and servers).

In addition to the programming model, the Service Component Definition Language (SCDL) describes what components can perform in terms of interactions between each other, and instruct the framework to set-up necessary links (wires).

SCA Utilities

tuxscagen: Generates SCA, SCDL, and server-side interface files for Tuxedo services.
buildscaclient: Builds client processes that call SCA components.
buildscacomponent: Builds SCA components.
buildscaserver: Parses SCDL definitions and interfaces. It produces a Tuxedo-deployable server and elements.

For more information, see the Oracle SALT Command Reference.

SCA Client Programming

The runtime reference binding extension is the implementation of the client-side aspect of the SCA container. It encapsulates the necessary code used to call other services, SCA components, Tuxedo servers or even Web services, transparently from an SCA-based component.

SCA Client Programming Steps

Developing SCA client programs requires the following steps:

Setting Up the Client Directory Structure

You must define the applications physical representation. Strict SCA client applications are SCA component types. Listing 6-1shows the directory structure used to place SCA components in an application.

Listing 6-1 SCA Component Directory Structure

myApplication/ (top-level directory, designated by the APPDIR environment variable)
    root.composite (SCDL top-level composite, contains the list of components in this application)
    myClient/ (directory containing actual client component described in this section)
        myClient.composite (SCDL for the client component)

        myClient.cpp (client program source file)
        TuxService.h (interface of component called by client program)

Listing 6-2 shows an example of typical root.composite content.

Listing 6-2 root.composite Content

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
       name="simple.app">
       <component name="myClientComponent"> 
              <implementation.composite name="myClient"/> 
       </component> 
</composite>

The individual components are listed here. The implementation.composite@name parameter references the directory that contains the component named 'myClientComponent'. This last value is required at runtime. For more information, see Running the Client Application.

Developing the Client Application

Client programs are required to implement a call to a single API. This following call is required in order to set up the SCA runtime:

...

	CompositeContext theContext = CompositeContext::getCurrent();

...

Actual calls are based on an interface. This interface is usually developed along with the component being called. In the case of existing Tuxedo ATMI services, this interface can be generated by accessing the Tuxedo METADATA repository, For more information, see the Oracle SALT Administration Guide and tuxscagen in the Oracle SALT Reference Guide.

In the case of calling external Web services, an interface matching the service WSDL must be provided. For more information, see SCA ATMI Binding Data Type Mapping for the correspondence between WSDL types and C++ types.

Listing 6-3 shows an interface example.

Listing 6-3 Interface Example

#include <string> 
/** 
       *  Tuxedo service business interface 
       */ 
       class TuxService 
       { 
       public: 
       virtual std::string TOUPPER(const std::string inputString) = 0;
       };

In the interface shown in Listing 6-3, a single method TOUPPER is defined. It takes a single parameter of type std::string, and returns a value of type std::string. This interface needs to be located in its own .h file, and is referenced by the client program by including the .h file.

Listing 6-4 shows an example of a succession of calls required to perform an invocation.

Listing 6-4 Invocation Call Example

// SCA definitions
// These also include a Tuxedo-specific exception definition: ATMIBindingException
#include "tuxsca.h"
// Include interface
#include "TuxService.h"
...
       // A client program uses the CompositeContext class
       CompositeContext theContext = CompositeContext::getCurrent();
...
       // Locate Service
       TuxService* toupperService = 
              (TuxService *)theContext.locateService("TOUPPER"); 
...
       // Perform invocation
       const std::string result = toupperService->TOUPPER("somestring"); 
...

Notes:

The invocation itself is equivalent to making a local call (as if the class were in another file linked in the program itself).

Note:

For detailed code examples, see the SCA samples located in following directories:

UNIX samples: $TUXDIR/samples/salt/sca
Windows samples: %TUXDIR%\samples\salt\sca

Composing the SCDL Descriptor

The link between the local call and the actual component is made by defining a binding in the SCDL side-file. For example, Listing 6-4 shows a call to an existing Tuxedo ATMI service, the SCDL descriptor shown in Listing 6-5 should be used. This SCDL is contained in a file called <componentname>.composite.

Listing 6-5 SCDL Descriptor

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" 
          name="simpapp.client"> 
     <reference name="TOUPPER"> 
        <interface.cpp header="TuxService.h"/> 
        <binding.atmi requires="legacy"> 
           <inputBufferType target="TOUPPER">STRING</inputBufferType> 
           <outputBufferType target="TOUPPER">STRING</outputBufferType> 
        </binding.atmi>
    </reference>
</composite>

This composite file indicates that a client component may perform a call to the TOUPPER reference, and that this call is performed using the ATMI binding. In effect, this results in a tpcall() to the "TOUPPER" Tuxedo service. This Tuxedo service may be an actual existing Tuxedo ATMI service, or another SCA component exposed using the ATMI binding. For more information, see SCA Component Programming.

The inputBufferType and outputBufferType elements are used to determine the type of Tuxedo buffer used to exchange data. For more information, see SCA ATMI Binding Data Type Mapping and the ATMI Binding Element Reference for a description of all possible values that can be used in the binding.atmi element.

Building the Client Application (Using buildscaclient)

Once all the elements are in place, the client program can be built using the buildscaclient command. You must use the following steps:

Navigate to the directory containing the client source and SCDL composite files
Execute the following command: $ buildscaclient -c myClientComponent -s . -f myClient.cpp

This command verifies the SCDL code, and builds the following required elements:

a shared library (or DLL on Windows) containing generated proxy code
the client program itself

If no syntax or compilation error is found, the client program is ready to use.

Running the Client Application

To execute the client program, the following environment variables are required:

APPDIR - designates the application directory; in the case of SCA this typically contains the top-level SCDL composite.
SCA_COMPONENT - the default SCA component (the value 'myClientComponent' in the example shown in Listing 6-2). It tells the SCA runtime where to start when looking for services in the locateService() call.

Invoking Existing Tuxedo Services

Access to existing Tuxedo ATMI services from an SCA client program can be simplified using the examples shown in Listing 6-6, Listing 6-7, and Listing 6-8.

Note:

These examples can also be used for server-side SCA components.

Starting from a Tuxedo METADATA repository entry as shown in Listing 6-6, the tuxscagen command can be used to generate interface and SCDL.

Listing 6-6 SCA Components Calling an Existing Tuxedo Service

service=TestString
tuxservice=ECHO
servicetype=service
inbuf=STRING
outbuf=STRING

service=TestCarray
tuxservice=ECHO
servicetype=service
inbuf=CARRAY
outbuf=CARRAY

Listing 6-7 Generated Header

#ifndef ECHO_h #define ECHO_h #include <string> #include <tuxsca.h> class ECHO { public: virtual std::string TestString(const std::string arg) = 0; virtual std::string TestCarray(const struct carray_t * arg) = 0; }; #endif /* ECHO_h */

Listing 6-8 Generated SCDL Reference

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
name="ECHO">
  <reference name="ECHO">
    <interface.cpp header="ECHO.h"/>
    <binding.atmi requires="legacy">
      <serviceType target="TestString">RequestResponse</serviceType>
      <inputBufferType target="TestString">STRING</inputBufferType>
      <outputBufferType target="TestString">STRING</outputBufferType>
      <serviceType target="TestCarray">RequestResponse</serviceType>
      <inputBufferType target="TestCarray">CARRAY</inputBufferType>
      <outputBufferType target="TestCarray">CARRAY</outputBufferType>
    </binding.atmi>
  </reference>
</composite>

The steps used to invoke these services are then identical to the examples shown in Listing 6-6 through Listing 6-8.

Handling TPFAIL Data

When invoking a non-SCA Tuxedo ATMI service, that service may return in error but still send back data by using the tpreturn(TPFAIL, …) API. When this happens, an SCA client or component is interrupted by the ATMIBindingException type.

The data returned by the service, if present, can be obtained by using the ATMIBindingException.getData().

The example in Listing 6-9 corresponds to a binding.atmi definition as shown in Listing 6-10.

Listing 6-9 Invocation Interruption Example

...
        try {
          const char* result = toupperService->charToup("someInput");
        } catch (tuscany::sca::atmi::ATMIBindingException& abe) {
          // Returns a pointer to data corresponding to
          // mapping defined in <errorBufferType> element
          // in SCDL
          const char* *result = (const char **)abe.getData();
          if (abe.getData() == NULL) {
              // No data was returned
          } else {
              // Process data returned
              ...
          }
        } catch (tuscany::sca::ServiceInvocationException& sie) {
          // Other type of exception is returned
        }
...

Listing 6-10 /binding.atmi Definition

...
        <binding.atmi requires="legacy">
              <inputBufferType target="charToup">STRING</inputBufferType>
              <outputBufferType target="charToup">STRING</outputBufferType>
              <errorBufferType target="charToup">STRING</errorBufferType>
<binding.atmi/>
...

Other returned data types have to be cast to the corresponding type. For instance, an invocation returning a commonj::sdo::DataObjectPtr such that, in SCDL as shown in Listing 6-11.

Listing 6-11 SCDL

...
       <errorBufferType target="myMethod">FML32/myType</errorBufferType>
...

The results of ATMIBindingException.getData() is shown in Listing 6-12.

Listing 6-12 ATMIBindingException.getData() Results

...
              catch (tuscany::sca::atmi::ATMIBindingException& abe) {
              const commonj::sdo::DataObjectPtr *result = 
              (const commonj::sdo::DataObjectPtr *)abe.getData();
...

The rules for returning TPFAIL data to the calling application are as follows:

For each <errorBufferType>, a canonical type is defined, where <errorBufferType> is converted. When the <errorBufferType> is equal to the <outputBufferType>, the canonical type is the same C++ type that is returned on a successful service implementation.
When the <errorBufferType> is different from the <outputBufferType>, the canonical type is as follows:

For STRING buffers, a C++ char* or char[ ]datatype.
For MBSTRING buffers, a C++ wchar_t* or wchar_t[ ].
For CARRAY buffers, a C++ CARRAY_PTR.
For X_OCTET buffers, a C++ X_OCTET_PTR.
For XML buffers, a C++ XML_PTR.
For FML, FML32, VIEW, VIEW32, X_COMMON, and X_C_TYPE buffers, a C++ commonj::sdo::DataObjectPtr.

In each case, the value returned by getData() is a pointer to the type above.

For more conversion rules between Tuxedo buffer types and C++ data information, see SCA ATMI Binding Data Type Mapping.

SCA Component Programming

The SCA Component terminology designates SCA runtime artifacts that can be invoked by other SCA or non-SCA runtime components. In turn, these SCA Components can perform calls to other SCA or non-SCA components. This is as opposed to strict SCA clients which can only make calls to other SCA or non-SCA components, but cannot be invoked.

The SCA container in Oracle SALT offers the capability of hosting SCA components in an Oracle Tuxedo server environment. This allows you to take full advantage of proven Oracle Tuxedo qualities: reliability, scalability and performance.

Figure 6-1 summarizes SCA components and Tuxedo server mapping rules.

Figure 6-1

While SCA components using Tuxedo references do not require special processing, SCA components offering services must still be handled in a Tuxedo environment.

The mapping is as follows:

An SCA composite declaring one or more services with a <binding.atmi> definition maps to a single Tuxedo server advertising the same number of services as the SCA composite.
There can be more than one composite.
Composites can be nested.
Promotion handling:

a composite promoting a service contained in a nested component results in the promoted service being advertised as a Tuxedo service.
a service declared in a component, but not promoted, is not advertised.

The resulting Tuxedo server advertises as many services as there are binding.atmi sections in the SCDL definition
Interfaces may declare multiple methods. Each method is linked to a Tuxedo native service by way of the /binding.atmi/@map attribute. A method not declared via the /binding.atmi/@map attribute is not accessible through Tuxedo. The use of duplicate service names are detected at server generation time, so that Tuxedo service names to interface method mapping in a single Tuxedo server instance is 1:1.
A generated Tuxedo server acts as a proxy for SCA components. An instance of this generated server corresponds to an SCA composite as defined in the SCDL configuration. Such servers are deployed as necessary by the Tuxedo administrator.

SCA composites are deployed in a Tuxedo application by configuring instances of generated SCA servers in the UBBCONFIG file. Multiple instances are allowed. Multi-threading capabilities are also allowed and controllable using already-existing Tuxedo features.

SCA Component Programming Steps

The steps required for developing SCA component programs are as follows:

Setting Up the Component Directory Structure

The first step is to define the applications physical representation. Listing 6-13 shows the directory structure used to place SCA components in an application:

Listing 6-13 SCA Component Directory Structure

myApplication/ (top-level directory, designated by the APPDIR environment variable)
    root.composite (SCDL top-level composite, contains the list of components in this application)
    myComponent/ (directory containing actual component described in this section)
        myComponent.composite (SCDL for the component)
        myComponentImpl.cpp (component implementation source file)
        TuxService.h (interface of component being exposed)
        TuxServiceImpl.h (component implementation definitions)

Listing 6-14 shows typical root.composite content.

Listing 6-14 root.composite Content

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" 
       name="simple.app"> 
       <component name="myComponent"> 
              <implementation.composite name="myComponent"/> 
       </component> 
</composite>

Here the individual components are listed. The implementation.composite@name parameter references the directory that contains the 'myComponent' component.

Developing the Component Implementation

Components designed to be called by other components do not need to be aware of the SCA runtime. There are, however, limitations in terms of interface capabilities, such as:

C structures and C++ classes (other than std::string and commonj::sdo::DataObjectPtr) cannot be used as parameters or return values
Parameter arrays are not supported

For more information, see SCA ATMI Binding Data Type Mapping.

Listing 6-15 shows an example of an interface implemented for a client program.

Listing 6-15 Component Implementation Interface

#include <string> 
/** 
  *  Tuxedo service business interface 
  */ 
  class TuxService 
  { 
  public: 
       virtual std::string TOUPPER(const std::string inputString) = 0;
  };

The component implementation then generally consists of two source files (as shown Listing 6-16 and Listing 6-17 respectively):

component implementation definitions, contained in a <servicename>Impl.h file, and
component implementation, contained in a <servicename>Impl.cpp file

Listing 6-16 Example (TuxServiceImpl.h):

#include "TuxService.h" 
 
      /** 
       * TuxServiceImpl component implementation class 
       */ 
      class TuxServiceImpl:  public TuxService  
      { 
      public: 
       virtual std::string toupper(const std::string inputString); 
      };

Listing 6-17 Example (TuxServiceImpl.cpp):

#include "TuxServiceImpl.h"  
 #include "tuxsca.h" 
 
using namespace std; 
using namespace osoa::sca; 
 
/** 
* TuxServiceImpl component implementation 
*/ 
std::string TuxServiceImpl::toupper(const string inputString) 
{ 
    string result = inputString; 
        
    int len = inputString.size(); 

    for (int i = 0; i < len; i++) { 
       result[i] = std::toupper(inputString[i]); 
    } 
 
    return result; 
}

Additionally, a side-file (componentType), is required. It contains the necessary information for the SCA wrapper generation and possibly proxy code (if this component calls another component).

This componentType file (<componentname>Impl.componentType)is an SCDL file type. Listing 6-18 shows an example of a componentType file (TuxServiceImpl.componentType).

Listing 6-18 componentType File Example

<?xml version="1.0" encoding="UTF-8"?> 
 <componentType xmlns="http://www.osoa.org/xmlns/sca/1.0" >
       <service name="TuxService"> 
              <interface.cpp header="TuxService.h"/> 
       </service> 
 </componentType>

Composing the SCDL Descriptor

The link between the local implementation and the actual component is made by defining a binding in the SCDL side-file. For example, for the file type in Listing 6-18 to be exposed as a Tuxedo ATMI service, the SCDL below in Listing 6-19 should be used. This SCDL is contained in a file called <componentname>.composite (for example, myComponent.composite).

Listing 6-19 Example SCDL Descriptor

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" 
           name="simpapp.server"> 
    <service name="mySVC"> 
        <interface.cpp header="TuxService.h"/> 
        <binding.atmi requires="legacy"> 
           <map target="toupper">TUXSVC</map> 
           <inputBufferType target="toupper">STRING</inputBufferType> 
           <outputBufferType target="toupper">STRING</outputBufferType> 
        </binding.atmi> 
        <reference>TuxServiceComponent</reference> 
    </service> 

    <component name="TuxServiceComponent"> 
      <implementation.cpp library="TuxSvc" header="TuxServiceImpl.h"/> 
    </component> 
</composite>

This composite file indicates that the service, mySVC, can be invoked via the Tuxedo infrastructure. It further indicates that the toupper() method is advertised as the TUXSVC service in the Oracle Tuxedo system. Once initialized, another SCA component may now call this service, as well as a non-SCA Tuxedo ATMI client.

Compiling and Linking the Components

Once all the elements are in place, the component is built using the buildscacomponent command. The steps are as follows:

Navigate to the APPDIR directory. The component and side files should be in its own directory one level down
Execute the command: $ buildscacomponent -c myComponent -s . -f TuxServiceImpl.cpp

This command verifies the SCDL code, and builds the following required elements:

a shared library (or DLL on Windows) containing generated proxy code

Building the Tuxedo Server Host

In order for components to be supported in an Oracle Tuxedo environment, a host Tuxedo server must be built. This is achieved using the buildscaserver command.

For example: $ buildscaserver -c myComponent -s . -o mySCAServer

The mySCAServer is then ready to be used. It automatically locates the component(s) to be deployed according to the SCDL, and performs the appropriate Tuxedo/SCA associations.

Web Services Binding

The Web Services binding (binding.ws) leverages previously existing Oracle SALT capabilities by funneling Web service traffic through the GWWS gateway. SCA components are hosted in Tuxedo servers, and communications to and from those servers are performed using the GWWS gateway.

SCA clients using a Web services binding remain unchanged whether the server is running in a Tuxedo environment or a native Tuscany environment (for example, exposing the component using the Axis2 Web services binding).

Note:

HTTPS is not currently supported.

When SCA components are exposed using the Web services binding (binding.ws), tooling performs the generation of WSDF information, metadata entries and FML32 field definitions.

When SCDL code of SCA components to be hosted in a Tuxedo domain (for example, service elements) contains <binding.ws> elements, the buildscaserver command generates an WSDF entry in a file named service.wsdf where 'service' is the name of the service exposed. An accompanying service.mif and service.fml32 field table files are also generated, based on the contents of the WSDL interface associated with the Web service. You must compose a WSDL interface. If no WSDL interface is found, an error message is generated.

Web services accessed from a Tuxedo domain using a Web services binding (for example, reference elements found in SCDL) require the following manual configuration steps:

Convert the WSDL file into a WSDF entry by using the wsdlcvt tool. Simultaneously, a Service Metadata Entry file (.mif), and fml32 mapping file are generated.
Make sure that the UBB source has the TMMETADATA and GWWS servers configured
Import the WSDF file into the SALTDEPLOY file
Convert the SALTDEPLOY file into binary using wsloadcf.
Load the Service Metadata Entry file (.mif) into the Service Metadata Repository using the tmloadrepos command.
Boot (or re-boot) the GWWS process to initiate the new deployment.

The Web services binding reference extension initiates the Web services call.

Listing 6-20 shows an SCA component service exposed as a Web service.

Listing 6-20 Example SCA Component Service Exposed as a Web Service

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
       name="bigbank.account">
...
   <service name="AccountService">
       <interface.wsdl interface="http://www.bigbank.com/AccountService
              #wsdl.interface(AccountService)"/>
       <binding.ws/>
       <reference>AccountServiceComponent</reference>
   </service>

   <component name="AccountServiceComponent">
       <implementation.cpp 
                     library="Account" header="AccountServiceImpl.h"/>
       <reference name="accountDataService">
              AccountDataServiceComponent
       </reference>
   </component>  
...
</composite>

The steps required to expose the corresponding service are as follows:

Compose a WSDL interface matching the component interface.
Use buildscacomponent to build the application component runtime, similar to building a regular SCA component.
buildscaserver -w is used to convert SCDL code into a WSDF entry, and produce a deployable server (Tuxedo server + library + SCDL).

The service from the above SCDL creates a WSDF entry as shown in Listing 6-21.

Listing 6-21 WSDF Entry

<Definition>
       <WSBinding id="AccountService_binding">
              <ServiceGroup id="AccountService">
                     <Service name="TuxAccountService"/>
              </ServiceGroup>
       </WSBinding>
</Definition>

buildscaserver -w also constructs a Service Metadata Repository entry based by parsing the SCDL and interface. The interface needs to be in WSDL form, and manually-composed in this release.
Make sure that the UBB source has the TMMETADATA and GWWS servers configured
The Service Metadata Repository entry is loaded into the Service Metadata Repository using the tmloadrepos command.
The WSDF file must be imported into the SALTDEPLOY file and SALTDEPLOY converted into binary using wsloadcf.
The Service Metadata Entry file (.mif) is loaded into the Service Metadata Repository.
The Tuxedo server hosting the Web service is booted and made available.
The GWWS is rebooted to take into account the new deployment.

These steps are required, in addition to the SALTDEPLOY configuration, in order to set up the GWWS gateway for Web services processing (for example, configuration of GWInstance, Server Level Properties, etc.). When completed, Web service clients (SCA or other) have access to the Web service.

Listing 6-22 shows a reference accessing a Web service.

Listing 6-22 Example Reference Accessing a Web Service

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
       name="bigbank.account">
...
       <reference name="StockQuoteWebService">
              <interface.wsdl interface="http://www.webserviceX.NET/#
                            wsdl.interface(StockQuoteSoap)"/>
              <binding.ws endpoint="http://www.webserviceX.NET/#
                            wsdl.endpoint(StockQuote/StockQuoteSoap)"/>
       </reference>
...
</composite>

The steps required to access the Web service are as follows:

A WSDL file is necessary. This is usually published by the Web Service provider.
The WSDL file must be converted into a WSDF entry using the wsdlcvt tool. At the same time a Service Metadata Entry file (.mif), and fml32 mapping file is generated.
The WSDF file must be imported into the SALTDEPLOY file and SALTDEPLOY converted into binary using wsloadcf.
The Service Metadata Entry file (.mif) is loaded into the Service Metadata Repository using the tmloadrepos command.
The GWWS process is rebooted to take into account the new deployment.

The process is the same, whether the client is stand-alone SCA program or an SCA component (already a server) referencing another SCA component via the Web service binding.

SCA Remote Protocol Support

Tuxedo SCA invocation support the following remote protocols:

/WS
/Domains
Java ATMI (JATMI) Binding

/WS

SCA invocations made using the SCA container have the capability of being performed using the Tuxedo WorkStation protocol (/WS). This is accomplished by specifying the value WorkStation (not abbreviated so as not to confuse it with WebServices) in the <remoteAccess> element of the <binding.atmi> element.

Only reference-type invocations are be available in this mode. Service-type invocations may be performed using the /WS transparently (there is no difference in behavior or configuration, and setting the <remoteAccess> element to WorkStation for an SCA service has no effect).

Since native and WorkStation libraries cannot be mixed within the same process, client processes must be built differently depending on the type of remote access chosen.

Note: When using the value propagatesTransaction in /binding.atmi/@requires, the behavior of the ATMI binding does not actually perform any transaction propagation. It actually starts a transaction, since the use of this protocol is reserved for client-side access to Tuxedo (SCA or non-SCA) applications only. For more information, see SCA ATMI Binding.

/Domains

SCA invocations made using the SCA container have the capability of being performed using the Tuxedo /Domains protocol. No additional configurations are necessary on <binding.atmi> declarations in SCDL files.

Note:

/Domains interoperability configuration is controlled by the Tuxedo administrator.

Note:

The SCA service name configured for Tuxedo /Domains is as follows:

SCA -> SCA mode - /binding.atmi/service/@name attribute followed by a '/' and method name
Legacy mode (SCA -> Tux interop mode) - /binding.atmi/service/@name attribute.

Note:

For more information, see Tuxedo SCA Interoperability.

Java ATMI (JATMI) Binding

Java ATMI (JATMI) binding allows SCA clients written in Java to call Tuxedo services or SCA components. It provides one-way invocation of Tuxedo services based on the Tuxedo WorkStation protocol (/WS). The invocation is for outbound communication only from a Java environment to Tuxedo application acting as a server. Apart from a composite file for SCDL binding declarations, no external configuration is necessary. The service name, workstation address and authentication data are provided in the binding declaration.

Note:

Both SSL and LLE are not currently supported.

Most of the Tuxedo CPP ATMI binding elements support JATMI binding and have the same usage. However, due to different underlying technology and running environment differences, some elements are not supported and some that are supported but have different element names.

The following Tuxedo CPP ATMI binding elements are not supported:

binding.atmi/tuxconfig
binding.atmi/fieldTablesLocation
binding.atmi/fieldTablesLocation32
binding.atmi/viewFilesLocation
binding.atmi/viewFilesLocation32
binding.atmi/transaction

The following Tuxedo CPP ATMI binding workStationParameters elements are not supported:

binding.atmi/workStationParameters/secPrincipalName
binding.atmi/workStationParameters/secPrincipalLocation
binding.atmi/workStationParameters/secPrincipalPassId
binding.atmi/workStationParameters/encryptBits

The following Tuxedo CPP ATMI binding element is supported in a limited fashion.

binding.atmi/remoteAccess

Note: Only the value "WorkStation" is allowed. If not specified, "WorkStation" is assumed.

All the classes in the elements mentioned below must be specified in Java CLASSPATH:

binding.atmi/fieldTables - Specifies a comma-separated list of Java classes that are extended from the weblogic.wtc.jatmi.TypedFML base class.
binding.atmi/fieldTables32 - Specifies a comma-separated list of Java classes that are extended from the weblogic.wtc.jatmi.TypedFML32 base class.
binding.atmi/viewFiles - Specifies a comma-separated list of Java classes that are extended from the weblogic.wtc.jatmi.TypedView base class. These derived classes usually are generated from a Tuxedo VIEW file using the weblogic.wtc.jatmi.viewj compiler. These also includes derived from weblogic.wtc.jatmi.TypedXCType and weblogic.wtc.jatmi.TypedXCommon.

For more information, see How to Use the viewj Compiler in the Tuxedo WebLogic Tuxedo Connector Programmer's Guide.

binding.atmi/viewFiles32 - Specifies a comma-separated list of Java classes that are extended from the webogic.wtc.jatmi.TypedView32 base class. These derived classes usually are aslo generated from a Tuxedo VIEW file using the weblogic.wtc.jatmi.viewj32 compiler.

Listing 6-23 shows an example of composite file for binding declaration of a Tuxedo service named "ECHO“.

Listing 6-23 ECHO Composite File

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" xmlns:f="binding-atmi.xsd"
name="ECHO">
    <reference name="ECHO" promote="EchoComponent/ECHO">
       <interface.java interface="com.abc.sca.jclient.Echo" />
       <f:binding.atmi requires="legacy">
       <f:inputBufferType target="echoStr">STRING</f:inputBufferType>
         <f:outputBufferType target="echoStr">STRING</f:outputBufferType>

           <f:errorBufferType target="echoStr">STRING</f:errorBufferType>

            <f:workStationParameters>
<f:networkAddress>//STRIATUM:9999,//STRIATUM:1881</f:networkAddr
ess>
            </f:workStationParameters>
            <f:remoteAccess>WorkStation</f:remoteAccess>
        </f:binding.atmi>
    </reference>
    <component name="EchoComponent">
      <implementation.java class="com.abc.sca.jclient.EchoComponentImpl" />
    </component>
</component>

Listing 6-24 shows the interface for the example mentioned above.

Listing 6-24 ECHO Interface

package com.abc.sca.jclient;

import com.oracle.jatmi.AtmiBindingException;

public interface Echo {
        String echoStr(String requestString) throws AtmiBindingException;

Listing 6-25 shows an example of an SCA client implementation.

Listing 6-25 SCA Client Implementation

package com.abc.sca.jclient;

import org.osoa.sca.annotations.Constructor;
import org.osoa.sca.annotations.Reference;
import com.oracle.jatmi.AtmiBindingException;

/**
* A simple client component that uses a reference with a JATMI binding.
*/
public class EchoComponentImpl implements Echo {

       private Echo echoReference;

        @Constructor
       public EchoComponentImpl(@Reference(name = "ECHO", required = true) Echo
 echoReference) {
                this.echoReference = echoReference;
       }

        public String echoStr(String requestString) throws AtmiBindingException {
                return echoReference.echoStr(requestString);
        }
}

Tuxedo SCA Interoperability

Existing Tuxedo service interoperability is performed by using the /binding.atmi/@requires attribute with the legacy value. When a legacy value is specified, invocations are performed using the following behavior:

If a <map> element is present in either a <reference> or a <service>, that value is used to determine which Tuxedo service is associated with the specified method name to call or advertise.

Otherwise:

In a <reference> element: the value specified in the /reference/@name element is used to perform the Tuxedo call, with semantics according to the interface method used.
In a <service> element: the Tuxedo service specified in the /binding.atmi/map element is advertised, and mapped to the method specified in the /binding.atmi/map/@target attribute.

Additionally, the /binding.atmi/@requires attribute is used to internally control data mapping, such that FML32 or FML field tables are not required.

Note: When not specified, communications are assumed to have SCA -> SCA semantics where the actual Tuxedo service name is constructed from /service/@name or /reference/@name and actual method name (see the pseudo schema shown Listing 6-26).

SCA Transactions

The ATMI binding schema supports SCA transaction policies by using the /binding.atmi/@requires attribute and three transaction values. These transaction values specify the transactional behavior that the binding extension follows when ATMI binding is used (see the pseudo schema shown Listing 6-26).

The transaction values are as follows:

not specified (no value)

All transactional behavior is left up to the Tuxedo configuration. If the Tuxedo configuration supports transactions, then one may be propagated if it exists. If the Tuxedo configuration does not support transactions and one exists then an error will occur. However, a transaction is not started if one does not already exist.

suspendsTransaction

When specified, the transaction context will not be propagated to the service called. For a <service>, the transaction, if present, will be automatically suspended before invoking the application code, and resumed afterwards, regardless of the outcome of the invocation. For a <reference>, equivalent to making a tpcall() with the TPNOTRAN flag.

propagatesTransaction

Only applicable to <reference> elements, ignored for <service> elements. Starts a new transaction if one does not already exist, otherwise participate in existing transaction. Such a behavior can be obtained in a component or composite <service> by configuring it AUTOTRAN in the UBBCONFIG. An error will be generated if a Tuxedo server host the SCA component implementation and it is not configured in a transactional group in the UBBCONFIG.

SCA Security

SCA references pass credentials using the <authentication> element of the binding.atmi SCDL element.

SCA services can be ACL protected by referencing their internal name: /binding.atmi/service/@name attribute followed by a '/' and method name in SCA -> SCA mode, /binding.atmi/service/@name attribute in legacy mode (SCA -> Tux interop mode).

SCA ATMI Binding

Tuxedo communications are configured in SCDL using a <binding.atmi> element. This allows you to specify configuration elements specific to the ATMI transport, such as the location of the TUXCONFIG file, the native Tuxedo buffer types used, Tuxedo-specific authentication or /WS (WorkStation) configuration elements, etc.

Listing 6-26 shows a summary of the <binding.atmi> element.

Note: ? refers to a parameter that can be specified 0 or 1 times.

Note: * refers to a parameter that can be specified 0 or more times.

For more information, see Appendix F: Oracle SALT SCA ATMI Binding Reference in the Oracle SALT Reference Guide.

Listing 6-26 ATMI Binding Pseudoschema

<binding.atmi requires="transactionalintent legacyintent"?>
       <tuxconfig>...</tuxconfig>?
       <map target="name">...</map>*
       <serviceType target="name">...</serviceType>*
       <inputBufferType target="name">...</inputBufferType>*
       <outputBufferType target="name">...</outputBufferType>*
       <errorBufferType target="name">...</errorBufferType>*
       <workStationParameters>?
              <networkAddress>...</networkAddress>?
              <secPrincipalName>...</secPrincipalName>?
              <secPrincipalLocation>...</secPrincipalLocation>?
              <secPrincipalPassId>...</secPrincipalPassId>?
              <encryptBits>...</encryptBits>?
       </workStationParameters>
       <authentication>?
              <userName>...</userName>?
              <clientName>...</clientName>?
              <groupName>...</groupName>?
              <passwordIdentifier>...</passwordIdentifier>?
              <userPasswordIdentifier>...
                                          </userPasswordIdentifier>?
       </authentication>
       <fieldTablesLocation>...</fieldTablesLocation>?
       <fieldTables>...</fieldTables>?
       <fieldTablesLocation32>...</fieldTablesLocation32>?
       <fieldTables32>...</fieldTables32>?
       <viewFilesLocation>...</viewFilesLocation>?
       <viewFiles>...</viewFiles>?
       <viewFilesLocation32>...</viewFilesLocation32>?
       <viewFiles32>...</viewFiles32>?
       <remoteAccess>...</remoteAccess>?
       <transaction timeout="xsd:long"/>?
</binding.atmi>

SCA ATMI Binding Data Type Mapping

Using the ATMI binding leverages the Tuxedo infrastructure. As such, data exchanged between SCA components, or Tuxedo clients/services and SCA clients/components is performed using Tuxedo typed buffers. The tables below summarize the correspondence between native types and Tuxedo buffers/types, as well as SOAP types when applicable.

In the example shown in Listing 6-27, implementations send and receive a Tuxedo STRING buffer. To the software (binding and reference extension implementations), the determination of the actual Tuxedo buffer to be used is provided by the contents of the /binding.atmi/inputBufferType, /binding.atmi/outputBufferType, or /binding.atmi/errorBufferType elements in the SCDL configuration, and the type of buffer returned (or sent) by a server (or client). It does not matter whether client or server is an ATMI program or an SCA component.

Notice that the Tuxedo simpapp service has its own namespace within namespace services. A C++ method toupper is associated with this service.

Listing 6-27 C++ Interface Example

#include <string>
namespace services
{
    namespace simpapp
    {
        /**
         *  business interface
         */
           class ToupperService
        {
        public:

        virtual std::string
           toupper(const std::string inputString) = 0;
        };

    } // End simpapp
} // End services

The following data type mapping rules apply:

Simple Tuxedo Buffer Data Mapping

The following are considered to be simple Tuxedo buffers:

STRING
CARRAY (and X_OCTET)
MBSTRING
XML

Table 6-1 lists simple Tuxedo buffer types that are mapped to SCA binding.

Table 6-1 Simple Tuxedo Buffer Type Data Mapping
C++ or STL Type	Java Type	Tuxedo Buffer Type	Notes
`char*`, `char array` or `std::string`	`java.lang.String`	`STRING`
`CARRAY_T`	`byte[] or java.lang.Byte[]`	`CARRAY`
`X_OCTET_T`	`byte[] or java.lang.Byte[]`	`X_OCTET`
`XML_T`	`byte[] or java.lang.Byte[]`	`XML`	This type is passed as a C++ array within the data element of struct XML or as an array of java bytes. It is transformed to SDO.
`wchar_t *` or `wchar_t array`	`N/A`	`MBSTRING`	See Multibyte String Data Mapping
`std::wstring`	`java.lang.String`	`MBSTRING`	See Multibyte String Data Mapping

When a service called by an SCA client returns successfully, a pointer to the service return data is passed back to the Proxy stub generated by buildscaclient. The Proxy stub then de-references this pointer and returns the data to the application.

Table 6-1 can be interpreted as follows:

When the reference or service binding extension runtime sees a Tuxedo STRING buffer, it looks for either a char*, char array, std::string parameter or return type (depending on the direction). If a different type is found, an exception is thrown with a message explaining what happened.
When the reference or service binding extension runtime sees a char* (for example) as a single parameter or return type, it looks for STRING as the buffer type in the binding.atmi element. If a different Tuxedo buffer type is found, an exception is thrown with a message explaining what happened.

Multibyte String Data Mapping

Tuxedo uses multibyte strings to represent multibyte character data, with encoding names based on iconv as defined by Tuxedo. C++ uses a wstring, wchar_t*, or wchar_t[] data type to represent multibyte character data, with encoding names as defined by the C++ library.

Tuxedo and C++ sometimes use different names to represent a particular multibyte encoding. Mapping between Tuxedo encoding names and C++ encoding names is as follows:

Receiving a Multibyte String Buffer

When an SCA client or server receives an MBSTRING buffer or an FML32 buffer with a FLD_MBSTRING field, it considers the encoding for that multibyte string to be the first locale from the following cases:

Locale associated with the FLD_MBSTRING field, if present.

Note:

For more information, see Table 6-2.

Locale associated with the MBSTRING or FML32 buffer.
Locale set in the environment of the SCA client or server.

If case 1 or 2 is matched, Tuxedo invokes the setlocale() function for locale type LC_CTYPE with the locale for the received buffer. If setlocale() fails (indicating there is no such locale) and an alternate name has been associated with this locale in the optional $TUXDIR/locale/setlocale_alias file, Tuxedo attempts to set the LC_CTYPE locale to the alternate locale.

The $TUXDIR/locale/setlocale_alias file may be optionally created by the Tuxedo administrator. If present, it contains a mapping of Tuxedo MBSTRING codeset names to an equivalent operating system locale accepted by the setlocale() function.

Lines consist of a Tuxedo MBSTRING codeset name followed by whitespace and an OS locale name. Only the first line in the file corresponding to a particular MBSTRING codeset name are considered. Comment lines begin with #.

The $TUXDIR/locale/setlocale_alias file is used by the SALT SCA software when converting MBSTRING data into C++ wstring or wchar_t[] data. If setlocale() fails when using the Tuxedo MBSTRING codeset name, then the SALT SCA software attempts to use the alias name, if present. For example, if the file contains a line 'GB2312 zh_CN.GB2312' then if setlocale(LC_CTYPE, 'GB2312') fails, the SALT SCA software attempts setlocale(LC_CTYPE, 'zh_CN.GB2312').

Sending a Multibyte String Buffer

When an SCA client or server converts a wstring, wchar_t[], or wchar_t* to an MBSTRING buffer or a FLD_MBSTRING field, it uses the TPMBENC environment variable value as the locale to set when converting from C++ wide characters to a multibyte string. If the operating system does not recognize this locale, Tuxedo uses the alternate locale from the $TUXDIR/locale/setlocale_alias file, if any.

Note: In SALT 10g Release 3 (10.3), it is possible to transmit multibyte data retrieved from a Tuxedo MBSTRING buffer, an FML32 FLD_MBSTRING field, or a VIEW32 mbstring field. It is also possible to transmit multibyte data entered using the SDO setString() method.

Note: However, it is not possible to enter multibyte characters directly into an XML document and transmit this data via SALT 10g Release 3 (10.3). This is because multibyte characters entered in XML documents are transcoded into multibyte strings, and SDO uses wchar_t arrays to represent multibyte characters.

Complex Return Type Mapping

The following C++ built-in types (used as return types) are considered complex and automatically encapsulated in an FML/FML32 buffer as a single generic field following the complex buffer mapping rules described in Complex Tuxedo Buffer Data Mapping. This mechanism addresses the need for returning types where a corresponding Tuxedo buffer can not be used.

Note: Interfaces returning any of the built-in types assume that FML/FML32 is the output buffer type. The name of this generic field is TUX_RTNdatatype based on the type of data being returned. TUX_RTNdatatype fields are defined in the Usysflds.h/Usysfl32.h and Usysflds/Usysfl32 shipped with Tuxedo.

bool : maps to TUX_RTNCHAR field
char: maps to TUX_RTNCHAR field
signed char: maps to TUX_RTNCHAR field
unsigned char: maps to TUX_RTNCHAR field
short: maps to TUX_RTNSHORT field
unsigned short: maps to TUX_RTNSHORT field
int: maps to TUX_RTNLONG field
unsigned int: maps to TUX_RTNLONG field
long: maps to TUX_RTNLONG field
unsigned long: maps to TUX_RTNLONG field
long long: (maps to TUX_RTNLONG field
unsigned long long: maps to TUX_RTNLONG field
float: maps to TUX_RTNFLOAT field
double: maps to TUX_RTNDOUBLE field
long double: maps to TUX_RTNDOUBLE field

Complex Tuxedo Buffer Data Mapping

The following are considered to be complex Tuxedo buffers:

FML
FML32
VIEW (and X_* equivalents)
VIEW32

Table 6-2 lists the complex Tuxedo buffer types that are mapped to SCA binding.

For FML and FML32 buffers, parameter names in interfaces must correspond to field names, and follow the restrictions that apply to Tuxedo fields (length, characters allowed). When these interfaces are generated from metadata using tuxscagen(1), the generated code contains the properly formatted parameter names.

If an application manually develops interfaces without parameter names, manually develops interfaces that are otherwise incorrect, or makes incompatible changes to SALT generated interfaces, then incorrect results are likely to occur.

VIEW (and X_* equivalents) and VIEW32 buffers require the use of SDO DataObject wrappers.

Listing 6-28 shows an interface example. The associated field definitions (following the interface) must be present in the process environment.

Table 6-2 Complex Tuxedo Buffer Type Data Mapping
C++, STL, or SDO type	Java Type	Tuxedo field type	Tuxedo view type	Notes
`bool`	`boolean or java.lang.Boolean`	`FLD_CHAR`	`char`	Maps to 'T' or 'F'. (This matches the mapping used elsewhere in SALT.)
`char, signed char, or unsigned char`	`byte or java.lang.Byte`	`FLD_CHAR`	`char`
`short or unsigned short`	`short or java.lang.Short`	`FLD_SHORT`	`short`	An unsigned short is cast to a short before being converted to `FLD_SHORT` or `short`.
`int or unsigned int`	`int or java.lang.Integer`	`FLD_LONG`	`int`	An unsigned `int` being converted to FML or FML32 is cast to a long before being converted to `FLD_LONG` or `long`. An unsigned `int` being converted to a VIEW or VIEW32 member is cast to an `int`.
`long or unsigned long`	`long or java.lang.Long`	`FLD_LONG`	`long`	An exception is thrown if the value of a `64-bit long` does not fit into a `FLD_LONG` or `long` on a 32-bit platform. An unsigned long is cast to long before being converted to `FLD_LONG` or `long.`
`long long or unsigned long long`	`N/A`	`FLD_LONG`	`long`	An exception is thrown if the data value does not fit within a `FLD_LONG` or `long`. An unsigned `long long` is cast to `long long` before being converted to `FLD_LONG` or `long`.
`float`	`float or java.lang.Float`	`FLD_FLOAT`	`float`
`double`	`double or java.lang.Double`	`FLD_DOUBLE`	`double`
long double	N/A	FLD_DOUBLE	double
`char* or char array`	`N/A`	`FLD_STRING`	`string`
`std::string`	`java.lang.String`	`FLD_STRING`	`string`
`struct CARRAY`	`class CARRAY`	`FLD_CARRAY`	`carray`	Will map externally following GWWS rules. This departs from the OSOA spec. (which does not support them), and should be considered an improvement.
`Bytes`	`N/A`	`FLD_CARRAY`	`Carray`	This mapping is used when part of a `DataObject`
`wchar_t* or wchar_t array`	`N/A`	`FLD_MBSTRING (FML32 only)`	`mbstring (VIEW32 only)`	(Java char is Unicode and can range from `-32768` to `+32767`.) See also Multibyte String Data Mapping
`std::wstring`	`java.lang.String`	`FLD_MBSTRING (FML32 only)`	`mbstring (VIEW32 only)`	See also Multibyte String Data Mapping
`commonj::sdo::DataObjectPtr`	`TypedFML32`	`FLD_FML32 (FML32 only)`	`N/A`	Generate a data transformation exception, which is translated to an `ATMIBindingException` before being returned to the application, when: Attempting to add such a field in a Tuxedo buffer other than FML32 The data object is not typed (i.e., there is no corresponding schema describing it). See also Multibyte String Data Mapping
`commonj::sdo::DataObjectPtr`	`TypedView32`	`FLD_VIEW32 (FML32 only)`	`N/A`	See also Multibyte String Data Mapping

Listing 6-28 Interface Example

...
int myService(int param1, float param2); ...
Field table definitions
#name         number type          flag comment
#---------------------------------------------------------
param1 20     int           -     Parameter 1
param2 30     float         -     Parameter 2
...

SDO Mapping

C++ method prototypes that use commonj::sdo::DataObjectPtr objects as parameter or return types are mapped to an FML, FML32, VIEW, or VIEW32 buffer.

You must provide an XML schema that describes the SDO object. The schema is made available to the service or reference extension runtime by placing the schema file (.xsd file) in the same location as the SCDL composite file that contains the reference or service definition affected. The schema will be used internally to associate element names and field names.

Note: When using view or view32, a schema type (for example, complexType) which name matches the view or view32 used is required.

For more information, see mkfldfromschema and mkfld32fromschema in the SALT 10g Release 3 (10.3) Reference Guide.

For example, a C++ method prototype defined in a header such as:

long myMethod(commonj::sdo::DataObjectPtr data);

Listing 6-29 shows the associated schema.

Listing 6-29 Schema

<xsd:schema xmlns:xsd=http://www.w3.org/2001/XMLSchema
     xmlns="http://www.example.com/myExample"
     targetNamespace="http://www.example.com/myExample">

     <xsd:element name="bike" type="BikeType"/>
     <xsd:element name="comment" type="xsd:string"/>

     <xsd:complexType name="BikeType">
         <xsd:sequence>
             <xsd:element name="serialNO" type="xsd:string"/>
             <xsd:element name="name" type="xsd:string"/>
             <xsd:element name="type"  type="xsd:string"/>
             <xsd:element name="price"  type="xsd:float"/>
         </xsd:sequence>
     </xsd:complexType>
</xsd:schema>

Table 6-3 shows the generated field table.

Table 6-3 Generated Field Tables
NAME	NUMBER	TYPE	FLAG
`bike`	`20`	`fml32`	`-`
`comment`	`30`	`string`	`-`
`serialNO`	`40`	`string`	`-`
`name`	`50`	`string`	`-`
`type`	`60`	`string`	`-`
`price`	`70`	`float`	`-`

The following restrictions in XML schemas apply:

Attributes cannot be specified and are ignored if specified
Values in restrictions are ignored (their meaning is application-related), only the field name and type are generated
When using XML schema types, only signed integral types will be supported.
See "SDO C++ Specification" for a list of available SDO primitive types.

Programming Guide

Oracle SALT SCA Programming

Overview

SCA Utilities

SCA Client Programming

SCA Client Programming Steps

Setting Up the Client Directory Structure

Developing the Client Application

Composing the SCDL Descriptor

Building the Client Application (Using buildscaclient)

Running the Client Application

Invoking Existing Tuxedo Services

Handling TPFAIL Data

SCA Component Programming

SCA Component Programming Steps

Setting Up the Component Directory Structure

Developing the Component Implementation

Composing the SCDL Descriptor

Compiling and Linking the Components

Building the Tuxedo Server Host

Web Services Binding

SCA Remote Protocol Support

/WS

/Domains

Java ATMI (JATMI) Binding

Tuxedo SCA Interoperability

SCA Transactions

SCA Security

SCA ATMI Binding

SCA ATMI Binding Data Type Mapping

Simple Tuxedo Buffer Data Mapping

Multibyte String Data Mapping

Receiving a Multibyte String Buffer

Sending a Multibyte String Buffer

Complex Return Type Mapping

Complex Tuxedo Buffer Data Mapping

SDO Mapping

See Also