• 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.The Local Access Point corresponds to DM_LOCAL_DOMAINS, and Remote Access Point corresponds to DM_REMOTE_DOMAINS in the Oracle Tuxedo Domain BDMCONFIG configuration file.An Oracle Tuxedo resource must be imported to be accessed by a Java client using either CCI or JATMI. The imported resource has a name and a RemoteName. The "name" is what a JCA client uses to tell the Tuxedo JCA Adapter which remote resource configuration entry to use and the "RemoteName" is the actual name the Remote Access Point uses to reference its exported resource. When more than one TDOMAIN session provides the same service using the same configuration entry, the Tuxedo JCA Adapter performs load balancing among all imported Oracle Tuxedo resources with the same name.There are two load balancing algorithms supported by the Tuxedo JCA Adapter; by default the load balancing algorithm is RoundRobin, but it can be changed to Random. If the Tuxedo JCA Adapter is not configured for import, then all client requests are distributed among all the Remote Access Points configured using load balance; this is called Default Import.
•
• Resource Adapter Deployment Descriptor-only based configuration is aimed for simple and easy configuration. All the configuration information is in the Resource Adapter Deployment Descriptor (also known as ra.xml). The configuration includes Local Access Point, Remote Access Point, and Session Profile. The sessions are implicitly defined from every Local Access Point to every Remote Access Point. They all share one session profile.A Configuration File based configuration requires the creation of a separate XML based configuration file. This configuration method is the most complete way to configure the Tuxedo JCA Adapter. If any information resides in the configuration that requires extra privacy and protection, the Tuxedo JCA Adapter provides a tool (com.oracle.tuxedo.tools.DMConfigChecker), that must be used to encrypt those elements and generates a properly obfuscated key file used at runtime to decode those elements. This tool is provided by Tuxedo JCA Adapter.
Note: The Tuxedo JCA Adapter release 12c is distributed in one.ZIP file (downloaded from the Oracle Web site). This .ZIP file contains four files which include a complete Tuxedo JCA Adapter and an Tuxedo JCA Adapter SOA configuration wizard for JDeveloper.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.
Note: For WebLogic Server, this jar file must be exported using EXT_PRE_CLASSPATH to replace the one included with WebLogic Server installation. This environmental variable must be set before starting WebLogic Server.
Note: WebLogic Server users should not set this jar file in the CLASSPATH if the WebLogic Server version is 11gR1 or above. An example Resource Adapter Deployment Descriptor that uses the dmconfig file as its configuration.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. The Tuxedo JCA Adapter Manifest 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.The Tuxedo JCA Adapter Resource Archive contains the most recent fix to enable the Tuxedo JCA Adapter. For all other Java Application Servers, no JATMI file needs to be overridden.
1.
2.
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/configurationJDeveloper is installed in the $JDEVELOPER_HOME directory.The XML-based configuration file provides a way to configure using complete the capabilities of Tuxedo JCA Adapter. It is suitable for users with complex configuration requirements. To configure using this method, you must configure the "resourceadapter-class" with com.oracle.tuxedo.adapter.TuxedoResourceAdapter in the "resourceadapter" element of the Resource Adapter Deployment Descriptor.Listing 1 shows a Resource Adapter Deployment Descriptor fragment that enables using an XML-based dmconfig file.The Resource Adapter Deployment Descriptor (commonly known by its file name ra.xml) based configuration utilizes the custom properties in the deployment descriptor. It provides an Tuxedo JCA Adapter configuration capability subset that is suitable for client-side only operations. It provides an easy way to configure an Tuxedo JCA Adapter.To configure using Resource Adapter Deployment Descriptor method, you must configure the "resourceadapter-class" with com.oracle.tuxedo.adapter.TuxedoClientSideResourceAdapter in the 'resource adapter' element of the Resource Adapter Deployment Descriptor.Listing 2 shows a Resource Adapter Deployment Descriptor fragment that enables using Custom Properties-based configuration.To configure using factory-based configuration method user must configure the "resourceadapter-class" with com.oracle.tuxedo.adapter.TuxedoFBCResourceAdapter in the 'resourceadapter' element and the "managedconnectionfactory-class" in the 'connection-definition' of the 'outbound-resourceadapter' element with the value com.oracle.tuxedo.adapter.spi.TuxedoFBCManagedConnectionFactory.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.JBoss (release 4 and above) requires that JNDI registration be done through the use of *-ds.xml files placed in the $JBOSS_HOME/server/$BOOTMODE/deploy directory. You may create a TJA-ds.xml file with the following contents for example.Listing 4 Example for XA TransactionsListing 5 Example for non-XA TransactionsThe "default" configuration refers to the Tuxedo JCA Adapter ability to dynamically generate configuration for some of the configuration object types if you do not configure any one of these object types explicitly. Not all configuration object types support the "default" configuration. It is available for Local AccessPoint, SessionProfile, Session, and Import. The rest of the configuration object types (such as Resources, RemoteAccessPoint, and Export), do not support this type of configuration.The "default" configuration works with all three configuration styles. It is not necessary to configure LocalAccessPoint, SessionProfile, Session, and Import in some situations. In those instances, you 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 Tuxedo JCA Adapter usability.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 a factory-based configuration, the default LocalAccessPoint supports SSL. You can specify a password for Key Store, Identity Alias, and Trusted Certificate Store.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.GWTDOMAIN gateway must be modified to allow Dynamic RemoteAccessPoint (RAP) Registration. If DYNAMIC_RAP is set to YES, it also updates the in-memory database of the status of the connection from dynamically registered RAPs. If the connection from those dynamically registered RAP is lost, then the information about that RAP is removed from the in-memory database.
Note: 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 dynamically registered RAPs are not added to /DOMAIN configuration permanently. Their existence is only known when the Session is established. Their existence is lost when the connection is lost.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-wise default session profile is always created whether or not a SessionProfile is configured in the dmconfig configuration file. There can only be one default SessionProfile for both dmconfig-based configuration and Deployment Descriptor-based configuration; it is the adapter-wide default SessionProfile.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:
Table 3 SessionProfile Type Elements The user credential propagation policy. When the value is LOCAL, then there is no propagation. The number of seconds that a session waits between automatic connection establishment attempts. This is meaningful only when ConnectionPolicy is set to ON_STARTUP. The minimum encryption key length (in bits) a session uses after establishing a session connection. A value of 0 indicates encryption is optional. Value "256" is for SSL. Key strength of 256 bits is for SSL support only. The maximum encryption key length (in bits) a session uses to transport data after establishing a session connection. A value of 0 indicates encryption is optional. Value "256" is for SSL. Key strength of 256 bits is for SSL support only. 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 ProfileThe Tuxedo JCA Adapter configuration file is an XML-based file represented by a property named 'dmconfig' in the Resource Adapter Deployment Descriptor (ra.xml). This property value can be either an absolute path to a configuration file, or it can be represented as a resource of the resource archive (RAR) file. You must use this method for configuration when full blown client and server operations are required.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 6 dmconfig Full Path ExampleListing 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.Listing 7 dmconfig ArchiveThere 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):
•
•
•
Table 4 TuxedoConnectorType Element Listing 8 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 Tuxedo JCA Adapter configuration file. Table 5 lists the "ResourceType" elements.
Table 5 ResourceType Element The TPUSR file full path name.
Note: There is no attribute defined for any "ResourceType" element; however, the "TPUsrFile" element can be overridden by the TpusrFile element in the RemoteAccessPoint.Listing 9 shows a "Resources" configuration example.Listing 9 Resources Configuration ExampleIf "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.Listing 10 Key Store Resource ExampleThe Local Access Point element is represented by LocalAccessPointType. It specifies a listening address and possible link-level failover address. Table 6 lists the LocalAccessPointType elements.
Table 6 LocalAccessPointType Element The connection principal name. It must be globally unique.If not specified, it uses the locally unique LocalAccessPoint “name” attribute value (see Listing 11). 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 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.
Table 7 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.Listing 11 LocalAccessPoint Name Attribute<LocalAccessPoint name="LDOM1">
<LocalAccessPointId>Godfried</LocalAccessPointId>
<NetworkAddress>//neocortex:14001</NetworkAddress>
</LocalAccessPoint>'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.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 8 lists RemoteAccessPointType elements.
Table 8 RemoteAccessPointType Element If not specified, it uses the locally unique RemoteAccessPoint “name” attribute value (see Listing 12). The host network address and port number of the remote Oracle Tuxedo access point. Specify the TCP/IP address in the format //hostname:port or //#.#.#.#:port. The full path name to a TPUSR file for this remote access point. 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.
Table 9 CustomApplicationKey Element The “name” attribute is defined for RemoteAccessPoint. It specifies the locally unique Remote Access Point Name. Listing 12 shows a RemoteAccessPointType name attribute example.Listing 12 RemoteAccessPoint 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 TDOMAIN sessions between an Tuxedo JCA Adapter Local Access Point and an Oracle Tuxedo Remote Access Point. Table 10 lists SessionProfileType elements.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.Listing 13 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 11 lists the SessionType elements.
Table 11 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 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.
Table 12 PasswordPair Element The “name” attribute is defined for SessionType. It is used to identify a TDOMAIN session. Listing 14 shows a SessionType name attribute example.Listing 14 SessionType Name ExampleThe Import element is represented by ImportType. It identifies an existing remote Oracle Tuxedo Application Domain resource that can be accessed by the Tuxedo JCA Adapter client. Table 13 lists ImportType elements.
Table 13 ImportType Element
• Specifies the resource name to used by a JATMI tpcall() as service name or by a CCI execute() as function name.
• 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.If it is not configured then the adapter-wise AUTOTRAN property in the Resource Adapter Deployment Descriptor is used to determine the AUTOTRAN.
• 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 secondsListing 15 ImportType Name ExampleThe Export element is represented by ExportType. It specifies a local resource that is accessible from a remote Oracle Tuxedo Application Domain. Table 14 lists ExportType elements.
Table 14 ExportType Element 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.Listing 16 ExportType Name ExampleThe main component used to deploy and repackage the resource archive for deployment is the resource adaptor 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.For Deployment Descriptor-based configuration, you must specify an Tuxedo JCA Adapter deployment configuration using the deployment descriptor file (ra.xml). There is a set of custom properties to allow you to specify the configuration. The scope of all properties specified this way is adapter-wise.The deployment descriptor-based configuration style is based on standard simple property types: config-property-name, config-property-type, and config-property-value. These property types cannot be repeated. They are available in the resource adapter section of the Resource Adapter Deployment Descriptor "resourceadapter" file.Most of the Resources elements specified in the dmconfig file are available for deployment descriptor-based configuration.Table 15 lists the Resource Adapter Deployment Descriptor Resources properties.
Table 15 Resources Properties Listing 17 shows a configuration example that describes two VIEW32 classes information using Resource Adapter Deployment Descriptor-based custom property configuration.
Note: This causes the Tuxedo JCA Adapter to use the viewFile32Classes with full package name accessible through SYSTEM CLASSPATH.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.
Table 16 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.To get around this clustered environment problem, do not to configure it at all (then the default LocalAccessPoint is created with UUID-based LocalAccessPointId). This UUID-based LocalAccessPointId is written in a file named .lapid in the current working directory.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.If this is not desirable, you must either modify the Resource Adapter Deployment Descriptor for all the nodes that requires different behavior or change to use dmconfig method to configure the clustered Tuxedo JCA Adapter.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.
Table 17 RemoteAccessPoint 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.To support link level failover parenthesis is used to group failover addresses together for a RemoteAccessPoint. The first address specified in a group is the primary address. The second address in a group backs up the first address, and the third address in a group backs up the second address and so on.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.The second is accessible through domain galahad with network address //orion:37456, and the back up network address //bluestar:37456.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 Resource Adapter Deployment Descriptor file-based configuration utilizes the Default Import; however, it also provides ability to restrict what can be accessed from adapter to remote Tuxedo application domain in a uniformly way. A single "impResourceName" property can be specified and it contains a comma-separated list of remote Oracle Tuxedo services/resources allowed to access.One restriction applies is that these will be applied to all the sessions that are possible.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.
Table 19 Import Related Property The valid Oracle Tuxedo service name or queue name. There is no name transaction done for the wire protocol. This is basically the same as the RemoteName attribute of an Import in the dmconfig file.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.Listing 22 impResourceName ExampleFor 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.Factory-based configuration consists of two major parts. The first part is adapter-wise properties that need to be configured in the Deployment Descriptor file in the "resourceadapter" using custom property. The second part is factory-wise properties that can are configured differently for different Java Application Servers. For WebSphere, they are configured through the custom properties page of the "J2C connection factory" For WebLogic they are configured in weblogic-ra.xml.These properties are based on standard simple property types: config-property-name, config-property-type, and config-property-value. These property names cannot be repeated. They are available in the Resource Adapter Deployment Descriptor "resourceadapter".Table 20 lists these adapter-wise custom properties in the Resource Adapter Deployment Descriptor that are supported by factory-based configuration.
Table 20 Adapter-Wise Properties 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 following is the precedence order for AUTOTRAN transaction timeout in factory-based configuration:
1. factory-wise appManagedLocalTxTimeout property
2. adapter-wise appManagedLocalTxTimeout property
3. com.oracle.tuxedo.adapter.AppManagedLocalTxTimeout JVM propertyThe adapter-wise "appManagedLocalTxTimeout" is configured in "resourceadapter" type in the Resource Adapter Deployment Descriptor (RADD), ra.xml, file as "config-property".<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>Resource-Related PropertiesThe 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.
Table 21 Resource Related Properties The full path name to the TPUSR file. 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.
•
•
Table 22 Factory-Wise Property Table 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.The following is the precedence order for AUTOTRAN in a factory-based configuration.
1. factory appManagedLocalTxTimeout property
2. adapter-wise appManagedLocalTxTimeout property
3. com.oracle.tuxedo.adapter.AppManagedLocalTxTimeout JVM propertyListing 25 shows a weblogic-ra.xml file example.Listing 25 weblogic-ra.xml FileA 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.
Table 23 Connection Factory Property Table Listing 26 shows a weblogic-ra.xml file example.Listing 26 Connection Factory weblogic_ra-xml FileIf 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 inTable 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 24 Application Password Property Oracle Tuxedo Application Password in either clear text, or cipher text generated using the com.oracle.tuxedo.tools.EncryptPassword tool.Table 25 is the table for LocalAccessPoint related properties for factory-based configuration.
Table 25 Properties of LocalAccessPoint There are seven SSL-related properties. Six of them are related to Key/Certificate store and must be configured if SSL is required; the only one that is optional for using SSL is mutalAuthenticationRequired.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.Listing 27 shows a weblogic-ra.xml file example.Listing 27 weblogic-ra.xml Usage ExampleThe 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.
Table 26 RemoteAccessPoint Property Table 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.Listing 28 RemoteAccessPoint weblogic-ra.xml FileThere 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.At least one password pair must be valid if session authentication is "DM_PW". If both password pair 1 and password pair 2 are valid then password pair one will be used to encrypt session authentication information.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:Table 27 lists the default value of the default SessionProfile for factory-based configuration.
Table 27 SessionProfile Property Table The maximum number of milliseconds allowed for a blocking outbound request using this profile. The default value is 60 seconds, which is 60000 milliseconds. The InteractionSpec.setExecutionTime() time method can override this block timeout. If not configured then GWTDOMAIN session authentication is not required. When DM_PW session authentication security type is configured then at least one password pair must be configured for every remoteAccessPoint. If APP_PW session authentication security type is configured, you must configure applicationPassword for the factory. Behaves like ON_STARTUP. The user credential propagation policy. When its value s "LOCAL",there is no propagation. Default value is "LOCAL". The number of seconds that this session waits between automatic connection establishment attempt. Set this element value only when ConnectionPolicy is "ON_STARTUP". Default value is 60. The value 0 disables the connection retry mechanism. The maximum number of times that this session tries to establish a session connection to remote Oracle Tuxedo access points. Set this element only when ConnectionPolicy is "ON_STARTUP". Default value is 922337206385775807. The minimum encryption key length (in bits), this session uses when establishing a session connection.A value of 0 indicates encryption is optional. Value "256" is for SSL. Default value is "0". The maximum encryption key length (in bits), this sessions uses when establish a session connection. A value of 0 indicates no encryption is used. The default value is "128". Specifies whether this GWTDOMAIN session is configured with Application-Level Keep Alive, and its maximum idle time before wait timer start ticking. Default value is "0", and it means application level keep alive is disabled. The measurement is in milliseconds.When connection is busy, there is no need to send a special keep alive message to remote gateway; however, when there is spKeepAlive number of milliseconds, rounded up to second, without activities over the connection then a special keep alive message is sent and a timer of spKeepAliveWait (rounded up to second) will be started. If the value specified is '0' then there will be no checking the acknowledgement from RemoteAccessPoint; this can prevent the session connection being closed by KeepAlive feature. The measurement is in milliseconds.Listing 30 shows a SessionProfile Property weblogic-ra.xml file example.Listing 30 SessionProfile Property weblogic-ra.xml FileFactory- based configuration can utilize the default Import; however, it will also provide ability to restrict what can be accessed from adapter to remote Tuxedo Application Domain in a uniformly way. A single "impResourceName" property can be specified for each factory and it contains a comma-separated list of remote Oracle Tuxedo service/resources the Tuxedo JCA Adapter client is allowed to access.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.
The valid Oracle Tuxedo service name or queue name. There is no name translation done for the wire protocol. This is essentially the same as the RemoteName attribute of an Import in the dmconfig file.Listing 31 shows a weblogic-ra.xml file example.Listing 31 Weblogic-ra.xml Usage ExampleA 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.Listing 32 Session weblogic-ra.xml.The Tuxedo JCA Adapter factory-based configuration is shown in Listing 33 (for XA transactions) and Listing 34 (for non-XA transactions). The file name can be anything you want, take TJA-ds.xml for example, this file should be copied to the $JBOSS_HOME/server/$BOOTMODE/deploy directory.Tuxedo JCA Adapter factory-based configuration is done through the WebLogic weblogic-ra.xml file. Examples of the configuration can be found in previous sections;Listing 35 lists a complete sample configuration.Listing 35 WebLogic Server Sample Configuration<value>//localhost:12498/domainId=TDOM3_ID,
lPasswd1={Salted-AES}xNgOdUuXB7Z49D0cssluxA==,
rPasswd1={Salted-AES}hAIzbPI+YyaeuHX0A9Umqg==</value>Resources ' Resource Adapters' Resource adapters
3. From Resources ' Resource Adapters' Resource adapter ' Tuxedo JCA Adapter.Click on "Preference" on top of custom property table. The console expands to add an input field "Maximum rows", change the default value to "60", and then click on "Apply" button right below the input field box and check box.For instance: "remoteAccessPointSpec"
6. From Tuxedo JCA Adapter ' Custom properties ' remoteAccessPointSpecChange 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.Assume you entered "factory1" in the "Name" field.click on the "factory1" in the "Name" column, and then it will take you to page "factory1".
9. From Tuxedo JCA Adapter ' J2C connection factories ' factory1 ' Custom properties,click on the property name in the "Name" column and then it will take you to property page. Assume you selected "localAccessPointSpec".
10. From J2C connection factories ' factory1 ' Custom properties ' localAccessPointSpec,
• Dropping the .rar file in a generic auto-deployment location.
• Explicitly deploying the .rar file (or the directory containing its exploded version) via a console function.
• Using an application supported scripting tool to install and deploy. For example wsadmin in WebSphere or wldeployer in WebLogic.Deploying the Tuxedo JCA Adapter involves choosing a deployment mode, configuring the resource adapter descriptor, repackaging the adapter and deploying it on a JCA 1.5/1.6 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.
Notes: In most cases, you only need to modify the ra.xml file (in the META-INF directory) to get the adapter up and running.
1. Unjar the com.oracle.tuxedo.TuxedoAdapter.rar file into a directory.
• remove META-INF/ra.xml
• remove META-INF/server.ra.xml
• remove META-INF/sample.weblogic-ra.xml
•
• modify META-INF/ra.xml by adding properties for the /Domain configuration.
• remove META-INF/ra.xml
• remove META-INF/client-side.ra.xml
• remove META-INF/sample.weblogic-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
•
• 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/server.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
4. Check the configured adapter class for Tuxedo JCA Adapter is one of the following: TuxedoResourceAdapter, or TuxedoClientSideResourceAdapter, or TuxedoFBCResourceAdapter.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 it fails to load from the resource archive, it is treated as a file located in the current working directory. If the file fails to open, the resource adapter will not start and a ResourceAdapterException is thrown.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.Listing 37 dmconfig Property Loaded as a FileIf 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.…
<resourceadapter>
<resourceadapter-class>com.oracle.tuxedo.adapter.
TuxedoResourceAdapter</resourceadapter-class>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.Listing 39 resourceadapter-class Element - com.oracle.tuxedo.adapter.TuxedoClientSideResourceAdapterIf 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.<resourceadapter>
<resourceadapter-class>com.oracle.tuxedo.adapter.
TuxedoFBCResourceAdapter</resourceadapter-class>
...There is a set of Resource Adapter Deployment Descriptor custom properties that are available for all three styles configuration: Resource Adapter Deployment Descriptor configuration, factory-based configuration, and dmconfig-based configuration. The only exception is the "dmconfig" custom property that is only available using dmconfig-based configuration. If you specified this property while using a Resource Adapter Deployment Descriptor-based configuration, this property is ignored.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.You must specify the 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 Tuxedo JCA Adapter Programming Guide.
Table 29 Customization Properties For more information, see Transaction Support. 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. Table 30 lists the trace-level control values.
Table 30 Trace Level Control Values Gateway input and output, including the ATMI verbs. JATMI input and output, including low-level JATMI calls. More JATMI information. Listing 41 shows an example deployment descriptor file using the customization properties.Repackaging requires converting the 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 *The application server has a default connection pool size. For most applications, the default connection pool size is large enough; however, in some situations the default connection pool size may not be enough. For example, the Oracle WebLogic Server has a default connection pool size of10 which means it can support a maximum of 10 concurrent JCA clients using the same adapter to access remote Enterprise Information Systems (EIS). If an application wants to support more than 10 concurrent clients using the Tuxedo JCA Adapter, the application must expand the connection pool size.For example, to change the connection pool size from default value to 20 in an Oracle WebLogic Server installation, you can modify the weblogic-ra.xml file in the META-INF directory as shown in Listing 42.
Note: 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.The Tuxedo JCA Adapter attempts to use the first network address to establish connection with a remote Oracle Tuxedo GWTDOMAIN gateway. If it fails, it tries the next one until either a connection is established, or it exhausted all the network addresses. However, there is no link-level fail back. Listing 43 shows an example using dmconfig file configuration that a local access point, LDOM1, has two network addresses for link-level failover. It also shows that a remote access point, RDOM1, has 2 network addresses for link level fail over.Listing 43 Link-Level Fail Over ExampleBesides link-level fail over, Tuxedo JCA Adapter also supports Service-Level Fail Over. The service- level fail over specifies the alternate sessions that the remote Oracle Tuxedo resources can be accessed. This is a comma separated list. It is different from load balancing. Service-Level Fail Over only available when ConnectionPolicy equals to ON_STARTUP. Other types of ConnectionPolicy will only have load balancing.Listing 44 shows an example imported resource, TOUPPER, load balanced between session_1 and session_2.Listing 44 Load Balancing ExampleListing 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.Link-Level Encryption (LLE), is a fast, proprietary technology that encrypts all user-message flow between the Tuxedo JCA Adapter and the Tuxedo TDomain gateway. It supports 40-bit, 56-bit and 128-bit encryption strength. This feature is enabled by configuring MaxEncryptBits and MinEncryptBits in the SessionProfile of the adapter configuration.The default value for MaxEncryptBits is 128-bit and the default value for MinEncryptBits is 0. The permissible values for both elements are 0 (no encryption), 40-bit, 56-bit, 128-bit, and 256-bit. 256-bit encryption is for SSL AES 256-bit encryption (LLE does not support 256-bit encryption). The MinEncryptBits value must be smaller than or equal to the MaxEncryptBits value.
Notes: If SSL is not configured and MaxEncryptBits is set to256-bit, MaxEncryptBits is scaled down to maximum 128-bit LLE.LLE must also be configured in the GWTDOMAIN gateway.
•
• 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 by setting the "MutualAuthenticationRequired" element to "true".Listing 46 SSLInfo Configuration ExampleIn this example, you must run the DMConfigChecker utility before it can be used by the Tuxedo JCA Adapter (since there are three elements that require encryption).The 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 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.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 is already established, it will not invalidate the session and restarts the session negotiation process. However, if a password pair expired before the session negotiation started, then that password pair is not used for authentication. If no valid password pair is found during session authentication, 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 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 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" information in the host Application Server JCA container.Listing 47 Identity Propagation ExampleAn Oracle Tuxedo ATMI conversation is a half duplex conversation (which means the sending and receiving is done in a controlled manner). The party that has control of the conversation can send data; when it is time for that party to relinquish the control of the conversation it sends the TPRECVONLY flag along with the data. When the other party receives the latest data, it sees the flag being translated into TPSENDONLY and knows it obtained control the conversation.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.When the server receives this data, it turns around to send data back to the Java client until it decides it is time for Java client to send data. These send and receive sequences can be repeated several times until the conversation is completed. When the conversation is completed, the server sends a tpreturn(), and the Java client receives an event indicating the conversation is completed.
•
•
• The change of conversation control is done using a pair of flags for tpconnect, tpsend, and the tprecv method. These flags are defined in the weblogic.wtc.jatmi.TPException class. These flags are: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.For a normal conversation to complete, the Oracle Tuxedo conversational server must have control over the conversation. It ends the conversation normally through tpreturn() in the service routine. In this case, the Java client should receive a TPReplyException with conversational event "TPEV_SVCSUCC" (or "TPEV_SVCFAIL").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.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.Listing 50 is an interface declaration example.Listing 50 Interface Declaration ExamplePublic 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.This flag signifies that after caller data is sent, the caller gives up control of the conversation; this means the caller can no long issue any more tpsend calls. When the receiver on the other end of conversation receives the data, it l also receives an event, TPEV_SENDONLY, indicating that it has conversation control.If the java client wants to send data several times before the last data sent with the TPRECVONLY flag, the client can set the flags value to 0.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:
•
•
• An event occurred. User data is not sent when this error occurs. The event type is returned in event, and it can be retrieved by calling TPReplyException.getrevent().
• 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 TPReplyException.getrevent(). The following is a list of valid events.This event indicates that the Oracle Tuxedo conversational server has initiated tpreturn() and during tpreturn() it encountered an error that precluded the service from returning successfully. Because of the nature of this event, any application defined data or return code are not available. The conversation also becomes invalid.This event indicates that the Oracle Tuxedo conversation server has finished unsuccessfully as defined by the application. It called tpreturn() with either TPFAIL or TPEXIT. If the Oracle Tuxedo conversation server has conversation control at the time tpreturn() was called, then it can pass an application defined return code and a typed buffer. When the Java client sees this event, the conversation becomes invalid.This event indicates that the Oracle Tuxedo conversational server has finished the conversation successfully as defined by the application and calls tpreturn() with TPSUCCESS. When the Java client receives this event, the conversation is invalid.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:
•
•
• An event occurred. Its event type is available in event. It can be retrieved by calling TPReplyException.getrevent().
• tprecv() was called improperly. For example, the Java client still has conversation control.Either the Tuxedo JCA Adapter or a remote access point encountered a problem.Java client code should capture both exception types and handle them accordingly.For a Java client conversation always ending with tprecv(), the last tprecv() corresponds to the Oracle Tuxedo conversation server tpreturn(). When a Java client is done using the Connection that obtained through ConnectionFactory.getConnection(), it must return the Connection to the pool by calling Connection.close(); failing to do this causes a Connection leak.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.When a conversation event occurs, Java clients receive a TPReplyException. Java clients must call TPRecplyException.gettperrno() to decide whether an event occurred or not ,and then uses TPReplyException.getrevent() to retrieve the conversational event.Listing 51 shows a relinquish conversation control example.Listing 51 Relinquish Conversation ControlThe Tuxedo JCA Adapter conversational Java client can regain conversation control when it receives a TPEV_SENDONLY event inside a TPReplyException while calling tprecv(). The Java client must check the returned TPERRNO to see if the conversational event exists or not, and then retrieves the event as shown in Listing 52.Listing 52 Regain Conversation ControlThe Oracle Tuxedo conversational server also could regain conversation control when it receives a TPEV_SENDONLY event while calling tprecv(). It also could relinquish the conversational control by calling tpsend() with TPRECVONLY.Listing 53 Retrieving Conversational EventThere is no special configuration required to make a conversation; however, a correctly configured Oracle Tuxedo conversation server must be presented in TUXCONFIG and exports its service through BDMCONFIG. For the Tuxedo JCA Adapter, you can elect not to configure Import and allow the default import to work, or you can configure an Import for every imported Oracle Tuxedo service (including conversational service).Listing 54 Conversational ServerIn the above example, the Oracle Tuxedo server "Convserv" is a conversational server set by "CONV=Y".The conversation service must be exported by Tuxedo GWTDOMAIN using the configuration in the BDMCONFIG file. For example, if "Convserv" provides the service "CTOUPPER", then "CTOUPPER" must be exported through the BDMCONFIG file.
• You can either explicitly configure the Oracle Tuxedo service (i.e., CTOUPPER), as an imported resource, orListing 55 shows a Tuxedo JCA Adapter dmconfig file imported resource example.Listing 56 shows a very simple complete example application.
1. The client initiates tpconnect() with data to start conversation.
2. The client calls tpsend() to send a second piece of data and gives control to the Oracle Tuxedo Server.
3. The name of the source file is called "convsimp.c".Listing 56 Oracle Tuxedo Conversation ServerListing 57 is an example Oracle Tuxedo configuration file.Listing 57 Oracle Tuxedo Configuration FileListing 58 shows an Oracle Tuxedo Domain configuration example.Listing 58 Oracle Tuxedo Domain ConfigurationListing 59 shows a JATMI client code example for WebLogic server.Listing 59 Java Client ApplicationThe 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 60 dmconfig FileThe above configuration example configures one local access point "JDOM", one remote access point "TDOM". It also configures one Oracle Tuxedo TDomain session between JDOM and TDOM named "session_1", and also configures session_1 profile with the name "profile_1".There is one imported resource configured with the name "MYCONV" corresponding with the Oracle Tuxedo exported service name "MYCONV".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.Listing 61 The Resource Adapter Deployment DescriptorTo use the Tuxedo JCA Adapter running in WebLogic Server, you must configure the JNDI name to a file with the specific name "weblogic-ra.xml". This file should be put in the META-INF of the Resource Archive as shown in Listing 62.Listing 62 WebLogic Server Specific Side FileThe 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.The Tuxedo JCA Adapter SOA configuration wizard helps you to navigate through the configuration pages. These pages include the Welcome Page, Service Name page, JNDI connection factory page, operation page, and Tuxedo JCA Adapter properties page. The Tuxedo JCA Adapter properties page contains com.oracle.tuxedo.adapter.cci.TuxedoInteractionSpec properties.Listing 63 shows the new Tuxedo JCA Adapter type to be configure in the SOA configuration file, soa-config.xml.Listing 63 soa-config.xmlThe SOA configuration file is located in the $JDEVELOPER_HOME/integration/seed/soa/configuration directory.You can start the Oracle JDeveloper IDE by either double clicking the JDeveloper icon, or by starting it using $JDEVELOPER_HOME/jdev/bin/jdev. By scrolling down the slider in the Component palette, you can find an "Oracle Tuxedo" icon for the Tuxedo JCA Adapter. Figure 1provides a screenshot of JDeveloper with Tuxedo JCA Adapter enabled through SOA Extension.The following are step-by-step procedures to configure an "External Reference" to the Oracle Tuxedo service TOUPPER that can be invoked by SOA framework at runtime to access an Oracle Tuxedo service through the Tuxedo JCA Adapter.Scroll down the "Component Palette" from panel right-hand side to find "Tuxedo JCA Adapter", you can drag-and-drop the "Tuxedo JCA Adapter'" icon to the "External References" area in the middle window pane.The Tuxedo JCA Adapter SOA configuration wizard"Welcome" page appears as shown in Figure 2.Figure 2 Welcome PageClick the "Next" button on the "Welcome" page and the Service Name page is displayed as shown in Figure 3. You can enter the same service name as the Oracle Tuxedo exported service name, or any name that makes sense for an SOA application. This Service Name is for SOA reference.Figure 3 Service Name PageFigure 4 STRING_TOUPPERClick the "NEXT" button on "Service Name" page.The "Connection Factory Information" page appears as shown in Figure 5. The "Connection Factory Information" page allows you to specify which Tuxedo JCA Adapter connection factory to use by specifying the JNDI name of the intended connection factory.Figure 5 Connection Factory Information PageEnter the JNDI name for the connection factory you intend to use. In this example we'll use the default JNDI name "eis/TuxedoConnectionFactory".Click the "NEXT" button. The Adapter Interface Page appears as shown inFigure 6. The "Adapter Information" page is used to construct WSDL and specifies the XSD schema for the data buffer.Figure 6 Adapter Interface PageClick the "NEXT" button and the "Operation" page appears as shown in Figure 7. Leave the "Outbound" value alone as the Tuxedo JCA Adapter SOA configuration wizard only supports "Outbound Operation".Figure 7 Operation PageClick the "NEXT" button and the "Oracle Tuxedo Interaction Properties" page appears as shown in Figure 8. You must enter the actual Tuxedo JCA Adapter imported Tuxedo service name.In this example, the imported Tuxedo service name is "STR_TOUPPER". Enter "STR_TOUPPER" as the Oracle Tuxedo service as shown in Figure 9.Figure 9 STR_TOUPPERClick the "NEXT" button and the "Oracle Tuxedo Request Buffer Properties" page appears as shown in Figure 10. Specify the Tuxedo JCA Adapter Interaction Request buffer type for the targeted Oracle Tuxedo service.If the Oracle Tuxedo buffer type is one of the structure buffer types (such as FML/FML32/VIEW/VIEW32/X_C_TYPE/X_COMMON), you must provide a corresponding Java class generated from the Field Table or View Table Definition file. These class can be generated using tools provided by Tuxedo JCA Adapter, and they must match the user-defined XSD d for that buffer.Figure 10 Tuxedo Request Buffer PropertiesFigure 11 STRING Buffer TypeClick the "NEXT" button and the "Oracle Tuxedo Reply Buffer Properties" appears as shown in Figure 12. Select all the Tuxedo JCA Adapter Interaction reply buffer types that can be returned from an Oracle Tuxedo Service.Figure 12 Tuxedo Reply Buffer Properties PageFigure 13 String BufferClick on "NEXT" button and the "Message" page appears as shown in Figure 14. The "Message" configuration is used to configure the corresponding schema. You must specify the schema file location and select the schema element that defines the outbound message.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 14 Message Configuration PageFigure 15 Import Schema FileFigure 16 Localize FilesFigure 17 Type ChooserFigure 18 InboundFigure 19 OutboundFigure 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 messageFigure 20 Message SchemaFigure 21 Finish PageClick the "Finish" button and an Tuxedo JCA Adapter external reference is created as shown in Figure 22.Figure 22 External referenceThe corresponding class is generated using an Oracle Tuxedo FML table as input for the weblogic.wtc.jatmi.mkfldclass compiler to generate the class. The XSD must indicate that the XML is enclosed in an element with tag name "FML" as shown in Listing 81.Listing 82 Output FML SchemaThe corresponding class is generated using a Tuxedo FML32 table as input for the weblogic.wtc.jatmi.mkfldclass32 compiler to generate the class. The XSD must indicate that the XML is enclosed in an element with tag name "FML32" as shown in Listing 83.Listing 83 XML Enclosed Element Tag "FML32"Listing 84 Output FML32 SchemaThe corresponding class is generated using an Oracle Tuxedo VIEW definition file as input for the weblogic.wtc.jatmi.viewj compiler to generate the class. The XSD must indicate that the XML is enclosed in an element tag named "VIEW". The buffer sub-type is the name defined in VIEW definition file and should be used as XML tag name that encloses the actual payload as shown Listing 85.Listing 85 XML Enclosed in Element Tag "VIEW"Listing 86 Output View SchemaThe corresponding class is generated using an Oracle Tuxedo VIEW32 definition file as input for the weblogic.wtc.jatmi.viewj32 compiler to generate the class. The XSD must indicate that the XML is enclosed in an element tag named "VIEW32". The buffer sub-type is the name defined in VIEW definition file and should be used as an XML tag name that encloses the actual payload as shown in Listing 87.Listing 88 Output View32 SchemaThe corresponding class is generated using an Oracle Tuxedo VIEW definition file as input for the weblogic.wtc.jatmi.viewj compiler with command line option "-xctype" to generate the class. The XSD must indicate that the XML is enclosed in an element tag named "X_C_TYPE". The buffer sub-type is the name defined in VIEW definition file and should be used as a XML tag name that encloses the actual payload as shown in Listing 89.The "MyXCType" tag is the buffer sub-type.Listing 90 Output X_C_TYPE SchemaThe corresponding class is generated using an Oracle Tuxedo VIEW definition file as input for the weblogic.wtc.jatmi.viewj compiler with command line option "-xcommon" to generate the class. The XSD must indicate that the XML is enclosed in an element tag named "X_COMMON". The buffer sub-type is the name defined in VIEW definition file and should be used as a XML tag name that encloses the actual payload as shown in Listing 91.The "MyXCommon" tag is the X_COMMON buffer sub-type.Listing 92 Output X_C_TYPE SchemaSince SOA is universally WSDL-based, the WSDL operation signature decides which "verb" to use. SYNC_SEND_RECEIVE corresponds to WSDL as shown in Listing 92.Listing 93 SYNC_SEND_RECEIVE corresponds to WSDLSYNC_SEND corresponds to WSDL as shown in Listing 94.Listing 94 SYNC_SEND"SYNC_RECEIVE" is not supported by WSDL operation.The input data means the XML record received from SOA Framework by the Tuxedo JCA Adapter for service request targeted to Oracle Tuxedo. Table 31 gives a matrix for input data conversion from SOA Framework to Oracle Tuxedo.
Table 31 Input Buffer Type Conversion Table If an Oracle Tuxedo service supports multiple Oracle Tuxedo buffer types and the corresponding SOA composite application can generate requests with more than one type of an Oracle Tuxedo buffer, you should configure the same service multiple times using configuration wizard. This causes more than one TuxedoInteractionSpec to be available to SOA framework invoking an Oracle Tuxedo service.If the targeted Oracle Tuxedo service requires FML/FML32 as an input buffer type, a request Class must be configured with a corresponding FML/FML32 class. If not specified, the configuration wizard will not allow you to advance to the next wizard page. If the actual received input XML record contains a tag that there is no corresponding FML/FML32 field name, then a ResourceException is thrown when SOA Framework invokes the Tuxedo JCA Adapter.Table 32 provides a matrix for output data conversion from an Oracle Tuxedo buffer to an XML record.
Table 32 Output Buffer Type Conversion Table If the reply buffer type is one of VIEW/VIEW32/X_C_TYPE/X_COMMON and you did not configure the corresponding property for the class name TuxedoInteractionSpec., a ResourceException exception is thrown. The same requirement also applies to FML/FML32 buffer types.If the reply buffer type is one of STRING/CARRAY/X_OCTET/MBSTRING and you did not configure an appropriate XML tag, a ResourceException exception is thrown."No Conversion" means the Tuxedo JCA Adapter returns a reply buffer, or accepts a request with direct mapping. If the reply XML buffer does not contain a well-formed XML document, a ResourceException is thrown."Type 1" conversion means the Tuxedo JCA Adapter uses FLDID to retrieve FIELD NAME. It uses an XML element tag for both request and reply as handled by ALSB Tuxedo Transport. In this case, you must configure an FML class name for FML and an FML32 class name for FML32 as shown in Table 33.
Table 33 XML Root Element Tag Name Listing 95shows is an FML32 table example.Listing 95 FML32 Table Example.Using the above FML32 table as input for weblogic.wtc.jatmi.mkfldclass32 with package name tuxedo.test.datarecord.FML32 creates a Java class as shown in Listing 96Listing 96 Java Class ExampleListing 97 shows what it looks like after it is converted from FML32 buffer.Listing 97 XML Document Converted from an FML32 BufferListing 98 shows the corresponding Schema:Listing 98 Corresponding SchemaWhen you select VIEW/VIEW32/X_C_TYPE/X_COMMON as request and/or reply buffer type as shown in Listing 34, a fully qualified Java class corresponding to the Oracle Tuxedo buffer type is needed. You can enter Java class information in a Text Input Field.X_C_TYPE and X_COMMON are similar to VIEW and thus they can be treated/created the same way as VIEW.The fully qualified class path will be part of the expanded TuxedoInteractionSpec.
Table 34 XML Root Element Tag Name You must specify an element of the same name as sub-type as the wrapping XML wrapping element in the corresponding schema file. For instance, if the sub-type name is "myview32" then the corresponding XML document should look like Listing 99Listing 99 myview32 XML DocumentListing 100 View32 XSD FileListing 101 shows a VIEW definition file that can be used with weblogic.wtc.jatmi.viewj32.Listing 101 VIEW Definition FileListing 103shows VIEW32 class file generated using viewj32 compiler.Listing 102 viewj32 Compiler Generated View32 Class FileListing 103 is the corresponding XML document generated using the above VIEW32 class.Listing 103 Corresponding VIEW332 Class XML DocumentListing 104 shows is the corresponding schema:Listing 104 Corresponding SchemaTo 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 the reply buffer is CARRAY and you specified "attachment", the CARRAY data is attached to XMLRecord. If the reply buffer is CARRAY and you did not specify "attachment", the reply data is treated as an XML document.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.Listing 105 FML32 Schema With Embedded FML32 and VIEW32