Oracle Tuxedo JCA Adapter Users Guide

This chapter contains the following topics:

•	Prerequisites

•	Installing the Oracle Tuxedo JCA Adapter

•	Configuring the Oracle Tuxedo JCA Adapter

•	Oracle Tuxedo JCA Adapter Deployment

•	Oracle Tuxedo JCA Adapter Management

•	Oracle Tuxedo JCA Adapter Security

Prerequisites

Installing and deploying the Oracle Tuxedo JCA Adapter requires the following prerequisites:

•	Access to JDK 1.5 or later

•	5 MB free disk space

•	A text editor or XML editor

Installing the Oracle Tuxedo JCA Adapter

The complete Oracle Tuxedo JCA Adapter is contained in a single resource archive file (com.oracle.tuxedo.TuxedoAdapter.rar) which you can download from the Oracle Web site. It contains both Java .jar files for resource adapter and standard JCA adapter deployment descriptor.

Table 1 lists the Oracle Tuxedo JCA Adapter resource archive file content.

Copy the downloaded Resource Archive file to a target directory with correct read and write access control. Un-jar the resource archive file to browse the contents and view the standard deployment descriptor.

 

Table 1 Resource Archive Content

Resource name	Description
com.oracle.tuxedo.adapter_1.0.0.0.jar	JAR file containing the Oracle Tuxedo JCA Adapter classes.
com.bea.core.jatmi_1.3.0.0.jar	JAR file containing the Java ATMI buffer types, and interfaces.
com.bea.core.i18n_1.4.0.0.jar	The I18N utility classes.
javax.transaction_1.0.0.0_1-1.jar	JTA 1.1 classes.
javax.ejb_3.0.1.jar	EJB 3.0 support classes.
adapter.properties	The Oracle Tuxedo JCA Adapter message catalogue.
tja.xsd	The Oracle Tuxedo JCA Adapter configuration XML schema.
META-INF/ra.xml	The resource adapter deployment descriptor.
META-INF/weblogic-ra.xml	The WebLogic JCA adapter deployment descriptor. Note: The META-INF/weblogic-ra.xml file is specific to Oracle WebLogic Server. It is required when Oracle Tuxedo JCA Adapter is deployed in WebLogic and managed by its JCA container. It is not required for other application servers such as WebSphere or JBoss.

Configuring the Oracle Tuxedo JCA Adapter

A separate Oracle Tuxedo JCA Adapter configuration file is required in addition to the “config-property” elements in the resource adapter deployment descriptor. The configuration file is an XML-based text file and contains the TuxedoConnector root element and sub-elements.

You must specify the Oracle Tuxedo JCA Adapter configuration file using the "dmconfig" property in the resource deployment descriptor META-INF/ra.xml file. For more information, see Configuration File Examples in the Oracle Tuxedo JCA Adapter Programming Guide.

Root Element

There is only one root element, "TuxedoConnector", in the Oracle Tuxedo JCA Adapter configuration file; it is represented by the complex type TuxedoConnectorType. It contains the following elements as listed in Table 2:

•

Resources

•	Local Access Point

•	Remote Access Point

•	Session Profile

•

Session

•

Import

•

Export

 

Table 2 TuxedoConnectorType Elements

Element Name	Type	Occurrence	Description
Resources	ResourceType	0..1	Oracle Tuxedo JCA Adapter environment
LocalAccessPoint	LocalAccessPointType	1..unbounded	Local access point
RemoteAccessPoint	RemoteAccessPointType	0..unbounded	Remote access point
SessionProfile	SessionProfileType	0..unbounded	Session profile including QoS configuration information.
Session	SessionType	0..unbounded	Defines the possible session/connection to a remote domain.
Import	ImportType	0..unbounded	Defines a remote resource available to the adapter
Export	ExportType	0..unbounded	Defines a local resource available to remote domain.

The configuration must use the <TuxedoConnector> and </TuxedoConnector> tags as shown in Listing 1.

Listing 1 TuxedoConnector Tags Example

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

 

Resources

The Resources element is represented by ResourceType. It specifies the resource adapter execution environment.Only one "Resource" element can be configured in the Oracle Tuxedo JCA Adapter configuration file. Table 3 lists the "ResourceType" elements.

 

Table 3 ResourceType Elements

