Table 1 lists the Oracle Tuxedo JCA Adapter resource archive file content.
|
|
|
|
|
|
Note: For WebLogic Server, com.bea.core.jatmi_1.3.1.0.jar must be exported using EXT_PRE_CLASSPATH to replace the one that come with WebLogic Server installation. This environmental variable must be set before starting WebLogic Server.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The dmconfig-based resource adapter deployment descriptor.
You can choose to use dmconfig to configure the Oracle Tuxedo JCA Adapter and then modify the configuration using the sample dmconfig.xml and server.ra.xml file.
|
|
Note:
|
The com.bea.core.i18n_1.4.0.0.jar is for Java application servers other than WebLogic Server; do not set it to replace WebLogic Server. The only file that needs to be overriden is the WLS jatmi.jar file.
|
Listing 1 shows a Resource Adapter Deployment Descriptor fragment that enables using an XML-based
dmconfiguration file.
Listing 2 shows a Resource Adapter Deployment Descriptor fragment that enables using Custom Properties based configuration.
Listing 3shows a Resource Adapter Deployment Descriptor fragment that enables using factory-based configuration.
If the resourceadapter-class class configured is
TuxedoResourceAdapter then all the resource adapter deployment-based configuration will be ignored.
The "default" configuration works with dmconfig file-based configuration, resource adapter descriptor property based configuration, and factory based configuration. It makes it un-necessary to configure
LocalAccessPoint,
SessionProfile,
Session, and import in some situations. In those instances user may only need to configure RemoteAccessPoint in the
dmconfig file or
remoteAccessPontSpec in the
Resource Adapter Deployment Descriptor file, or
remoteAccessPointSpec in the factory-based configuration file, this greatly enhances the usability of Oracle Tuxedo JCA Adapter.
GWTDOMAIN gateway must be modified to allow Dynamic RemoteAccessPoint (RAP) Registration. If
DYNAMIC_RAP is set to
YES, it will also update the in-memory database of the status of the connection from those dynamically registered RAP. If the connection from those dynamically registered RAP lost then the information about that RAP will be removed from the SHM database.
GWADM must be modified to process the
DM MIB correctly to reflect the connection status of those dynamically registered RAP. When the connection from those dynamically registered RAP lost their entries in the SHM database will also be removed so that the
DM MIB query can return the connection status correctly.
The DM_CONNECTION Oracle Tuxedo /Domain DMIB call returns all the connected dynamically registered RemoteAccessPoint. All other dynamically registered RemoteAccessPoint that are not connected will not be shown.
The OPENCONNECTION DMIB request will not be supported to connect to those dynamically registered RAP.
The CLOSECONNECTION Oracle Tuxedo
/DMIB request closes the connection and remove the session from those dynamically registered RemoteAccessPoint, and returns its connection status as
'UNKNOWN.
The PERSISTENT_DISCONNECT type of
CONNECTION_POLICY will be honored that means when
PERSISTENT_DISCONNECT is in effect all connections request from any RAP, whether they are dynamically or non-dynamically registered, will be rejected.
The adapter-wise default SessionProfile can not be modified when using dmconfig based configuration; however, if user needs different
SessionProfile other than the default one then user should configure the appropriate
SessionProfile, and assign it to the target Session.
The adapter-wise default SessionProfile can be modified when using Deployment Descriptor based configuration using a set of custom properties to achieve it. Since there is no specific session profile can be configured explicitly when using Deployment Descriptor based configuration, this adapter-wise default
SessionProfile will be used for all the Sessions.
The factory-based configuration adds the support for factory-wise default SessionProfile in addition to the adapter-wise default
SessionProfile. User using this configuration method cannot modify the adapter-wise default
SessionProfile; however, user is allowed to modify factory-wise default
SessionProfile using a set of factory custom properties. If the default
SessionProfile is not suitable for any connection factories created connection then user can configure the factory-wise default
SessionProfile for each connection factories.
Table 2 lists the default configuration
SessionProfile type elements.
|
Note:
|
The SessionProfile related property configured in the resource adapter deployment descriptor file as shown in Listing 19 are used in the construction of the default SessionProfile.
|
Listing 4 shows an example that tells the Oracle Tuxedo JCA Adapter to use a 'dmconfig' configuration file. The full path name to the configuration file is:
/home/work/adapter/dmconfig.xml.
Listing 5 shows an example telling the Oracle Tuxedo JCA Adapter that it uses a 'dmconfig' configuration file and it is packaged as part of the resource archive with the resource file name 'dmconfig.xml'. However, if this configuration resource file is not found in the archive it will be treated as a configuration file located in the current working directory.
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 3:
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 4 lists the "
ResourceType" elements.
Listing 7 shows a "
Resources" configuration example.
Listing 8 shows an example that tells Oracle Tuxedo JCA Adapter that a key store resource is configured.
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 if encryption is required.
Table 6 lists
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 9.
'LDOM1' must be locally unique. '
Gotfried' must be globally unique. If the '
AccessPointId' element is not specified, the value of the name attribute is used as '
AccessPointId'. In this scenario, the value of the name attribute must be globally unique.
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 8 lists
CustomApplicationKey elements.
The “name” attribute is defined for
RemoteAccessPoint. It specifies the
locally unique Remote Access Point Name.
Listing 10 shows a
RemoteAccessPointType name attribute example.
'RDOM1' must be locally unique. '
Geneve' must be globally unique. If the '
AccessPointId' element is not specified, the value of the name attribute is used as '
AccessPointId'. In this scenario, the value of the name attribute must be globally unique.
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 9 lists
SessionProfileType elements.
The “name” attribute is defined for
SessionProfileType. It is used by the Session object to get the correct session profile.
Listing 11 shows a
SessionProfileType name attribute example.
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 10 lists the
SessionType elements.
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 11 lists the
PasswordPair elements.
The “name” attribute is defined for
SessionType. It is used to identify a TDOMAIN session.
Listing 12 shows a
SessionType name attribute example.
|
•
|
name: specifies the resource name to used by a TPCALL or function name for " execute()" CCI interface.
|
|
•
|
autotran: enables/disables of AUTOTRAN. It only accepts true or false values. If it is set to true then when this imported resource is to be invoked by Oracle Tuxedo JCA Adapter client outside a global or local transaction then the Oracle Tuxedo JCA Adapter starts a transaction with a remote Oracle Tuxedo Domain.
|
|
•
|
trantime: specifies the transaction timeout value for AUTOTRAN of this resource. The value is measured in seconds. If not specified and AUTOTRAN is required then the 'appManagedLocalTxTimeout' property of the resource adapter deployment descriptor will be used.
|
If appManagedLocalTxTimeout is not specified then JVM property
com.oracle.tuxedo.adapter.appManagedLocalTxTimeout is used.
If com.oracle.tuxedo.adapter.appManagedLocalTxTime JVM property is not specified, it defaults to 300 seconds.
Listing 13 shows an
ImportType name example that describes an imported resource with name
TUXUPPER. The
AUTOTRAN transaction timeout is set to 10 seconds
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This is the EJB name or the target class of the POJO. It must be specified.
|
|
|
|
|
|
The “name” attribute is attribute is defined for
ExportType. It is used to identify an exported resource.
Listing 14 shows an
ExportType name example.
Table 14 lists the resource adapter deployment descriptor
Resources properties.
Listing 15 shows a configuration example that describes two VIEW32 classes information using resource adapter deployment descriptor- based custom property configuration.
The majority of the LocalAccessPoint type elements are not available in a resource adapter descriptor-based configuration; however, a single
localAccessPointSpec can be specified.
Table 15 lists the resource adapter deployment descriptor
LocalAccessPoint properties.
The localAccessPointSpec property is optional. When specified in a non-clustered environment then it is useful if you want to have all the configuration information in the resource adapter deployment descriptor file. However, when it is specified in a clustered environment where the configuration is copied to all cluster nodes, all Oracle Tuxedo JCA Adapters have the same access point identification.In this situation, the connection behavior becomes unpredictable and is not supported.
Listing 16 provides an
localAccessPointSpec custom configuration example.
This example specifies a LocalAccessPoint with
AccessPointName and
AccessPointId equal to
jdom_id is created and listens for the incoming connection requests at port 12345 on the local host.
If the default LocalAccessPoint is created, the connection policy can only be
"ON_STARTUP", the listening endpoint is not created.
When "default LocalAccessPoint" is constructed by the Oracle Tuxedo JCA Adapter dynamically there is no listening endpoint and it will be purely for Client-Side only operation mode. There is no incoming connection request possible.
The RemoteAccessPoint is represented by a text string that contains both networking address and per
RemoteAccessPoint access control-related information; however, in resource adapter deployment descriptor property based configuration it can be represented by a single
remoteAccessPointSpec property. The
remoteAccessPointSpec property will be a comma-separated list and a comma separates each remote access point. Each remote access point is represented in a specific format described in the sample after the following table.
Table 16 lists the resource adapter deployment descriptor
RemoteAccessPoint-related properties.
|
|
|
|
|
|
|
|
|
This contains both NetworkAddress and AccessPointId plus the name attribute. This is a comma-separated list of RemoteAccessPoint. The domainId in each entry is used to replace AccessPointId.
This domainId is used by default as connection principal name that is used to identify a remote access point when attempting to establish a session with remote Tuxedo access point. If not specified then it is an error in Deployment Descriptor based configuration; and the name has to be globally unique.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If property rapApplicationKeyClass is not specified then
rapApplicationKeyClassParam will be ignored if one is configured.
Listing 17 provides an example that configures two
RemoteAccessPoint. The first is accessible through domain
guinevre with network address
//bluestar:11023. The second is accessible through domain
galahad with network address
//orion:37456.
Both remote domains guinevre and
galahad will have the same QoS associate with them. In this case if
rapApplicationKeyClass and
rapApplicationKeyClassParam are specified they will be treated as if they are available to both
RemoteAccessPoint guinevre and
galahad, user must make the
rapApplicationKeyClass available to both RAP with same fully qualified class path otherwise the Oracle Tuxedo JCA Adapter will fail to start.
Listing 18 provides an example that configures two
RemoteAccessPoint with failover address. The first is accessible through domain
guinevre with primary network address
//bluestar:11023, and the back up network address
//orion:12345.
There can be one and only one remoteAccessPointSpec property be specified in the resource adapter deployment descriptor file. If there are more than one configured then the application server's JCA container will only honor the last one configured.
There is no default RemoteAccessPoint so if
remoteAccessPointSpec property is not configured then there is no dynamically created RemoteAccessPoint and this will make Oracle Tuxedo JCA Adapter useless even though it still can be started. To configure
RemoteAccessPoint through
remoteAccessPointSpec property the "
resourceadapter-class" element in the resource adapter deployment descriptor file must be configured using
TuxedoClientSideResourceAdapter.
Table 17 lists the resource adapter deployment descriptor
SessionProfile properties.
Listing 19 provides a
SessionProfile configuration example.
All these SessionProfile related property configured in the resource adapter deployment descriptor file is used in the construction of the default
SessionProfile.
The LoadBalancing algorithm cannot be specified and uses
RoundRobin. If
impResourceName is specified then there is no default Import be created by Oracle Tuxedo JCA Adapter.
Table 18 lists the resource adapter deployment descriptor Import-Related property.
Listing 20 provides an
impResourceName example. This property is limited to the resource adapter deployment descriptor based configuration so a "resourceadapter-class" must be configured with
TuxedoClientSideResourceAdapter.
Table 19 lists these adapter-wise custom properties in the resource adapter deployment descriptor that are supported by factory-based configuration.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Configure whether a TuxedoFailureReplyException will be thrown or not if a failure reply is received from Tuxedo. It will be used by factory if factory-wise throwFailureReplyException is not configured.
|
The adapter-wise "appManagedLocalTxTimeout" is configured in "resourceadapter" type in the Resource Adapter Deployment Descriptor(RADD), a.k.a. ra.xml, file as "config-property".
Listing 21 shows an example using AUTOTRAN with transaction timeout in ra.xml file.
Listing 22 shows a configuration example that describes two VIEW32 classes information in the Resource Adapter Deployment Descriptor for factory-based configuration.
|
|
|
|
|
|
|
|
|
Defines whether AUTOTRAN is available for requests using this factory. If not configured then use adapter-wise AUTOTRAN configuration. If configured, whether it is true or false, will override adapter-wise AUTOTRAN configuration.
|
|
|
|
|
Define the transaction timeout used by AUTOTRAN or client application managed transaction. If not configured then use adapter-wise local TX timeout. It is measured in second.
|
|
|
|
|
Configure whether a TuxedoFailureReplyException will be thrown or not if a failure reply received from Tuxedo. If it is not configured then adapter-wise setting will be used.
|
|
1.
|
factory appManagedLocalTxTimeout property
|
A connection factory name can be specified by using connectionFactoryName property. Although this property is optional, it is recommended to configure it if transaction is possible for service request originated from this connection factory, and also if user want to use DMMIB to configure a
DM_REMOTE_DOMAINS in Tuxedo /Domain configuration dynamically.
Table 24 is the table for LocalAccessPoint related properties for the factory-based configuration.
It is optional to specify localAccessPointSpec property. If it is not specified then default LocalAccessPoint will be used. When default LocalAccessPoint is used for this factory it is recommended to also configure
connectionFactoryName.
Listing 25 shows the example of using WebLogic's
weblogic-ra.xml file.
|
|
|
|
|
|
|
|
|
This property contains both NetworkAddress and AccessPointId plus the name attribute. This is a comma separated list of RemoteAccessPoint. The domainId in each entry is used to replace AccessPointId. This domainId is used by default as connection principal name that is used to identify a remote access point when attempting to establish a session with remote Tuxedo access point. If not specified then it is an error in Client-Side only operation mode, and it has to be globally unique.
The NetworkAddress also become part of the specification. The NetworkAddress contains both host network address and port number of the remote Tuxedo access point. Specify the TCP/.IP address in the format of //hostname:port or //#.#.#.#:port.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
There can be one and only one remoteAccessPointSpec be specified for each factory. If
rapApplicationKeyClass and
rapApplicationKeyClassParam are specified they will be used for identity propagation for both guinevre and galahad.
The remoteAccessPointSpec property has been enhanced to be able to configure more RemoteAccessPoint and Session related attributes. Comma is used to separate these attributes. Each attribute is a name and value pair. The following is the list of attributes supported.
|
•
|
domainId - The remote access point Id. It must be specified.
|
|
•
|
lPasswd1 - Local password of password pair 1, can be in either clear text or cipher text.
|
|
•
|
lPasswd2 - Local password of password pair 2, can be in either clear text or cipher text.
|
|
•
|
rPasswd1 - Remote password of password pair 1, can be in either clear text or cipher text.
|
|
•
|
rPasswd2 - Remote password of password pair 2, can be in either clear text or cipher text.
|
Listing 29 shows the WebLogic example of weblogic-ra.xml:
A session connects an Oracle Tuxedo JCA Adapter LocalAccessPoint to a remote Tuxedo GWTDOMAIN gateway. In factory-based configuration there is no need to specify session explicitly so there is no "Session" related property available, and all the sessions available in a factory will be default Session. The Oracle Tuxedo JCA Adapter will create a session for every possible LocalAccessPoint and RemoteAccessPoint combinations for a connection factory. Since there can only be one LocalAccessPoint per connection factory configuration so there can be at most 1xN number of sessions possible where the 'N' is the number of RemoteAccessPoint. For instance, if your configured the following, using WebLogic's weblogic-ra.xml as example
<value>//localhost:12498/domainId=TDOM3_ID,
lPasswd1={Salted-AES}xNgOdUuXB7Z49D0cssluxA==,
rPasswd1={Salted-AES}hAIzbPI+YyaeuHX0A9Umqg==</value>
Change or add the desired remoteAccessPointSpec value to the "Value" field, then click on the "Apply" button and the click on "Save".
If user configures applicationPassword property for WebSphere 7.0 user should not encrypt the password using
com.oracle.tuxedo.tools.EncryptPassword tool because WebSphere 7.0 will encrypt the password.
|
•
|
Dropping the .rar file in a generic auto-deployment location
|
|
1.
|
Unjar the com.oracle.tuxedo.TuxedoAdapter.rar file into a directory.
|
If TuxedoResourceAdapter is used, then the
dmconfig property must be configured. If the configured
dmconfig property contains only file name without any path information, the configuration is loaded as a resource as shown in
Listing 32.
If the dmconfig property configured contains path information, it is treated and loaded as file as shown in
Listing 33. If the file fails to open, the resource adapter will not start and a
ResourceAdapterException is thrown.
If the dmconfig file does not have any
LocalAccessPoint configured then it creates a single default
LocalAccessPoint. This default
LocalAccessPoint can only have a session with
RemoteAccessPoint using the default
SessionProfile; it can only initiate outbound connection.
The Adapter creates a default SessionProfile using all the default values (except for the
ConnectionPolicy which is always
ON_STARTUP for the default
SessionProfile. If
SessionProfile is configured in the
dmconfig file, it is constructed in addition to the default
SessionProfile.
If the dmconfig file does not have
SessionProfile configured, the adapter creates
RemoteAccessPoint Sessions if the default
LocalAccessPoint is created.
The resourceadapter-class element in the resource descriptor
ra.xml file should contain the
com.oracle.tuxedo.adapter.TuxedoResourceAdapter fully qualified class name as its value as show in
Listing 34.
If TuxedoClientSideResourceAdapter is configured, then
dmconfig configuration is ignored. When this class of resource adapter is configured it assumes all the configuration information is in the resource adapter Java Bean provided by the application server JCA container.
If no localAccessPointSpec property is configured, a default
LocalAccessPoint is created for the resource adapter deployment descriptor file-based configuration. The "at least one
LocalAccessPoint must be configured" restriction in the 11gR1 11.1.1.1.0 release is removed.
If remoteAccessPointSpec property is configured, it is used to construct
RemoteAccessPoint. If there is no
remoteAccessPointSpec property configured, the configuration cannot be used and a warning message is logged in the adapter log file.
A default SessionProfile is created using information from properties related to
Session Profile. If no session profile related properties are configured, the default
SessionProfile is constructed using only the default values. It creates sessions from the
LocalAccessPoint to every
RemoteAccessPoint using the default
SessionProfile.
The resourceadapter-class element in the resource descriptor
ra.xml file, should contain the
com.oracle.tuxedo.adapter.TuxedoClientSideResourceAdapter fully qualified class name as its value as shown in
Listing 35.
If TuxedoFBCResourceAdapter is configured, then dmconfig configuration and Resource Adapter Deployment Descriptor specific configuration properties are ignored. When this class of resource adapter is configured it assumes all the configuration information is in the resource adapter Java Bean provided by the application server JCA container and the Managed Connection Factory Java Bean that is also provided by the application server JCA container.
If no localAccessPointSpec property is configured for a factory, a default
LocaAccessPoint is created to that factory. A
remoteAccessPointSpec must be configured for each factory, and they will be used to construct
RemoteAccessPoint.
A default SessionProfile is created for each factory using information from the properties related to
SessionProfile of that factory. If no session profile related properties are configured for a factory, the factory will use default
SessionProfile.
The resourceadapter-class element in the resource deployment descriptor
ra.xml file, should contain the
com.oracle.tuxedo.adapter.TuxedoFBCResourceAdapter fully qualified class name as its value as shown in
Listing 36.
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 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 28 lists the properties that are used to customize the Oracle Tuxedo JCA Adapter.
Table 29 lists the trace-level control values.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
JATMI input and output, including low-level JATMI calls.
|
|
|
|
|
|
|
|
|
Listing 37 shows an example deployment descriptor file using the customization properties.
The link level fail over gives user ability to specify different Access Point network addresses. This is applicable to both Local Access Point and Remote Access Point. In dmconfig file configuration user can specify multiple NetworkAddress element in the RemoteAccessPoint and LocalAccessPoint. The order of these network address dictate the order of preference. The Oracle Tuxedo JCA Adapter will attempt using the first network address in the LocalAccess Point to establish listening endpoint, if it failed it will try the next one until either listening endpoint established or it exhausted all the network addresses. The Oracle Tuxedo JCA Adapter will attempt to use the first network address to establish connection with remote Tuxedo
GWTDOMAIN gateway, if it failed it will try the next one until either connection established or it exhausted all the network addresses. However, there is no link level fail back. The following example shows using dmconfig file configuration that a local access point,
LDOM1, has 2 network addresses for link level failover; and it also shows that a remote access point,
RDOM1, has 2 network addresses for link level fail over.
The service level fail back is automatic when ConnectionPolicy is set to
ON_STARTUP for all the sessions of a particular imported resource. With the above example if session_1 is not available then all the service request destined to session_1 will be routed to session_3; when session_1 become available then service request will be routed back to the session_1 the primary route.
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.
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.
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.
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".
