A OC4J Resource Adapter Configuration Files

This appendix begins with an overview of resource adapter configuration files, then provides detailed reference information about the OC4J-specific files. The following topics are covered:

Overview of Resource Adapter Configuration Files
Hierarchy of oc4j-ra.xml
Elements and Attributes of oc4j-ra.xml
Sample oc4j-ra.xml
Hierarchy of oc4j-connectors.xml
Elements and Attributes of oc4j-connectors.xml
Sample oc4j-connectors.xml

Overview of Resource Adapter Configuration Files

This section provides an overview of the resource adapter configuration files: the standard ra.xml file and the Oracle oc4j-ra.xml and oc4j-connectors.xml files.

Figure A-1 shows the relationship between OC4J J2CA XML files and EAR and RAR files for deployment, as follows:

An oc4j-ra.xml file is associated with each RAR file, whether for a standalone or in-application resource adapter, to set configuration for the resource adapter being deployed.
An oc4j-connectors.xml file is associated with each EAR file (for applications using resource adapters), to reference the resource adapters being deployed with the application as well as set additional configuration.
Also, an oc4j-connectors.xml file is associated with the OC4J default application, to reference standalone resource adapters as well as set additional configuration.

Figure A-1 Deployment of OC4J-Specific XML Configuration Files for J2CA

Description of "Figure A-1 Deployment of OC4J-Specific XML Configuration Files for J2CA"

Stan dard ra.xml Configuration File

An ra.xml file for a resource adapter is supplied by the resource adapter provider and is included in the RAR file for deployment. When you subsequently configure a resource adapter, as discussed throughout this manual, entries in ra.xml typically serve as defaults, which you can override through Application Server Control. Any configuration settings that override ra.xml entries are reflected in corresponding oc4j-ra.xml entries generated by OC4J.

Here are portions of a sample J2CA 1.5 ra.xml file:

<outbound-resourceadapter>
   <connection-definition>
      <managedconnectionfactory-class>
         com.example.ManagedConnectionFactoryImpl
      </managedconnectionfactory-class> 
      <connectionfactory-interface>
         javax.resource.cci.ConnectionFactory
      </connectionfactory-interface> 
      <connectionfactory-impl-class>
         com.example.ConnectionFactoryWrapper
      </connectionfactory-impl-class> 
      <connection-interface>javax.resource.cci.Connection</connection-interface> 
      <connection-impl-class>
         com.example.ConnectionWrapper
      </connection-impl-class> 
      <config-property> 
         <config-property-name>ServerName</config-property-name> 
         <config-property-type>java.lang.String</config-property-type> 
         <config-property-value>www.example.com</config-property-value> 
      </config-property> 
      <config-property> 
         <config-property-name>ConnectionUrl</config-property-name> 
         <config-property-type>java.lang.String</config-property-type> 
         <config-property-value>
            jdbc:oracle:thin:@www.example.com:1521/myservice
         </config-property-value> 
      </config-property> 
   </connection-definition> 
...
</outbound-resourceadapter>

Refer to the J2CA specification for detailed information about ra.xml and the elements and attributes it supports.

Ora cle oc4j-ra.xml Configuration File

The oc4j-ra.xml file contains OC4J-specific configuration for a resource adapter. When you deploy a RAR file that does not contain an oc4j-ra.xml file, OC4J will create one automatically, using settings from the ra.xml file as default values as applicable. Then, whenever you use Application Server Control Console to create or edit a connection factory, OC4J updates the oc4j-ra.xml file.

This file declares connection factories, with each <connector-factory> element mapping to a <connection-definition> element in ra.xml. This is a many-to-one relationship, as there can be multiple <connector-factory> elements corresponding to a single <connection-definition> element. The <connector-factory> elements are all under the root <oc4j-connector-factories> element.

Subelements of <connector-factory> include <connection-pooling>, to set up connection pooling for the factory, and <security-config>, to set up container-managed sign-on. Each connector factory can have configuration for a private connection pool, or can use a shared connection pool that is set up through a <connection-pool> subelement of <oc4j-connector-factories>.

You can optionally package an oc4j-ra.xml file with the RAR file for deployment. It is typical for a resource adapter provider to supply a number of configuration files specific to particular application servers, in addition to their ra.xml file, and this may include an oc4j-ra.xml file. When you deploy a RAR file that includes oc4j-ra.xml, OC4J does not generate an oc4j-ra.xml file or alter your packaged oc4j-ra.xml file during deployment. It simply accepts the settings in the packaged file and exposes them as assembled values through Application Server Control, which of course you can later edit if desired.

See "What Are the Packaging and Deployment Features?" for related information.

Ora cle oc4j-connectors.xml Configuration File

For each EAR file deployed to OC4J, the oc4j-connectors.xml file lists the resource adapters deployed with the application, using a <connector> element for each adapter. Subelements of <connector>, for configuration relating to a particular resource adapter, include <adminobject-config> to configure administered objects, and <security-permission> to set up permissions.

An oc4j-connectors.xml file is also used to store the list of standalone resource adapters in OC4J, indicating the number of resource adapters that were deployed outside of EAR files and are to be globally available. This oc4j-connectors.xml file is associated with the OC4J default application.

