Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   WebLogic Server Documentation

WebLogic J2EE Connector Architecture Beta Implementation

This document contains information about the WebLogic® J2EE Connector Architecture Beta Implementation. The following topics are discussed:

• Overview

• Support for This Beta Release

• Installing the WebLogic J2EE Connector Architecture Beta Implementation

• Creating the connector Domain

• Deploying a Resource Adapter

• Resource Adapter Packaging

• Creating the weblogic-ra.xml File

• Running the Black Box Example

• Security Considerations

• Known Limitations

• Known Problems

• Future Plans

• Additional Resources

Overview

The WebLogic J2EE Connector Architecture Beta Implementation is an implementation of the new J2EE 1.3 Connector Architecture Version 1.0 Specification from Sun Microsystems. This specification provides a standard architecture for integrating the J2EE platform with one or more heterogeneous Enterprise Information Systems (EIS). An EIS is an enterprise information resource such as a legacy database system or a mainframe transaction processing system such as SAP or PeopleSoft.

This early release of the WebLogic J2EE Connector Architecture Beta Implementation is primarily intended for vendors who are creating resource adapters and who need an environment in which to test the resource adapters. This implementation is also useful for application developers who want to learn about deploying resource adapters and accessing their resources. This release provides support based on the Proposed Final Draft of Sun's J2EE Connector Architecture v 1.0, which is a non-final/beta version of the specification and subject to change when the specification finalizes.

Resource Adapter

The central component for this integration is the resource adapter. The J2EE Connector Architecture enables both EIS vendors and third-party application developers to develop resource adapters that can be deployed in any application server that supports the J2EE 1.3 specification. Resource adapters contain the Java, and if necessary, the native components required to interact with the EIS.

When a resource adapter is deployed in the WebLogic Server environment it enables the development of robust J2EE applications that now have access to a remote EIS system. Developers of WebLogic Server applications can use HTTP servlets, JavaServer Pages, EJBs, and other APIs to develop integrated applications that use the data and business logic of the EIS.

For information on creating resource adapters, see the J2EE Connector Architecture page, from Sun Microsystems and the proposed final draft of the J2EE Connector Architecture Specification, v. 1.0. Please be aware that the specification has not yet been finalized. Any changes to the specification will be incorporated into the final release of the WebLogic J2EE Connector Architecture Implementation.

Code Example

A simple code example is also provided. The code example uses a Black Box resource adapter that mimics JDBC calls. An EJB is used to model the data in the Black Box and a Java client is used to query the Black Box resource adapter and display the output. The example uses the all-Java Cloudscape DBMS, which is provided in an evaluation version with WebLogic Server. For more information, see Running the Black Box Example

Support for This Beta Release

All customer support for this release of the WebLogic J2EE Connector Architecture Beta Implementation is provided through the following newsgroup:

weblogic.developer.interest.connector, available from http://newsgroups.bea.com.

BEA Customer Support does not provide support for the beta release.

Installing the WebLogic J2EE Connector Architecture Beta Implementation

The following installation instructions describe how to install the WebLogic J2EE Connector Architecture Beta Implementation and explain how to set up an environment in which to run the included resource adapter example. If you do not intend to run the example, but wish to deploy a resource adapter in WebLogic Server, use these instructions as a guide for setting up a WebLogic Server domain that is configured to use a resource adapter.

1. Download and install WebLogic Server 6.0. The download is available at http://commerce.bea.com/downloads/weblogic_server.jsp#wls.

2. Download and install the EJB 2.0 upgrade for WebLogic Server 6.0. The upgrade is available at: http://commerce.bea.com/downloads/weblogic_server.jsp#wls. The EJB 2.0 upgrade is required if you intend to run the included Black Box code example, or if you intend to develop EJB 2.0 applications using the WebLogic J2EE Connector Architecture Beta Implementation.

3. Unpack the downloaded weblogic60J2eeConnector.zip file into a temporary directory.

