Both access point types can have a name and
identifier. The
name is used to identify an access point configuration entry in a configuration; it must be unique to the configuration. The
identifier is used to specify an access point during TDOMAIN Session establishment; it must be globally unique within all interconnected domains.
Copy the downloaded .zip file to a target directory with correct read and write access control. Unzip the file and browse the contents.
Table 1 lists the Tuxedo JCA Adapter resource
.zip file contents.
Table 2 lists the Tuxedo JCA Adapter resource archive file content.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If you choose to use dmconfig to configure the Tuxedo JCA Adapter, you can rename this sample deployment descriptor to ra.xml and modify it to point to your dmconfig file. You can use the sample dmconfig.xml as base for your dmconfig 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 overridden is the WebLogic Server com.bea.core.jatmi_xxxx.jar file.
|
|
1.
|
Copy com.oracle.tuxedo.adapter.tja_soa_1.3.0.0.jar to $JDEVELOPER_HOME/jdev/lib/patches
|
|
2.
|
Copy tuxedoAdpater-config.xml to $JDEVELOPER_HOME/integration/seed/soa/configuration
|
|
3.
|
Save $JDEVELOPER_HOME/integration/seed/soa/configuration/soa-config.xml if needed.
|
|
4.
|
Copy soa-config.xml from the Tuxedo JCA Adapter .zip file to $JDEVELOPER_HOME/integration/seed/soa/configuration
|
Listing 1 shows a Resource Adapter Deployment Descriptor fragment that enables using an XML-based
dmconfig 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 /Domain configuration, dmconfig file, is configured in the deployment descriptor file, but the
"resourceadapter-class" class configured is not
com.oracle.tuxedo.adapter.TuxedoResourceAdapter, then the
dmconfig information is to be ignored.
If the resourceadapter-class class configured is
TuxedoResourceAdapter, all resource adapter configuration-related custom properties are ignored.
The default LocalAccessPoint does not allow you not to configure a
LocalAccessPoint. It does not have a listening end point and will not accept inbound connecting requests from Oracle Tuxedo GWTDOMAIN gateway. The Connection Policy can only be "
ON_STARTUP".
In a dmconfig-based configuration and Deployment Descriptor-based configuration, there can be only one
default LocalAccessPoint; however, for a factory- based configuration each factory can have its own
default LocalAccessPoint.
The default LocalAccessPoint, when used, creates a UUID-based
LocalAccessPointId. This UUID-based
LocalAccessPointId is written in a file named
.lapid, but for factory-based configurations, a file named "
.lapid.<factory-name>" is created.
In a dmconfig-based configuration, the
default LocalAccessPoint does not support SSL. If you need SSL, a
LocalAccessPoint must be configured.
In Deployment Descriptor-based configuration the default LocalAccessPoint supports SSL in a limited fashion by configuring custom properties
identityKeyStoreFileName,
privateKeyAlias,
trustedKeyStoreFileName in the Resource Adapter Deployment Descriptor. You cannot configure
Key Store,
Identity Alias, and
Trusted Certificate Store with password protection.
In order to make default LocalAccessPoint to work, Oracle Tuxedo GWTDOMAIN gateway configuration is required in order to make this simplified /Domain configuration to work.
Currently, only Tuxedo JCA Adapter with default LocalAccessPoint enabled has the ability to connect to a remote Oracle Tuxedo GWTDOMAIN gateway. When GWTDOMAIN receives a connection request, it checks whether the remote domain is configured. If not, then it checks whether
DYNAMIC_RAP is set to
YES. If it is set to
YES, it checks the message data to determine whether the request came from a legitimate Tuxedo JCA Adapter.
GWADM must be modified to process the
DM MIB correctly to reflect the connection status of dynamically registered RAPs. When the connection from dynamically registered RAP s is lost, their entries in the in memory database is also 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
RemoteAccessPoints that are not connected are not shown.
The OPENCONNECTION DMIB request is not supported to connect to those dynamically registered RAPs.
The CLOSECONNECTION Oracle Tuxedo
/DMIB request closes the connection and removes the session from those dynamically registered
RemoteAccessPoint, and returns its connection status as
'UNKNOWN.
If the PERSISTENT_DISCONNECT type of
CONNECTION_POLICY is honored and
PERSISTENT_DISCONNECT is in effect, all connection requests from any RAP (whether they are dynamically or non-dynamically registered), are rejected.
The adapter-wide default SessionProfile cannot be modified when using
dmconfig=based configuration; however, if you need a different
SessionProfile other than the default one, you should configure the appropriate
SessionProfile, and assign it to the target
Session.
The adapter-wise default SessionProfile can be modified when using Resource Deployment Descriptor-based configuration with a set of custom properties. Since there is no specific session profile that can be configured explicitly using a Deployment Descriptor-based configuration, this adapter-wise default
SessionProfile is used for all Sessions.
The factory-based configuration adds the support for factory-wise default SessionProfile in addition to the adapter-wise default
SessionProfile. If you use this configuration method, you cannot modify the adapter-wise default
SessionProfile; however, you can modify the 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 you can configure the factory-wise default
SessionProfile for each connection factories.
Table 3 lists the default configuration
SessionProfile type elements.
|
Note:
|
The SessionProfile related properties are configured in the Resource Adapter Deployment Descriptor file shown in Table 3 are used in the construction of the default SessionProfile.
|
If Resource Adapter Deployment Descriptor-based configuration or factory-based configuration is used, or there is no Session configured in the
dmconfig file, the session is implicitly created between all
local access points and all
remote access points. This is called default Session. If default Session is used, it can only use the adapter-wise default
SessionProfile when Resource Adapter Deployment Descriptor-based or
dmconfig-based configuration is used. The factory-based configuration uses the factory-wise default
SessionProfile. Any factory not configured with its own default
SessionProfile uses the adapter-wise default
SessionProfile.
For example, if two RemoteAccessPoint are configured and the
default LocalAccessPoint is used and there is no Session configured, then two default Session are created: one to the first
RemoteAccessPoint configured, and one to the second
RemoteAccessPoint configured. Both sessions use default Session Profile
Listing 6 shows an example Tuxedo JCA Adapter using a '
dmconfig' file. In this example, the full path name to the configuration file is:
/home/work/adapter/dmconfig.xml.
Listing 7 shows an example telling the Tuxedo JCA Adapter that it uses a '
dmconfig' file and 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 is treated as a configuration file located in the current working directory.
There is only one root element, "TuxedoConnector", in the Tuxedo JCA Adapter configuration file. It is represented by the complex type
TuxedoConnectorType. It contains the following elements (listed in
Table 4):
The Resources element is represented by
ResourceType. It specifies the resource adapter execution environment.Only one
Resource element can be configured in the Tuxedo JCA Adapter configuration file.
Table 5 lists the "
ResourceType" elements.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The TPUSR file full path name.
|
|
|
|
|
|
Listing 9 shows a "
Resources" configuration example.
If "ApplicationPassowrdEncrypted" is configured, it is required to run the provided utility
com.oracle.tuxedo.tools.DMConfigChecker to encrypt the password, and optionally generate a key store. In this case, the
keyFileName must point to a valid key store file or key store resource. If
keyFileName is not configured in the Resource Adapter Deployment Descriptor, the Tuxedo JCA Adapter fails to decrypt the password.
Listing 10 shows an example that tells the Tuxedo JCA Adapter that a key store resource is configured.
The SSLInfo element is an anonymous complex type. If 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 7 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 11.
'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
CustomApplicationKey plug-in class is loaded for every session that communicates with this remote access point.
Table 9 lists
CustomApplicationKey elements.
The “name” attribute is defined for
RemoteAccessPoint. It specifies the
locally unique Remote Access Point Name.
Listing 12 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 minimum encryption key length (in bits) a session uses when establishing a session connection. A value of 0 tells the Tuxedo JCA Adapter that the session created using this profile allows no encryption. Key strength of 256 bits is for SSL support only. 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. Measured in milliseconds.Default value is 0 (which means ignore the KeepAlive acknowledgement; however, if the KeepAlive feature is disabled, the Tuxedo JCA Adapter ignores this part of the configuration information when a session is created using this profile).
|
The “name” attribute is defined for
SessionProfileType. It is used by the Session object to get the correct session profile.
Listing 13 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 11 lists the
SessionType elements.
The PasswordPair element is an anonymous complex type. At most, two password pairs can be configured. It allows you to configure passwords for Oracle Tuxedo Domain Session Authentication.
Table 12 lists the
PasswordPair elements.
The “name” attribute is defined for
SessionType. It is used to identify a TDOMAIN session.
Listing 14 shows a
SessionType name attribute example.
Enables/disables of AUTOTRAN. It only accepts
true or
false values. If set to true, when this imported resource is invoked by an Tuxedo JCA Adapter client outside a global or local transaction the Tuxedo JCA Adapter starts a transaction with a remote Oracle Tuxedo Domain.
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 is used.
If appManagedLocalTxTimeout is not specified, the 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 15 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 JNDI name for EJB, for instance tuxedo.services.TolowerEJBHome; or the target class of the POJO, for instance, com.abc.test.MyTolower; or the JNDI name for MDB, for instance is/echo. It must be specified.
|
|
|
|
|
|
The “name” attribute is defined for
ExportType. It is used to identify an exported resource.
Listing 16 shows an
ExportType name example.
Table 15 lists the Resource Adapter Deployment Descriptor
Resources properties.
Listing 17 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 16 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 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 Tuxedo JCA Adapters have the same access point identification.In this situation, the connection behavior becomes unpredictable and is not supported. It can only use default Session, and default
SessionProfile.
Listing 18 provides an
localAccessPointSpec custom configuration example.
This example shows a LocalAccessPoint with
AccessPointName and
AccessPointId equal to
jdom_id is created and listens for the incoming connection requests at
port12345 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 Tuxedo JCA Adapter dynamically, there is no listening endpoint and it is for Client-Side only operation mode. There is no incoming connection request possible.
RemoteAccessPoint is represented by a text string that contains both networking address and per
RemoteAccessPoint access control related information; however, in a Resource Adapter Deployment Descriptor property-based configuration, it can be represented by a single
remoteAccessPointSpec property.
Table 17 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The remoteAccessPointSpec property is a comma-delimited list; a comma separates each remote access point. Each remote access point is represented in a specific format.
If property rapApplicationKeyClass is not specified,
rapApplicationKeyClassParam is ignored if one is configured.
Listing 19 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 have the same QoS associated with them. In this case, if
rapApplicationKeyClass and
rapApplicationKeyClassParam are specified, they are treated as if they are available to both
RemoteAccessPoint guinevre and
galahad. You must make
rapApplicationKeyClass available to both RAP with same fully qualified class path, otherwise the Tuxedo JCA Adapter fails to start.
Listing 20 provides an example that configures two
RemoteAccessPoint with a failover address. The first is accessible through domain
guinevre with the primary network address
//bluestar:11023, and the back up network address
//orion:12345.
There can be only one remoteAccessPointSpec property specified in the Resource Adapter Deployment Descriptor file. If there are more than one configured, the application server's JCA container will only honor the last one configured.
There is no default RemoteAccessPoint.If
remoteAccessPointSpec property is not configured, there is no dynamically created
RemoteAccessPoint.This makes 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
com.oracle.tuxedo.adapter.TuxedoClientSideResourceAdapter class.
Table 18 lists the Resource Adapter Deployment Descriptor
SessionProfile properties.
Listing 21 provides a
SessionProfile configuration example.
All SessionProfile related property configured in the Resource Adapter Deployment Descriptor file is used in the construction of the default
SessionProfile.
The LoadBalancing algorithm is preset to
RoundRobin and cannot be changed. If
impResourceName is specified then there is no default Import created by Tuxedo JCA Adapter.
Table 19 lists the Resource Adapter Deployment Descriptor Import Related property.
Listing 22 provides an
impResourceName example that limits the available remote Oracle Tuxedo resources to
Toupper_1, and
ECHO. This property is limited to the Resource Adapter Deployment Descriptor-based configuration; a "
resourceadapter-class" must be configured with
TuxedoClientSideResourceAdapter class.
For example, if there are two RemoteAccessPoint elements configured and the
default LocalAccessPoint is used and there is no Session configured, two default Sessions are created.
Table 20 lists these adapter-wise custom properties in the Resource Adapter Deployment Descriptor that are supported by factory-based configuration.
|
|
|
|
|
|
|
|
|
Defines whether AUTOTRAN is allowed or not. It is used by a factory if factory-wise autoTran is not configured.
|
|
|
|
|
Define the transaction timeout used by AUTOTRAN or client application managed local transaction. It is used by a factory if factory-wise appManagedLocalTxTimeout is not configured.
|
|
|
|
|
Configures whether a com.oracle.tuxedo.adapter.TuxedoReplyException is thrown or not if a failure reply is received from Oracle Tuxedo. It is used by a factory if factory-wise throwFailureReplyException is not configured for that factory.
|
The adapter-wise "appManagedLocalTxTimeout" is configured in "
resourceadapter" type in the Resource Adapter Deployment Descriptor (RADD), ra.xml, file as "
config-property".
Listing 23 shows an example using
AUTOTRAN with transaction timeout in the
ra.xml file.
<config-property>
<config-property-name>autoTran</config-property-name>
<config-property-type>java.lang.Boolean</config-property-type>
<config-property-value>true</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>50</config-property-value>
<config-property>
The Resources-related properties are available for every factory, and configured using Resource Adapter Deployment Descriptor. They are configured in the "
resourceadapter" type in the Deployment Descriptor. The only exception is Application Password that it is made available to each factory for flexibility and is not available in Resources Related properties.
Listing 24 shows a configuration example that describes two VIEW32 classes (view1 and view2), information in the Resource Adapter Deployment Descriptor for factory-based configuration.
|
|
|
|
|
|
|
|
|
Defines whether AUTOTRAN is available for requests using connections created by this factory. If not configured then use adapter-wise AUTOTRAN configuration. If configured, whether true or false, will override adapter-wise AUTOTRAN configuration.
|
|
|
|
|
Defines 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 seconds.
|
|
|
|
|
Configures whether a com.oracle.tuxedo.adapter.TuxedoReplyException is thrown or not if a failure reply received from Oracle Tuxedo. If it is not configured then adapter-wise setting is used.
|
|
1.
|
factory appManagedLocalTxTimeout property
|
A connection factory name can be specified by using connectionFactoryName property. Although this property is optional, it is recommended for configuration if a transaction is possible for service requests originated using a connection that is created by this connection factory. It is also recommended if you want to use
DMMIB to configure
DM_REMOTE_DOMAINS in an Oracle Tuxedo /Domain configuration dynamically.
Table 23 lists connection factory properties.
If this property is configured and default LocalAccessPoint is configured then a file with the name "
.lapid.<connectionFactoryName>" will be created in the current working directory which will contains the LocalAccessPoint Id generated dynamically. For instance, using the above as an example, a file with the name
".lapid.TuxedoConnectionFactory1" will be created.
The applicationPassword property for factory-based configuration as shown in
Table 24, can be in either clear text or cipher text. To configure it using cipher text, you must use the output of
com.oracle.tuxedo.tools.EncryptPassword. The following is the sample output:
Table 25 is the table for
LocalAccessPoint related properties for factory-based configuration.
By default "mutualAuthenticationRequire" is
false. If anyone of the six required properties is missing, SSL is ignored. Toni depends on session profile information plus session negotiation with remote Oracle Tuxedo GWTDOMAIN gateway and uses LLE.
Specifying localAccessPointSpec property is optional. If not specified,
default LocalAccessPoint is used. When
default LocalAccessPoint is used for this factory, it is recommended to also configure
connectionFactoryName.
The RemoteAccessPoint is represented by both networking address and per
RemoteAccessPoint Access Control related information. The most important property is
remoteAccessPointSpec. It is a comma-separated list; a comma separates each
RemoteAccessPoint.
Table 26 lists the RemoteAccessPoint related properties that are available in factory-based configuration.
|
|
|
|
|
|
|
|
|
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, 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Each RemoteAccessPoint is represented in a specific format. In order to make the factory usable a
"remoteAccessPointSpec" must be configured.
Listing 28 shows a RemoteAccessPoint
weblogic-ra.xml file example.
There can be only one remoteAccessPointSpec specified for each factory. If
rapApplicationKeyClass and
rapApplicationKeyClassParam are specified, they are 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.
|
The lPasswd1,
lPasswd2,
rPasswd1, and
rPasswd2 attributes for factory-based configuration can be in either clear text or cipher text. To configure using cipher text, you must use the output of
com.oracle.tuxedo.tools.EncryptPassword. The following is the sample output:
Listing 29 shows a
RemoteAccessPointSpec property in the
weblogic-ra.xml file example.
Table 27 lists the default value of the default
SessionProfile for factory-based configuration.
Listing 30 shows a SessionProfile Property
weblogic-ra.xml file example.
The LoadBalancing algorithm cannot be specified and it will always use RoundRobin. Your service requests are load balanced among all the
RemoteAccessPoints of that particular connection factory.
Table 28 lists the new property related to Import in a factory-based configuration.
A session connects a Tuxedo JCA Adapter LocalAccessPoint to a remote Oracle Tuxedo GWTDOMAIN gateway. In a factory-based configuration, there is no need to explicitly specify a session so there is no "
Session" related property available. All the sessions available in a factory will be default Session.
The Tuxedo JCA Adapter creates a session for every possible LocalAccessPoint and
RemoteAccessPoint combinations for a connection factory. Since there can only be one
LocalAccessPoint per connection factory configuration, there can be at most
1xN number of sessions possible (where the '
N' is the number of the
RemoteAccessPoint).
Listing 32 shows an example using Session.
<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 you configure applicationPassword property for WebSphere 7.0, you should not encrypt the password using
com.oracle.tuxedo.tools.EncryptPassword tool because WebSphere 7.0 will encrypt the password.
click on the "factory1" in the "Name" column, and then it will take you to page "factory1".
|
•
|
Dropping the .rar file in a generic auto-deployment location.
|
|
1.
|
Unjar the com.oracle.tuxedo.TuxedoAdapter.rar file into a directory.
|
|
•
|
remove META-INF/sample.weblogic-ra.xml
|
|
•
|
rename META-INF/client-side.ra.xml to META-INF/ra.xml
|
|
•
|
modify META-INF/ra.xml by adding properties for the /Domain configuration.
|
|
•
|
remove META-INF/client-side.ra.xml
|
|
•
|
remove META-INF/sample.weblogic-ra.xml
|
|
•
|
rename META-INF/server.ra.xml to META-INF/ra.xml
|
|
•
|
modify ra.xml file with the desired /Domain configuration properties, ' dmconfig' property must be specified
|
|
•
|
modify the dmconfig.xml with the desired and correct /Domain configuration
|
|
•
|
rename the dmconfig.xml file to whichever name ' dmconfig' property specified.
|
|
•
|
if you choose the 'dmconfig' file not to be treated as part of resource archive then move it to desired directory.
|
|
•
|
remove META-INF/client-side.ra.xml
|
|
•
|
remove META-INF/weblogic-ra.xml
|
|
•
|
rename META-INF/sample.weblogic-ra.xml to META-INF/weblogic-ra.xml if configuring it for WebLogic server.
|
|
•
|
For WebLogic server user modifies the META-INF/weblogic-ra.xml with the desired configuration. For WebSphere server user use the steps described in previous chapter to configure it from console.
|
|
3.
|
.jar the working directory to create Resource Adapter Archive
|
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 36.
If the configured dmconfig property contains path information, it is treated and loaded as file as shown in
Listing 37. 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, 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 any Session configured, the adapter creates a default Session between each
LocalAccessPoint and each
RemoteAccessPoint configured using default
SessionProfile.
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 shown in
Listing 38.
If TuxedoClientSideResourceAdapter is configured,
dmconfig configuration is ignored. When this class of resource adapter is configured it assumes all 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.
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 39.
If TuxedoFBCResourceAdapter is configured,
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 for 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 uses the adapter-wise 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 40.
Some of the properties in ra.xml file should not be changed as they pertain to the Tuxedo JCA Adapter internally or its descriptive information; however, there are other properties you must modify to customize the operation and application.
The config-property element is generally used to define Tuxedo JCA Adapter custom properties in the standard JCA deployment descriptor
META-INF/ra.xml file.
Table 29 lists the properties that are used to customize the Tuxedo JCA Adapter.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For dmconfig-based configuration only, this is the full path name to the key file. This file contains key used to encrypt all the passwords in the " dmconfig" file.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Enables/disables AUTOTRAN. By default there is no AUTOTRAN.
|
Table 30 lists the trace-level control values.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
JATMI input and output, including low-level JATMI calls.
|
|
|
|
|
|
|
|
|
Listing 41 shows an example deployment descriptor file using the customization properties.
In dmconfig file configuration, you can specify multiple
NetworkAddress elements in
RemoteAccessPoint and
LocalAccessPoint. The order of these network addresses dictates the order of preference. The Tuxedo JCA Adapter will attempt using the first network address in
LocalAccessPoint to establish a listening endpoint. If it fails, it tries the next one until a listening endpoint established, or it exhausted all the network addresses.
Listing 44 shows an example imported resource,
TOUPPER, load balanced between
session_1 and
session_2.
Listing 45 shows an example that is not only capable of load balancing, but also capable of service-level fail over.
The above configuration load balances between session_1 and
session_2. In the event that
session_1 is not available, the service request is forwarded to
session_3 when the load balancing algorithm decides it is
session_1 turn. The same for
session_2; in this case
session_3 also backs up session_2.
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 previous example, if
session_1 is not available, all service requests destined to
session_1 are routed to
session_3. When
session_1 becomes available, the service request are routed to the primary route
session_1.
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 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 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 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".
The Java client initiates the conversation by calling tpconnect() to establish a conversation with a remote Oracle Tuxedo conversational server. The Java client continues sending data to a remote conversational server using
tpsend(). When the Java client finishes sending data, it sends the
TPRECVONLY flag along with the last
tpsend() to the server.
The Java client initiates conversation using the tpconnect() extension from the Tuxedo JCA Adapter implementation of the Interaction class,
TuxedoInteraction. The
TuxedoInteraction class
tpconnect() method returns a conversational object if the conversation is started successfully. The Java client can then use the returned conversational object to continue communicating with an Oracle Tuxedo conversational server using
tpsend() and
tprecv() object interface.
The JATMI Conversation model uses TPReplyExcepton to carry the conversational event. When the conversational event needs to be conveyed to a Java client, the Tuxedo JCA Adapter throws
TPReplyException.
TPReplyException can also carry data returned from an Oracle Tuxedo conversational server. When a Java client captures a
TPReplyException, it should also check both event and data. There are two types of conversational events:
TPEV_DISCONIMM,
TPEV_SVCSUCC,
TPEV_SVCERR,
TPEV_SVCFAIL are conversation completion status types. When any one of these events occur, the conversation has already become stale and the conversation object should not be used.
TPEV_SENDONLY is a conversation change of control event type; When this event occurs the Java client regains control of the conversation.
If there is no event (whether there is accompanied data or not), the tprecv() performs a normal return without any exception. If there is an error encountered related to connection, protocol, and configuration, the Tuxedo JCA Adapter throws a
TPException. In the above illustration, the Oracle Tuxedo conversation server initiates a
tpreturn (
TPSUCCESS) and the client initiates a
tprecv() and retrieves the
TPEV_SVCSUCC event from
TPReplyException.
A new method, (tpconnect()used to initiate a conversation with an Oracle Tuxedo Conversational serve), r is added to the
com.oracle.tuxedo.adapter.cci.TuxedoInteraction class. To access this new ATMI conversation, you must typecast the Interaction object returned from
Connection.createInteraction() to
TuxedoInteraction class to gain access to the JATMI conversation extension.
Listing 48 shows a
TuxedoInteraction class
tpconnect interface definition example.
Either TPSENDONLY or
TPRECVONLY must be specified for the flags field in
tpconnect(), these two flags are defined in the
weblogic.wtc.jatmi.ApplicationToMonitorInterface class as shown in
Listing 49.
The tpconnect() interface in the
com.oracle.tuxedo.adapter.cci.TuxedoInteraction class returns a
weblogic.wtc.jatmi.Conversation conversational object. You can use the returned conversational object to have a conversation with an Oracle Tuxedo conversational server.
Public void tpsend(TypedBuffer data, int flags) throws
TPException.This method sends data across an open conversation from a Java client to an Oracle Tuxedo conversational server. The Java client must have control of the conversation. If the Java client initiates
tpsend() in an improper context (i.e., without conversation control), it receives a
TPException.TPEPROTO error.
When an error occurs, a TPException is thrown and the error code can be retrieved by calling
TPExcepiton.gettperrno(). The following is the list of possible
TPException errors:
tpsend() was called improperly (e.g., without conversation control).
Public Reply tprecv(int flags) throws
TPException,
TPReplyException. This method is used by a Java client to receive data sent by an Oracle Tuxedo conversational server across an open conversation. The method call can only be issued by a Java client when it does not have conversation control. If the Java client calls this method improperly (i.e., still has conversation control), a
TPException.TPEPROTO exception is thrown. This method can throw either
TPException or
TPReplyException, depending on the nature of the situation.
Normally, it uses TPReplyException to convey the event coming from the Oracle Tuxedo conversation server (for example, conversation completion, or change of conversation control). However, sometimes it can also throw
TPException because an unexpected error is encountered while receiving data (for example, calling this method improperly or encountering a network error).
If an event exists for the conversation, tprecv() returns
TPReplyException with
TPERRNO set to
TPException.TPEEVENT. The event type is returned as well, and the Java client can retrieve it through invoking T
PReplyException.getrevent(). The following is a list of valid events.
This event indicates that originator of the conversation has issued an immediate connection disconnect via tpdiscon(). This event is also returned to the originator or subordinate when a connection is broken due to a communication error. In regards to the Tuxedo JCA Adapter, this could also be due to the server initiating
tpreturn() without conversation control; the TDOMAIN protocol translates it into a
TPEV_DISCONIMM event. Because this is an immediate disconnection notification abortive (rather than orderly), data in transit may be lost. The descriptor used for the connection is no longer valid.
When an error occurs, a TPException is thrown and the error code can be retrieved by calling
TPExcepiton.gettperrno(). The following is a list of possible
TPException errors:
tprecv() was called improperly. For example, the Java client still has conversation control.
The tpdiscon() method immediately tears down the conversation represented by the conversational object. This method can only be called by the initiator of the conversation (which is the Java client). Although a conversational Java client can tear down a conversation using
tpdiscon(), it is preferred to let the Oracle Tuxedo conversational server tear down the connection using
tpreturn(); doing so ensures correct results.
Listing 51 shows a relinquish conversation control example.
Listing 55 shows a Tuxedo JCA Adapter
dmconfig file imported resource example.
Listing 56 shows a very simple complete example application.
|
2.
|
The client calls tpsend() to send a second piece of data and gives control to the Oracle Tuxedo Server.
|
Listing 57 is an example Oracle Tuxedo configuration file.
Listing 58 shows an Oracle Tuxedo Domain configuration example.
Listing 59 shows a JATMI client code example for WebLogic server.
The dmconfig file is a property in the Resource Adapter Deployment Descriptor that tells the Tuxedo JCA Adapter where to look for its configuration file as shown in
Listing 60.
Listing 61 shows the corresponding Resource Adapter Deployment Descriptor. This file is named "
ra.xml", and is located in the
META-INF of the Resource Archive file.
The Tuxedo JCA Adapter has an SOA configuration wizard in a separate .jar file that supports JDeveloper SOA Extension. By using this graphical IDE, it allows an SOA application to leverage Oracle Tuxedo hosted services through the Tuxedo JCA Adapter. You can create Oracle Tuxedo"External References" by dragging-and-dropping the Tuxedo JCA Adapter icon and configure its SOA operations using this configuration wizard.
Listing 63 shows the new Tuxedo JCA Adapter type to be configure in the SOA configuration file,
soa-config.xml.
Enter the JNDI name for the connection factory you intend to use. In this example we'll use the default JNDI name "
eis/TuxedoConnectionFactory".
Figure 14 shows the Message configuration wizard page when a reply is required. Notice there are two schema input fields; the first one is labeled "Inbound" which is the schema required for request message; the second one is labeled "Outbound" which is the schema required for reply message.
Figure 20 shows the Message configuration wizard page when reply is not required. (by selecting
TPNOREPLY in the "Tuxedo Interaction Properties" page). Notice there is only one schema input field. It is labeled "Message Schema" which is the schema required for request message
The "MyXCType" tag is the buffer sub-type.
The "MyXCommon" tag is the X_COMMON buffer sub-type.
Table 32 provides a matrix for output data conversion from an Oracle Tuxedo buffer to an XML record.
Listing 97 shows what it looks like after it is converted from FML32 buffer.
Listing 101 shows a VIEW definition file that can be used with
weblogic.wtc.jatmi.viewj32.
Listing 103shows VIEW32 class file generated using viewj32 compiler.
Listing 103 is the corresponding XML document generated using the above VIEW32 class.
To requestXMLRecord request buffer, if there is more than one element in the record, a runtime
ResourceException is thrown. If the request
XMLRecord is empty or the element contains 0 length string then a 0 length corresponding Oracle Tuxedo buffer type is used to transport the request.
If you select "wrapped" operation with an XML element tag named "
MYSTRING", the reply is wrapped as follows:.
If you do not select the "wrapped" operation, the Tuxedo JCA Adapter treats the reply as a native XML document and uses it to create
XMLRecord. If the data is not a well formed XML document, a
ResourceException is thrown.
Listing 105 is the XSD file for a FML32 buffer type with embedded FML32 field named
TEST_FML32, and the embedded View32 field named
TEST_VIEW32. The
TEST_VIEW32 VIEW32 field has a sub-type
myview32.
