Configuration

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

• Resource Adapter Developer Tools

• Configuring Resource Adapters

• Configuring the ra.xml File

• Configuring the weblogic-ra.xml File

• Configuring the Deprecated Security Principal Map Mechanism

• Using the Deprecated Password Converter Tool

• Configuring the Transaction Level Type

 

---

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 Packaging Resource Adapters.

Resource Adapter Deployment Descriptor Editor

The WebLogic Server Administration Console has an integrated deployment descriptor editor. You must create at least a skeleton ra.xml deployment descriptor before using this integrated editor. For more information, see weblogic-ra.xml Deployment Descriptor Elements.

XML Editor

BEA now provides a simple, user-friendly tool from Ensemble for creating and editing XML files. It can validate XML code according to a specified DTD or XML Schema. The XML editor can be used on Windows or Solaris machines and is downloadable from the BEA Developer Center.

 

---

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):

1. 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>

2. Compile the Java code for the interfaces and implementation into class files.

   For detailed information about compiling, refer to "Preparing to Compile" in "Developing WebLogic Server Applications."

3. Package the Java classes into a Java archive (JAR). For more information on packaging, see Packaging and Deploying Resource Adapters.

4. Create the resource adapter-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 more information, refer to Configuring the ra.xml File and Configuring the weblogic-ra.xml File.

   Note: If your resource adapter RAR does not contain a weblogic-ra.xml file, WebLogic Server automatically generates this file for you. For more information, see Configuring the ra.xml File.

5. Create a resource adapter archive (RAR).

   1. The first step is to create an empty staging directory.

   2. Place the RAR containing the resource adapter Java classes in the staging directory.

   3. Then, place the deployment descriptors in a subdirectory called META-INF.

   4. Next, create the resource adapter archive by executing a jar command like the following in the staging directory:

      jar cvf myRAR.rar *

      For detailed information about creating the resource adapter archive file, refer to Packaging Resource Adapters Archives (RARs).

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

   For more information on deploying resource adapters, see Packaging and Deploying Resource Adapters.

Modifying an Existing Resource Adapter Archive (RAR)

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

1. Create a temporary directory to stage the resource adapter:

	mkdir c:/stagedir

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

	cp blackbox-notx.rar c:/stagedir

3. 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.jar 

		META-INF

	c:/stagedir> ls META-INF

		MANIFEST.MF

		ra.xml

4. 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.

   Note: If your RAR does not contain a weblogic-ra.xml file, WebLogic Server automatically generates this file for you. For more information, see Configuring the ra.xml File.

   Refer to Configuring the weblogic-ra.xml File and weblogic-ra.xml Deployment Descriptor Elements, for more information on the weblogic-ra.xml file.

5. 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 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

6. Create the resource adapter archive:

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

7. Deploy the resource adapter in WebLogic Server. For more information on deploying a resource adapter in WebLogic Server, see Packaging and Deploying Resource Adapters.

 

---

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 Using the Console Deployment Descriptor Editor to Edit Files in 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 5-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-period-minutes>200</shrink-period-minutes> 

	</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) using the Console Deployment Descriptor Editor. 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 Using the Console Deployment Descriptor Editor to Edit Files in weblogic-ra.xml Deployment Descriptor Elements.

 

---

Configuring the Deprecated Security Principal Map Mechanism

The default JAAS Login module has replaced the Security Principal Mapping mechanism provided with the weblogic-ra.xml deployment descriptor within the resource adapter archive. As a result, the weblogic-ra.xml <security-principal-map> element has been deprecated. However, instructions for using the Security Principal Mapping mechanism are still in place.

To use container-managed sign-on, WebLogic Server must identify a resource principal and then request the connection to the EIS on behalf of the resource principal. In order to make this identification, WebLogic Server looks for a security principal map that you have specified with the <security-principal-map> element in the weblogic-ra.xml deployment descriptor file.

This map builds associations between WebLogic Server initiating principals (WebLogic Server users with identities defined in the WebLogic Security Realm) and resource principals (users known to the resource adapter / EIS system).

In addition, the <security-principal-map> enables you to define a default initiating principal that you can map to an appropriate resource principal when the initiating principal identified at run time is not found in the mapping. You establish the default initiating principal in the <security-principal-map> element with an <initiating-principal> element that has a value of *, for example:

<initiating-principal>*</initiating-principal>

You must also include a corresponding <resource-principal> entry in the <security-principal-map> element that specifies a username and password.

The following example shows an association between a WebLogic Server initiating principal and a resource principal.

Listing 5-2 Example <initiating-principal> and <resource-principal> Entry

<security-principal-map>

   <map-entry>

	<initiating-principal>*</initiating-principal>

	   <resource-principal>

	       <resource-username>default</resource-username>

		<resource-password>try</resource-password>

	   </resource-principal>

   </map-entry>

</security-principal-map>

This default initiating principal mapping is also used at deployment time if the connection pool parameters indicate that WebLogic Server should initialize connections. The absence of a default initiating principal entry or the absence of a <security-principal-map> element may prevent WebLogic Server from creating connections using container-managed security.

 

---

Using the Deprecated Password Converter Tool

The Password Converter Tool is a deprecated tool due to the fact that the default JAAS Login module has replaced the Security Principal Mapping mechanism provided with the weblogic-ra.xml deployment descriptor within the resource adapter archive. However, instructions for using the Password Converter Tool are still in place for this release.

Because previous configuration and packaging requirements for resource adapters in WebLogic Server required manual editing of the weblogic-ra.xml file, any new passwords specified in the security-principal-map entries were done in clear-text.

BEA provides a Password Converter Tool that allows for the encryption of all passwords present in the weblogic-ra.xml file. The converter tool is shipped in the standard weblogic.jar file. The Password Converter Tool parses an existing weblogic-ra.xml file containing clear-text passwords and creates a new weblogic-ra.xml file that contains encrypted passwords. This is the new file that you package in the RAR for deployment to WebLogic Server.

How to Execute

To run the converter tool, execute the following syntax in a DOS command shell:

Listing 5-3 Converter Tool Syntax

java weblogic.Connector.ConnectorXMLEncrypt <input-weblogic-ra.xml> <output-weblogic-ra.xml> <domain-config-directory-location>

Security Hint

A security hint that is specific to the domain used in the encryption / decryption process requires inclusion of the <domain config directory location>; the converter tool must be directed to use the specific hint for this domain. The resultant encrypted passwords are specific to this domain. Therefore, the resultant RAR with encrypted password values are deployable only on the specified domain.

 

---

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 Manually Editing XML Deployment Files and Using the Console Deployment Descriptor Editor to Edit Files in 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).