Programming WebLogic Server J2EE Connectors

Configuration

The following sections outline configuration requirements for the WebLogic J2EE Connector Architecture implementation:

Resource Adapter Developer Tools

BEA provides several tools you can use to help you create and configure resource adapters. These tools are described in this section.

ANT Tasks to Create Skeleton Deployment Descriptors

You can use the WebLogic ANT utilities to create skeleton deployment descriptors. These utilities are Java classes shipped with your WebLogic Server distribution. The ANT task looks at a directory containing a resource adapter creates deployment descriptors based on the files it finds in the resource adapter. Because the ANT utility does not have information about all of the desired configurations and mappings for your resource adapter, the skeleton deployment descriptors the utility creates are incomplete. After the utility creates the skeleton deployment descriptors, you can use a text editor, an XML editor, or the Administration Console to edit the deployment descriptors and complete the configuration of your resource adapter.

For more information on using ANT utilities to create deployment descriptors, see Creating WebLogic Server Applications in Developing WebLogic Server Applications.

WebLogic Builder

WebLogic Builder is a visual environment for editing an application's deployment descriptor XML files. You can view descriptor files while you visually edit them in WebLogic Builder, and you won't need to make textual edits to the XML files. For more information, see the WebLogic Builder Online Help.

XML Editors

You can use an XML Editor with DTD validation, such as BEA XML Editor on dev2dev or XMLSpy. (An evaluation copy of XMLSpy is bundled with this version of WebLogic Server.) See BEA dev2dev Online http://dev2dev.bea.com/index.jsp.

Configuring Resource Adapters

This section introduces and discusses how to configure the resource adapter for deployment to WebLogic Server.

Resource Adapter Overview

The J2EE Connector Architecture enables both Enterprise Information System (EIS) vendors and third-party application developers to develop resource adapters that can be deployed in any application server supporting the Sun Microsystems J2EE Platform Specification, Version 1.3.

The resource adapter is the central piece of the WebLogic J2EE Connector Architecture; it serves as the J2EE connector between the client component and the EIS. When a resource adapter is deployed in the WebLogic Server environment, it enables the development of robust J2EE Platform applications that can access remote EIS systems. Resource adapters contain the Java components, and if necessary, the native components required to interact with the EIS.

For more information on creating resource adapters, see the Sun Microsystems J2EE Connector Architecture page and the J2EE Connector Specification, Version 1.0 Final Release. These can be found on the Sun Microsystems Web site at the following respective URLs:

http://java.sun.com/j2ee/connector/

http://java.sun.com/j2ee/download.html#connectorspec

Creating and Modifying Resource Adapters: Main Steps

Creating a resource adapter requires creating the classes for the particular resource adapter (ConnectionFactory, Connection, and so on) and the connector-specific deployment descriptors, and then packaging everything up into an jar file to be deployed to WebLogic Server.

Creating a New Resource Adapter Archive (RAR)

The following are the main steps for creating a resource adapter archive (RAR):

