WebLogic J2EE Connector Architecture Beta Implementation
This document contains information about the WebLogic® J2EE Connector Architecture Beta Implementation. The following topics are discussed:
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.
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.
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.
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.
Edit a value for the following variable in the script:
Edit values for the following variables in the script:
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.
jar xf NewBlackBoxNoTx.rar
jar cvOf myResourceAdapter.rar .
Deploying a Resource Adapter in WebLogic Server
The following sections describe the three methods of deploying a resource adapter in WebLogic Server.
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:
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):
After copying a rar file, your WebLogic Server installation looks like this:
Deploying a Resource Adapter Using the Administration Console
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:
Note the following when creating application.xml:
<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD
J2EE Application 1.3//EN'
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:
<display-name> ConnectorSampleearApp </display-name>
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:
Note the following about the files in a resource adapter:
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:
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:
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:
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:
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 of this beta release include the following:
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.
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.
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.
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.
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.
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.
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.
Resources from BEA:
weblogic.developer.interest.connector, available from http://newsgroups.bea.com.
Resources from Sun Microsystems:
Copyright © 2001 BEA Systems, Inc. All rights reserved.