test

Sun GlassFish Mobility Platform 1.1 Developer's Guide for Enterprise Connectors

Chapter 1 Introduction to Enterprise Connectors

To provide an interface between data on mobile client devices and data stored in a database or an EIS/EAI system, you create an Enterprise Connector. The Enterprise Connector can be implemented in either of the following ways:

In conjunction with a client application developed using the Mobile Client Business Object API (MCBO) and, optionally, the JerseyME API, the Enterprise Connector provides a complete solution that allows you to synchronize arbitrary enterprise data between a client device and a database or EIS system, using a Sun GlassFish Mobility Platform Gateway Engine (the Gateway) deployed on the Sun GlassFish Enterprise Server that acts as an intermediary. The Gateway determines what objects need to be synchronized, while the Enterprise Connector implements the operations required to keep the client and the back-end system in sync.

You can use an Enterprise Connector in many ways, including the following:

This chapter covers the following topics:

Developing Connectors Using the Java API for RESTful Web Services (JAX-RS)

You can create Enterprise Connectors that use the Java API for RESTful Web Services (JAX-RS). A JAX-RS Enterprise Connector is a web application that consists of classes that are packaged as a servlet in a WAR file along with required libraries.

Two classes in the Enterprise Connector use the container-item design pattern to define the resource classes required by JAX-RS. These resource classes include the methods needed to perform Create, Retrieve, Update, and Delete (CRUD) operations on the business objects.

One or more classes in the Enterprise Connector may define the business object or objects, which are the data to be synchronized. The way in which these arbitrary Java objects are serialized is open-ended and is part of the contract between an Enterprise Connector and its corresponding Java ME client. Because the client usually uses the MCBO API, the definition of the business objects is usually similar to that of the client business objects. It is recommended that you use a format that supports data versioning.

The Enterprise Connector may contain additional utility classes.

You can use NetBeans IDE to develop a JAX-RS Enterprise Connector. For details about developing JAX-RS Enterprise Connectors, see Chapter 2, Creating an Enterprise Connector Using the Java API for RESTful Web Services (JAX-RS).

Packaging and Deploying JAX-RS Enterprise Connectors

To package an Enterprise Connector that uses the JAX-RS API, compile the Java classes and include them in a WAR file.

To see how the sample JAX-RS 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 Sun GlassFish Mobility Platform was unzipped:

musicdb-ws.war

salesforce-ws.war

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 JAX-RS Enterprise Connectors.

Figure 1–1 shows the location of a JAX-RS Enterprise Connector in a single-tier installation. The client communicates with the Gateway tier in two different ways: it can use the MCBO API to communicate with the Gateway, or it can use the JerseyME API to communicate directly with the Enterprise Connector using the JAX-RS API. The Gateway communicates with the Enterprise Connector using the JAX-RS API. The Enterprise Connector in turn communicates with a back-end system using an appropriate application protocol.

Figure 1–1 A JAX-RS Enterprise Connector in a Single-tier Sun GlassFish Mobility Platform Installation

A JAX-RS Enterprise Connector in a Single-tier Sun GlassFish Mobility Platform Deployment

In addition, if the back-end system has a RESTful interface, the client can use the JerseyME API to communicate directly with the back-end system.

You can use a JAX-RS Enterprise Connector in either a single-tier or a two-tier Sun GlassFish Mobility Platform installation. You do not need to use a two-tier installation, however, in order to use a JAX-RS Enterprise Connector remotely. You can deploy the Enterprise Connector on a different system from the one where the Gateway is installed, and then configure the Gateway to point to the URL of the system where the Enterprise Connector is deployed.

To configure your deployed Enterprise Connector, use the Sun GlassFish Enterprise Server Administration Console and the Sun GlassFish Mobility Platform Administration Console. For details, see Building, Deploying, and Configuring a JAX-RS Enterprise Connector.

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:

ds-jcr-musicdb.rar

ds-jcr-siebel-eway.rar

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:

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

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.

Deciding Which Kind of Enterprise Connector to Use

Consider the following issues in deciding to develop a JAX-RS or an ECBO Enterprise Connector:

Ease of Use

The JAX-RS API is somewhat easier to use than the ECBO API, particularly if you are already familiar with the JAX-RS API. The ECBO API was developed specifically for data synchronization, while the JAX-RS API has many other uses.

Deployment Flexibility

The JAX-RS API provides more flexibility in how you deploy an Enterprise Connector.

If you install Sun GlassFish Mobility Platform and you decide to use the ECBO API, you must remain with your original installation, whether it is a single-tier or a two-tier installation. If you use the ECBO API in a two-tier installation, communication between the Gateway on the first tier and the Enterprise Connector on the second tier requires the Web Services Connector endpoint that is installed as part of the two-tier installation. If you use the ECBO API in a single-tier installation, the Gateway and the Enterprise Connector communicate directly using ECBO API calls.

If you decide to use the JAX-RS API for your Enterprise Connector, however, you gain some flexibility in how you deploy your Enterprise Connector. A JAX-RS Enterprise Connector does not use the Web Services Connector endpoint. Instead, communication between the Gateway and the Enterprise Connector takes place over HTTP/S. This means that you can deploy the Enterprise Connector (and a Sun JCA Adapter, if it uses one) on any system with a GlassFish installation. If you used a single-tier installation, you can deploy the Enterprise Connector locally (on the same system where you installed the Gateway) or remotely (on a different system from the one where you installed the Gateway).

It is easier to develop a JAX-RS Enterprise Connector initially, because you can easily redeploy the Enterprise Connector on the fly, without having to restart the server. Redeploying an ECBO Enterprise Connector, on the other hand, usually requires you to restart the domain when you deploy a new version.

Performance with Local or Remote Deployment

In most cases, an ECBO Enterprise Connector deployed locally (on the same system as the Gateway) will have better performance than a JAX-RS Enterprise Connector deployed locally, because the JAX-RS Enterprise Connector must communicate over HTTP even when it is installed locally.

In most cases, a JAX-RS Enterprise Connector deployed remotely (on a different system from the Gateway) will have better performance than an ECBO Enterprise Connector deployed remotely.