Configuration

 

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

• Resource Adapter Developer Tools

• Resource Adapter Developer Tools

• Configuring the ra.xml File

• Configuring the weblogic-ra.xml File

• Configuring the Security Principal Map

• Using the 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 BEA dev2dev.

 

---

Configuring Resource Adapters

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

Overview of the Resource Adapter

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, Proposed Final Draft 2. 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 (.rar)

The following are the main steps for creating a resource adapter (.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, Proposed Final Draft 2 (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) file.

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 Automatic Generation of the weblogic-ra.xml File.

5. Create a resource adapter archive file (.rar file).

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

   2. Place the .rar file 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 (.rar).

6. 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 Applications and Components" in "Packaging and 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.

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 resource adapter .rar does not contain a weblogic-ra.xml file, WebLogic Server automatically generates this file for you. For more information, see Automatic Generation of the weblogic-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 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
   

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 Resource Adapter Deployment.

Automatic Generation of the weblogic-ra.xml File

If your resource adapter .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 2-1 weblogic-ra.xml Default Values

<weblogic-connection-factory-dd> 

<connection-factory-name>__TMP_CFNAME_.\config\mydomain\applicati
ons\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, .jar files, 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.

Packaging Guidelines

A resource adapter is a WebLogic Server component contained in an .rar archive file within the applications/ directory. The deployment process begins with the .rar file or a deployment directory, both of which contain the compiled resource adapter interfaces and implementation classes created by the resource adapter provider. Regardless of whether the compiled classes are stored in an .rar file or a deployment directory, they must reside in subdirectories that match their Java package structures.

Resource adapters use a common directory format. This same format is used when a resource adapter is packaged in an exploded directory format as an .rar file. A resource adapter is structured as in the following example:

Listing 2-2 Resource Adapter Structure

/META-INF/ra.xml

/META-INF/weblogic-ra.xml

/images/ra.jpg

/readme.html

/eis.jar

/utilities.jar

/windows.dll

unix.so

Note the following about the files in a resource adapter:

• Deployment descriptors (ra.xml and weblogic-ra.xml) must be in a subdirectory called META-INF.

• The resource adapter can contain multiple jar files that contain the Java classes and interfaces used by the resource adapter. (For example, eis.jar and utilities.jar)

• The resource adapter can contain native libraries required by the resource adapter for interacting with the EIS. (For example, windows.dll and unix.so)

The resource adapter can include documentation and related files not directly used by the resource adapter. (For example, readme.html and /images/ra.jpg)

Packaging Resource Adapters (.rar)

You can stage one or more resource adapters in a directory and package them in a jar file. Before you package your resource adapters, be sure you read and understand "Resolving Class References Between Components" in "Packaging and Deploying WebLogic Server Applications," which describes how WebLogic Server loads classes.

To stage and package a resource adapter:

1. Create a temporary staging directory.

2. Compile or copy the resource adapter Java classes into the staging directory.

3. Create a .jar file to store the resource adapter Java classes. Add this .jar file to the top level of the staging directory.

4. Create a META-INF subdirectory in the staging directory.

5. Create an ra.xml deployment descriptor in the META-INF subdirectory and add entries for the resource adapter.

   Note: Refer to the following Sun Microsystems documentation for information on the ra.xml document type definition at: http://java.sun.com/dtd/connector_1_0.dtd

6. Create a weblogic-ra.xml deployment descriptor in the META-INF subdirectory and add entries for the resource adapter.

   Note: Refer to weblogic-ra.xml Deployment Descriptor Elements, for information on the weblogic-ra.xml document type definition.

7. When all of the resource adapter classes and deployment descriptors are set up in the staging directory, you can create the resource adapter JAR file with a jar command such as:

   jar cvf jar-file.rar -C staging-dir.
   

   This command creates a jar file that you can deploy on a WebLogic Server or package in an application JAR file.

   The -C staging-dir option instructs the jar command to change to the staging-dir directory so that the directory paths recorded in the JAR file are relative to the directory where you staged the resource adapters.

For instructions on creating a resource adapter and modifying an existing resource adapter for deployment to WebLogic Server, see Creating and Modifying Resource Adapters: Main Steps.

 

---

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, Proposed Final Draft 2: http://java.sun.com/j2ee/download.html#connectorspec

 

---

Configuring the weblogic-ra.xml File

The weblogic-ra.xml file contains information required for deploying a resource adapter in WebLogic Server. In this file, you specify certain attributes. 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.

These sections describe how to configure the weblogic-ra.xml file to define WebLogic Server-specific content for deployment to WebLogic Server.

Configuring the weblogic-ra.xml File

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.

The weblogic-ra.xml file defines the connection factory, connection pool parameters, security principal mapping parameters, and more. See weblogic-ra.xml Deployment Descriptor Elements, for a complete list of properties available in the file.

Configurable weblogic-ra.xml Entities

The weblogic-ra.xml file contains information required for deploying a resource adapter in WebLogic Server. In this 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.

  • The frequency of time to detect and reclaim connections that have exceeded their usage time.

  • The amount of usage time allowed for a connection.

• Values for configuration properties defined in a <config-entry> element of the J2EE resource adapter deployment descriptor, ra.xml.

• Mapping of security principals for Resource Adapter/EIS sign-on processing. This mapping identifies resource principals to be used when requesting EIS connections for applications that use container-managed security and for EIS connections requested during initial deployment.

• Flag to indicate whether logging is required for the ManagedConnectionFactory or ManagedConnection.

• File to store logging information for the ManagedConnectionFactory or ManagedConnection.

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.

 

---

Configuring the Security Principal Map

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 2-3 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 Password Converter Tool

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

Because BEA understands the importance of protecting security passwords, it provides a 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.

If you require a resource adapter to have clear-text passwords that do not exist in the WebLogic Server environment, then you must post-process the resultant weblogic-ra.xml file by using the converter tool each time a new clear-text password is added.

You must run the provided password converter tool to convert all resource-password values that are in clear text to encrypted password values. This 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 file for deployment to WebLogic Server.

How to Execute

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

Listing 2-4 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, Proposed Final Draft 2 (http://java.sun.com/j2ee/download.html#connectorspec).