Element Name	Type	Occurrence	Description
FieldTable16Classes	string	0..unbounded	Fully qualified Field Table 16 class for FML.
FieldTable32Classes	string	0..unbounded	Fully qualified Field Table 32 class for FML32.
ViewFile16Classes	string	0..unbounded	Fully qualified VIEW table 16 class for VIEW.
ViewFile32Classes	string	0..unbounded	Fully qualified VIEW table 32 class for VIEW32.
ApplicationPasswordEncrypted	string	0..1	The application password for joining an Oracle Tuxedo application. The password is in encrypted format. The password length cannot exceed 30 characters and should be the same as the Oracle Tuxedo application password.
TpusrFile	string	0..1	The TPUSR file full path name.
RemoteMBEncoding	string	0..1	The MB encoding used by an Oracle Tuxedo Application.
MBEncodingMapFile	string	0..1	Full encoding map file path name.

Note:

There is no attribute defined for any "ResourceType" element; however, the "TpusrFile" element can be overridden.

Listing 2 shows a "Resources" configuration example.

Listing 2 Resources Configuration Example

<Resources>
  <FieldTable16Classes>tuxedo.test.fml16.FieldTbl16</FieldTable16Classes>
  <ViewFile32Classes>tuxedo.test.simpapp.View32</ViewFile32Classes>
  <ApplicationPasswordEncrypted>tuxpassword</ApplicationPasswordEncrypted>
</Resources>

 

Local Access Point

The Local Access Point element is represented by LocalAccessPointType. It specifies a listening address and possible link-level failover address. Table 4 lists the LocalAccessPointType elements.

 

Table 4 LocalAccessPointType Elements

Element Name	Type	Occurrence	Description
AccessPointId	string	0..1	The connection principal name. It must be globally unique. Note: Globally unique means the identification specified in the configuration must be unique within all the interconnected Oracle Tuxedo Domains and Application Servers through Oracle Tuxedo GWTDOMAIN gateway, WebLogic Server WTC, and Oracle Tuxedo JCA Adapter. If not specified, it uses the locally unique LocalAccessPoint “name” attribute value (see Listing 3).
NetworkAddress	string	1..unbounded	The local access point listening address including both host address and port number. Specify the TCP/IP address in the format //hostname:port or //#.#.#.#:port.
SSLInfo	complexType	0..1	Specifies whether SSL encryption is used to secure communication or not. If not configured, LLE is used.

The SSLInfo element is an anonymous complex type. If it is included in the configuration, all its elements must be configured and SSL is used as the transport mechanism. If it is not included, TCP/IP is used as the transport mechanism and uses link-level encryption for data privacy. Table 5 lists SSLInfo elements.

 

Table 5 SSLInfo Elements

Element Name	Type	Occurrence	Description
MutualAuthenticationRequired	boolean	0..1	Specifies if client authentication is required for SSL communication. The default value is "false".
IdentityKeyStoreFileName	string	1..1	Full identity key store file path name.
IdentityKeyStorePassPhraseEncrypted	string	1..1	Password used to encrypt the identity key store.
PrivateKeyAlias	string	1..1	Alias in the identity key store used to retrieve private key.
PrivateKeyPassPhraseEncrypted	string	1..1	Encrypted password used to decrypt the private key in the identity key store.
TrustKeyStoreFileName	string	1..1	Full trust key store file path name.
TrustKeyStorePassPhraseEncrypted	string	1..1	Pass phrase used to decrypt the trust key store when retrieving certificates.

The “name” attribute is defined for LocalAccessPointType. It is used to identify the configuration record as represented by LocalAccessPointType. It specifies a locally unique local access point name as shown in Listing 3.

Listing 3 LocalAccessPoint Name Attribute

<LocalAccessPoint name="LDOM1">
  <AccessPointId>Godfried</LocalAccessPointId>
  <NetworkAddress>//neocortex:14001</NetworkAddress>
</LocalAccessPoint>

 

By default SSL only authenticates the server (connection request responder). However, to enable the client authentication the "MutualAuthenticationRequired" element must be set to “true.”

Remote Access Point

The Remote Access Point element is represented by RemoteAccessPointType. It defines a network address for remote Oracle Tuxedo Domain access points. Table 6 lists RemoteAccessPointType elements.

 

Table 6 RemoteAccessPointType Elements