4. Copy the following jar files from the jars subdirectory in your temporary directory into the /lib directory of your WebLogic Server installation:

   • connector.jar

   • weblogic60J2eeConnector.jar

5. If you intend to run the included Black Box resource adapter and client code example, continue with the next section, Creating the connector Domain

6. Add the jar files to the CLASSPATH that you use when starting WebLogic Server. Usually, adding jar files to the CLASSPATH involves modifying the script that you use to start WebLogic Server. Add the following jar files to the beginning of the CLASSPATH portion of the command line that you use to start WebLogic server:

   • connector.jar

   • weblogic60J2eeConnector.jar

     For example:

     set CLASSPATH=.;.\lib\connector.jar;
     .\lib\weblogic60J2eeConnector.jar;.
     \lib\weblogic_sp.jar;.\lib\weblogic.jar;
     .\samples\eval\cloudscape\lib\cloudscape.jar

7. If you intend to deploy the Black Box resource adapter and to create your own client code to access it, you must perform the following additional steps:

   1. Add connector.jar and weblogic60J2eeConnector.jar to the beginning of the CLASSPATH you use to start WebLogic Server.

   2. Add .\samples\eval\cloudscape\lib\cloudscape.jar to the end of the CLASSPATH you use to start WebLogic Server.

   3. Add the following switches to the command line you use to start WebLogic Server:

      -Djdbc.drivers=COM.cloudscape.core.JDBCDriver 
      -Dcloudscape.system.home=./samples/eval/cloudscape/data

   4. Deploy the Black Box resource adapter in a WebLogic Server Domain. For more information, see Deploying a Resource Adapter.

8. If you intend to use the Administration Console to deploy a resource adapter, you must first deploy a modified version of the Administration Console by deploying the console.war file included with the beta distribution in the same domain in which you deploy the Black Box resource adapter.

   Deploy the console.war by copying it from the sample/config/connector/applications directory of the unpacked distribution to the applications directory of the domain where you intend to deploy the Black Box resource adapter.

Creating the connector Domain

The following procedure describes how to set up a pre-configured WebLogic Server domain called connector in which you can deploy the included Black Box resource adapter and run the code example. You can also use this domain as a template for deploying a resource adapter other than the sample.

1. Copy the samples/config/connector directory and its contents from the temporary directory where you unpacked the distribution to the /config directory of your WebLogic Server installation. This directory contains configuration files and scripts that set up a WebLogic Server domain that is configured to use the sample Black Box resource adapter and the example client application.

2. Copy the sample/samples/connector directory and its contents into the samples directory of your WebLogic Server Installation. You can omit this step if you do not intend to run the included Black Box example.

3. Copy the following files from an existing WebLogic Server domain to the config/connector directory of your WebLogic Server installation.

   • fileRealm.properties

   • password.ini

   • SerializedSystemIni.dat

     For example, the files for a domain called mydomain are located in the config/mydomain directory of your WebLogic Server installation.

4. Modify a start script to start WebLogic Server with the WebLogic J2EE Connector Architecture Beta Implementation. The distribution includes two start scripts: startConnectorServer.cmd, for use on Windows NT/2000 systems and startConnectorServer.sh, for use in a Bourne shell on UNIX systems.

   Edit a value for the following variable in the script:

   JAVA_HOME

   Enter the location of your JDK. For example:

   set JAVA_HOME=d:\bea\wlserver6.0\jdk130

5. Modify the script that sets up a development environment. The setConnectorEnv.cmd (Windows NT/2000) and the setConnectorEnv.sh (UNIX) scripts set your PATH, CLASSPATH, and other environment variables to facilitate building the included example and to use in developing applications that use a resource adapter. For more information on this script, see the examples.html file, located in the sample/samples/connector directory of the distribution.

   Edit values for the following variables in the script:

   JAVA_HOME

   Enter the location of your JDK. For example:

   set JAVA_HOME=d:\bea\wlserver6.0\jdk130

   WL_HOME

   Enter the location of your WebLogic Server installation. For example:

   set WL_HOME=d:\bea\wlserver6.0

