Developing Connectors Using the Enterprise Connector Business Object (ECBO) API

The Enterprise Connector Business Object (ECBO) API provides classes and methods that allow you to create an Enterprise Connector. An ECBO Enterprise Connector is a Java artifact that consists of extensions of five classes compiled and packaged into a RAR file as a resource adapter, along with other files needed for the resource adapter.

The methods you implement in your Enterprise Connector are called by the Sun GlassFish Mobility Platform libraries deployed on the Gateway. In this respect, the ECBO API is more like a Service Provider Interface (SPI) than an Application Programmer Interface (API).

Each Enterprise Connector defines a particular business object whose data is to be synchronized. It also defines commands and operations that allow the Enterprise Connector to perform Create, Retrieve, Update, and Delete (CRUD) operations on the business objects.

The five classes you must implement are called BusinessObject, BusinessObjectProvider, InsertCommand, UpdateCommand, and DeleteCommand. The BusinessObjectProvider class provides a method to perform the retrieve operation. Chapter 3, Creating an Enterprise Connector Using the Enterprise Connector Business Objects (ECBO) API, describes in detail how to implement these classes.

The resource file is an XML file that is used by the underlying implementation. It defines a repository name, a workspace name, and a few node types. All Enterprise Connectors use the same set of node types.

The data to be synchronized takes the form of arbitrary Java objects. The way in which these Java objects are serialized is open-ended and is part of the contract between an Enterprise Connector and its corresponding Java ME client. It is recommended that you use a format that supports data versioning.

For details about developing ECBO Enterprise Connectors, see Chapter 3, Creating an Enterprise Connector Using the Enterprise Connector Business Objects (ECBO) API.

Packaging and Deploying ECBO Enterprise Connectors

To package an Enterprise Connector that uses the ECBO API, compile the five Java classes. Then create a resource adapter using the Java Connector Architecture and include the five classes and the ECBO library in the RAR file for the resource adapter.

To see how the sample ECBO Enterprise Connectors provided with Sun GlassFish Mobility Platform are packaged, use the jar command or another utility to view the contents of either of the following files in the gateway subdirectory of the directory where the Sun GlassFish Mobility Platform installation bundle was unzipped:

Alternatively, you can see the deployed versions by looking in the applications/j2ee-modules directory of the Enterprise Server domain for Sun GlassFish Mobility Platform.

The Maven plugin for NetBeans IDE makes available a set of Maven archetypes (templates) that you can use to develop ECBO Enterprise Connectors.

The same Enterprise Connector works equally well in a one-tier or two-tier Sun GlassFish Mobility Platform installation. (See Sun GlassFish Mobility Platform Architecture in Sun GlassFish Mobility Platform 1.1 Architectural Overview for details on these two types of installation.) Deploy the Enterprise Connector to the Enterprise Server domain that contains your Sun GlassFish Mobility Platform installation. You can use the Enterprise Server Administration Console or the asadmin command to deploy the Enterprise Connector.

In a two-tier Sun GlassFish Mobility Platform installation, an ECBO Enterprise Connector is deployed on the second tier, as shown in Figure 1–2. In this situation, communication between the Gateway and the Enterprise Connector goes through a web service. The Gateway communicates with the web service client. The web service client communicates with the web service endpoint using SOAP/HTTP(S). Finally, the web service endpoint communicates with the Enterprise Connector.

The Enterprise Connector in the figure represents both an ECBO Enterprise Connector and a JAX-RS Enterprise Connector. In a Sun GlassFish Mobility Platform installation, both an ECBO Enterprise Connector and a JAX-RS Enterprise Connector are deployed by default. In this figure, the client application on the mobile device does the following:

• Uses the MCBO API to synchronize data with the ECBO Enterprise Connector

• Uses the JerseyME API to communicate with the JAX-RS Enterprise Connector to retrieve dynamic data, separate from the synchronized data

Figure 1–2 An Enterprise Connector in a Two-tier Sun GlassFish Mobility Platform Installation

You can deploy an ECBO Enterprise Connector in either a single-tier or a two-tier Sun GlassFish Mobility Platform installation. In order to use an ECBO Enterprise Connector remotely, however, you must deploy it in a two-tier installation, because remote use of an ECBO Enterprise Connector requires the Web Services Connector endpoint to communicate between the Gateway and the remote Enterprise Connector.

To configure your deployed Enterprise Connector, use the Sun GlassFish Mobility Platform Administration Console. For details, see Deploying and Configuring an ECBO Enterprise Connector.