Element Name	Type	Occurrence	Description
AccessPointId	string	0..1	It is used by default as connection principal name that is used to identify this remote access point when attempting to establish a session with remote Tuxedo access point. It must be globally unique. Note: Globally unique means the identification specified in the configuration must be unique within all the interconnected Oracle Tuxedo Domains and Application Servers through Oracle Tuxedo GWTDOMAIN gateway, WebLogic Server WTC, and Oracle Tuxedo JCA Adapter If not specified, it uses the locally unique RemoteAccessPoint “name” attribute value (see Listing 4).
NetworkAddress	string	1..unbounded	The host network address and port number of this remote Tuxedo access point. Specify the TCP/IP address in the format //hostname:port or //#.#.#.#:port.
TpusrFile	string	0..1	The full path name to a TPUSR file for this remote access point.
AllowAnonymous	boolean	0..1 Value set {true, false}	Indicates whether the remote Tuxedo access point allow anonymous access or not. The default value is "false".
DefaultApplicationKey	string	0..1	The default application key value for the remote Oracle Tuxedo access point. If not specified, then "-1" is assumed.
CustomApplicationKey	complexType	0..1	Configures the custom application key generator. If not specified, the default application key generator is used.

The CustomApplicationKey element is an anonymous complex type. If not specified, the default Application Key plug-in is used. If specified, all of its elements must be configured and the Custom Application Key plug-in class is loaded for every session that communicates with the remote access point. Table 7 lists CustomApplicationKey elements.

 

Table 7 CustomApplicationKey Elements

Element Name	Type	Occurrence	Description
ApplicationKeyClass	string	1..1	The application key generator class name.
ApplicationKeyClassParam	string	1..1	The parameter string passed to the application key generator when it is initialize at runtime

The “name” attribute is defined for RemoteAccessPoint. It specifies the locally unique Remote Access Point Name. Listing 4 shows a RemoteAccessPointType name attribute example.

Listing 4 RemoteAccessPoint Name Attribute Example

<RemoteAccessPoint name="RDOM1">
  <AccessPointId>Geneve</AccessPointId>
  <NetworkAddress>//bluestart:11023</NetworkAddress>
  <TpusrFile>/tja/lady-geneve/tpusr</TpusrFile>
</RemoteAccessPoint>

 

Session Profile

The Session Profile element is represented by SessionProfileType. It contains all the QoS parameters for a TDOMAIN session between an Oracle Tuxedo JCA Adapter Local Access Point and an Oracle Tuxedo Remote Access Point. Table 8 lists SessionProfileType elements.

 

Table 8 SessionProfileType Elements

Element Name	Type	Occurrence	Description
Security	string	0..1 Value set {NONE, APP_PW, DM_PW}	The type of /Domain authentication required. The default value is NONE.
BlockTime	int	0..1 Value range 0..2147483647	The maximum number of milliseconds allowed for a blocking outbound request using this profile. The default value is 60000.
Interoperate	boolean	0..1 Value set {true, false}	Specifies whether the session is allowed to interoperate with a remote Tuxedo 6.5 release GWTDOMAIN gateway or not. The default value is "false".
ConnectionPolicy	string	0..1 Value set {ON_DEMAND, ON_STARTUP, INCOMING_ONLY}	The condition under which this GWTDOMAIN session is established. The default value is ON_DEMAND.
ACLPolicy	string	0..1 Value set {Local, Global}	The ACL policy to be enforced on this GWTDOMAIN session. The default value is Local.
CredentialPolicy	string	0..1 Value set {Local, Global}	The user credential propagation policy. When the value Is Local, then there is no propagation. The default value is Local.
RetryInterval	long	0..1 Value range 0..2147483647	The number of seconds that a session waits between automatic connection establishment attempts. Set this element value only when ConnectionPolicy is set to ON_STARTUP. Default value is 60.
MaxRetries	long	0..1 Value range 0..922337206385775807	The maximum number of times that a session tries to establish a session connection to remote Oracle Tuxedo access points. Set this element only when ConnectionPolicy is set to ON_STARTUP. The default value is 922337206385775807.
CompressionLimit	int	0..1 Value range 0..2147483647	The compression threshold a session uses when sending data to a remote Oracle Tuxedo Access Point. Application buffers larger than this size are compressed. The default value is 2147483647.
MinEncryptBits	string	0..1 Value set {"0", "40", "56", "128", "256"}	The minimum encryption key length (in bits) a session uses when establishing a session connection. A value of 0 indicates no encryption is needed. Key strength of 256 bits is for SSL support only. The default value is 0.
MaxEncryptBits	string	0..1 Value set {"0", "40", "56", "128", "256"}	The maximum encryption key length (in bits) a session uses when establishing a session connection. A value of 0 indicates no encryption is used. Key strength of 256 bits is for SSL support only. The default value is 128.
KeepAlive	long	0..1 Value range {0..2147483647}	Specifies if a GWTDOMAIN session is configured with Application Level Keep Alive, and its maximum idle time before wait timer start ticking. The default value is 0.
KeepAliveWait	long	0..1 Value range {0..2147483647}	Specifies if a session requires the Application Level Keep Alive acknowledgement, and how long it will wait without receiving acknowledgement before declaring the connection inaccessible. Default value is 10.

