Sun GlassFish Mobility Platform 1.1 Developer's Guide for Client Applications

Chapter 1 Introduction to the Sun GlassFish Mobility Platform Client APIs

Sun GlassFish Mobility Platform provides two client libraries that you can use to develop client applications

A Java Platform, Mobile Edition (Java ME) data synchronization library, called the Mobile Client Business Object (MCBO) API. This library, in conjunction with either the Enterprise Connector Business Object (ECBO) API or the Java API for RESTful Web Services (JAX-RS) API, provides a complete solution that allows you to synchronize arbitrary enterprise data. Although the MCBO and ECBO APIs are based on Open Mobile Alliance Data Synchronization (OMA DS), you do not need to know specifics of OMA DS in order to use the APIs.
A client API called the JerseyMe library, which allows a client application to access RESTful web services using Java ME. It is modelled after Jersey's client API for Java SE.

You must be connected to a server in order to synchronize data with the server. However, you can use the MCBO library in disconnected mode; that is, you can add, delete, and modify client data without being connected to a server.

This chapter covers the following topics:

About the Mobile Client Business Object (MCBO) API

The Mobile Client Business Object (MCBO) API provides a simple set of APIs to build Java ME client applications that can synchronize business data with databases or ERP/EAI systems. To provide this synchronization capability, the APIs use an implementation of the Open Mobile Alliance Data Synchronization (OMA DS) protocols known as SyncML. Even if you have no knowledge of SyncML, you can use the MCBO API to build Java ME client applications with SyncML capabilities on Java ME devices. These client applications can synchronize their local data with a Sun GlassFish Mobility Platform server, which in turn communicates with a database or ERP/EAI system. The MCBO API can establish connections to any server that conforms to the OMA DS standard.

The MCBO API provides the ability to synchronize business objects in the form of arbitrary user-defined data types.

The MCBO API allows you to synchronize any objects that can be represented as a byte array, including arbitrary data types and data collections. Examples include:

Databases
Binary data, such as images
Nodes belonging to hierarchical/tree data structures (for example, registry entries)

The MCBO API offers the following benefits:

It provides a very simple framework for data synchronization of business objects
It keeps the resulting application jar files small
Client device memory requirements are low (the maximum size of the heap is kept low)

Synchronization Types

The MCBO API supports the following types of client-initiated synchronizations:

Both from server to client and from client to server:
- Two-way sync (fast sync)
  
  Two-way sync, also called fast sync, is the normal synchronization mode, in which the client and the server exchange modifications to the data that they have stored. An initial slow sync is used to populate the data on the client.
  
  For details, see Two-way Sync (Fast Sync) in Sun GlassFish Mobility Platform 1.1 Architectural Overview.
- Slow sync
  
  The slow sync is similar to two-way sync, except that all the items in the client databases are compared with all the items in the server databases. A slow sync is typically the first synchronization to be performed; it can also be requested if the client and server data is mismatched or if the client or server loses its information. A slow sync is similar to a full backup, while a fast sync is similar to an incremental backup. The slow sync behaves as if no previous sync has been done, so items deleted from the client are not deleted from the server.
  
  For details, see Slow Sync in Sun GlassFish Mobility Platform 1.1 Architectural Overview
From client to server only:
- One-way sync from client
  
  This is one half of a two-way sync. In this mode, the client sends modifications of its data store to the server. The server updates its data store appropriately but does not send modifications of its data store to the client. After a one-way sync, the data on the client and server may not be the same.
- Refresh sync from client
  
  In this mode, the client exports all its data to the server. The server is expected to replace all its data with the data sent by the client.
  
  Note –
  Use this synchronization type with caution.
From server to client only:
- One-way sync from server
  
  This is the other half of a two-way sync. In this mode, the server sends modifications of its data store to the client. The client updates its data store appropriately but does not send modifications of its data store to the server. After a one-way sync, the data on the client and server may not be the same.
- Refresh sync from server
  
  In this mode, the server exports all its data from a database to the client. The client is expected to replace all its data with the data sent by the server.

Server-initiated synchronization is also possible. The server can initiate syncs by sending SMS messages to the client device.

Both the client and the server store information about changes to their respective data stores since the last successful synchronization. When the next synchronization is performed, the client and server negotiate how the changes are resolved and propagated according to the type of synchronization being performed.

Client Device Requirements

The client device must be a Java and GPRS/UMTS enabled device that supports the following specifications:

Mobile Information Device Profile (MIDP) 2.0

MIDP is a specification published for the use of Java on embedded devices such as cell phones and PDAs. MIDP is part of the Java ME framework. MIDP 2.0 was developed under the Java Community Process as JSR-118.
Either Connected Limited Device Configuration (CLDC) 1.1 or Connected Device Configuration (CDC) 1.1.2

CLDC is a specification of a framework for Java ME applications targeted at devices with very limited resources, such as pagers and mobile phones. CLDC 1.1 was developed under the Java Community Process as JSR-139.

CDC is a specification of a framework for Java ME applications targeted at devices with less limited resources, such as PDAs. CDC 1.1.2 was developed under the Java Community Process as JSR-218.
JSR-75, PDA Optional Packages for the Java ME Platform, for accessing mobile device filesystems

The size of the obfuscated jar file for the MCBO API is approximately 190 KB (it can vary depending upon the size of the application), so the burden of supporting this API is low even on devices that have limited memory. Client applications are bundled with a copy of the API as a single jar file.

Server-side Requirements

On the server side, the MCBO API needs a standard-conforming OMA DS server. The Sun GlassFish Mobility Platform gateway installed on Sun GlassFish Enterprise Server is such a server.