bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic J2EE Connectors

Overview of WebLogic J2EE Connectors

The following sections provide an overview of BEA WebLogic J2EE Connectors:

- J2EE Connector Architecture Terminology

- Overview of the BEA WebLogic J2EE Connector Architecture Implementation

- J2EE Connector Architecture Components

- Enhancements in This Release

- Black Box Example

J2EE Connector Architecture Terminology

Key terms and concepts that you will encounter throughout the WebLogic J2EE Connector Architecture documentation include the following:

- Application Component—can be a server-side component, such as an EJB, JSP, or servlet, that is deployed, managed, and executed on an application server. It can also be a component executed on the Web-client tier but made available to the Web-client by an application server. Examples of the latter type of application component include a Java applet and a DHTML page.

- Caller Principal—a principal that is associated with an application component instance during a method invocation. For example, an EJB instance can call the getCallerPrincipal method to get the principal associated with the current security context.

- Common Client Interface (CCI)—defines a standard client API for application components and enables application components and Enterprise Application Integration (EAI) frameworks to drive interactions across heterogeneous EISes using a common client API. The J2EE Connector Architecture defines a CCI for EIS access.

- Connection—provides connectivity to a resource manager and enables an application client to connect to a resource manager, perform transactions, and access services provided by that resource manager. A connection can be either transactional or non-transactional. Examples include a database connection and an SAP R/3 connection.

- Container—part of an application server—such as WebLogic Server—that provides deployment and run-time support for application components. A container allows you to monitor and manage supported components as well as the service(s) that monitor and manage the components. Containers can be one of the following:

  - Connector containers that host resource adapters

  - Web containers that host JSP, servlets, and static HTML pages

  - EJB containers that host EJB components

  - Application client containers that host standalone application clients

    For more details on different types of standard containers, refer to Enterprise JavaBeans (EJBs), Java Server Pages (JSPs), and Servlets specifications.

- Credential—contains or references security information that can authenticate a principal to additional services. A principal acquires a credential upon authentication or from another principal that allows its credential to be used: the latter is termed principal delegation.

- Enterprise Information System (EIS)—provides the information infrastructure for an enterprise. An EIS offers a set of services to its clients. These services are exposed to clients as local and/or remote interfaces. Examples of an EIS include:

  - ERP system

  - Mainframe transaction processing system

  - Legacy database system

- Enterprise Information System (EIS) resource—provides EIS-specific functionality to its clients. Examples of an EIS resource include:

  - Record or set of records in a database system

  - Business object in an Enterprise Resource Planning (ERP) system

  - Transaction program in a transaction processing system

- Initiating Principal—the security principal representing the end-user that interacts directly with the application. An end-user can authenticate using either a Web client or an application client.

- J2EE Connector—See Resource Adapter.

- J2EE Connector Architecture—an architecture for integration of J2EE-compliant application servers with enterprise information systems (EISes). There are two parts to this architecture: an EIS vendor-provided resource adapter and an application server—such as WebLogic Server— to which the resource adapter plugs in. This architecture defines a set of contracts—such as transactions, security, and connection management—that a resource adapter has to support to plug in to an application server. The J2EE Connector Architecture also defines a Common Client Interface (CCI) for EIS access. The CCI defines a client API for interacting with heterogeneous EISes.

- Managed Environment—defines an operational environment for a J2EE-based, multi-tier, Web-enabled application that accesses EISes. The application consists of one or more application components—EJBs, JSPs, servlets—which are deployed on containers. These containers can be one of the following:

  - Web containers that host JSP, servlets, and static HTML pages

  - EJB containers that host EJB components

  - Application client containers that host standalone application clients

- Non-managed Environment—defines an operational environment for a two-tier application. An application client directly uses a resource adapter to access the EIS; the EIS defines the second tier for a two-tier application.

- Principal—an entity that can be authenticated by an authentication mechanism deployed in an enterprise. A principal is identified using a principal name and authenticated using authentication data. The content and format of the principal name and the authentication data depend upon the authentication mechanism.

- RAR—resource adapter archive. A compressed (.zip) file used to load classes and other files required to run a resource adapter.

- ra.xml—describes the resource adapter-related attributes type and its deployment properties using a standard DTD from Sun Microsystems.

- Resource Adapter—a system-level software driver used by an application server such as WebLogic Server to connect to an EIS. A resource adapter serves as the "J2EE connector." The WebLogic J2EE Connector Architecture supports resource adapters developed by Enterprise Information Systems (EISes) vendors and third-party application developers that can be deployed in any application server supporting the Sun Microsystems J2EE Platform Specification, Version 1.3. Resource adapters contain the Java, and if necessary, the native components required to interact with the EIS.