The “name” attribute is defined for SessionProfileType. It is used by the Session object to get the correct session profile. Listing 5 shows a SessionProfileType name attribute example.

Listing 5 SessionProfile Name Attribute Example

<SessionProfile name="profile1">
  <Security>DM_PW</Security>
  <ConnectionPolicy>ON_STARTUP</ConnectionPolicy>
  <ACLPolicy>Global</ACLPolicy>
  <CredentialPolicy>Global</CredentialPolicy>
  <RetryInterval>100</RetryInterval>
</SessionProfile>

 

Session

The Session element is represented by "SessionType". It specifies a permissible connection between a Local Access Point and a Remote Access Point. Only one session can be configured between a Local Access Point and a Remote Access Point. Table 9 lists the SessionType elements.

 

Table 9 SessionType Elements

Element Name	Type	Occurrence	Description
LocalAccessPointName	string	1..1	The local access point that is used to compose a TDOMAIN session. This "LocalAccessPoint" refers to the "name" attribute of a “LocalAccessPoint” element.
RemoteAccessPointName	string	1..1	The remote access point that is used to compose a TDOMAIN session. This "LocalAccessPoint" refers to the "name" attribute of a “LocalAccessPoint” element.
ProfileName	string	1..1	The profile to be used for a session.
PasswordPair	complexType	0..2	The password pair used when SECURITY equals DM_PW to authentication the session.

The PasswordPair element is an anonymous complex type. At most, two password pairs can be configured. It allows user to configure passwords for Tuxedo Domain Session Authentication. Table 10 lists the PasswordPair elements.

 

Table 10 PasswordPair Elements

Element Name	Type	Occurrence	Description
LocalPasswordEncrypted	string	1..1	The encrypted local password. The password length cannot exceed 30 characters.
RemotePasswordEncrypted	string	1..1	The encrypted remote password. The password length cannot exceed 30 characters.
ActivationTime	string	0..1	The date and time string used to indicate when a password pair becomes effective. If not specified, then it is assumed already become effective. The format is YYYY:MM:DD:hh:mm:ss.
DeactivationTime	string	0..1	The date and time string used to indicate when a password pair becomes obsolete. If not specified, it assumes that it will never expire. Same format as ActivationTime.

The “name” attribute is defined for SessionType. It is used to identify a TDOMAIN session. Listing 6 shows a SessionType name attribute example.

Listing 6 SessionType Name Example

<Session name="session1_1">
  <LocalAccessPointName>LDOM1</LocalAccessPointName>
  <RemoteAccessPointName>RDOM1</RemoteAccessPointName>
  <ProfileName>profile1</ProfileName>
</Session>

 

Import

The Import element is represented by ImportType. It identifies an existing remote Tuxedo Application Domain resource that can be accessed by the Oracle Tuxedo JCA Adapter client. Table 11 lists ImportType elements.

 

Table 11 ImportType Elements

Element Name	Type	Occurrence	Description
RemoteName	string	0..1	The actual remote Tuxedo resource name being exported by the Oracle Tuxedo TDomain gateway. If not specified, it has the same value as the "name" attribute.
SessionName	string	1..unbounded	The name of the session that imports a resource from the remote Oracle Tuxedo Application Domain.
LoadBalancing	string	0..1 Value set {RoundRobin, Random}	The load balancing algorithm used for an imported resource. The default value is RoundRobin.