For each application, there is a <connectors> element in the orion-application.xml file to indicate where the associated oc4j-connectors.xml file is located. For standalone resource adapters, oc4j-connectors.xml is located by default in the OC4J j2ee/instance/config directory, as indicated in the <connectors> element in the global OC4J application.xml file. In the directory name, instance is the name of an OC4J instance (home by default in an Oracle Application Server environment and always home in a standalone environment).

If you do not provide an oc4j-connectors.xml file in an EAR file, OC4J creates it for you. The global oc4j-connectors.xml file for standalone resource adapters already exists by default.

Hiera rchy of oc4j-ra.xml

Here is an overview of the oc4j-ra.xml element hierarchy.

Elem ents and Attributes of oc4j-ra.xml

This section is an alphabetical dictionary of elements of the oc4j-ra.xml file. See the preceding section, "Hierarchy of oc4j-ra.xml", if you are interested in the hierarchy.

Note:

Where attributes are discussed, note that attribute values are always set inside quotes: attribute="value"

<co nfig-property>

Parent element: <connector-factory>

Child elements: None

Required? Optional; zero or more

Each <config-property> element specifies the name and value of a property setting for the connection factory. These map to <config-property> elements in the corresponding connection definition in the ra.xml file.

Table A-1 <config-property> Attributes

Name Description

Name	Description
name	Values: String Default: n/a (required) The name (from `ra.xml`) of the connection property being set.
value	Values: String Default: n/a (required) The desired value of the connection property being set.

name

Values: String

Default: n/a (required)

The name (from ra.xml) of the connection property being set.

value

Values: String

Default: n/a (required)

The desired value of the connection property being set.

<con nection-pool>

Parent element: <oc4j-connector-factories>

Child elements: <property>

Required? Optional; zero or more

This element specifies the name of a shared connection pool, and optionally specifies property settings of the pool through <property> subelements.

Note:

Do not confuse the <connection-pool> element with the <connection-pooling> element, which is a subelement of <connector-factory>.

Table A-2 <connection-pool> Attributes

Name	Description
name	Values: String Default: n/a (required) The desired name of the shared connection pool.

<con nection-pooling>

Parent element: <connector-factory>

Child elements: <property>, <use-connection-pool>

Required? Optional; zero or one

This element specifies a connection pool for use by the connection factory defined through the parent <connector-factory> element.

The <connection-pool> element either specifies a private connection pool with its own settings, through <property> subelements, or uses a shared pool, through a <use-connection-pool> subelement.

The absence of this element is equivalent to an attribute setting of use="none", disabling connection pooling.

See "Configuring Connection Pooling in OC4J" and "Sharing Connection Pools" for related information about connection pools.

Note:

Do not confuse the <connection-pooling> element with the <connection-pool> element, which is a subelement of <oc4j-connector-factories>.

Table A-3 <connection-pooling> Attributes

Name	Description
use	Values: shared\|private\|none Default: No default Use "`shared`" to use a shared connection pool, "`private`" to specify a private connection pool, or "`none`" to disable connection pooling for the connection factory.

<con nectionfactory-interface>

Parent element: <connector-factory>

Child elements: None

Required? Optional; zero or one

The value of this element indicates the fully qualified name of the Java interface upon which connection factories defined through the parent <connector-factory> element are based:

<connectionfactory-interface>interfacename</connectionfactory-interface>

A connection factory object is an instance of a class that implements this interface. This must be one of the interfaces specified for the corresponding connection definition in the ra.xml file.

The <connectionfactory-interface> element has no attributes.

Important:

This element is not required according to the schema definition, for backward compatibility reasons, but its omission will result in an exception.

<con nector-factory>

Parent element: <oc4j-connector-factories>

Child elements: <config-property>, <connection-pooling>, <connectionfactory-interface>, <description>, <log>, <security-config>, <xa-recovery-config>

Required? Optional; zero or more

This element, through its attributes and subelements, specifies a connection factory for the resource adapter.

Table A-4 <connector-factory> Attributes

Name Description

Name	Description
connector-name	Values: String Default: n/a (required) The name of the resource adapter instance. This name can be the same as the connector name specified during deployment for a standalone resource adapter (in the `deploymentName` property of the `deploy` task or through the Application Server Control Console deployment page) or the RAR file name, without the `.rar` extension, for a resource adapter deployed within an EAR file. The connector name or RAR file name (without the extension) corresponds to the `name` attribute of the applicable `<connector>` element in the `oc4j-connectors.xml` file.
location	Values: String Default: n/a (required) A JNDI location to which the connection factory object will be bound.

connector-name

Values: String

Default: n/a (required)

The name of the resource adapter instance. This name can be the same as the connector name specified during deployment for a standalone resource adapter (in the deploymentName property of the deploy task or through the Application Server Control Console deployment page) or the RAR file name, without the .rar extension, for a resource adapter deployed within an EAR file. The connector name or RAR file name (without the extension) corresponds to the name attribute of the applicable <connector> element in the oc4j-connectors.xml file.

