Administering Oracle Tuxedo SCA Components

This chapter contains the following sections:

•	Oracle SALT SCA Deployment Model

•	Configuring Oracle Tuxedo SCA Components

•	Administering Oracle Tuxedo SCA Components

Oracle Tuxedo SCA Deployment Model

An SCA composite is typically described in an associated configuration file, the file name ends with ".composite". This file uses an XML-based format call the Service Component Definition Language (SCDL) to describe the components this composite contains and specify how they related to one another. Deploying Oracle Tuxedo SCA requires at least one root composite file that is located in $APPDIR.

There are two configuration file types:

•	SCA Composite Configuration File (.composite)

•	SCA Component Configuration File (.componentType)

There can be one or more components configured in the root composite file, and each of these components has its own .composite and .componentType file residing in its own subdirectory.

SCA Composite Configuration File

There can be zero or more component elements within a composite. The root composite files must be stored in $APPDIR in a server environment.

Listing 1‑1shows an example of a root composite which contains two components:

Listing 1‑1 Root Composite with Two Components

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" name="ECHO.app">
       <component name="ECHO">
              <implementation.composite name="ECHO" />
       </component>
       <component name="TOUPPER">
              <implementation.composite name="TOUPPER" />
       </component>
</composite>

 

Based on the configuration in Listing 1‑1, Listing 1‑2 shows the implied the directory hierarchy.

Listing 1‑2 SCA Composite Directory Hierarchy

$APPDIR/ECHO.app.composite
$APPDIR/ECHO
$APPDIR/ECHO/ECHO.composite
$APPDIR/ECHO/ECHO.componentType
$APPDIR/TOUPPER
$APPDIR/TOUPPER/TOUPPER.composite
$APPDIR/TOUPPER/TOUPPER.componentType

 

This example is a typical server configuration. The Oracle Tuxedo SCA client also has a similar application topology meaning that the client application is located in a subdirectory of the root composite file. Listing 1‑3 lists the directory structure for a client named EchoClient that uses the ECHO1 service provided by ECHO.

Listing 1‑3 Directory Structure

$APPDIR/root.composite
$APPDIR/EchoClient/EchoClient.composite
$APPDIR/EchoClient.composite
$APPDIR/EchoClient/EchoClient.dll
$APPDIR/EchoClient/EchoClient.exe

 

Note:

One slight difference between an SCA server environment and an SCA client environment is that there is no need to have a component configuration file in the client environment.

SCA Component Configuration File

Components are the basic elements of business function in an SCA assembly, which are combined into complete business solutions by SCA composites. Components are configured instances of implementations. Components provide and consume services. More than one component can use and configure the same implementation, where each component configures the implementation differently.

Components are declared as sub-elements of a composite in an xxx.composite file. A component is represented by a component element that is a child of the composite element. Using the composite from Listing 1‑1, the 2 components (ECHO and TOUPPER), contains specific information. For the ECHO service ($APPDIR/ECHO/ECHO.composite), the ECHO.composite information is shown in Listing 1‑4.

Listing 1‑4 ECHO.composite

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
       name="ECHO">
       <service name="ECHO">
              <interface.cpp header="ECHO.h" />
              <binding.atmi requires="legacy">
                     <map target="EchoString1">ECHO1</map>
                     <map target="EchoString2">ECHO2</map>
              </binding.atmi>
              <reference>EchoServiceComponent</reference>
       </service>
       <component name="EchoServiceComponent">
              <implementation.cpp library="ECHO" header="ECHOImpl.h" />
       </component>
</composite>

 

The ECHO service provides two Oracle Tuxedo services: ECHO1 and ECHO2. ECHO1 executes CPP function “EchoString1”. ECHO2 executes CPP function "EchoString2". The existence of $APPDIR/ECHO/ECHOImpl.componentType and $APPDIR/ECHO/ECHO.so. are implied. Listing 1‑5 shows information that may be contained in ECHOImpl.componentType.

Note:

On some Unix systems the suffix is .so.71 or .sl.

ECHO.so (or ECHO.dll Windows), is the shared library that contains the actual implementation of EchoString1 and EchoString2 and is loaded into memory when the service is initialized. ECHO1 and ECHO2 are dynamically advertised at server initialization. For example, if EchoServer is the Oracle Tuxedo server that provides these two services, the Oracle Tuxedo UBBCONFIG file should contain information as shown in Listing 1‑6.

Listing 1‑5 ECHOImpl.componentType

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

 

Listing 1‑6 UBBCONFIG File Example

...
*SERVERS
DEFAULT:
       CLOPT="-A"
EchoServer SRVGRP=GROUP1 SRVID=1001
...

 

For the TOUPPER service, the existence of $APPDIR/TOUPPER/TOUPPER.composite is also implied by the ECHO.app.composite file. Listing 1‑7 shows information that may be contained in TOUPPER.composite file.