Deploying a Resource Adapter

Deployment of a resource adapter is similar to deployment of Web Applications, EJBs, and Enterprise Applications. Like these deployment units, you can deploy a resource adapter in an exploded directory format or as an archive file. You can deploy a resource adapter dynamically, by copying the archive file or exploded directory into the applications directory of a WebLogic Server domain, or you can use the Administration Console.

You can also deploy resource adapters as part of an Enterprise Application. Enterprise applications are deployed in an archive file called an ear.

Also similar to Web Applications, EJB and Enterprise Applications, resource adapters use two deployment descriptors to define their operational parameters. The deployment descriptor ra.xml is defined by Sun Microsystems in the J2EE Connector Specification. The weblogic-ra.xml deployment descriptor is specific to WebLogic Server and defines operational parameters unique to WebLogic Server.

Modifying a Resource Adapter for Deployment in the WebLogic Server Environment

This section describes how to take an existing resource adapter and configure it for deployment in WebLogic Server.

1. If your existing resource adapter is in an rar archive file, extract the rar file to a temporary directory. On Windows, you can use the WinZip utility. You can also use the Java jar command. For example:

   jar xf NewBlackBoxNoTx.rar

2. 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. For more information, see Creating the weblogic-ra.xml File and the DTD (Document Type Definition) for this file. A template for this deployment descriptor is included with the distribution, in the rar directory of the distribution. You can use this template as a starting point for creating the weblogic-ra.xml file.

3. Copy the weblogic-ra.xml file into the META-INF directory of the resource adapter directory. 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.

4. Archive the resource adapter into a rar file, including weblogic-ra.xml. You can use the Java jar command, for example:

   jar cvOf myResourceAdapter.rar .

5. Deploy the resource adapter. See the next section, Deploying a Resource Adapter in WebLogic Server.

Deploying a Resource Adapter in WebLogic Server

The following sections describe the three methods of deploying a resource adapter in WebLogic Server.

• Deploying a Resource Adapter Dynamically

• Deploying a Resource Adapter Using the Administration Console

• Deploying a Resource Adapter in an Enterprise Application (ear file)

You must complete the installation procedure before deploying a resource adapter. For more information, see Installing the WebLogic J2EE Connector Architecture Beta Implementation.

Deploying a Resource Adapter Dynamically

To deploy a resource adapter by copying it to the applications directory:

1. Copy the rar archive or the exploded directory containing a resource adapter to the applications directory of a domain.

   For example, after copying a resource adapter called myResourceAdapter in exploded format, your WebLogic Server installation looks like this (not all the files for a resource adapter are shown here):

   \---beaHome
       \---wlserver6.0
           \---config
               \---mydomain
                   \---applications
                       \---myResourceAdapter
                           |   eis.jar
                           |   readme.html
                           |   unix.so
                           |   utilities.jar
                           |   windows.dll
                           |   
                           \---META-INF
                                   ra.xml
                                   weblogic-ra.xml

   After copying a rar file, your WebLogic Server installation looks like this:

   \---beaHome
       \---wlserver6.0
           \---config
               \---mydomain
                   \---applications
                           myResourceAdapter.rar

2. Start WebLogic Server.

3. Open the Administration Console.

4. Click on the Resource Adapter node in the left panel.

5. Verify that the resource adapter is listed and that the Deployed box is checked.

Deploying a Resource Adapter Using the Administration Console

1. Start WebLogic Server.

2. Open the Administration Console.

3. Click the Resource Adapter node in the left panel.

4. Click the Install a new ResourceAdapterComponent ... link in the right panel.

5. Click the Browse button.

6. Browse to the rar file you intend to deploy.

7. Click the Upload button.

8. Note that the new resource adapter now appears in the list of resource adapters.

9. Click your new resource adapter in the left pane.

10. Select the Targets tab in the right pane.

11. Target one or more servers by clicking on a server in the Available box and then clicking the right arrow button to move the server to the Chosen box.