Write the Java code for the various classes required by resource adapter (ConnectionFactory, Connection, and so on) in accordance with the J2EE Connector Specification, Version 1.0, Final Release (http://java.sun.com/j2ee/download.html#connectorspec).

When implementing a resource adapter, you must specify classes in the ra.xml file. For example:

<managedconnectionfactory-class>com.sun.connector.blackbox.LocalTxManagedConnectionFactory</managedconnectionfactory-class>
<connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface>
<connectionfactory-impl-class>com.sun.connector.blackbox.JdbcDataSource</connectionfactory-impl-class>
<connection-interface>java.sql.Connection</connection-interface>
<connection-impl-class>com.sun.connector.blackbox.JdbcConnection</connection-impl-class>

Compile the Java code using a standard compiler for the interfaces and implementation into class files.

For instructions on compiling, refer to Compiling Java Code in Developing WebLogic Server J2EE Applications.

Create the resource connector-specific deployment descriptors:

ra.xml describes the resource adapter-related attributes type and its deployment properties using a standard DTD from Sun Microsystems.
weblogic-ra.xml adds additional WebLogic Server-specific deployment information.

For detailed information about creating connector-specific deployment descriptors, refer to weblogic-ra.xml Deployment Descriptor Elements.

Package the Java classes into a Java archive (JAR) file.

The first step in creating a JAR file is to create a connector staging directory anywhere on your hard drive. Place the JAR file in the staging directory and the deployment descriptors in a subdirectory called META-INF.
Then you create the resource adapter archive by executing a jar command similar to the following in the staging directory: jar cvf myRAR.rar *

Auto-deploy the RAR resource adapter archive file on WebLogic Server for testing purposes.

For detailed information about auto-deploying components and applications, refer to Tools for Deploying in Deploying WebLogic Server Applications.
While you are testing the resource adapter, you might need to edit the resource adapter deployment descriptors. You can do this manually or use WebLogic Builder.
For detailed information, refer to WebLogic Builder Online Help. See weblogic-ra.xml Deployment Descriptor Elements for detailed information on the elements in these deployment descriptors.

Deploy the RAR resource adapter archive file on WebLogic Server or include it in an enterprise archive (EAR) file to be deployed as part of an enterprise application.

Refer to Deploying WebLogic Server Applications for detailed information about deploying components and applications.

Modifying an Existing Resource Adapter (RAR)

The following is an example of how to take an existing resource adapter (RAR) and modify it for deployment to WebLogic Server. This involves adding the weblogic-ra.xml deployment descriptor and repacking.

Create a temporary directory anywhere on your hard drive to stage the resource adapter:

	mkdir c:/stagedir

Copy the resource adapter that you will deploy into the temporary directory:

	cp blackbox-notx.rar c:/stagedir

Extract the contents of the resource adapter archive:

	cd c:/stagedir

	jar xf blackbox-notx.rar

The staging directory should now contain the following:

A jar file containing Java classes that implement the resource adapter
A META-INF directory containing the files: Manifest.mf and ra.xml

Execute these commands to see these files:

	c:/stagedir> ls

		blackbox-notx.rar

		META-INF

	c:/stagedir> ls META-INF

		Manifest.mf

		ra.xml

Create the weblogic-ra.xml file. This file is the WebLogic-specific deployment descriptor for resource adapters. In this file, you specify parameters for connection factories, connection pools, and security mappings.

Refer to weblogic-ra.xml Deployment Descriptor Elements for more information on the weblogic-ra.xml DTD.

Copy the weblogic-ra.xml file into the temporary directory's META-INF subdirectory. The META-INF directory is located in the temporary directory where you extracted the RAR file or in the directory containing a resource adapter in exploded directory format. Use the following command:

	cp weblogic-ra.xml c:/stagedir/META-INF

	c:/stagedir> ls META-INF

		Manifest.mf

		ra.xml

		weblogic-ra.xml

Create the resource adapter archive:

	jar cvf blackbox-notx.rar -C c:/stagedir

Deploy the resource adapter to WebLogic Server. For detailed information about deploying components and applications, refer to Tools for Deploying in Deploying WebLogic Server Applications.

Configuring the ra.xml File

If you do not have an ra.xml file, you must manually create or edit an existing one to set the necessary deployment properties for the resource adapter. You can use a text editor to edit the properties. For information on creating an ra.xml file, refer to the J2EE Connector Specification, Version 1.0 Final Release: http://java.sun.com/j2ee/download.html#connectorspec

Configuring the weblogic-ra.xml File

In addition to supporting features of the standard resource adapter configuration ra.xml file, BEA WebLogic Server defines an additional deployment descriptor file, the weblogic-ra.xml file. This file contains parameters that are specific to configuring and deploying resource adapters in WebLogic Server. This functionality is consistent with the equivalent .xml extensions for EJBs and Web applications in WebLogic Server, which also add WebLogic-specific deployment descriptors to the deployable archive. As is, the basic RAR or deployment directory cannot be deployed to WebLogic Server. You must first create and configure WebLogic Server-specific deployment properties in the weblogic-ra.xml file and add that file to the deployment.

In the weblogic-ra.xml file, you specify the following attributes:

Name of the connection factory.
Descriptive text about the connection factory.
JNDI name bound to a connection factory.
Reference to a separately deployed connection factory that contains resource adapter components that can be shared with the current resource adapter.
Directory where all shared libraries should be copied.
Connection pool parameters that set the following behavior:

Initial number of managed connections WebLogic Server attempts to allocate at deployment time.
Maximum number of managed connections WebLogic Server allows to be allocated at any one time.
Number of managed connections WebLogic Server attempts to allocate when filling a request for a new connection.
Whether WebLogic Server attempts to reclaim unused managed connections to save system resources.
The time WebLogic Server waits between attempts to reclaim unused managed connections.

Values for configuration properties defined in a <config-entry> element of the J2EE resource adapter deployment descriptor, ra.xml.
Flag to indicate whether logging is required for the ManagedConnectionFactory or ManagedConnection.
File to store logging information for the ManagedConnectionFactory or ManagedConnection.
The amount of time a connection can remain idle.
Whether to store call stacks of where each connection is allocated.

Note: Refer to the weblogic-ra.xml DTD in weblogic-ra.xml Deployment Descriptor Elements, for more information on setting the parameters in weblogic-ra.xml. You can also look at the weblogic-ra.xml file in the included Simple Black Box resource adapter example provided with the product download.

Note: For information on configuring connection properties in a resource adapter, refer to Connection Management.

Automatic Generation of the weblogic-ra.xml File

In WebLogic Server, a resource adapter archive (RAR) must include a weblogic-ra.xml deployment descriptor file in addition to the ra.xml deployment descriptor file specified in the J2EE Connector 1.0 specification. However, if a resource adapter is deployed in WebLogic Server without a weblogic-ra.xml file, a template weblogic-ra.xml file populated with default element values is automatically added to the resource adapter archive. This automatic resource file generation simplifies the process of establishing the parameters necessary to deploy the resource adapter in WebLogic Server.

If your RAR does not contain a weblogic-ra.xml file, WebLogic Server automatically generates this file for you. This feature enables you to deploy third-party resource adapters to WebLogic Server without worrying about modifying them for WebLogic Server. You need only modify two default attribute values that WebLogic Server generates in the weblogic-ra.xml file: <connection-factory-name> and <jndi-name>.

WebLogic Server prepends <connection-factory-name> with the default value of __TMP_CFNAME_.
It prepends <jndi-name> with the default value of __TMP_JNDINAME_.

For instructions on how to change these default values, see weblogic-ra.xml Deployment Descriptor Elements.

The following is what the generated weblogic-ra.xml file looks like before you change the default values:

Listing 6-1 weblogic-ra.xml Default Values

<weblogic-connection-factory-dd>

<connection-factory-name>__TMP_CFNAME_.\config\mydomain\applications\whitebox-notx.rar</connection-factory-name>

<jndi-name>__TMP_JNDINAME_.\config\mydomain\applications\whitebox-notx.rar</jndi-name>

	<pool-params>

		<initial-capacity>0</initial-capacity>

		<max-capacity>1</max-capacity>

		<capacity-increment>1</capacity-increment>

		<shrinking-enabled>false</shrinking-enabled>

	    <shrink-frequency-seconds>900</shrink-frequency-seconds>

	</pool-params>

	<security-principal-map>

	</security-principal-map>

</weblogic-connection-factory-dd>

Configuring the ra-link-ref Element

The optional <ra-link-ref> element allows you to associate multiple deployed resource adapters with a single deployed resource adapter. In other words, it allows you to link (reuse) resources already configured in a base resource adapter to another resource adapter, modifying only a subset of attributes. The <ra-link-ref> element enables you to avoid—where possible—duplicating resources (such as classes, JARs, image files, and so on). Any values defined in the base resource adapter deployment are inherited by the linked resource adapter, unless otherwise specified in the <ra-link-ref> element.

If you use the optional <ra-link-ref> element, you must provide either all or none of the values in the <pool-params> element. The <pool-params> element values are not partially inherited by the linked resource adapter from the base resource adapter.

Do one of the following:

Assign the <max-capacity> element the value of 0 (zero). This allows the linked resource adapter to inherit its <pool-params> element values from the base resource adapter.
Assign the <max-capacity> element any value other than 0 (zero). The linked resource adapter will inherit no values from the base resource adapter. If you choose this option, you must specify all of the <pool-params> element values for the linked resource adapter.

For instructions on editing the weblogic-ra.xml file, see weblogic-ra.xml Deployment Descriptor Elements.

Configuring the Transaction Level Type

You must specify the transaction level type supported by the resource adapter in the ra.xml deployment descriptor file. To specify the transaction support level:

For No Transaction, add the following entry to the ra.xml deployment descriptor file: <transaction-support>NoTransaction</transaction-support>
For XA Transaction, add the following entry to the ra.xml deployment descriptor file: <transaction-support>XATransaction</transaction-support>
For Local Transaction, add the following entry to the ra.xml deployment descriptor file: <transaction-support>LocalTransaction</transaction-support>

For instructions on editing an .xml file, see weblogic-ra.xml Deployment Descriptor Elements.

For more information on specifying the transaction level in the RAR configuration, see "Resource Adapter XML DTD" under "Packaging and Deployment" in the J2EE Connector Specification, Version 1.0 Final Release (http://java.sun.com/j2ee/download.html#connectorspec).