Listing 1‑7 TOUPPER.composite file Example

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
       name="TOUPPER">
       <service name="TOUPPER">
              <interface.cpp header="TOUPPER.h" />
                     <binding.atmi requires="legacy">
                            <map target="UpperString1">TOUPPER1</map>
                            <map target="UpperString2">TOUPPER2</map>
                     </binding.atmi>
              <reference>ToupperServiceComponent</reference>
       </service>

       <component name="ToupperServiceComponent">
              <implementation.cpp library="TOUPPER" header="TOUPPERImpl.h" />
       </component>

</composite>

 

This composite file also implies the existence of $APPDIR/TOUPPER/TOUPPERImpl.componentType and $APPDIR/TOUPPER/TOUPPER.so.

Note:

Oracle Tuxedo SCA only supports "cpp" implementation types.

Configuring Oracle Tuxedo SCA Components

Configuring Oracle Tuxedo SCA components comprises the following:

•	Configuring an SCA ATMI Client

•	Configuring an SCA Workstation Client

•	Configuring an SCA Workstation Client

•	The above SCA component are hosted in an Oracle Tuxedo server built using buildscaserver with the -w option (for Web services) and named WSServer

•	The above SCA component are hosted in an Oracle Tuxedo server built using buildscaserver with the -w option (for Web services) and named WSServer

•	Configuring an SCA Web Service Server

•	Configuring SCA Client Security

Configuring an SCA ATMI Client

The SCA ATMI client is a native Oracle Tuxedo client that is written using the SCA paradigm and built using the buildscaclient utility. The client executable must be in a subdirectory of a directory that contains the root.composite file.

Note:

The APPDIR environment variable must point to the root.composite file directory.

Listing 1‑8 shows the client application root composite file $APPDIR/root.composite.

Listing 1‑8 Client Application Root Composite File

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" name="testApp">
       <component name="testStringClientComp">
              <implementation.composite name="ECHO"/>
       </component>
</composite>

 

The $APPDIR/ECHO directory contains the ECHO application. The directory name, "ECHO", must match the name specified in <implementation.composite name="ECHO"/>. Listing 1‑9 shows the client application composite file.

Listing 1‑9 Client Application Composite File

<?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">
        <tuxconfig>/tux/application/ECHOServer/tuxconfig</tuxconfig>
          <inputBufferType target="TestString">STRING</inputBufferType>
          <outputBufferType target="TestString">STRING</outputBufferType>
          <errorBufferType target="TestString">STRING</errorBufferType>
       <binding.atmi>
  </reference>
</composite>

 

The client dynamic link library for this client application is also contained in this directory. For example, using the example in Listing 1‑9, the $APPDIR/ECHO/ECHO.so shared object exists in the ECHO directory. The target "TestStr" is used to group buffer types together.

The client executable also exists in this directory. There is no naming convention associated with a client application. This client ECHO application could very well contain "doEchoClient" in the ECHO application directory. For example: $APPDIR/ECHO/doEchoClient.

Note:

You must set SCA_COMPONENT. See Listing 1‑9, SCA_COMPONENT=testStringClientComp.

Configuring an SCA JATMI Client

The JATMI client application configuration composite file is part of the Java .jar file. The JATMI client composite file is not part of any package and is located in the base of the .jar file. When client application is invoked, SCA Java runtime loads the composite file. No special setup is required.

Note:

The client application .jar file must be included in the CLASSPATH. The following .jar files should also be part of CLASSPATH:

•	binding-jatmi-extension.jar

•	com.oracle.jatmi.dataxfm_1.0.0.0.jar

•	com.bea.core.jatmi_1.2.0.3.jar

•	com.bea.core.i18n_1.4.0.0.jar

•	tuscany-sca-manifest.jar

Listing 1‑10 shows an SCA JATMI client composite file example.

Listing 1‑10 SCA JATMI Client Composite File Example

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" xmlns:f="binding-atmi.xsd"
name="EchoComposite">
       <reference name="ECHO" promote="EchoComponent/ECHO">
              <interface.java class="com.abc.sca.java.Echo" />
              <f:binding.atmi requires="legacy">
                     <f:serviceType>RequestResponse</f:serviceType>
                     <f:inputBufferType>FML</f:inputBufferType>
                     <f:outputBufferType>FML</f:outputBufferType>
                     <f:fieldTables>com.abc.sca.java.fml.FMLTABLE
                     </f:fieldTables>
                     <f:workStationParameters>
                            <f:networkAddress>//STRIATUM:15011
                            </f:networkAddress>
                     </f:workStationParameters>
              </f:binding.atmi>
       </reference>
       <component name="EchoComponent">
              <implementation.java
              class="com.abc.sca.java.EchoComponentImpl />
       </component>
</composite>

 

Configuring an SCA Workstation Client

Configuring an SCA workstation clients is similar to configuring SCA native clients. One difference is that an SCA workstation client requires using the <workStationParameters> element and its sub-elements in the composite. The SCA runtime automatically detects whether the client is built as an SCA native client or SCA workstation client and loads the correct reference binding library accordingly.