12. Click the Apply button.

Deploying a Resource Adapter in an Enterprise Application (ear file)

As part of the J2EE 1.3 specification, it is now possible to include a resource adapter archive (rar) file inside an Enterprise Application archive (ear) and then deploy the application in Weblogic Server.

To deploy an Enterprise Application that contains a resource adapter archive:

1. Place the rar file inside the ear archive just as you would a war or jar archive.

2. Create a valid application.xml and place it in the META-INF directory of the ear archive.

   Note the following when creating application.xml:

   • The application.xml file must contain the new <connector> element to identify the resource adapter archive within the ear archive. For example:

     <connector>RevisedBlackBoxNoTx.rar</connector>

   • Because the <connector> element is a new addition to the J2EE 1.3 specification, the application.xml file must contain the following DOCTYPE entry to identify it as a J2EE version 1.3 deployment descriptor:

     <!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD
      J2EE Application 1.3//EN'
       'http://java.sun.com/dtd/application_1_3.dtd'> 

     If you do not use this DOCTYPE entry, the resource adapter will not be deployed.

     The following is an example of an application.xml file:

     <application>
        <display-name> ConnectorSampleearApp </display-name>
        <module>
          <connector>RevisedBlackBoxNoTx.rar</connector>
        </module>
        <module>
          <ejb>ejb_basic_beanManaged.jar</ejb>
        </module>
     </application>

3. Deploy the Enterprise Application in WebLogic Server.

   For general information about deployment of Enterprise Applications, see the "Packaging Components and Applications" section of the WebLogic Server documentation .

Resource Adapter Packaging

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

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

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

• Mapping of security principals for Resource Adapter/EIS authorization 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.

Refer to the weblogic-ra.xml DTD for more information on setting the parameters in weblogic-ra.xml. You can also look at the weblogic-ra.xml file in the included example, in the META-INF directory of the Black Box resource adapter.

A template weblogic-ra.xml file is located in the rar directory of the distribution.

Running the Black Box Example

A code example is included with the distribution that demonstrates the use of an entity EJB to interact with a resource adapter. In this example, which uses the Black Box resource adapter from the Sun reference implementation, the resource adapter does not use the Common Client Interface. Instead, it uses JDBC to interact with a DBMS.

A complete description of the example and instructions for building and running the example are included with the distribution. See the examples.html file, located in the sample/samples/connector directory of the distribution.

To build and run the Black Box example:

1. Complete the procedure in Installing the WebLogic J2EE Connector Architecture Beta Implementation.

2. Read the example documentation. See the examples.html file, located in the sample/samples/connector directory of the distribution.

3. Start WebLogic Server by using the supplied start scripts. Make sure you have edited the scripts according to the installation instructions. See Installing the WebLogic J2EE Connector Architecture Beta Implementation.

4. Follow the instructions for building and running the example. See the package-summary.html file, located in the sample/samples/connector/ejb/basic/beanManaged directory of the distribution.

Security Considerations

As specified in the J2EE Connector Architecture Specification, the WebLogic J2EE Connector Architecture Beta Implementation supports both container-managed and application-managed authorization. (For more information on how application components specify the authorization mechanism, see the "Application Programming Model" section of the "Connection Management" chapter in the J2EE Connector Architecture Specification, v. 1.0.)

With application-managed authorization, the application component provides the necessary authorization information (typically a username and password) when making the call to obtain a connection. In the case of container-managed authorization, this information is not provided, and the container must determine the authorization information and provide this information to the resource adapter when requesting a connection.

To use container-managed authorization, Weblogic Server must identify a resource principal and then request the connection on behalf of the resource principal. In order to make this identification, Weblogic Server looks for a security principal specified with the <security-principal-map> element in the weblogic-ra.xml file. This map associates an initiating principal with a resource principal. The initiating principal is identified at run time and has a user identity that is defined in the Weblogic Server security realm.

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 also include a corresponding <resource-principal> entry in the <security-principal-map> element that specifies a username and password, as shown in the following example:

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

