Overview of the Sun ONE Connector Builder

This module describes the following topics:

• Application Integration
• Introduction
• Key Features
• Key Features of the Generated Resource Adapters
• Basic Concepts
• Development Process
• Runtime Deployment Scenarios

Application Integration

---

Application Integration is a diverse and often complex task. Application Integration includes both Enterprise Application Integration (EAI) and Business-to-Business (B2B) Integration. There are a great number of Enterprise Information Systems (EIS), such as SAP, PeopleSoft, Vantive, CICS, and legacy C/C++ applications, and an even greater need to connect them with one another and with new business applications.

An adapter is a software module developed for a given EIS. It provides a way for a client application to connect with, interact with, and execute work in that EIS. There are a multitude of proprietary adapters and proprietary containers that cater to this need to integrate. The J2EE Connector Architecture (J2EE CA) answers the need for Java-based standards in application integration. The J2EE Connector Architecture is a standard for connecting a compliant J2EE platform to EISs.

Rapid Application Development is as much a need of the enterprises today as is application integration. The Connector Builder provides a solution to this need by enabling generation of J2EE CA compliant resource adapters rather than hand-coding them from scratch. This dramatically reduces the time to develop the resource adapters.

Introduction

---

The Connector Builder is a set of tools, components and libraries that allows developers to build resource adapters - compliant with the J2EE Connector Architecture 1.0 - for Enterprise Information Systems (EIS) and legacy applications. The resource adapters built using Connector Builder provide J2EE applications an easy-to-use and standards-based way to access these external systems. The generated resource adapters are accessed using the Common Client Interface (CCI) API as described in the J2EE CA. Optionally, Connector Builder generated resource adapters can also be accessed using Simple Object Access Protocol (SOAP) services thus providing a web services solution to application integration.

The Connector Builder enables users to leverage investments in existing custom or otherwise unique applications and to integrate them with other applications while also taking advantage of the J2EE Connector Architecture Service Provider Interface (SPI) implementation that provides connection management, transaction control, and authentication.

This guide is designed to explain how to define, build, and test a resource adapter using Connector Builder and describes the software tools necessary to deploy the resource adapter so applications can use it to work with the EIS.

Key Features

---

The following lists the key features of the Sun ONE Connector Builder:

• An IDE a graphical Wizard for defining the resource adapter.
• Generation of resource adapters accessible via CCI and SOAP, and deployable into both managed and non-managed environments.

In a managed environment, the generated resource adapter makes use of connection pooling, transaction and security features offered by the application server. In the non-managed case, the resource adapter runs stand-alone and provides its own capabilities for connection pooling.

• Customization points for allowing the resource adapter developer to customize the behavior of the generated resource adapter.
• Generation of Ant scripts to help build and package the generated adapter.
• Generation of deployment descriptors to deploy the resource adapter and associated SOAP services.
• Deployment Tool to deploy and configure the resource adapters in non-managed environment.
• Test client environment to test the generated resource adapter.

Key Features of the Generated Resource Adapters

---

The following lists some of the key features of the resource adapters generated using the Sun ONE Connector Builder:

• A Common Client Interface (CCI)-compliant API for tightly coupled client interaction.
• SOAP services (layered on the CCI API) for loosely coupled client interaction.
• Built-in adapter engine that enables the resource adapter to run in either a managed environment or a non-managed environment.
• Monitoring and administration features for adapter run-time.

Basic Concepts

---

This section explains some of the key concepts in the Connector Builder.

The EIS applications are provided by various vendors or built in-house, reside on various server platforms, and can be written in various languages such as COBOL, C, C++, and Java. Simple client applications running outside an application server access these applications by making direct calls to the EIS's Application Programming Interfaces (APIs). The EIS API contains methods, procedures, or functions that allow a client to do such operations as create a purchase order or perform a credit check. These client APIs are often very complex and differ from each other in the way they expose transactional and security management features. Applications or application developers that deal with multiple EIS APIs must therefore master numerous different APIs.

The resource adapters built according to the J2EE Connector Architecture provide a uniform way to access the resource management services provided by the host environment through Service Provider Interface (SPI), and the features of the EIS API via the CCI API.