An SCA Oracle Tuxedo Workstation client has a similar directory hierarchy to an SCA native client. Both rely on the environment variable $APPDIR, which points to where the client application is located.

Listing 1‑11 and Listing 1‑12 show SCA Oracle Tuxedo workstation client configuration examples.

Listing 1‑11 $APPDIR/root.composite

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" name="testApp">
       <component name="testStringClientComp">
              <implementation.composite name="ECHO"/>
       </component>
</composite>

 

Listing 1‑12 $APPDIR/ECHO/ECHO.composite

<?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">
        <inputBufferType target="TestString">STRING</inputBufferType>
        <outputBufferType target="TestString">STRING</outputBufferType>
        <errorBufferType target="TestString">STRING</errorBufferType>
      <workStationParameters>
        <networkAddress>//STRIATUM:4890</networkAddress>
        <encryptBits>128/128</encryptBits>
      </workStationParameters>
      <remoteAccess>WorkStation</remoteAccess>
      </binding.atmi>
  <reference>
</composite>

 

Configuring an SCA Web Service Client

The SCA Web service client is basically the same as SCA native client except that is uses the <binding.ws> element instead of <binding.atmi>. The SCA runtime automatically detects which binding the client is using, and loads the correct reference binding accordingly.

The SCA Web service client has a similar directory hierarchy as native client. They both rely on the $APPDIR environment variable to point to where the client application is located.

Listing 1‑13 and Listing 1‑14 show SCA Web service client configuration examples.

Listing 1‑13 $APPDIR/root.composite

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" name="testApp">
       <component name="calcClient">
              <implementation.composite name="calcClient"/>
       </component>
</composite>

 

Listing 1‑14 $APPDIR/calcClient/calcClient.composite

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"name="calcClient">
       <reference name="Calculator">
              <interface.cpp header="CalcService.h"/>
              <binding.ws
              endpoint="http://calc.sample#wsdl.endpoint
              (Calculator/CalculatorSOAP11port)"/>
       </reference>

</composite>

 

The <interface.cpp> element is required to build the appropriate proxy stub. Also, the client directory should contain the WSDL file where the endpoint specified in <binding.ws> is located. In addition, the configuration of the Oracle Tuxedo Web services gateway (GWWS) is necessary and requires the following steps:

1.	Make sure the TMMETADATA and GWWS servers are shut down.

2.	Run wsdlcvt on the WSDL of the service(s) used. This produces a WSDF file, an Oracle Tuxedo Metadata Repository interface definitions file, fml32 field tables and XML schemas.

3.	Optionally, modify the generated WSDF file to override the actual endpoint address used at runtime. For more information, see WSDF documentation.

4.	Load the Oracle Tuxedo Metadata Repository interface definitions into the TMMETADATA server repository (e.g.: $ tmloadrepos -I calc.mif metadata.repos -y). For more information, see tmloadrepos documentation.

5.	Add a reference to the WSDF in the GWWS configuration input file (named gwws.dep for example). Listing 1‑15 shows the added elements highlighted in blue.

6.	Reload the GWWS binary configuration file to take into account the changes performed in the previous five (e.g.: $ wsloadcf -y gwws.dep).

7.	Reboot GWWS and TMMETADATA.

Listing 1‑15 GWWS Configuration File

<?xml version="1.0" encoding="UTF-8"?>
<saltdep:Deployment xmlns:saltdep="http://www.bea.com/Tuxedo/SALTDEPLOY/2007" xmlns="http://www.bea.com/Tuxedo/SALTDEPLOY/2007" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <saltdep:WSDF>
              <saltdep:Import location="calc.wsdf"/>
       </saltdep:WSDF>
       <saltdep:WSGateway>
              <saltdep:GWInstance id="GWWS1">
                     <saltdep:Outbound>
                     <saltdep:Binding ref="calc:CalculatorSOAP11Binding">
                     <saltdep:Endpoint use="CalculatorSOAP11port"/>
                     </saltdep:Binding>
                     </saltdep:Outbound>
              </saltdep:GWInstance>
       </saltdep:WSGateway>
        <saltdep:System/>
</saltdep:Deployment>

 

Configuring an SCA ATMI Server

For an SCA ATMI server, the SCA ROOT is the same as $APPDIR. There should be at least one composite file that describes the SCA application. The SCA runtime searches for this composite file and from there it loads all the composite and componentType files for SCA server applications that are hosted in an Oracle Tuxedo environment.

Listing 1‑16 shows a root composite file, named root.composite contains two SCA applications hosted in an Oracle Tuxedo application domain. The two applications are called Purchase and Finance. There are at least two subdirectories for these two SCA applications. One is called Purchase.component and the other is called Finance.component.

