Using the J2EE Connector Architecture and SOAP to Build Web-Service-Ready Enterprise Applications, Part 1

A combination of the Java 2 Platform, Enterprise Edition (J2EE) connector architecture and Simple Object Access Protocol (SOAP) technologies provides a standard way to use SOAP-encoded Extensible Markup Language (XML) to interact with legacy systems. In parallel, you can also take advantage of the effective resource management capabilities offered by the J2EE platform.

This article describes how to use connectors and SOAP in the J2EE environment and suggests three approaches to implementation. It contains five sections:

This article assumes familiarity with the following:

• Common Client Interface (CCI) in the J2EE connector architecture

Enterprise Application Integration (EAI) and Connectors: J2EE Application Server as the Design Center

You can use the latest J2EE application servers, such as Sun ONE Application Server 7, to build and deploy J2EE connectors in a standard manner. A J2EE connector is a system component that enables J2EE applications to use a specific back-end system, such as Enterprise Resource Planning (ERP), Customer Relationship Management (CRM), and other legacy applications, in accordance with the J2EE Connector Architecture Specification. That architecture simplifies enterprise application integration (EAI) on the J2EE platform and paves the way for building more sophisticated value-add client layers on top of back-end applications.

The J2EE 1.3 Specification includes the J2EE Connector 1.0 Specification, which standardizes connector deployment and use in a J2EE-platform-compliant application server. Presently, the J2EE Connector 1.5 Specification is undergoing the Java Community Process with a recent release of the Public Final Draft. This article includes only a discussion of the J2EE Connector 1.0-compliant connectors and possible scenarios for their use.

Following are three interesting scenarios that demonstrate how client applications and connectors can interact:

In all three scenarios, the connector uses the effective resource management capabilities, such as pooling, provided by the application server. In the scenario for tightly coupled interactions, the client uses the container-managed security and transactional capabilities of the connector. In the scenario for loosely coupled interactions, the SOAP service end-point uses those features. For details, see the section, " Implementation Approaches."

Note - In all three scenarios, neither the connector sources nor the connector capacity to interact with the application server is forced to change in any manner. Only the use of the connector changes according to the requirements of the application. Such a protocol ensures a return on investments in building or acquiring connectors instead of directly exposing the back-end system for XML or SOAP interactions.

SOAP for Remote Procedure Calls (RPC)

SOAP is a lightweight, XML-based protocol for exchanging information in a decentralized, distributed environment. It contains three parts:

• An envelope that defines a framework for describing what a message contains and how to process it
• A set of encoding rules for expressing instances of application-defined data types
• A convention for representing remote procedure calls and responses

Potentially, you can use SOAP in combination with a variety of other protocols. The only predominant binding is for the use of SOAP in combination with HyperText Transfer Protocol (HTTP). SOAP for remote procedure calls (RPC) defines a uniform representation of remote procedure calls and responses. Using SOAP for RPC is orthogonal to the SOAP protocol binding. If you use HTTP as the protocol binding, an RPC call maps to an HTTP request and an RPC response maps to an HTTP response. When preparing the SOAP message, you can use the SOAP encoding style to construct the method, request, and response elements. For details on the SOAP protocol, SOAP encoding, and SOAP for RPC, see the W3C note on SOAP.

The Java API for XML-based RPC (JAX-RPC) specifies the APIs for supporting XML-based RPC for the Java platform. One of the key protocol bindings the JAX-RPC specifies is the SOAP protocol binding. Also, the JAX-RPC Specification mandates that compliant runtime systems support HTTP as the transport protocol. For details, see the JAX-RPC site.

Implementation Approaches

This section focuses on methods for creating service end-points and enabling connectors for interactions with SOAP messages over HTTP. (For details on how to develop Web services, see Sun ONE Studio 4 Developer Resources.) These approaches are not mutually exclusive, however, and have the following components in common:

• Back-end systems -- The system of interest to interact with, such as ERP, CRM, or a custom legacy application. This system runs in a different address space or sometimes on a separate physical system.
• Connectors -- A system component that's specifically developed to connect to and interact with the back-end system. It's typically built on a client API that's exposed by the back-end system.
• Java Interaction Object (JIO) -- A Java utility class that wraps the connector interaction API, exposing a simpler API to the client, thus enhancing the code structure and facilitating maintenance. You can build a JIO for a specific business function or for a set of commonly used business functions. Client applications can then use these JIOs directly or as service end-points. You can layer JIOs on top of connectors to isolate their interactions from the application. CODE EXAMPLE 1 contains a JIO code sample.
• Clients -- A client is a J2EE, non-J2EE, or non-Java component that's interested in interacting with the connector.

Tightly Coupled Interactions

FIGURE 1 illustrates how to use connectors to implement a scenario in which interactions are tightly coupled.

• Legend
• ex
• Example
• EJB
• Enterprise JavaBeans (EJB) component
• FIGURE 1 Tightly Coupled Interactions with a Connector That Uses a JIO