Common Client Interface (CCI)

Resource adapters support the CCI API to allow J2EE clients to access an underlying EIS or database in a uniform way. The CCI defines standard interfaces and classes, used to access a resource adapter, that simplify the writing of code to connect a client to an EIS. The classes include those for performing operations in the EIS and for obtaining and managing connections. Connector Builder generates all the CCI classes. J2EE client applications such as Enterprise Java Beans and Servlets use these CCI classes to interact with the resource adapter.

Service Provider Interface (SPI)

The SPI implementation provides a uniform way to access the connection management, transaction support and security management features provided by the J2EE platform.

The following figure illustrates the Generated Resource Adapter Conceptual Overview.

   Generated Resource Adapter Conceptual Overview

EIS API

An EIS provides a set of services to its clients through the client API. This API could be a set of C/C++ libraries or a Java archive (.jar). The Java archive may contain pure Java classes or may contain Java Native Interface (JNI) code to provide access from Java code to the underlying C/C++ libraries. The EIS API typically provides a set of methods for resource management (such as connection creation and security) and another set of methods for interaction with the EIS (such as executing EIS services and manipulating data). EIS interactions could be specific - such as submitOrder or checkCredit - or general-purpose - such as executeFunction - that accepts the function name as a parameter.

Resource adapter development in Connector Builder requires the EIS API to be in Java. When the EIS API is C/C++ libraries, it needs to be wrapped in Java using Java Native Interface(JNI). To build the resource adapters for an underlying C/C++ API, the Native Connector Toolkit (NCT) module available with the Sun ONE IDE can be used to build the JNI layer and bring the EIS API to Java.

Resource Adapter

The resource adapter uses the EIS API resource management and interaction management methods to implement the J2EE CA SPI and CCI contracts. The SPI implementation enables the resource adapter to utilize the resource management services provided by the host server environment. The CCI implementation enables the resource adapter to provide a uniform interaction API for J2EE application developers and enables it for the addition of more value added services.

The Connector Builder generated resource adapter can be deployed into managed as well as non-managed environments. A managed environment is any server environment that is J2EE 1.3 compliant. The built-in adapter engine in the Connector Builder generated adapter utilizes the host provided services in the managed environment and provides a default pool manager in non-managed environment for optimal resource usage.

The resource adapter definition is created in Connector Builder using a Sun ONE IDE Wizard to declare the EIS capabilities for transactions and authentication and to choose which EIS API methods the adapter should support. The resulting generated resource adapter includes, for each EIS API method, Java classes that implement an InteractionSpec, an input Record, and an output Record. These and other generated classes have predefined customization points where the adapter developer can insert EIS-specific logic.

In addition, each generated resource adapter includes classes that work with the SPI implementation of the container to provide connection, transaction, and authentication management.

Java Interaction Object (JIO)

A JIO is a value-added wrapper around the adapter CCI, that provides an even more convenient way for a client application to invoke an EIS API method. JIOs isolate applications from some of the necessary details of the connector architecture's CCI and form the basis of SOAP services for the resource adapter. The JIO implementation follows the J2EE CA CCI application programming model and is portable across managed and non-managed environments.

SOAP Services

The InteractionSpec classes of the generated resource adapter can be selectively exposed as SOAP services layered on the JIOs. Generation of the SOAP layer is an integral, but optional part of the resource adapter development using Connector Builder.

The SOAP RPC interaction with the adapter is achieved by deploying JIOs as service end points in Apache SOAP runtime. Connector Builder generates the necessary deployment descriptors, Java to XML and XML to Java Serializer/Deserializer templates to enable the JIO to be a service end point. Additionally, Connector Builder generates client programs that can send/receive the SOAP encoded XML documents to/from the target SOAP service.

Once enabled, these SOAP services allow any web client to access the deployed resource adapters using SOAP encoded XML over HTTP.

Development Process

---

The following lists the process of building a resource adapter using Connector Builder:

1. Generating the Resource Adapter