Listing 1‑16 $APPDIR/root.composite

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" name="root">
       <component name="Purchase.component">
              <implementation.composite name="Purchase" />
       </component>
       <component name="Finance.component">
              <implementation.composite name="Finance" />
       </component>
</composite>

 

Listing 1‑17 shows the Purchase.component directory contains a composite file for the Purchase application named Purchase.composite. Similarly, the Finance.component directory contains a composite file for the Finance application named Finance.composite.

Listing 1‑17 $APPDIR/Purchase.component/Purchase.composite

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
       name="Purchase">
       <service name="purchase">
              <interface.cpp header="Purchase.h" />
       <binding.atmi requires="legacy">
              <map target="Order">ORDER</map>
              <map target="TrackOrder">TRACKORDER</map>
       </binding.atmi>
       <reference>PurchaseServiceComponent</reference>
       </service>
       <component name="PurchaseServiceComponent">
              <implementation.cpp library="Purchase" header="PurchaseImpl.h" />
       </component>
</composite>

 

Listing 1‑18 shows Purchase.composite contains the PurchaseImpl.componentType file in the $APPDIR/Purchase.component directory and uses CPP as its application implementation. When an SCA server using this configuration is built using the buildscaserver utility, it advertises two SCA services automatically at runtime (ORDER and TRACKORDER). The actual CPP implementation of the services is called Order and TrackOrder.

Listing 1‑18 $APPDIR/Purchase.component/PurchaseImpl.componentType

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

 

Assume these two SCA applications hosted in Oracle Tuxedo and built using buildscaserver are called PurchaseSvr and FinanceSvr. You must add the following lines to the *SERVERS section in the UBBCONFIG file:

PurchaseSvr SRVGRP=PURCHASEGRP SRVID=500

FinanceSvr SRVGRP=FINANCEGRP SRVID=600

There is no need to add a service in the *SERVICES section. SCA services hosted by Oracle Tuxedo are dynamically advertised.

Configuring an SCA Web Service Server

Configuring Web services binding for components (server side) is similar to configuring ATMI binding for hosting SCA components.

Listing 1‑19 shows a root composite file named root.composite. It contains one SCA component hosted in an Oracle Tuxedo application domain. The two applications are called Purchase and Finance. There are at least two subdirectories for these two SCA applications, one is called Purchase.component, and the other is called Finance.component.

Listing 1‑20 shows the actual component subdirectory. Listing 1‑21 shows the componentType side file

Listing 1‑19 $APPDIR/root.composite

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0" name="root">
       <component name="account">
              <implementation.composite name="account" />
       </component>
</composite>

 

Listing 1‑20 $APPDIR/account/account.composite

<?xml version="1.0" encoding="UTF-8"?>
<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
       name="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"/>
       </component>
</composite>

 

Listing 1‑21 $APPDIR/account/AccountServiceImpl.componentType

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

       </service>
</componentType>

 

The above SCA component are hosted in an Oracle Tuxedo server built using buildscaserver with the -w option (for Web services) and named WSServer

Then in the Oracle Tuxedo UBBCONFIG file you need to add the following line in the *SERVERS section: WSServer SRVGRP=ACCTGRP SRVID=500.

There is no need add a service in the *SERVICES section. SCA services hosted by Oracle Tuxedo are dynamically advertised.

In addition, configuration of the Oracle Tuxedo Web services gateway (GWWS) is necessary. Do the following steps:

1.	Make sure the TMMETADATA and GWWS servers are shut down

2.	Run wsdlcvt on the WSDL of the service(s) used. This produces a WSDF file, an Oracle Tuxedo Metadata Repository interface definitions file, fml32 field tables and XML schemas.

3.	Modify the generated WSDF file to specify the actual endpoint address used at runtime to accept requests. For more information, see WSDF documentation.

4.	Load the Oracle Tuxedo Metadata Repository interface definitions into the TMMETADATA server repository (for example, $ tmloadrepos -I AccountService.mif metadata.repos -y). For more information, see tmloadrepos documentation.

5.	Add a reference to the WSDF in the GWWS configuration input file (named gwws.dep for example). Listing 1‑22 shows the elements added highlighted in blue.

6.	Reload the GWWS binary configuration file to take into account the changes performed in the step five (e.g.: $ wsloadcf -y gwws.dep).

7.	Reboot GWWS and TMMETADATA.

Listing 1‑22 gwws.dep File

<?xml version="1.0" encoding="UTF-8"?>
<saltdep:Deployment xmlns:saltdep="http://www.bea.com/Tuxedo/SALTDEPLOY/2007" xmlns="http://www.bea.com/Tuxedo/SALTDEPLOY/2007" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <saltdep:WSDF>
              <saltdep:Import location="AccountService.wsdf"/>
       </saltdep:WSDF>
       <saltdep:WSGateway>
              <saltdep:GWInstance id="GWWS1">
                     <saltdep:Inbound>
                            <saltdep:Binding ref="AccountService:AccountServiceSOAP">
                            <saltdep:Endpoint use="AccountServiceSOAP"/>
                                </saltdep:Binding>
                     </saltdep:Inbound>
              </saltdep:GWInstance>
       </saltdep:WSGateway>
       <saltdep:System/>