- Resource Manager—part of an EIS that manages a set of shared EIS resources. Examples of resource managers are a database system, a mainframe TP system, and an ERP system. A client requests access to a resource manager to use its managed resources. A transactional resource manager can participate in transactions that are externally controlled and coordinated by a transaction manager. In the context of the J2EE Connector Architecture, clients of a resource manager can include middle-tier application servers and client-tier applications. A resource manager is typically a different address space or on a different machine from the client that accesses it.

- Resource Principal—a security principal under whose security context a connection to an EIS instance is established.

- Security Attributes—a principal has a set of security attributes associated with it. These are related to the authentication and authorization mechanisms. Examples are security permissions and credentials for a principal.

- Service Provider Interface (SPI)—contains the objects that provide and manage connectivity to the EIS, establish transaction demarcation, and provide a framework for event listening and request transmission. All J2EE Connector Architecture-compliant resource adapters must provide an implementation for these interfaces in the javax.resource.spi package.

- System Contract—a mechanism by which connection requests are passed between entities. To achieve a standard system-level pluggability between application servers such as WebLogic Server and EISes, the Connector Architecture defines a standard set of system-level contracts between an application server and an EIS. The EIS side of these system-level contracts is implemented in a resource adapter.

- weblogic-ra.xml—adds additional WebLogic Server-specific deployment information to the ra.xml file.

Overview of the BEA WebLogic J2EE Connector Architecture Implementation

BEA WebLogic Server continues to build upon the implementation of the Sun Microsystems J2EE Platform Specification, Version 1.3. The J2EE Connector Architecture adds simplified Enterprise Information System (EIS) integration to the J2EE platform. The goal is to leverage the strengths of the J2EE platform—including component models, transaction and security infrastructures—to address the challenges of EIS integration.

The J2EE Connector Architecture provides a Java solution to the problem of connectivity between the multitude of application servers and EISes. By using the Connector Architecture, it is no longer necessary for EIS vendors to customize their product for each application server. By conforming to the J2EE Connector Architecture, BEA WebLogic Server does not require added custom code in order to extend its support connectivity to a new EIS.

The Connector Architecture enables an EIS vendor to provide a standard resource adapter for its EIS. This resource adapter plugs into WebLogic Server and provides the underlying infrastructure for the integration between an EIS and WebLogic Server.

By supporting the Connector Architecture, BEA WebLogic Server is assured of connectivity to multiple EISes. In turn, EIS vendors must provide only one standard Connector Architecture-compliant resource adapter that has the capability to plug into BEA WebLogic Server.

Note: BEA WebLogic Server 7.0 is completely compliant with J2EE 1.3. Also, since J2EE is backward compatible, you can still run J2EE 1.2 on WebLogic Server 7.0.

J2EE Connector Architecture Components

The J2EE Connector Architecture is implemented in an application server such as WebLogic Server and an EIS-specific resource adapter. A resource adapter is a system library specific to an EIS and provides connectivity to the EIS. A resource adapter is analogous to a JDBC driver. The interface between a resource adapter and the EIS is specific to the underlying EIS; it can be a native interface.

The J2EE Connector Architecture has three main components:

- System-level Contracts—between the resource adapter and the application server (WebLogic Server)

- Common Client Interface (CCI)—provides a client API for Java applications and development tools to access the resource adapter

- Packaging and Deployment Interfaces—provides ability for various resource adapters to plug into J2EE applications in a modular manner

The following diagram illustrates the J2EE Connector Architecture:

Figure 1-1 J2EE Connector Architecture

A resource adapter serves as the "J2EE connector." The WebLogic J2EE Connector Architecture supports resource adapters developed by Enterprise Information Systems (EISes) vendors and third-party application developers that can be deployed in any application server supporting the Sun Microsystems J2EE Platform Specification, Version 1.3. Resource adapters contain the Java, and if necessary, the native components required to interact with the EIS.

System-level Contracts

The J2EE Connector Architecture specification defines a set of system-level contracts between the J2EE-compliant application server (WebLogic Server) and an EIS-specific resource adapter. WebLogic Server, in compliance with this specification, has implemented a set of defined standard contracts for:

- Connection management—a contract that gives an application server pool connections to underlying EISes. It also allows application components to connect to an EIS. This results in a scalable application environment that supports a large number of clients requiring access to EISes.

Note: For more information on connection management, refer to Connection Management.

- Transaction management—a contract between the transaction manager and an EIS supporting transaction access to EIS resource managers. This contract allows an application server to use a transaction manager to manage transactions across multiple resource managers.

Note: For more information on transaction management, refer to Transaction Management.

- Security management—a contract that provides secure access to an EIS and provides support for a secure application environment. This reduces threats to the EIS and protects information resources that the EIS manages.