The “name” attribute is defined for ImportType. It specifies the resource name to used by a TPCALL or function name for "execute()" CCI interface. Listing 7 shows an ImportType name example.

Listing 7 ImportType Name Example

<Import name="TUXUPPER">
  <RemoteName>TOUPPER_1</RemoteName>
  <SessionNameList>session1</SessionNameList>
  <LoadBalancing>RoundRobin</LoadBalancing>
</Import>

 

Default Import

Oracle Tuxedo JCA Adapter allows you to access remote oracle Tuxedo services or resources through the configured sessions even when there is no oracle Tuxedo service or resource configured. This feature is called Default Import. If there is at least one configured Oracle Tuxedo service or resource, then this feature is automatically disabled and only the requested configured Oracle Tuxedo services or resources can be forwarded to Oracle Tuxedo.

When there is no Oracle Tuxedo service or resource configured as Import in the Oracle Tuxedo JCA Adapter configuration, then request filtering is executed and all requests are forwarded to Oracle Tuxedo using the name specified in the service request invocation. If more than one session is configured, then all the service requests are load-balanced among those configured sessions using a RoundRobin algorithm.

All Oracle Tuxedo services/resources must be accessible through the Oracle Tuxedo JCA Adapter (not only available in all Oracle Tuxedo application domains, but also accessible through all configured sessions).

Export

The Export element is represented by ExportType. It specifies a local resource that is accessible from a remote Tuxedo Application Domain. Table 12 lists ExportType elements.

 

Table 12 ExportType Elements

Element Name	Type	Occurrence	Description
RemoteName	string	0..1	Resource name the Oracle Tuxedo application uses to access service in an application server. If not specified, it has the same value as the name attribute.
SessionName	string	1..unbounded	The session that allows access to the local resource.
Type	string	0..1 Value set {EJB, POJO}	Type of resource. The default is EJB.
Source	string	1..1	This is the name of EJB or the target class of the POJO. Must be specified.
SourceLocation	string	0..1	This is the target jar for POJO. Its value is ignored if ServiceType is EJB.

The “name” attribute is attribute is defined for ExportType. It is used to identify an exported resource. Listing 8 shows an ExportType name example.

Listing 8 ExportType Name Example

<Export ResourceName="tolower" RemoteName="wtolower">
  <SessionNameList>session1</SessionNameList>
  <Type>EJB</Type>
  <Source>TolowerEJB</Source>
</Export>

 

Oracle Tuxedo JCA Adapter Deployment

Deploying an Oracle Tuxedo JCA Adapter involves repackaging the adapter and deploying it on a JCA 1.5 compliant JEE application server. In most cases, you only need to modify the ra.xml file (in the META-INF directory) to get the adapter up and running.

Deploying the Oracle Tuxedo JCA Adapter on an application server with JCA 1.5 support requires the following tasks:

•	Configuring the Deployment Descriptor

•	Repackaging the Oracle Tuxedo JCA Adapter

•	Change Connector Connection Pool Size.

The resource archive configure and repackage procedure is the same regardless the type of the targeted application; however, the deployment of the Oracle Tuxedo JCA Adapter is different from application server to application server.

For more information, see your target application server documentation.

Configuring the Deployment Descriptor

The main component used to configure and repackage the resource archive for deployment is the resource deployment descriptor (the ra.xml file in the META-INF directory). The resource adapter deployment descriptor must be configured before repacking the resources into a resource archive.

This XML-based text file and can be modified by using a text or XML editor. The downloaded Oracle Tuxedo JCA Adapter contains a simple version of the deployment descriptor to assist you configuring the Oracle Tuxedo JCA Adapter deployment.

Some of the ra.xml file fields should not be changed as they pertain to the Oracle Tuxedo JCA Adapter internally or its descriptive information; however, there are other fields you must modify to customize the operation and application.

The following are the common fields that you can customize:

Note:

It is recommended that you do not change fields that are not listed.

•	resourceadapter/config-property

•	outbound-resourceadapter/transaction-support

config-property

The "config-property" field is generally used to define Oracle Tuxedo JCA Adapter custom properties in the standard JCA deployment descriptor META-INF/ra.xml file. Table 13 lists the properties that are used to customize the Oracle Tuxedo JCA Adapter.

 