location

Values: String

Default: n/a (required)

A JNDI location to which the connection factory object will be bound.

<default-map ping>

Parent element: <principal-mapping-entries>

Child elements: <res-user>, <res-password>

Required? Optional; zero or one

This element, through its subelements, specifies a default resource principal. If an initiating principal does not match any of those that are mapped to resource principals through <principal-mapping-entry> elements, then the default resource principal is used.

The <default-mapping> element has no attributes.

<description>

Parent element: <connector-factory>

Child elements: None

Required? Optional; zero or one

The value of this optional element describes the connection factory:

<description>Description of connection factory.</description>

The <description> element has no attributes.

<description>

Parent element: <principal-mapping-entries>

Child elements: None

Required? Optional; zero or one

The value of this optional element describes the principal mapping entries:

<description>Description of principal mapping entries.</description>

The <description> element has no attributes.

<fil e>

Parent element: <log>

Child elements: None

Required? Required within <log>; one only

This element, through its path attribute, specifies the absolute or relative path and name of a log file where OC4J will write logging and tracing messages relating to the resource adapter and EIS.

Table A-5 <file> Attributes

Name	Description
path	Values: String Default: No default The absolute or relative path and name of the log file.

<impl-clas s>

Parent element: <principal-mapping-interface>

Child elements: None

Required? Required; one only

The value of this element indicates the fully qualified name of the principal mapping class:

<impl-class>classname</impl-class>

The <impl-class> element has no attributes.

<initi ating-user>

Parent element: <principal-mapping-entry>

Child elements: None

Required? Required within <principal-mapping-entry>; one only

The value of this element is the user name of an initiating principal, to be mapped to a resource principal through an associated <res-user> (and <res-password>) element:

<principal-mapping-entry>
   <initiating-user>name</initiating-user>
   <res-user>name</res-user>
   <res-password>pwd</res-password>
</principal-mapping-entry>

The <initiating-user> element has no attributes.

The OC4J property jaas.username.simple determines whether realm names are prefixed in user names for returned principals. With the default "true" setting, realm names are not prefixed. If you configure and use custom realms, you must explicitly set this property to "false" to ensure that OracleAS JAAS Provider authentication and authorization work properly.

To specify a "false" setting, use a <property> subelement of the <jazn> element (in orion-application.xml for application level, or in the instance-level jazn.xml file for OC4J instance level), as follows:

<jazn ... >
...
<property name="jaas.username.simple" value="false" />
...
</jazn>

Important:

Always set jaas.username.simple to "false" when multiple realms are configured.

See the Oracle Containers for J2EE Security Guide for more information about the jaas.username.simple property.

<jaas-ap plication-name>

Parent element: <jaas-module>

Child elements: None

Required? Required within <jaas-module>; one only

The value of this element indicates the name of the JAAS login module used for container-managed sign-on:

<jaas-module>
   <jaas-application-name>modulename</jaas-application-name>
</jaas-module>

The <jaas-application-name> element has no attributes.

<jaas-mo dule>

Parent element: <security-config>

Child elements: <jaas-application-name>

Required? Optional; zero or one (but required if use="jaas-module" in the parent <security-config>)

This element is for the "JAAS login module" mechanism for container-managed sign-on. In this mechanism, a developer plugs in a JAAS login module (specified in the <jaas-application-name> subelement) under the application to use a particular authentication mechanism. A login module may, for example, simply implement a user/password authentication mechanism, or may use more sophisticated technology such as by connecting to a Smart Card.

Use of the <jaas-module> element must be combined with a setting of use="jaas-module" in the parent <security-config> element (each requires the other).

The <jaas-module> element has no attributes.

<lo g>

Parent element: <connector-factory>

Child elements: <file>

Required? Optional; zero or one

This specifies a log file, through its <file> subelement.

See "Configuring OC4J Logging for Connection Factories" for related information about log files and their configuration.

The <log> element has no attributes.

<oc4j-con nector-factories>

Parent element: n/a (root)

Child elements: <connection-pool>, <connector-factory>

Required? Required; one only

This is the top-level element of the oc4j-ra.xml file, encompassing configuration of connection factories and connection pools for a single resource adapter deployed to OC4J.

Table A-6 <oc4j-connector-factories> Attributes

Name Description

Name	Description
schema-major-version	Values: String Default: No default The major version number of the `oc4j-ra.xml` XSD. If you create `oc4j-ra.xml` manually, set this attribute to 10 for use with the OC4J 10.1.3 implementation.
schema-minor-version	Values: String Default: No default The minor version number of the `oc4j-ra.xml` XSD. If you create `oc4j-ra.xml` manually, set this attribute to 0 for use with the OC4J 10.1.3 implementation.

schema-major-version

Values: String

Default: No default

The major version number of the oc4j-ra.xml XSD. If you create oc4j-ra.xml manually, set this attribute to 10 for use with the OC4J 10.1.3 implementation.

schema-minor-version

Values: String

Default: No default

The minor version number of the oc4j-ra.xml XSD. If you create oc4j-ra.xml manually, set this attribute to 0 for use with the OC4J 10.1.3 implementation.

