Configuring WebLogic J2EE-CA

Configuring and deploying a resource adapter in WebLogic is a straightforward process. The end result is a special Java archive file called a resource adapter archive (*.rar), or RAR file for short. Each RAR file has all the classes needed for the resource adapter plus the configuration XML files ra.xml and the WebLogic-specific weblogic-ra.xml.

Resource Adapter Developer Tools

BEA makes several tools available for configuration and deployment of the J2EE-CA. Minimally, you need at least a text editor to modify or create the ra.xml and weblogic-ra.xml files. Although when you actually deploy the RAR file within WebLogic 8.1, it creates a weblogic-ra.xml file and puts that file in the RAR automatically. If you deploy the resource adapter expanded—meaning not in a RAR file but just a simple directory structure—you can edit the weblogic-ra.xml file from the console. After editing, simply click Apply at the bottom right of the screen, and the changes are updated and the resource adapter is redeployed.

When creating or modifying the ra.xml file, an XML editing tool is beneficial. WebLogic provides a XML editor: WebLogic Builder, which is included with WebLogic 8.1.

Configuring Resource Adapters

Resource adapters are meant to be configured and optimized for your intended application. Earlier in the chapter, the ra.xml and weblogic-ra.xml files were discussed. These two files hold the entire configuration for the resource adapter. When editing the configuration files, a few conventions must be followed. First, each tag has a corresponding end tag. Second, case should be followed not only in the name of the tag itself, but also in its value if needed. Finally, to use the default value of an optional element, omit the tags altogether or specify an empty value within the tags.

The file mandated to hold all the J2EE Adapter Architecture–specified configuration is called ra.xml. The DTD can be found at http://java.sun.com/dtd/connector_1_0.dtd.

Required Tags

The main element in a ra.xml file is the <connector></connector> element. All other elements are contained within these tags. For the connector to validate against the DTD, it must contain these five elements:

• <vendor-name>— This contains the name of the vendor supplying the resource adapter.

• <spec-version>— This contains the version of the J2EE Connector Architecture specification being used.

• <eis-type>— This contains the description information used to identify the EIS system that the resource adapter is connecting to.

• <version>— This contains the version of the resource adapter provided by the vendor.

• <resourceadapter>— This contains the all the information on the specific resource adapter, including fully qualified names of the classes or interfaces required as part of the J2EE Connector Architecture specification.

Optional Tags

Optionally, four other tags can be specified within the connector tags: display-name, description, icon, and license. The display-name and description tags are text tags that are for display in resource adapter tools. The icon tag specifies icons that can be displayed with the resource adapter. The license tag tells the user whether a license is required to be distributed with the resource adapter.

The resourceadapter Tag

The resourceadapter tag and associated subtags are most important in the configuration of the resource adapter. This tag specifies what classes the resource adapter uses for each of the required interfaces in the J2EE Connector Architecture specification, plus other required parameters. The following list describes the required tags:

• <managedconnectionfactory-class>— Contains the class that implements javax.resource.spi.ManagedConnectionFactory interface.

• <connectionfactory-interface>— Contains the ConnectionFactory interface that is supported by the resource adapter.

• <connectionfactory-impl-class>— Contains the class that implements the <connectionfactory-interface>.

• <connection-interface>— Contains the connection interface used by the adapter.

• <connection-impl-class>— Contains the class that implements the <connection-interface>.

• <transaction-support>— Contains the level of transaction support. Only three values are allowed: NoTransaction, LocalTransaction, and XATransaction.

• <reauthentication-support>— Contains either true or false, depending on whether the resource adapter allows re-authentication of a managed connection.

Optional tags that are included in the specification are as follows:

• <config-property>— Configuration properties that are loaded for the ManagedConnectionFactory class

• <authentication-mechanism>— Can optionally contain an authentication mechanism supported by the resource adapter

• <security-permission>— Specifies the security permission specified by the resource adapter

To learn more about the intricacies of the ra.xml file, information is available from Sun as part of the J2EE-CA specification located at http://java.sun.com/j2ee/connector/download.html.

WebLogic-Specific Configuration

The J2EE Connector Architecture forbids any extra configuration within the ra.xml file. To allow application server vendors the opportunity to fine-tune resource adapters, connector vendors must use an external configuration medium that can contain application server–specific information. WebLogic puts this information in the weblogic-ra.xml file. If the weblogic-ra.xml file does not exist, it is automatically generated when the resource adapter is deployed. The DTD can be found at http://www.bea.com/servers/wls810/dtd/weblogic810-ra.dtd.

The weblogic-ra.xml file has a root node labeled <weblogic-connection-factory-dd> and several configuration parameters, but only two that are required. The two required parameters are as follows:

• <connection-factory-name>— Defines the logical name of the specific resource adapter.

• <jndi-name>— Defines the JNDI name that points to the ConnectionFactory object used by the connector. WebLogic Server automatically creates a factory and binds it to this JNDI name at deployment time.

The optional parameters should be configured to optimize the needs of the intended application. The following is a list and a brief description of each parameter:

• <description>— A text description of or information about the deployed resource adapter.

• <ra-link-ref>— A mapping value that associates multiple connection factories with one deployed resource adapter.

• <native-libdir>— If native libraries are present for the deployment of a resource adapter, this tag specifies the directory that they should be placed in. It is required if there are native libraries.

• <pool-params>— This tag has several subtags that configure the connection pool handled by WebLogic. If this tag and the associated subtags are not present, WebLogic enters default values for them. If you deploy the resource adapter exploded in directory format, most of the properties are editable from the WebLogic console under the Deployments/Connector Modules on the left side tree, and Configuration/Descriptor on the right side. If the resource adapter was deployed as a .rar file, only links to view the ra.xml and weblogic-ra.xml files are present in the console. Please refer to the console help and the DTD for the weblogic-ra.xml mentioned earlier for a description of each parameter.

• <logging-enabled>— This value specifies whether logging is turned on or off for the ManagedConnectionFactory or ManagedConnection class. The value can be true or false. If true, the output is sent to the value of the <log-filename> value.

• <log-filename>— The full path to the file where the ManagedConnectionFactory or ManagedConnection class will send its logging output if the <logging-enabled> value is true.

• <map-config-property>— This element corresponds to the <config-entry> tag in the ra.xml file. Any property placed here will be available inside the ManagedConnectionFactory and override any property of the same name set in the ra.xml file.

The following excerpt from a weblogic-ra.xml file shows some of the optional configuration properties in use. These properties enable logging, specify the name logging file, and map a property from the ra.xml file to a new value based on the <config-property-value> in the weblogic-ra.xml file.

<weblogic-connection-factory-dd>
<connection-factory-name>eis/jcaconn</connection-factory-name>
<jndi-name>eis/jcaconn</jndi-name>
<logging-enabled>true</logging-enabled>
<log-filename>jcaoutput.log</log-filename>
<map-config-property>
<config-property-name>ConnectionURL</config-property-name>
<config-property-value>jdbc:pointbase://localhost/demo</config-property-value>
</map-config-property>
</weblogic-connection-factory-dd>