Table 13 Customization Properties

Property	Initial value (or default if not specified)	Type	Description
traceLevel	0	java.lang.String	Level of debug tracing. For more information, see Trace Level Support.
xaAffinity	true	java.lang.String	Turn on transaction-specific routing, for enhancing transaction performance.
keyFileName	c:\tuxedo\keyfile	java.lang.String	This is the full path name to the key file. This file contains key used to encrypt all the passwords in the "dmconfig" file.
dmconfig	C:\tuxedo\config.xml	java.lang.String	Full path name to the Oracle Tuxedo JCA Adapter configuration file
appManagedLocalTxTimeout	default value 300 seconds	java.lang.Integer	This is for transaction timeout value of the local transaction managed by the Oracle Tuxedo JCA Adapter.
throwFailureReplyException	default value true	java.lang.Boolean	This is for customize CCI execution interface to decide whether to throw exception or failure reply data in the output data record in case an Oracle Tuxedo service returns failure reply.

Listing 9 shows an example deployment descriptor file using the customization properties.

Listing 9 Deployment Descriptor File Example

<config-property>
  <config-property-name>traceLevel</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
  <config-property-value>0</config-property-value>
</config-property>
<config-property>
  <config-property-name>xaAffinity</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
  <config-property-value>true</config-property-value>
</config-property>
<config-property>
  <config-property-name>keyFileName</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
<config-property-value>C:\JCA\sample\adapter\foo.key</config-property-value>
</config-property>
<config-property>
  <config-property-name>dmconfig</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
<config-property-value>C:\JCA\sample\adapter\bdmconfig.xml</config-property-value>
</config-property>
<config-property>
  <config-property-name>throwFailureReplyException</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
<config-property-value>true</config-property-value</config-property-value>
</config-property>
<config-property>
  <config-property-name>appManagedLocalTxTimeout</config-property-name>
  <config-property-type>java.lang.Integer</config-property-type>
  <config-property-value>15</config-property-value>
</config-property>

 

Trace Level Support

Table 14 lists the trace-level control values.

 

Table 14 Trace Level Control Values

Values	Components Traced	Description
20000	GWT_IO	Gateway input and output, including the ATMI verbs.
25000	GWT_EX	More Gateway information.
50000	JATMI_IO	JATMI input and output, including low-level JATMI calls.
55000	JATMI_EX	More JATMI information.
100000	All components	Information on all Oracle Tuxedo JCA Adapter components.

Note:

Tracing is not executed for trace levels less that 20,000.

transaction-support

The "transaction-support" field describes the Oracle Tuxedo JCA Adapter level of transaction support. Oracle Tuxedo JCA Adapter supports XA transaction, the highest level of transaction support as defined by JEE Connector Architecture, in most circumstances you do not need to change its value; however, if your operating environment and application require different levels of transaction support, this field can be modified. Table 15 lists the valid transaction-support values.

 

Table 15 Transaction Support Values

Values	Description
NoTransaction	Used when Oracle Tuxedo application domain services do not support transactions.
LocalTransaction	Used for Enterprise Information Systems (EIS) that support transactions, but do not support the two-phase commit protocol. Note: However, since Oracle Tuxedo supports two-phase commit protocol, you can choose this value if Oracle Tuxedo is the only user application resource.
XATransaction (Global Transaction)	Used when you want to configure using XATransaction for the transaction type.

Repackaging the Oracle Tuxedo JCA Adapter

Most application servers allow the resource adapter to be deployed in un-archived form; however, it is best to repackage the adapter after modifying the resource deployment descriptor before it is deployed.

Repackaging requires converting the Oracle Tuxedo JCA Adapter into a resource archive using the "jar" command that comes with the JDK. The resource archive has the ".rar" extension.

For example, use the following command from the root directory of resource archive:
jar -cvf ../com.oracle.tuxedo.TuxedoAdapter.rar *

Change Connector Connection Pool Size

The application server has a default connection pool size. In most applications, the default connection pool size is large enough; however, in some situations the default connection pool size may not be enough. For example, the Oracle WebLogic Server has a default connection pool size equal to 10 which means it can support a maximum of 10 concurrent JCA clients using the same adapter to access remote Enterprise Information Systems (EIS). If an application wants to support more than 10 concurrent clients using the Oracle Tuxedo JCA adapter, then the application must expand the connection pool size.