Note:

These attributes do not appear directly in the XSD for ocj4-ra.xml. They are according to the attributeGroup specification in the top-level OC4J XSD.

<pas sword>

Parent element: <password-credential>

Child elements: None

Required? Optional; zero or one

The value of this element is for a password for the associated user name (through the corresponding <username> element), for XA recovery sign-on through the connection factory.

There is a corresponding <username> element for the associated user name.

Specify the password setting in one of the following ways:

Direct password: the value is the password itself
Indirect Password: the value is a right-arrow followed by a key that OC4J uses for a lookup in the User Manager (such as through the jazn-data.xml file)
No password: empty content

For an indirect password, the key is often just the user name, as in the following example:

...
<password-credential>
   <username>jmsuser</username>
   <password>->jmsuser</password>
</password-credential>
...

The <password> element has no attributes.

<pas sword-credential>

Parent element: <xa-recovery-config>

Child elements: <username>, <password>

Required? Optional; zero or more

This element, through its <username> and <password> subelements, specifies sign-on information for XA recovery.

You can use multiple <password-credential> elements to specify multiple XA recovery sign-on identities.

The <password-credential> element has no attributes.

<principal-map ping-entries>

Parent element: <security-config>

Child elements: <description>, <principal-mapping-entry>, <default-mapping>

Required? Optional; zero or one (but required if use="principal-mapping-entries" in the parent <security-config>)

This element is for the "principal mapping entries" mechanism for container-managed sign-on. In this mechanism, principal mappings are specified through OC4J-specific configuration settings ("declaratively").

Use of the <principal-mapping-entries> element must be combined with a setting of use="principal-mapping-entries" in the parent <security-config> element (each requires the other).

The <principal-mapping-entries> element has no attributes.

<principal-map ping-entry>

Parent element: <principal-mapping-entries>

Child elements: <initiating-user>, <res-user>, <res-password>

Required? Optional; zero or more

For the "principal mapping entries" mechanism, there can be any number of <principal-mapping-entry> elements. Each one specifies, through its subelements, a mapping between an initiating principal and a resource principal for the EIS connection.

The <principal-mapping-entry> element has no attributes.

<principal-map ping-interface>

Parent element: <security-config>

Child elements: <impl-class>, <property>

Required? Optional; zero or one (but required if use="principal-mapping-interface" in the parent <security-config>)

This element is for the "principal mapping class" mechanism for container-managed sign-on. In this mechanism, principal mappings are specified through a principal mapping class ("programmatically"). A principal mapping class is one that implements the oracle.j2ee.connector.PrincipalMapping interface, and its name is specified in the <impl-class> subelement. A developer can implement the PrincipalMapping interface directly, or can extend the oracle.j2ee.connector.AbstractPrincipalMapping class that is supplied by Oracle for convenience.

Properties of a principal mapping class are specific to the particular implementation. Property settings for a principal mapping instance are configured through <property> subelements.

Use of the <principal-mapping-interface> element must be combined with a setting of use="principal-mapping-interface" in the parent <security-config> element (each requires the other).

The <principal-mapping-interface> element has no attributes.

<pro perty>

Parent element: <connection-pool>

Child elements: None

Required? Optional; zero or more

Use a <property> element for each property you want to set for the shared connection pool defined in the parent <connection-pool> element.

Note:

This element has the same usage and attributes as the <property> subelement of <connection-pooling>, except initial-capacity is not supported.

Table A-7 <property> Attributes

Name	Description
name	Values: maxConnections \| minConnections \| scheme \| waitTimeout \| inactivity-timeout \| inactivity-timeout-check Default: n/a (required) The name of the property being set. See "Configuring Connection Pooling in OC4J" for descriptions of these properties.
value	Values: String Default: n/a (required) The desired value of the property being set. See "Configuring Connection Pooling in OC4J" for supported values of these properties.

Name

Description

name

Default: n/a (required)

The name of the property being set. See "Configuring Connection Pooling in OC4J" for descriptions of these properties.

value

Values: String

Default: n/a (required)

The desired value of the property being set. See "Configuring Connection Pooling in OC4J" for supported values of these properties.

<pro perty>

Parent element: <connection-pooling>

Child elements: None

Required? Optional; zero or more

Use a <property> element for each property you want to set for the private connection pool defined in the parent <connection-pooling> element.

Note:

This element has the same usage and attributes as the <property> subelement of <connection-pool>, except this element also supports the initial-capacity property.

Table A-8 <property> Attributes

Name	Description
name	Values: maxConnections \| minConnections \| initial-capacity\| scheme \| waitTimeout \| inactivity-timeout \| inactivity-timeout-check Default: n/a (required) The name of the property being set. See "Configuring Connection Pooling in OC4J" for descriptions of these properties.
value	Values: String Default: n/a (required) The desired value of the property being set. See "Configuring Connection Pooling in OC4J" for supported values of these properties.

Name

Description

name

Default: n/a (required)

The name of the property being set. See "Configuring Connection Pooling in OC4J" for descriptions of these properties.

value

Values: String

Default: n/a (required)