In this diagram, JIO is part of a connector interaction layer, which can contain a set of JIOs that model the interaction with the connector. This scenario exemplifies the following:

• How to build a JIO for a connector that interacts with a hypothetical Customer Order Tracking System (COTS) application
• How to wrap the GetCustomer and UpdateCustome business functions

The client component uses the COTS JIO class to interact with the connector.

Here is a code sample of a JIO.

public class COTSJIO implements COTSServiceEndPoints{

private Connection connection;

// Default constructor.
public COTSJIO(){
// Initialize instance variables.
}

public void acquireConnection(String jndiName)
throws ResourceException{

// Use jndiName to acquire Connection handle.
// Cache the Connection handle.

}

public COTSGetCustomerOutputRecord executeGetCustomer
(COTSGetCustomerInputRecord inputRecord) throws
ResourceException{
// Execute 'GetCustomer' business function,
using connector-provided API.

}

public COTSUpdateCustomerOutputRecord
executeUpdateCustomer(COTSUpdateCustomerInputRecord
inputRecord) throws ResourceException{
// Execute 'UpdateCustomer' business function,
using connector-provided API.
}

public void closeConnection() throws ResourceException{
// Close the Connection.
}

public COTSGetCustomerOutputRecord getCustomerEndPoint
(String jndiName, COTSGetCustomerInputRecord inputRecord)
throws RemoteException, ResourceException{
// Call to acquireConnection with jndiName as parameter.
// Call to executeGetCustomer with inputRecord as parameter.
// Call to closeConnection.
// Return executeGetCustomer output.
}

public COTSUpdateCustomerOutputRecord updateCustomerEndPoint
(String jndiName, COTSUpdateCustomerInputRecord inputRecord)
throws RemoteException, ResourceException{
// Call to acquireConnection with jndiName as parameter.
// Call to executeUpdateCustomer with inputRecord as parameter.
// Call to closeConnection.
// Return executeUpdateCustomer output.
}
}

CODE EXAMPLE 1 COTSJIO.java: a Sample JIO to Interact with a COTS Connector

Loosely Coupled Interactions

FIGURE 2 shows the components of interest in the scenario for loosely coupled interactions. Here, the JIO acts as a service end-point that can be exposed as SOAP services in an implementation-specific way, such as by the JAX-RPC or by Apache SOAP, and hence is referred to as a runtime system.

Legend

• ex
• Example
• EJB
• Enterprise JavaBeans (EJB) component
• FIGURE 2 Loosely Coupled Interactions with a Connector That Uses JIO and SOAP

The JIO shown in CODE EXAMPLE 1 implements an interface called COTSServiceEndPoints. The methods in the interface are exposed for invocation by a SOAP RPC. CODE EXAMPLE 2 is an example of the definition for the service end-points, which are accessible through a transport driver provided by the runtime system. SOAP requires that the data types of the input and output parameters be primitive types or beans. If a given data type does not fall into either of those categories, you must supply a serializer and deserializer to the runtime system.

public interface COTSServiceEndPoints extends Remote{

public COTSGetCustomerOutputRecord getCustomerEndPoint(String
jndiName, COTSGetCustomerInputRecord inputRecord) throws
RemoteException, ResourceException;

public COTSUpdateCustomerOutputRecord updateCustomerEndPoint
(String jndiName, COTSUpdateCustomerInputRecord inputRecord) throws
RemoteException, ResourceException;

}

CODE EXAMPLE 2 COTSServiceEndPoints.java: a Sample Set of Service End-points Implemented by JIO

In the preceding scenario, the JIOs are scoped to interact with a specified connector. Certain application requirements may mandate interactions with multiple connectors; you can comply by using multiple connector-dependent JIOs in the service end-point application and exposing the application as SOAP-accessible service. FIGURE 3 shows this type of use at a high level.

FIGURE 3 Loosely Coupled Interactions with Multiple Connectors That Use JIOs and SOAP

Summary

You can simplify the process of integrating enterprise applications in a J2EE application server by adhering to the J2EE Connector Specification. Be aware, though, that various drivers impact the use pattern of connectors. No matter which scenario you adopt, be sure to use the features provided by the application server and any access layers that are built on it.

Also bear in mind that you can expose the JIO components in the access layers as service end-points or the application can use them directly for connector interactions.

References

• W3C Note: Simple Object Access Protocol (SOAP)

Coming soon will be part 2 of this series, in which we describe how to use Sun ONE Connector Builder to implement tightly and loosely coupled interactions and how to build connectors that support SOAP over HTTPS and SOAP with attachments.

About the Authors

Venkat Amirisetty, a senior staff engineer at Sun Microsystems, has been with Sun for six years. Currently, he s developing technology products for application integration and is the engineering lead for Sun ONE Connector Builder. Venkat works closely with the J2EE Connector Architecture 1.5 (JSR-112) Expert Group.

Marina Sum is a staff writer for Sun ONE for Developers. She has been writing for Sun for 14 years, mostly in the technical arena.

Unless otherwise licensed, code in all technical manuals herein (including articles, FAQs, samples) is provided under this License.