For example, to change the connection pool size from default value to 20 in an Oracle WebLogic Server installation, you can modify the weblogic-ra.xml file in the META-INF directory as shown in Listing 10.

Listing 10 Change Oracle WebLogic Connector Connection Pool Size

 <outbound-resource-adapter>
  <default-connection-properties>
    <pool-params>
      <initial-capacity>15</initial-capacity>
      <max-capacity>20</max-capacity>
    </pool-params>
  </default-connection-properties>
  <connction-definition-group>
  ...
  </connection-definition-group>
</outbound-resource-adapter>

 

Note:

Different application servers have require different connection pool size configuration. Some application servers use the custom deployment descriptor to configure connection pool size (such as Oracle WebLogic Server). Other application servers use console configuration (such as IBM WebSphere).

For more information, see your application server documentation.

Oracle Tuxedo JCA Adapter Management

After deploying the Oracle Tuxedo JCA Adapter, you may want to expand or change the application. To do so, you must modify the adapter configuration. Modifying the Oracle Tuxedo JCA Adapter configuration involves using a text editor or XML editor to alter the contents of the configured adapter configuration.

For Oracle WebLogic Server and JBOSS application server environments, you must do the following steps:

1.	Modify the configuration file

2.	Stop the adapter

3.	Restart the adapter with the new configuration file

Note:

For IBM WebSphere application servers, you must stop the application server and then restart it.

Runtime Configuration Updating

The Oracle Tuxedo JCA Adapter does not support runtime dynamic configuration modification without stopping and restarting for the configuration changes to take effect.

Oracle Tuxedo JCA Adapter Security

The Oracle Tuxedo JCA Adapter supports data security using either Link-Level Encryption or Secured Socket Layer. It also provides outbound identity propagation from application servers to Oracle Tuxedo. This provides finer grain control over Oracle Tuxedo resource access.

The "DMConfigChecker" utility is used to ensure security. This utility not only checks the configuration file against the schema, but also converts the password into an encrypted form for better security. If encryption is required, you must run DMConfigChecker before starting the Oracle Tuxedo JCA Adapter. For more information, see the Oracle Tuxedo JCA Reference Guide.

Link-Level Encryption (LLE)

Link-Level Encryption (LLE), is a fast, proprietary technology that encrypts all user message flow between the Oracle Tuxedo JCA Adapter and the Tuxedo TDomain gateway. It supports 40-bit, 56-bit and 128-bit encryption strength. This feature is enabled by configuring MaxEncryptBits and MinEncryptBits in the SessionProfile of the adapter configuration.

The default value for MaxEncryptBits is 128-bit and the default value for MinEncryptBits is 0. The permissible values for both elements are 0 (no encryption), 40-bit, 56-bit, 128-bit, and 256-bit. 256-bit encryption is for SSL AES 256-bit encryption (LLE does not support 256-bit encryption). The MinEncryptBits value must be smaller than or equal to the MaxEncryptBits value.

Notes:

If SSL is not configured and MaxEncryptBits is set to256-bit, MaxEncryptBits is scaled down to maximum 128-bit LLE.

LLE must also be configured in the GWTDOMAIN gateway.

Secured Socket Layer (SSL) Encryption

The Oracle Tuxedo JCA Adapter also support Secure Socket Layer (SSL) encryption. To enable SSL encryption, you must do the following:

•	Configure Session Profile MinEncryptBits and MaxEncryptBits.

•	Configure Local Access Point SSLInfo.

Java Key Store (JKS) is supported. Both "IdentityKeyStoreFileName" and "TrustKeyStoreFileName" points to the JKS type.

Note:

By default, mutual authentication is disabled; however, it can be enabled it setting the "MutualAuthenticationRequired" element to "true".

An sample SSLInfo configuration example is shown in Listing 11.

Listing 11 SSLInfo Configuration Example

<LocalAccessPoint name="jdom">
...
  <SSLInfo>
<IdentityKeyStoreFileName>c:\test\cert\test_users.jks</IdentityKeyStoreFileName>
<IdentityKeyStorePassPhraseEncrypted>passphrase</IdentityKeyStorePassPhraseEncrypted>
    <PrivateKeyAlias>tester</PrivateKeyAlias>
