Introduction to the ADK

This guide provides instructions for using the WebLogic Integration Adapter Development Kit (ADK). It shows you how to develop, test, and deploy event and service connections and the design-time user interface.

Section Objectives

This section serves as an overview to using the ADK to develop event and service connections and a design-time GUI. You will learn:

What adapters are and how they are used
Prerequisites you must meet before beginning adapter development
Terminology associated with adapter development

What Is the ADK?

The ADK is a set of tools for implementing the event and service protocols supported by BEA WebLogic Integration. These tools are organized in a collection of frameworks that support the development, testing, packaging, and distribution of resource adapters for WebLogic Integration. Specifically, the ADK includes frameworks for four purposes:

Design-time operation
Run-time operation
Logging
Packaging

Requirements for Adapter Development

Development environment structure: The organization of a development project is important in any integrated development and debugging environment (IDDE). With a well structured development environment, you can begin coding an adapter immediately. The ADK provides an organized development environment, build process, intuitive class names and class hierarchy, and test methodology. By using the ADK, you avoid having to spend time designing and organizing a build process.

Because the ADK encompasses so many advanced technologies, an incremental development process (code a little, test a little) is the key to success. The ADK test process allows a developer to make a simple change and test it immediately.

Minimal exposure to peripheral implementation details: Peripheral implementation details are sections of code that are needed to support the framework in which a robust software program runs.

For example, the J2EE Connector Architecture specification requires that the javax.resource.cci.InteractionSpec implementation class provide getter and setter methods that follow the JavaBeans design pattern. To support the JavaBeans design pattern, you must, in turn, support PropertyChangeListeners and VetoableChangeListeners in your implementation class. You do not want to have to study the JavaBeans specification to learn how to do this. Rather, you want to focus on implementing the enterprise information system (EIS)-specific details of the adapter. The ADK provides a base implementation for a majority of the peripheral implementation details of an adapter.

A clear roadmap to success: Exit criteria enable you to answer the question: "How do I know my implementation is complete?" The ADK provides a clear methodology for developing an adapter. The methodology helps you organize your thoughts around a few key concepts: events, services, design-time operation, and run-time operation. Using this methodology, you can establish exit criteria that form a roadmap to implementation completion.

What the ADK Provides

Run-time support for events and services
An API for integrating an adapter's user interface with the Application Integration Design Console

The ADK adds value by making it possible to make adapters an integral part of a single graphical console application that can be used by business users to construct integration solutions.

What Are Adapters?

Resource adapters—referred to in this document as adapters—are software components used to connect applications that were not originally designed to communicate with each other. For example, an adapter might be needed to enable an order entry system built by one company to communicate with a customer information system built by another.

Service adapters, which accept requests and return responses
Event adapters, which generate messages

You can also create an adapter that supports both services and events. All these types of adapters include an implementation of a top-level adapter interface

ResourceAdapter—A top-level container for managing service and event adapters and connections.

You can also use the ADK to create J2EE-compliant adapters that are not specific to WebLogic Integration but that comply with the J2EE Connector Architecture Specification.

ResourceAdapter Interface

The ResourceAdapter interface is new in WebLogic Integration 8.1. It serves as a single object to unify both event and service handling. In prior WebLogic Integration releases, the event adapter and service adapter were treated as separate adapter components. Each was deployed and configured separately.

In this release, the event and service adapters are unified under the ResourceAdapter interface, and the adapter's implementation of that interface. It provides access to 0 or 1 event connection (created by the event adapter), and 0 or more service connections (created by the service adapter). The service connections are sometimes referred to as connection factories.

Configuration of event and service connections are now done under the umbrella of the ResourceAdapter interface. You will see the term Resource Adapter used in the Application Integration Design Console to represent a container of event and service connections.

Each adapter must implement ResourceAdapter in a concrete class and package that class into the adapter's EAR module in order to operate within WebLogic Integration. The ADK provides an abstract base implementation of the ResourceAdapter class in com.bea.adapter.spi.AbstractWLIResourceAdapter.

Service Connections