</saltdep:Deployment>

 

Configuring SCA Client Security

Oracle Tuxedo SCA components support two types of security:

•	Oracle Tuxedo Application Domain Security

•	Oracle Tuxedo Link-Level Security

Oracle Tuxedo Application Domain Security

Oracle Tuxedo Application Domain Security is set when the TUXCONFIG file for the Oracle Tuxedo Application Domain contains the SECURITY keyword in the *RESOURCES section. There are five levels of application security: NONE, APP_PW, USER_PW, ACL, and MANDATORY_ACL. All security levels except NONE require at least an application password from user to gain access to the Oracle Tuxedo application. At the USER_PW level and above there is an additional user password to authenticate the user and establish user credentials. In total there are potentially two passwords that need to be configured.

All SCA clients require this password information in order to gain access to Oracle Tuxedo application servers. There are two ways for an SCA client to retrieve password information:

•	The client application may provide password information to ATMI/JATMI reference binding extensions through a callback mechanism.

•	The client application may configure the identification of the password to be retrieved by the ATMI/JATMI reference binding extensions in the appropriate composite file.

Note:

For more information, see Password callback methods in Oracle Tuxedo SCA Programming.

In order for the Oracle Tuxedo administrator to configure password retrieval, the administrator must:

•	Maintain the password.store file and set this file up correctly for the client application. The administrator must duplicate the password.store file across different machines if necessary.

•	Add or delete password and identification pairs when necessary.

•	Configure the client application composite file with correct information.

Listing 1‑23 and Listing 1‑24 contain SCA ATMI client application examples.

Listing 1‑23 $APPDIR/password.store $APPDIR/simple.app.composite

<?xml version="1.0" encoding="UTF-8"?>

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
       name="simple.app">
       
       <component name="simpapp.TuxClient">
              <implementation.composite name="simpapp.client"/>
              <reference name="TOUPPER">tuxToupper</reference>
       </component>

</composite>

 

Listing 1‑24 $APPDIR/simpapp.client/simpapp.client.composite

<composite xmlns="http://www.osoa.org/xmlns/sca/1.0"
name="simpapp.client">

  <reference name="TOUPPER">
    <interface.cpp header="ToupperTuxService.h"/>
    <binding.atmi requires="legacy">
      <tuxconfig>d:\tests\tuxedo\sca\tests\TUXCONFIG</tuxconfig>
      <inputBufferType target="charToup">STRING</inputBufferType>
      <outputBufferType target="charToup">STRING</outputBufferType>
        <authentication
          <passwordIdentifier>aaa</passwordIdentifier>
        </authentication>
    </binding.atmi>
  </reference>
</composite>

 

The above composite defines an Oracle Tuxedo application domain password identification "aaa" which causes the ATMI reference binding to retrieve the password with identification "aaa" from the password.store file at the runtime. If you increased Oracle Tuxedo application domain security by requiring user authentication. (SECURITY=USER_PW or above) you would use the following command: scapasswordtool -i crusoe -a.

Then use a text editor or any other tool that can edit the simpapp.client.composite file and add the following entry in the <binding.atmi/authentication> element: <userPasswordIdentifier>crusoe</userPasswordIdentifier>

Anyone using the password "crusoe" can access Oracle Tuxedo applications.

Oracle Tuxedo Link-Level Security

Oracle Tuxedo Link-Level Security has two variations. One is the easily configured Link-Level Encryption (LLE) and the other one is the more commonly used Transport Layer Security (TLS) also known as Secured Socket Layer (SSL). An SCA ATMI client using the native ATMI reference binding does not need link-level security configured at the SCA level since its transport method is native message queues and the Oracle Tuxedo BRIDGE.

The SCA JATMI client reference binding does not support link-level security. The only type of SCA client that allows configuration of link-level security is SCA Workstation ATMI client.

The SCA Workstation ATMI client contains a <workStationParameters> element configured in the composite file. The SCA runtime automatically loads the correct reference binding for this type of client.

Configuring Link-Level Encryption

Link-level encryption can be configured by adding an <encryptBits> element in the composite file. The following elements should not be configured for LLE, since they are specific to SSL encryption and imply that SSL encryption is used:

•	secPrincipalName

•	secPrincipalLocation

•	secPrincipalPassId

The <encryptBits> element specifies the encryption strength that this client attempts to negotiate. The syntax for the <encryptBits> element is <minimum encryption strength>/<maximum encryption strength>. To configure minimum 56-bit encryption you must add the following to the composite file:

<networkAddress>//STRIATUM:8741</networkAddress>

<encryptBits>56/128</encryptBits>

Note:

encryptBits specifies the encryption strength that the client connection attempts to negotiate. The format is <minencryptbits>/<maxencprytbits> (for example, 128/128). Values can be 0 (no encryption is used), 40, 56, 128, or 256. Invalid values result in a configuration exception.

This tells SCA Workstation Reference binding to require 56 to 128 bits encryption strength when negotiating with WSH. You must also add the following line to the *SERVERS section in the UBBCONFIG file:

WSL SRVGRP=GROUP1 SRVID=1001 CLOPT="-A -- -n //STRIATUM:8741 -a -z 56 -Z 256

Configuring Transport Layer Security

In addition to <encryptBits>, to enable Link-Level Security over TLS/SSL you must configure secPrincipalName, secPrincipalLocation, and secPrincipalPassId.

•	secPrincipalName - the name of the security principal. It is used for searching the client X.509 certification from the LDAP server.

•	secPrincipalLocation - the client private key file.

•	secPrincipalPassId - the password identifier that is used to retrieve client password used to encrypt the private key file.

Note:

The "cn" attribute of a distinguished name is used as key for certificate lookup. Wildcards used in a name are not supported. Empty subject fields are not allowed. This limitation is also found in Oracle Tuxedo.

These three parameters specify the parameters needed when a TLS/SSL connection needs to be established by a SCA Workstation ATMI client.

Listing 1‑25 contains the lines you must add to the client composite file in /binding.atmi/workStationParameters to configure TLS/SSL.

Listing 1‑25 Client Composite File

<networkAddress>//STRITUM:8742</networkAddress>
<secPrincipalName>crusoe</secPrincipalName>
<secPrincipalLocation>/tux/udataobj/security/keys/crusoe.pem</secPrincipalLocation>
<secPrincipalPassId>crusoe</secPrincipalPassId>

 

In Oracle Tuxedo, you must add -S 8742 to WSL to indicate that TLS/SSL is used if the client connects through port 8742.

WSL SRVGRP=GROUP1 SRVID=1001
       CLOPT="-A -- -n //STRIATUM:8741 -S 8742 -z 56 -Z 128"

Administering Oracle Tuxedo SCA Components

This section contains the following topics:

•	Tracing the SCA ATMI Server and Client

•	Log File Contents

•	Log File Contents

Tracing the SCA ATMI Server and Client

Both The SCA ATMI server and client can utilized the existing tracing capability provided by Oracle Tuxedo and SCA. The following sections describe how to use them in detail:

•	Oracle Tuxedo TMTRACE

•	SCA Runtime, ATMI Service, and Reference Binding Tracing

Oracle Tuxedo TMTRACE

SCA ATMI servers and clients support the Oracle Tuxedo tmtrace(5)function. All traces generated from TMTRACE are logged in the ULOG file. Checking the ULOG file trace information helps to determine the cause of a failure. The Oracle Tuxedo TMTRACE facility is enabled by setting TMTRACE environmental variable, or by using the tmadmin chtr sub-command.

Note:

To trace Oracle Tuxedo ATMI messages enter: export TMTRACE=atmi:ulog at the command line.

SCA Runtime, ATMI Service, and Reference Binding Tracing

There are two environment variables used for tracing:

•	SCACPP_LOGGING: Set to a numeric value and controls the number of trace messages produced.

•	SCACPP_ULOG: Set to "yes" to send trace messages to the ULOG. If this environment variable is not set or is set to "no", then trace messages are written to standard output.

Note:

These tracing facilities are only available for Oracle Tuxedo server builds using buildscaserver and SCA client builds using buildscaclient.

Listing 1‑26 shows a ULOG example containing SCA runtime tracing:

Note:

Lines starting with ">>" or with "<<" is not printed when the code is compiled

Listing 1‑26 SCA Runtime Tracing Information ULOG File

142059.STRIATUM!?proc.1108.3000.-2: osoa::sca::CompositeContext::getCurrent
142059.STRIATUM!?proc.1108.3000.-2: >> Tuscany::sca::SCARuntime::getCurrent Runtime
142059.STRIATUM!?proc.1108.3000.-2: >> tuscany::sca::util::ThreadLocal::getValu e
142059.STRIATUM!?proc.1108.3000.-2: << tuscany::sca::util::ThreadLocal::getValu e
142059.STRIATUM!?proc.1108.3000.-2: >> tuscany::sca::SCARuntime::getShared Runtime
142059.STRIATUM!?proc.1108.3000.-2: SCARuntime::getSharedRuntime()
142059.STRIATUM!?proc.1108.3000.-2: >> tuscany::sca::util::Mutex::lock

142059.STRIATUM!?proc.1108.3000.-2: << tuscany::sca::util::Mutex::lock