<PrivateKeyPassPhraseEncrypted>passphrase</privatekeypassphraseencrypted>
    <TrustKeyStoreFileName>c:\test\cert\trusted.jks</TrustKeyStoreFileName>
<TrustKeyStorePassPhraseEncrypted>passphrase</TrustKeyStorePassPhraseEncrypted>
  </SSLInfo>
</LocalAccessPoint>

 

In this example, you must run the DMConfigChecker utility before it can be used by the Oracle Tuxedo JCA Adapter (since three elements require encryption).

Session Authentication

The Oracle Tuxedo JCA Adapter supports session authentication when SSL is not configured, but the "Security" of the SessionProfile must be configured using "DM_PW" or "APP_PW".

When the security is configured using "APP_PW", it uses the Oracle Tuxedo Application Password as a key to encrypt/decrypt the authenticator. Only one Application Password can be configured for the Oracle Tuxedo JCA Adapter. It is configured in the Resources "ApplicationPasswordEncrypted" element in the configuration file.

When security is configured with "DM_PW", it uses the Domain Password as a key to encrypt/decrypt the authenticator. At most, two passwords pairs can be configured for any given session configured.

Each password pair consists of one local password and one remote password and their activation/deactivation time. The activation/deactivation time uses the format "YYYY:MM:DD:hh:mm:ss" (for example: 2009:01:01:12:00:00).

The deactivation time must be later than the activation time. If the activation time is not specified it indicates that the password is already activated when the adapter is booted. If the deactivation time is not specified, then the password never expires.

If a password pair expired while the session already established, it will not invalidate the session and starts the session negotiation process. However, if a password pair expired before the session negotiation started, then that password pair is not be used for authentication. If no valid password pair is found during session authentication, then the session cannot be established.

If SSL is required for a Local Access Point, then the session between that Local Access Point and any Remote Access Point uses SSL to underline the data privacy mechanism. In this case, Session Authentication is not be performed even if "SessionProfile/Security" is configured with the correct values.

Appkey Generator

The AppKey Generator is a pluggable class that is used to determine user information to be sent from the application server to Tuxedo. Oracle Tuxedo uses this information to determine user access rights to a Tuxedo resource. This is also called ACL.

The Oracle Tuxedo JCA Adapter comes preconfigured with a default AppKey Generator class to work with default Oracle Tuxedo Authentication, Authorization, and Auditing plug-in (AAA). However, if Access Control is required using the default Oracle Tuxedo AAA plug-in, then you must also configure the TpusrFile element in the Remote Access Point. The TpusrFile element in RemoteAccessPoint points to an Oracle Tuxedo "tpusr" file.

The easiest way to do this is to copy it from Oracle Tuxedo or share it with Oracle Tuxedo if both are running on the same machine. If the RemoteAccessPoint TpusrFile file is not configured, the Oracle JCA Adapter also looks for the TpusrFile file in the Resources section.

You must also set "CredentialPolicy" to "Global" in order to allow the AAA security token to move across the network from the Oracle Tuxedo JCA Adapter to an Oracle Tuxedo application domain.

There are other configuration elements in the RemoteAccessPoint that further give you the ability to customize the AppKey Generator plug-in. The "AllowAnonymous" element tells adapter whether or not anonymous access to Oracle Tuxedo is allowed.

Note:

By default, anonymous access is not allowed; the application server performs authentication.

The "DefaultApplicationKey" is the key value used by anonymous users to access Oracle Tuxedo (the default value is "-1"). The default AppKey Generator assumes the anonymous user name is "anonymous".

In order to have successful identity propagation (in addition to all the previously described configuration options), you must also configure the "Principal Mapping" element in the host application server JCA container.

For more information, see your target application server documentation.

An example Oracle JCA Adapter configuration file identity propagation example is shown in Listing 12.

Listing 12 Identity Propagation Example

<RemoteAccessPoint name="tdom">
  ...
  <TpusrFile>c:\test\data\tpusr</TpusrFile>
  <AllowAnonymous>true</AllowAnonymous>
  ...
</RemoteAccessPoint>
<SessionProfile name="prof_1">
  ...
  <CredentialPolicy>global</CredentialPolicy>
  ...
</SessionProfile>

 

See Also

•	Oracle Tuxedo JCA Adapter Programming Guide

•	Oracle Tuxedo JCA Adapter Reference Guide