The desired value of the property being set. See "Configuring Connection Pooling in OC4J" for supported values of these properties.

<pro perty>

Parent element: <principal-mapping-interface>

Child elements: None

Required? Optional; zero or more

There can be any number of <property> elements to specify property settings for an instance of the principal mapping class, depending on how many properties the class itself has. For example, properties can specify a default user name and password, the path of a principal mapping file, information for an LDAP connection, or a default mapping.

Table A-9 <property> Attributes

Name	Description
name	The name of the property being set (a property of the principal mapping class).
value	The desired value of the property.

<re s-password>

Parent element: <default-mapping>

Child elements: None

Required? Required within <default-mapping>; one only

The value of this element specifies the password for the default resource principal of the associated <res-user> element, either directly or indirectly. This uses the same functionality as discussed for <password>.

The <res-password> element has no attributes.

<re s-password>

Parent element: <principal-mapping-entry>

Child elements: None

Required? Required within <principal-mapping-entry>; one only

The value of this element specifies the password for the resource principal of the associated <res-user> element, either directly or indirectly. This uses the same functionality as discussed for <password>.

The <res-password> element has no attributes.

<re s-user>

Parent element: <default-mapping>

Child elements: None

Required? Required within <default-mapping>; one only

The value of this element is the user name of the default resource principal for the principal mapping entries mechanism. There is also an associated <res-password> element:

<default-mapping>
   <res-user>name</res-user>
   <res-password>pwd</res-password>
</default-mapping>

The <res-user> element has no attributes.

<re s-user>

Parent element: <principal-mapping-entry>

Child elements: None

Required? Required within <principal-mapping-entry>; one only

The value of this element is the user name of a resource principal, being mapped from an initiating principal through an associated <initiating-user> element. Also use an associated <res-password> element:

<principal-mapping-entry>
   <initiating-user>name</initiating-user>
   <res-user>name</res-user>
   <res-password>pwd</res-password>
</principal-mapping-entry>

The <res-user> element has no attributes.

<se curity-config>

Parent element: <connector-factory>

Child elements: <principal-mapping-entries>, <principal-mapping-interface>, <jaas-module>

Required? Optional; zero or one

This element, through its use attribute and appropriate subelements, specifies container-managed sign-on and any associated principal mapping. Principal mapping is defined in the J2CA specification and refers to mapping from an initiating principal (such as an OC4J user) to a resource principal (resource user, or EIS user). The <security-config> element can specify any of the following:

Declarative container-managed sign-on through principal mapping entries
Programmatic container-managed sign-on through an implementation of the principal mapping interface
Programmatic container-managed sign-on through a JAAS application module
Disabling of container-managed sign-on

See the Oracle Containers for J2EE Security Guide for information about container-managed sign-on versus component-managed sign-on, and for additional information and examples regarding <security-config> and its subelements.

Table A-10 <security-config> Attributes

Name Description

Name	Description
use	Values: none \| principal-mapping-entries \| principal-mapping-interface \| jaas-module Default: No default Use "`none`" to disable container-managed sign-on (such as for component-managed sign-on), or use "`principal-mapping-entries`", "`principal-mapping-interface`", or "`jaas-module`" to indicate the mode of container-managed sign-on. These values for container-managed sign-on reflect the names of the corresponding subelements of `<security-config>`.

use

Values: none | principal-mapping-entries | principal-mapping-interface | jaas-module

Default: No default

Use "none" to disable container-managed sign-on (such as for component-managed sign-on), or use "principal-mapping-entries", "principal-mapping-interface", or "jaas-module" to indicate the mode of container-managed sign-on. These values for container-managed sign-on reflect the names of the corresponding subelements of <security-config>.

<use-connection-pool>

Parent element: <connection-pooling>

Child elements: None

Required? Optional; zero or one (but required if use="shared" in parent element, or OC4J will throw an exception)

When the parent <connection-pooling> element has the attribute setting use="shared" to use a shared connection pool, the value of the <use-connection-pool> subelement specifies the name of the shared connection pool to use:

<use-connection-pool>connectionpoolname</use-connection-pool>

This corresponds to the name attribute of the <connection-pool> element that specifies the shared pool.

The <use-connection-pool> element has no attributes.

<user name>

Parent element: <password-credential>

Child elements: None

Required? Optional; zero or one

The value of this element indicates a user name for XA recovery sign-on through the connection factory:

...
<password-credential>
   <username>name</username>
   <password>pwd</password>
</password-credential>
...

As shown, there is a corresponding <password> element for the associated password.

The <username> element has no attributes.

<xa-rec overy-config>

Parent element: <connector-factory>

Child elements: <password-credential>

Required? Optional; zero or one

This element, through one or more <password-credential> subelements, specifies sign-on information for XA recovery for the connection factory. See "Understanding and Configuring Transaction Recovery" for related information and concepts.

The <xa-recovery-config> element has no attributes.

Note:

If no sign-on credentials are specified for XA recovery, the first fallback is to use what is specified through the <security-config> element. If there is no <security-config> element, the next fallback is to sign on according to the OC4J user at the time of recovery execution.