142059.STRIATUM!?proc.1108.3000.-2: >> tuscany::sca::util::Mutex::unlock
142059.STRIATUM!?proc.1108.3000.-2: << tuscany::sca::util::Mutex::unlock
142059.STRIATUM!?proc.1108.3000.-2: << tuscany::sca::SCARuntime::getSharedR untime
142059.STRIATUM!?proc.1108.3000.-2: >> tuscany::sca::util::ThreadLocal::Thread Local
142059.STRIATUM!?proc.1108.3000.-2: << tuscany::sca::util::ThreadLocal::Thread Local
142059.STRIATUM!?proc.1108.3000.-2: >> tuscany::sca::SCARuntime::SCARuntime
142059.STRIATUM!?proc.1108.3000.-2: SCA runtime install root f:\tuxedo\tux101rp _wsc\udataobj\salt\sca
142059.STRIATUM!?proc.1108.3000.-2: Default component: testStringClientComp
142059.STRIATUM!?proc.1108.3000.-2: >> tuscany::sca::util::ThreadLocal::getValu e
142059.STRIATUM!?proc.1108.3000.-2: << tuscany::sca::util::ThreadLocal::getValu e

 

Monitoring SCA ATMI Servers

An Oracle Tuxedo SCA server built with the buildscaserver utility can be monitored using the scaadmin utility. This utility shows service statistics information and helps perform maintenance through dynamic shared library loading and unloading.

To reload all components hosted by the uBikeServer Oracle Tuxedo server previously built using the buildscaserver command, do the following:

1.	prompt> scaadmin

2.	prompt> reload -s uBikeServer

Enter the following at the command line to display statistics on the services offered by the uBikeServer Oracle Tuxedo server (Table 1‑1 shows the results):

1.	prompt> scaadmin

2.	prompt> pstats -s uBikeServer

 

Table 1‑1 pstats 0utput Service Statics

Service	Method	Status	Requests Processed
SEARCHINVENTORY	searchInventory	A	37

Before scaadmin is executed, you must set the TUXCONFIG environment variable. Table 1‑2 lists scaadmin sub-commands.

 

Table 1‑2 scaadmin Sub-Commands

Sub-Command	Abbrev.	Description
default	d	Sets the corresponding argument to default, and it can be machine name, group name, server id, or server name. If the default command is entered without an argument, the current default values is printed.
reload	r	Dynamically reloads the SCA components hosted in a Oracle Tuxedo server.
printstats	pstats	Displays the list of services hosted by an Oracle Tuxedo server, and the associated method, number of queries, and status (active, idle)
verbose	v	Produces output in verbose mode.
echo	e	Switches echo input on/off echo.
quit	q	Terminates the session.

Note:

Both Windows and HP systems have a limitation using the "reload" sub-command.

When multiple servers share the same component library on Windows and HP systems, the shared component library cannot be reloaded. To reload a component library common to multiple servers, the "scaadmin" reload sub-command must be performed on all affected servers simultaneously.

Tracing SCA JATMI Clients

The Oracle Tuxedo SCA Java reference binding and data transformation support output to the console and to a log file. By default there are at most 10 log files, the maximum size of each file is 100000 bytes, and are located in $APPDIR with name jatmi<number>.log file. The log file names are cycled with the latest one using the number 0, and the one just before latest one uses 1 (for example. jatmi0.log is the latest log file, and jatmi9.log is the oldest log file). If the APPDIR environment variable is not set and com.oracle.jatmi.APPDIR java property is not specified, the log is placed in the current working directory.

By default, the log files are overwritten each time the application starts. Many logger parameters can be fine tuned. Table 1‑3 lists tunable Java properties related to logging.

 

Table 1‑3 Logger Tuning Property Table

Function	Properties	Value Range	Default Value
Log File Location	com.oracle.jatmi.APPDIR	valid path name	APPDIR environmental variable, if APPDIR is not set uses current working directory
Log File Size	com.oracle.jatmi.LogFileSize	0 ... maximum file size supported by the system	100,000 bytes
Append File	com.oracle.jatmi.LogFileAppend	{true,false}	false
Number of Log Files	com.oracle.jatmi.LogFileCount	1 ... maximum number of files in a directory	10
Log Output	com.oracle.jatmi.LogDestination	{file,console,both}	both
Log Format	com.oracle.jatmi.LogFileFormat	{xml,plain}	plain

To have the Oracle Tuxedo SCA Java reference binding log in a different language, first check the supported languages that are installed. The default is English. To switch to a different language, add: "-Duser.language=<your preferred language>" to your Java command line when starting the Oracle Tuxedo SCA Java client. For example:

java -classpath .:/apps/classes:$CLASSPATH -Duser.langueage=ES -Dcom.oracle.jatmi.LogDestination=console myApplication.

This generates an English log in plain text format to the console only.

Table 1‑3 shows an example of the log file contents.

Listing 1‑27 Log File Contents