Please refer to the provided weblogic-ra.xml template and the weblogic-ra.dtd for complete information.

Known Limitations

Known limitations of this beta release include the following:

• Only resource adapters with a transaction support level of no_transaction are supported.

  This current beta implementation only supports resource adapters where the value of the <transaction-support> element specified in ra.xml is no_transaction. Any attempt to deploy a resource adapter with transaction-support values of local_transaction or xa_transaction results in a failed deployment.

  Please refer to the J2EE Connector Architecture Specification for a complete description of the different transaction-support levels that the specification allows.

• Use of a resource adapter in a cluster of WebLogic Servers is not supported.

  This current beta implementation does not allow the use of a resource adapter in a clustered environment. All client application access from EJBs, Servlets or JSPs must occur within the same managed server in which the resource adapter is deployed.

• Only password credentials are supported.

  This current beta implementation does not allow you to specify generic credentials to represent security credentials when you use container-managed security. This beta implementation only supports resource adapters where the value of the credential-interface element specified in ra.xml is javax.resource.spi.security.PasswordCredential. Any attempt to deploy a resource adapter with a credential-interface value of javax.resource.spi.security.GenericCredential results in a failed deployment. For a complete description of the available security implementations, see the "Security Contract" chapter of the J2EE Connector Architecture Specification.

• Resource adapter-specific permissions are not supported.

  This current beta implementation does not process the security-permission element specified in ra.xml. For a complete description of the expected processing of the security-permission element, see the "Security Permissions" section in the "Runtime Environment" chapter of the J2EE Connector Architecture Specification.

• Online help in the Administration Console for resource adapter attributes is not available.

• Detection of leaked connections in poorly behaved applications is not supported.

  This current beta implementation does attempt to detect connections that are leaked due to the improper coding of a client application. Specifically, it is expected that client applications will close their connections once they no longer need the resource. Failure to close connections causes unclosed connections to consume valuable system resources and can limit the allocation of new connections from the connection pool.

  If a leaked connection occurs, it requires redeployment of the connection factory and resource adapter to eliminate any leaked connections.

• Deployed connection factory or resource adapter settings cannot be viewed through the Administration Console.

  The current beta implementation has not fully integrated the resource adapter configuration information into the console. To view the specific properties of a deployed resource adapter, use the weblogic.Admin command, for example:

  java weblogic.Admin -url t3://host:port -pretty -username user
   -password pswrd GET -type ResourceAdapterComponent

  Replace user with the user name you specified during installation and pswrd with the password you specified during installation.

Known Problems

CR 41296

Attempting to view the JNDI tree from the Administration Console or by using the weblogic.Admin utility fails when a resource adapter is deployed and its JNDI entry is stored in the root context.

You can work around this problem by providing a value for the <jndi-name> element in weblogic-ra.xml that places the connection factory object in a sub-context. You specify a JNDI sub-context by including the / character as part of the value for the <jndi-name> element. For example, eis/BlackBoxNoTxConnector.

Future Plans

The final release of the WebLogic J2EE Connector Architecture Implementation will include full support for all required features in the Sun J2EE Connector Architecture Specification. These features will include support for all levels of transactions, including no-transaction, local-transaction, and xa-transaction. The use of general credentials will also be supported.

Additional Resources

Resources from BEA:

• BEA WebLogic Server 6.0 Documentation

• BEA Developer Center

• BEA Product Center

• DTD for weblogic-ra.xml (also available in the rar directory of the download)

• Newsgroup to report bugs and ask questions:

  weblogic.developer.interest.connector, available from http://newsgroups.bea.com.

Resources from Sun Microsystems:

• J2EE Connector Architecture page

• The proposed final draft of the J2EE Connector Architecture Specification, v. 1.0

  Note: The specification has not yet been finalized.

• Javadocs for J2EE Connector Architecture

• J2EE 1.3 Specification

• DTD for ra.xml