Note: For more information on security management, refer to Security.

Common Client Interface (CCI)

The Common Client Interface (CCI) defines a standard client API for application components. The CCI enables application components and Enterprise Application Integration (EAI) frameworks to drive interactions across heterogeneous EISes using a common client API.

The target users of the CCI are enterprise tool vendors and EAI vendors. Application components themselves may also write to the API, but the CCI is a low-level API. The specification recommends that the CCI be the basis for richer functionality provided by the tool vendors, rather than being an application-level programming interface used by most application developers.

Further, the CCI defines a remote function-call interface that focuses on executing functions on an EIS and retrieving the results. The CCI is independent of a specific EIS; for example: data types specific to an EIS. However, the CCI is capable of being driven by EIS-specific metadata from a repository.

The CCI enables WebLogic Server applications to create and manage connections to an EIS, execute an interaction, and manage data records as input, output or return values. The CCI is designed to leverage the JavaBeans architecture and Java Collection framework.

The 1.0 version of the J2EE Connector Architecture recommends that a resource adapter support CCI as its client API, while it requires that the resource adapter implement the system contracts. A resource adapter may choose to have a client API different from CCI, such as the client API based on the Java Database Connectivity (JDBC) API.

Note: For more information relating to the Common Client Interface, refer to Client Considerations.

Packaging and Deployment

The J2EE Connector Architecture provides packaging and deployment interfaces, so that various resources adapters can easily plug into compliant J2EE application servers such as WebLogic Server in a modular manner.

Figure 1-2 Packaging and Deployment

A resource adapter provider develops a set of Java interfaces and classes as part of its implementation of a resource adapter. These Java classes implement J2EE Connector Architecture-specified contracts and EIS-specific functionality provided by the resource adapter. The development of a resource adapter can also require use of native libraries specific to the underlying EIS.

The Java interfaces and classes are packaged together (with required native libraries, help files, documentation, and other resources) with a deployment descriptor to create a Resource Adapter Module. A deployment descriptor defines the contract between a resource adapter provider and a deployer for the deployment of a resource adapter.

You can deploy resource adapter module as a shared, stand-alone module or packaged as part of an application. During deployment, you install a resource adapter module on an application server such as WebLogic Server and then configure it into the target operational environment. The configuration of a resource adapter is based on the properties defined in the deployment descriptor as part of the resource adapter module.

Note: For more information on packaging and deployment, refer to Packaging and Deploying Resource Adapters.

Enhancements in This Release

The following J2EE Connector Architecture enhancements are new to this release of WebLogic Server.

Additional Classloading Support

WebLogic Server now supports the loading of properties or classes that are specified in ClassPath entry of the resource adapter's Manifest.mf file. The following is a description of how you configure properties and classes that are in and used by a resource adapter.

The resource adapter (RAR) archive file and the application component using it (for example, an EJB JAR) are contained in an Enterprise Application (EAR) archive. The RAR requires resources such as Java properties that are stored in a JAR file, and that JAR file is contained within the EAR file (not in the RAR itself).

You specify a reference to the RAR Java classes by adding a ClassPath= entry in the RAR Manifest.mf file. You can also store the EJB Java classes in the same JAR file that is contained within the EAR. This scenario provides a "support" JAR file that contains Java classes for the components in the EAR that require them.

Secure Password Credential Storage

This release provides a standard method for resource adapter deployers to plug in their specified authorization/authentication mechanism through secure password credential storage. This WebLogic Server storage mechanism 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. The Password Converter Tool provided with the previous release of WebLogic Server has also been deprecated.

This new storage mechanism is used to map initiating principals (such as WebLogic Server username and password combinations) to resource principals (EIS user name and password combinations).

Flexible Connection Leak Detection

In the past release, the connection leak detection mechanism was based upon a timer that started when a connection was created and triggered when the connection exceeded its usage duration. WebLogic Server now provides two mechanisms for preventing this scenario:

- Leveraging a garbage collector

- Providing an idle timer for tracking the usage of connection objects

The <connection-cleanup-frequency> and <connection-duration-time> elements in the weblogic-ra.xml deployment descriptor have been deprecated.

Security Policy Processing of an ra.xml Specification

BEA WebLogic Server J2EE Connector Architecture provides a set of security permissions for execution of a resource adapter in a managed runtime environment. WebLogic Server also grants a resource adapter explicit permissions to access system resources.

Black Box Example

A simple code example for a resource adapter is provided with this release. This 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 PointBase DBMS, which is provided in an evaluation version with WebLogic Server. For more information, refer to the WebLogic J2EE Connector Architecture Example Javadoc provided with the product download.