9/3/08:3:19:14 PM:10:TRACE[TuxedoConversion,processSendBuf]< (10) return 1st args
9/3/08:3:19:14 PM:10:DBG[AtmiBindingInvoker,invoke]ServiceType: requestresponse
9/3/08:3:19:14 PM:10:DBG[AtmiBindingInvoker,invoke]Return Type Class: simpapp.View7Rep
9/3/08:3:19:14 PM:10:DBG[AtmiBindingInvoker,invoke]target service name: RULE7
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]TPURCODE: 0
9/3/08:3:19:15 PM:10:TRACE[TuxedoConversion,processReplyBuffer]> (reply simpapp.View7Rep@191777e:0:null)
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processReplyBuffer]returnType: simpapp.View7Rep
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processReplyBuffer]Reply Buffer Class: simpapp.View7Rep
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processReplyBuffer]Reply Buffer Type: X_COMMON
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processReplyBuffer]Reply Buffer Subtype: View7Rep
9/3/08:3:19:15 PM:10:TRACE[TuxedoConversion,processReplyBuffer]< (30) return buffer directly
9/3/08:3:19:15 PM:10:DBG[Accessors,getConventionProperty]Convention Property: CONVENTIONS_TUX
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]networkAddress: host = STRIATUM, port = 8080
9/3/08:3:19:15 PM:10:TRACE[AtmiBindingInvoker,determineServiceCallParameters]> ()
9/3/08:3:19:15 PM:10:DBG[AtmiBindingImpl,isLegacy]> ()
9/3/08:3:19:15 PM:10:DBG[AtmiBindingImpl,isLegacy]< (10) return true
9/3/08:3:19:15 PM:10:DBG[AtmiBindingImpl,isMap]> ()
9/3/08:3:19:15 PM:10:DBG[AtmiBindingImpl,isMap]< (10) return false
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,determineServiceCallParameters]Operation name = rule7_OVVO
9/3/08:3:19:15 PM:10:TRACE[AtmiBindingImpl,getServiceType]> (rule7_OVVO)
9/3/08:3:19:15 PM:10:TRACE[AtmiBindingImpl,getServiceType]< (10) return null
9/3/08:3:19:15 PM:10:TRACE[AtmiBindingImpl,getInputBufferType]> (rule7_OVVO)
9/3/08:3:19:15 PM:10:TRACE[AtmiBindingImpl,getInputBufferType]< (10) return null
9/3/08:3:19:15 PM:10:TRACE[AtmiBindingImpl,getOutputBufferType]> (rule7_OVVO)
9/3/08:3:19:15 PM:10:TRACE[AtmiBindingImpl,getOutputBufferType]< (10) return null
9/3/08:3:19:15 PM:10:DBG[AtmiBindingImpl,getErrorBufferType]> (rule7_OVVO)

9/3/08:3:19:15 PM:10:DBG[AtmiBindingImpl,getErrorBufferType]< (10) return null
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,determineServiceCallParameters]svcName = RULE7
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,determineServiceCallParameters]svcType = requestresponse
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,determineServiceCallParameters]inbuf = X_COMMON
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,determineServiceCallParameters]outbuf = X_COMMON
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,determineServiceCallParameters]errbuf = null

9/3/08:3:19:15 PM:10:TRACE[AtmiBindingInvoker,determineServiceCallParameters]< (10) return
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]Input Buffer Type: X_COMMON
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]Output Buffer Type: X_COMMON
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]Error Buffer Type: null

9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]inBufType:X_COMMON, count: 1
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]outBufType:X_COMMON,

count: 1
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]View Classes: simpapp.View7Req,simpapp.View7Rep
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,getClassList]getClassList: Getting class for simpapp.View7Req
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,getClassList]getClassList: Getting class for simpapp.View7Rep
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,setFieldClasses]setFldClasses: null
9/3/08:3:19:15 PM:10:DBG[AtmiBindingInvoker,invoke]Passing thro invoker...

9/3/08:3:19:15 PM:10:TRACE[TuxedoConversion,processSendBuf]> (args [Ljava.lang.Object;@ab1b4)
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processSendBuf]args[0] class simpapp.Rule7Req
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,needConversion]buftype: X_COMMON

9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processSendBuf]Argument Class Name: simpapp.Rule7Req
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processSendBuf]Input Buffer Id : XCOMMON
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processSendBuf]Type code : 10
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,processSendBuf]InputBufferType: XCOMMON
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,getClassList]getClassList: Getting class for simpapp.View7Req
9/3/08:3:19:15 PM:10:DBG[TuxedoConversion,getClassList]getClassList: Getting class for simpapp.View7Rep
9/3/08:3:19:15 PM:10:TRACE[Accessors,determineConvention]> (simpapp.Rule7Req)
9/3/08:3:19:15 PM:10:DBG[Accessors,determineConvention]Method name: getId

9/3/08:3:19:15 PM:10:DBG[Accessors,determineConvention]Method name: setCmd

9/3/08:3:19:15 PM:10:DBG[Accessors,determineConvention]Method name: setId

9/3/08:3:19:15 PM:10:DBG[Accessors,determineConvention]Method name: getCmd

9/3/08:3:19:15 PM:10:TRACE[Accessors,determineConvention]< (30) return BEAN