Service connections receive XML request documents from clients and invoke specific functions in the underlying enterprise information system (EIS). They are consumers of messages; they may or may not provide a response.

A service may be invoked in either of two ways: asynchronously or synchronously. When a service is invoked asynchronously, the client application issues a service request and then proceeds with processing without waiting for the response. When a service is invoked synchronously, the client waits for the response before proceeding with processing. BEA WebLogic Integration supports both types of service connection invocations, so you are not required to provide this functionality.

Receive service requests from an external client.
Transform the XML format of a request document into an EIS-specific format. The request document conforms to the request XML schema for the service. The request XML schema is based on metadata in the EIS.
Invoke the underlying function in the EIS and wait for its response.
Transform the response from the EIS-specific data format to an XML document that conforms to the response XML schema for the service. The response XML schema is based on metadata in the EIS.

As with events, the ADK implements the aspects of these four functions that are common to all service connections.

Event Connections

Event connections are designed to propagate information from an EIS to WebLogic Server; they can be described as publishers of information.

There are two basic types of event connections: in-process and out-of-process. In-process event connections execute within the same process as the EIS. Out-of-process adapters execute in a separate process. In-process and out-of-process event connections differ only in terms of how they accomplish the data extraction process.

Event connections running in a WebLogic Integration environment perform the following three functions:

Respond to events deemed to be of interest to some external party that occur inside the running EIS and extract data about such events from the EIS.
Transform event data from an EIS-specific format to an XML document that conforms to the XML schema for the event. The XML schema is based on metadata in the EIS.
Propagate each event to an event message endpoint provided by the application server.

The ADK implements the aspects of these three functions that are common to all event connections. Consequently, you can focus on the EIS-specific aspects of your adapter. This concept is the same as the concept behind Enterprise Java Beans (EJB): the container provides system-level services for EJB developers so they can focus on implementing business application logic.

J2EE-Compliant Adapters Not Exclusive to WebLogic Integration

These adapters are not designed for WebLogic Integration exclusively; they can be plugged into any application server that supports the J2EE Connector Architecture specification. These adapters can be developed by making minor modifications to the procedures given for developing a service connection. To learn how to develop an adapter that is not specific to WebLogic Integration, see Creating an Adapter Not Specific to WebLogic Integration.

Design-Time GUI

Along with event and service connections, the ADK's design-time framework provides tools you can use to build the Web-based GUI that adapter users need to define, deploy, and test application views (see Application Views). Although each adapter has EIS-specific functionality, all adapters require a GUI for deploying application views. The design-time framework minimizes the effort required to create and deploy these interfaces, primarily by using two components:

A Web application component and a web request handler base class (AbstractDesignTimeRequestHandler) that allows you to build an HTML-based GUI by using Java Server Pages (JSP). This component is augmented by tools such as the JSP templates, the JSP tag library, and the JavaScript library.
A deployment helper component, called DesignTimeHelper, that provides a simple API for deploying, undeploying, and editing application views on WebLogic Server.

Application Views

While an adapter represents a system-level interface to all the functionality in an application, an application view represents a business-level interface to a particular set of functions in the application.

An application view is configured for a single business purpose and contains only services related to that purpose. These services require only business-relevant data to be specified in the request document; they return only business-relevant data in the response document. Without user intervention, the application view combines this business-relevant data with stored metadata necessary for the adapter. The adapter takes both the business-relevant data and the stored metadata and executes a system-level function on the application.

The application view also represents both the events and services that support the specified business purpose. As a result, the business user can perform all communication with an application through the application view. Such bidirectional communication is supported by two adapter components: the event connection and the service connection. The application view abstracts this fact from users and presents them with a unified business interface to the application.

Packaging Framework

The ADK packaging framework is a tool set for packaging an adapter for delivery to a customer. Ideally, all adapters are installed, configured, and uninstalled in the same way on WebLogic Server. All service connections must be J2EE compliant. The packaging framework simplifies the creation of a J2EE adapter archive (RAR) file, a Web application archive (WAR) file, an enterprise archive (EAR) file, and a WebLogic Integration design environment archive.

Developing Adapters