Sam ple oc4j-ra.xml

This section shows a sample oc4j-ra.xml file that configures connection factories for a JMS resource adapter, including setup of connection pooling (both private and shared) and container-managed sign-on.

<?xml version="1.0"?>

<oc4j-connector-factories xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation=
 "http://xmlns.oracle.com/oracleas/schema/oc4j-connector-factories-10_0.xsd"
 schema-major-version="10" schema-minor-version="0" >
   <connector-factory location="OracleASjms/MyXAQCF" connector-name="OracleASjms">
      <config-property name="jndiLocation" value="jms/XAQueueConnectionFactory"/>
      <connection-pooling use="private">
         <property name="waitTimeout" value="300" />
         <property name="scheme" value="fixed_wait" />
         <property name="maxConnections" value="50" />
         <property name="minConnections" value="0" />
      </connection-pooling>
      <security-config use="principal-mapping-entries">
         <principal-mapping-entries>
            <default-mapping>
               <res-user>anonymous</res-user>
               <res-password></res-password>
            </default-mapping>
            <principal-mapping-entry>
               <initiating-user>servletuser</initiating-user>
               <res-user>jmsuser</res-user>
               <res-password>->jmsuser</res-password>
            </principal-mapping-entry>
         </principal-mapping-entries>
      </security-config>
      <connectionfactory-interface>
         javax.jms.XAQueueConnectionFactory
      </connectionfactory-interface>
   </connector-factory>
   <connector-factory location="OracleASjms/MyCF1" connector-name="OracleASjms">
      <config-property name="jndiLocation" value="jms/ConnectionFactory1"/>
      <connection-pooling use="shared">
         <use-connection-pool>commonPool</use-connection-pool>
      </connection-pooling>
      <connectionfactory-interface>
         javax.jms.ConnectionFactory
      </connectionfactory-interface>
   </connector-factory>
   <connector-factory location="OracleASjms/MyCF2" connector-name="OracleASjms">
      <config-property name="jndiLocation" value="jms/ConnectionFactory2"/>
      <connection-pooling use="shared">
         <use-connection-pool>commonPool</use-connection-pool>
      </connection-pooling>
      <connectionfactory-interface>
         javax.jms.ConnectionFactory
      </connectionfactory-interface>
   </connector-factory>
   <connection-pool name="commonPool">
      <property name="minConnections" value="0" />
      <property name="maxConnections" value="10" />
      <property name="waitTimeout" value="300" />
      <property name="scheme" value="fixed_wait" />
   </connection-pool>
</oc4j-connector-factories>

Hier archy of oc4j-connectors.xml

Here is an overview of the oc4j-connectors.xml element hierarchy.

<oc4j-connectors>
   <connector>
      <config-property>
      <security-permission>
         <security-permission-spec>
      <adminobject-config>
         <adminobject-class>
         <config-property>
      <oc4j-connectors>
      <start-order>

Elem ents and Attributes of oc4j-connectors.xml

This section is an alphabetical dictionary of elements of the oc4j-connectors.xml file. See the preceding section, "Hierarchy of oc4j-connectors.xml", if you are interested in the hierarchy.

<admin object-class>

Parent element: <adminobject-config>

Child elements: None

Required? Required; one only

The value of this element indicates the fully qualified name of the JavaBean class for the administered object:

<adminobject-config>
   <adminobject-class>classname</adminobject-class>
   ...
</adminobject-config>

The <adminobject-class> element has no attributes.

<admin object-config>

Parent element: <connector>

Child elements: <adminobject-class>, <config-property>

Required? Optional; zero or more

Each <adminobject-config> element is for an administered object for the resource adapter, specifying through its attribute and subelements the JNDI location, administered object class, and any configuration property settings.

See Chapter 7, "Managing Administered Objects" for general information about administered objects and additional information about configuring them.

Table A-11 <adminobject-config> Attributes

Name	Description
location	Values: String Default: n/a (required) The JNDI location to which the administered object instance will be bound.

Name

Description

location

Values: String

Default: n/a (required)

The JNDI location to which the administered object instance will be bound.

<co nfig-property>

Parent element: <adminobject-config>

Child elements: None

Required? Optional; zero or more

Each <config-property> subelement of an <adminobject-config> element specifies the name and desired value of a property of the administered object JavaBean.

Table A-12 <config-property> Attributes

Name	Description
name	Values: String Default: n/a (required) The name of a property of the administered object JavaBean.
value	Values: String Default: n/a (required) The desired value of the administered object property.

Name

Description

name

Values: String

Default: n/a (required)

The name of a property of the administered object JavaBean.

value

Values: String

Default: n/a (required)

The desired value of the administered object property.

<co nfig-property>

Parent element: <connector>

Child elements: None

Required? Optional; zero or more

This element, when a subelement of a <connector> element, indicates the name and deployed value of a property of the resource adapter JavaBean. Each <config-property> subelement of a <connector> element corresponds to a <config-property> subelement of a <resourceadapter> element in the ra.xml file, where the ra.xml file specifies the name and assembled value of the property.

See "Setting Properties of the Resource Adapter JavaBean" for related information.

