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.
Table 1 Resource Archive Content
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.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.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:
•
•
•
Table 2 TuxedoConnectorType Elements Listing 1 TuxedoConnector Tags ExampleThe 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
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 ExampleThe 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 The connection principal name. It must be globally unique.If not specified, it uses the locally unique LocalAccessPoint “name” attribute value (see Listing 3). 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. 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 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.”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 If not specified, it uses the locally unique RemoteAccessPoint “name” attribute value (see Listing 4). 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. 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 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 ExampleThe 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 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. 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. 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. 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 ExampleThe 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 The local access point that is used to compose a TDOMAIN session. This "LocalAccessPoint" refers to the "name" attribute of a “LocalAccessPoint” element. The remote access point that is used to compose a TDOMAIN session. This "LocalAccessPoint" refers to the "name" attribute of a “LocalAccessPoint” element. 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 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 ExampleThe 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 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 ExampleOracle 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).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 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 ExampleDeploying 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.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.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.
Note: It is recommended that you do not change fields that are not listed.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 Listing 9 shows an example deployment descriptor file using the customization properties.Listing 9 Deployment Descriptor File ExampleTable 14 lists the trace-level control values.
Table 14 Trace Level Control Values 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 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. 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 *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.
Note: 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), 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.
•
• 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".Listing 11 SSLInfo Configuration ExampleIn this example, you must run the DMConfigChecker utility before it can be used by the Oracle Tuxedo JCA Adapter (since three elements require encryption).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).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.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.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.An example Oracle JCA Adapter configuration file identity propagation example is shown in Listing 12.Listing 12 Identity Propagation Example