Generate the resource adapter using Connector Builder wizard by defining the EIS API and other related information.

2. Customizing the Generated Resource Adapter

Provide mandatory customizations, such as establishing physical connections to the EIS, and other optional customizations.

3. Building and Packaging the Generated Resource Adapter

Use the generated build script to build and package the generated resource adapter.

4. Deploying the Generated Resource Adapter

Deploy the resource adapter onto a J2EE platform. For managed environments, use the platform-specific tools. For non-managed environment Connector Builder provides its own deployment tool.

5. Testing the Generated Resource Adapter

Use the Connector Builder-provided test client facility to test the generated resource adapter.

The following figure illustrates the Connector Builder Resource Adapter Definition.

   Connector Builder Resource Adapter Definition

The following figure illustrates the Resource Adapter Generation and Building.

   Resource Adapter Generation and Building

The following figure illustrates Resource Adapter Packaging, Deployment and Testing.

   Resource Adapter Packaging, Deployment and Testing

Runtime Deployment Scenarios

---

After you generate a resource adapter there are several options to deploy and use the resource adapter. Connector Builder supports the following runtime deployment scenarios of its generated adapters:

• Deployment in Managed Environment
• Deployment in Non-managed Environment
• Deployment in Managed Environment with SOAP over HTTP/S
• Deployment in Non-managed Environment with SOAP over HTTP/S

Deployment in Managed Environment

In this deployment scenario, the resource adapters are deployed onto a J2EE 1.3 compliant application server.

The following lists some of the highlights of a tightly-coupled deployment scenario in a managed environment:

• Multiple resource adapters built using Connector Builder can be deployed on the same application server.
• Multiple instances of the same deployed resource adapter can be configured in an application server.
• The J2EE application server provides the resource adapter with: connection pooling, transaction and security features.

The following figure illustrates Managed Mode Deployment.

   Managed Mode Deployment

Deployment in Non-managed Environment

In this deployment scenario, the resource adapters are deployed on iPlanet Web Server 6.0 or on iPlanet Application Server 6.5. Sun ONE Connector Builder provides a deployment tool to deploy and configure the resource adapters in non-managed mode.

The following lists some of the highlights of a tightly-coupled deployment scenario in a non-managed environment:

• Multiple resource adapters built using Sun ONE Connector Builder can be deployed on the same iPlanet Web Server 6.0 or iPlanet Application Server 6.5.
• Multiple instances of the same deployed resource adapter can be configured in an application server.
• J2EE client applications are built for iPlanet Web Server 6.0 using JSPs and servlets and for iPlanet Application Server 6.5 using EJBs.
• Container-managed transactions and security features that are part of the J2EE CA SPI implementation are not available in this mode.

The following figure illustrates deployment in non-managed mode.

   Non-Managed Mode Deployment

Deployment in Managed Environment with SOAP over HTTP/S

In this deployment scenario, the resource adapters are deployed on a J2EE 1.3 compliant application server. The Apache SOAP runtime must be deployed and configured for the application server.

This deployment scenario has, in addition to features of "Deployment in Managed Environment:"

• SOAP Servlet Router from the Apache SOAP runtime interacts with the deployed resource adapter. The resource adapter internally uses the CCI API.
• Client application uses SOAP-XML to communicate with the resource adapter over HTTP/S.

The following figure illustrates the deployment of SOAP enabled resource adapters in managed mode.

   Deployment of SOAP Enabled Resource Adapters in Managed Mode

Deployment in Non-managed Environment with SOAP over HTTP/S

In this deployment scenario, the resource adapters are deployed on iPlanet Web Server 6.0 or iPlanet Application Server 6.5. The Apache SOAP runtime must be deployed and configured for the server.

This deployment scenario has, in addition to the features of Deployment in Non-managed Environment:

• SOAP Servlet Router from the Apache SOAP runtime interacts with the deployed resource adapters. The resource adapters internally use CCI API.
• Client application uses SOAP-XML to communicate with the resource adapter over HTTP/S.

The following figure illustrates the deployment of SOAP enabled resource adapters in non-managed mode.

   Non-managed Mode with SOAP