Table A-13 <config-property> Attributes

Name Description

Name	Description
name	Values: String Default: n/a (required) The name of a resource adapter property (from `ra.xml`)
value	Values: String Default: n/a (required) The desired deployed value of the property (can override the assembled value from `ra.xml`).

name

Values: String

Default: n/a (required)

The name of a resource adapter property (from ra.xml)

value

Values: String

Default: n/a (required)

The desired deployed value of the property (can override the assembled value from ra.xml).

<con nector>

Parent element: <oc4j-connectors>

Child elements: <config-property>, <security-permission>, <adminobject-config>, <native-library>, <start-order>

Required? Optional; zero or more

There is a <connector> element for each resource adapter deployed within the EAR file (for resource adapters deployed with an application), or for each standalone resource adapter (in the case of the oc4j-connectors.xml file associated with the OC4J default application). This element indicates the name, path, and JNDI location of the corresponding resource adapter, along with additional configuration through its subelements.

Table A-14 <connector> Attributes

Name Description

Name	Description
name	Values: String Default: n/a (required) The name of the applicable resource adapter, as determined during deployment for a standalone resource adapter (such as through the Application Server Control Console deployment page), or according to the RAR file name, without the `.rar` extension, for a resource adapter deployed within an EAR file. This corresponds to the `connector-name` attribute of applicable `<connector-factory>` elements in the `oc4j-ra.xml` file.
path	Values: String Default: n/a (required) The directory path from which the RAR file was deployed.
location	Values: String Default: Empty string A JNDI location to which the resource adapter instance will be bound. This is relevant only if the resource adapter supports message inflow, and is generally for internal use only.

name

Values: String

Default: n/a (required)

The name of the applicable resource adapter, as determined during deployment for a standalone resource adapter (such as through the Application Server Control Console deployment page), or according to the RAR file name, without the .rar extension, for a resource adapter deployed within an EAR file. This corresponds to the connector-name attribute of applicable <connector-factory> elements in the oc4j-ra.xml file.

path

Values: String

Default: n/a (required)

The directory path from which the RAR file was deployed.

location

Values: String

Default: Empty string

A JNDI location to which the resource adapter instance will be bound. This is relevant only if the resource adapter supports message inflow, and is generally for internal use only.

<native-lib rary>

Parent element: <connector>

Child elements: None

Required? Optional; zero or one

This element points to the location of a native library for use by the resource adapter (and provided with the resource adapter). Also see "Configuring the Use of Resource Adapter Native Libraries".

Table A-15 <native-library> Attributes

Name	Description
path	Values: String Default: No default The relative path for a native library, according to its relative location in the RAR file during deployment.

Note:

You can use either the path attribute or the element value to specify the path. Either of the following examples is valid:

<native-library path="lib/foo.so" />

<native-library>lib/foo.so</native-library>

<oc4j-con nectors>

Parent element: n/a (root)

Child elements: <connector>

Required? Required; one only

This is the top-level element of the oc4j-connectors.xml file, encompassing the enumeration of all resource adapters deployed within a single EAR file, or all standalone resource adapters, as applicable.

Table A-16 <oc4j-connectors> Attributes

Name Description

Name	Description
schema-major-version	Values: String Default: No default The major version number of the `oc4j-connectors.xml` XSD. If you create `oc4j-connectors.xml` manually, set this attribute to 10 for use with the OC4J 10.1.3 implementation.
schema-minor-version	Values: String Default: No default The minor version number of the `oc4j-connectors.xml` XSD. If you create `oc4j-connectors.xml` manually, set this attribute to 0 for use with the OC4J 10.1.3 implementation.

schema-major-version

Values: String

Default: No default

The major version number of the oc4j-connectors.xml XSD. If you create oc4j-connectors.xml manually, set this attribute to 10 for use with the OC4J 10.1.3 implementation.

schema-minor-version

Values: String

Default: No default

The minor version number of the oc4j-connectors.xml XSD. If you create oc4j-connectors.xml manually, set this attribute to 0 for use with the OC4J 10.1.3 implementation.

Note:

These attributes do not appear directly in the XSD for ocj4-connectors.xml. They are according to the attributeGroup specification in the top-level OC4J XSD.

<security-permis sion>

Parent element: <connector>

Child elements: <security-permission-spec>

Required? Optional; zero or more

Each <security-permission> element corresponds to a <security-permission> element in the ra.xml file, and gives the deployer the ability to grant or deny the list of permissions requested by the resource adapter. (See "Security Permissions" for related information.)

Table A-17 <security-permission> Attributes

Name Description

Name	Description
enabled	Values: Boolean Default: false Set this to "`true`" to enable the security specification indicated in the `<security-permission-spec>` subelement.

enabled

Values: Boolean

Default: false

Set this to "true" to enable the security specification indicated in the <security-permission-spec> subelement.

<security-permis sion-spec>

Parent element: <security-permission>

Child elements: None

Required? Required within <security-permission>; one only

The value of this element (which may contain multiple lines of instructions) specifies a security permission based on security policy file syntax. Refer to the following URL for the Sun Microsystems implementation of the security permission specification:

http://java.sun.com/j2se/1.4.2/docs/guide/security/PolicyFiles.html#FileSyntax

See version 1.5 of the J2EE Connector Architecture Specification for additional information and examples.

The <security-permission-spec> element has no attributes.

<start-o rder>

Parent element: <connector>

Child elements: None

Required? Optional; zero or one

The values of any <start-order> elements in an oc4j-connectors.xml file determine the order in which resource adapters are loaded and started by OC4J within the application. In the case of the oc4j-connectors.xml file for the OC4J default application, this is the order in which standalone resource adapters are loaded and started.

<start-order>value</start-order>

There can be one (optional) element, under the associated <connector> element, for each resource adapter. The value must be a positive integer. Resource adapters with lower values are loaded and started first. If no value is specified for a resource adapter, or if the value specified is not a positive integer, OC4J is free to load the resource adapter according to any sequence.

See "Understanding the Resource Adapter Startup Process" for related information.

The <start-order> element has no attributes.

Sam ple oc4j-connectors.xml

This section shows a sample oc4j-connectors.xml file that lists a data source resource adapter and a JMS resource adapter, including configuration of administered objects for topics and queues for the JMS adapter.

<?xml version="1.0" standalone='yes'?>
 
<oc4j-connectors xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation=
 "http://xmlns.oracle.com/oracleas/schema/oc4j-connectors-10_0.xsd"
 schema-major-version="10" schema-minor-version="0"  >
   <connector name="datasources" path="datasources.rar" location="datasources" >
   </connector>
   <connector name="OracleASjms" path="OracleASjms.rar" location="OracleASjms" >
      <config-property name="lookupMethod" value="resourceProvider"/>
      <config-property name="resourceProviderName" value="oc4jjms"/>
      <adminobject-config location="OracleASjms/MyQueue1">
         <adminobject-class>
            oracle.j2ee.ra.jms.generic.AdminObjectQueueImpl
         </adminobject-class>
         <config-property name="jndiName" value="jms/demoQueue"/>
         <config-property name="resourceProviderName" value="oc4jjms"/>
      </adminobject-config>
      <adminobject-config location="OracleASjms/MyTopic1">
         <adminobject-class>
            oracle.j2ee.ra.jms.generic.AdminObjectTopicImpl
         </adminobject-class>
         <config-property name="jndiName" value="jms/demoTopic"/>
         <config-property name="resourceProviderName" value="oc4jjms"/>
      </adminobject-config>
   </connector>
</oc4j-connectors>

A OC4J Resource Adapter Configuration Files

Overview of Resource Adapter Configuration Files

Standard ra.xml Configuration File

Oracle oc4j-ra.xml Configuration File

Oracle oc4j-connectors.xml Configuration File

Hierarchy of oc4j-ra.xml

Elements and Attributes of oc4j-ra.xml

<config-property>

<connection-pool>

<connection-pooling>

<connectionfactory-interface>

<connector-factory>

<default-mapping>

<description>

<description>

<file>

<impl-class>

<initiating-user>

<jaas-application-name>

<jaas-module>

<log>

<oc4j-connector-factories>

<password>

<password-credential>

<principal-mapping-entries>

<principal-mapping-entry>

<principal-mapping-interface>

<property>

<property>

<property>

<res-password>

<res-password>

<res-user>

<res-user>

<security-config>

<use-connection-pool>

<username>

<xa-recovery-config>

Sample oc4j-ra.xml

Hierarchy of oc4j-connectors.xml

Elements and Attributes of oc4j-connectors.xml

<adminobject-class>

<adminobject-config>

<config-property>

<config-property>

<connector>

<native-library>

<oc4j-connectors>

<security-permission>

<security-permission-spec>

<start-order>

Sample oc4j-connectors.xml

Stan dard ra.xml Configuration File

Ora cle oc4j-ra.xml Configuration File

Ora cle oc4j-connectors.xml Configuration File

Hiera rchy of oc4j-ra.xml

Elem ents and Attributes of oc4j-ra.xml

<co nfig-property>

<con nection-pool>

<con nection-pooling>

<con nectionfactory-interface>

<con nector-factory>

<default-map ping>

<fil e>

<impl-clas s>

<initi ating-user>

<jaas-ap plication-name>

<jaas-mo dule>

<lo g>

<oc4j-con nector-factories>

<pas sword>

<pas sword-credential>

<principal-map ping-entries>

<principal-map ping-entry>

<principal-map ping-interface>

<pro perty>

<pro perty>

<pro perty>

<re s-password>

<re s-password>

<re s-user>

<re s-user>

<se curity-config>

<user name>

<xa-rec overy-config>

Sam ple oc4j-ra.xml

Hier archy of oc4j-connectors.xml

Elem ents and Attributes of oc4j-connectors.xml

<admin object-class>

<admin object-config>

<co nfig-property>

<co nfig-property>

<con nector>

<native-lib rary>

<oc4j-con nectors>

<security-permis sion>

<security-permis sion-spec>

<start-o rder>

Sam ple oc4j-connectors.xml