test

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

Using the Mobile Client Business Object API in a Java ME Application

A client application on a mobile device consists primarily of a Java ME MIDlet. The MIDlet implements the Graphical User Interface (GUI) for the application and also calls Mobile Client Business Object (MCBO) API methods to synchronize the BusinessObject data.

This section describes how to use the MCBO API in a MIDlet. It assumes that you are already familiar with the Java ME API. It does not describe how to create a Graphical User Interface (GUI) to display business objects and allow users to create or modify them. A good tool for creating a MIDlet is the NetBeans IDE with the Mobility Pack; for details, visit the NetBeans web site.

In the Secure MusicDB sample code, the SecureJdbcMIDlet.java file contains Java ME code and MCBO API code. The Java ME code creates the user interface that allows users to create, edit, and delete business objects. The MCBO API code stores and retrieves business object data on the client device and synchronizes client-side modifications with the data on the back end.

Typically, a MIDlet begins by importing the MCBO API and JerseyMe packages in addition to the Java ME packages: 

import com.sun.mep.client.api.*;
import com.sun.jerseyme.api.client.Client;
import com.sun.jerseyme.api.client.WebResource;

A MIDlet uses the API to perform the following tasks:

Creating DefaultSecurityManager, SyncManager, and BusinessObjectStorage Objects

The first task for the Sun GlassFish Mobility Platform client code is to create the objects needed for synchronization and data manipulation:

You may also want to enable logging for debugging purposes by calling the SyncManager.enableLogging method. If logging is enabled, logging messages for the client code are written both to standard output and to a file on the device named meplog.txt.

You commonly perform these operations within a thread, as follows:

Thread t = new Thread(new Runnable() {
    public void run() {
        securityMgr = new DefaultSecurityManager("musicdb");
        securityMgr.setMaxValidationAttempts(3);
        syncMgr = new SyncManager(".alb", securityMgr);
        syncMgr.enableLogging(true);
        boStorage = syncMgr.getBusinessObjectStorage();
    }
});
t.run();

This code first instantiates a security manager and sets the maximum allowed number of validation attempts. If this maximum is exceeded, all Sun GlassFish Mobility Platform records on the device are erased. See Data Destruction for details.

The code then uses the form of the SyncManager constructor that takes two arguments, the file extension used for the business object and the security manager. In this case, the extension is the string ".alb", as specified by the getExtension method of the Album class. The code also turns on logging.

Once you enable security by specifying an implementation of SecurityManager in the SyncManager constructor, all of the data stored locally on the device will be encrypted and decrypted automatically. There are no further requirements on the client application to explicitly perform encryption or decryption of the data.

The code then calls the SyncManager.getBusinessObjectStorage factory method to instantiate the BusinessObjectStorage object. This object provides storage for Album objects on the mobile device's file system.

Establishing Login Credentials

To provide application-level authentication, a secure client application must use the security manager to create login credentials for the user. The MIDlet code provides an initial login screen that requires the user to create both a secret and a Personal Identification Number (PIN). Users do not need to remember the secret, but they must remember the PIN.

The MIDlet code calls the security manager's computeKey and setKey methods to create a key from the PIN entered by the user. It then calls the security manager's storeCredentials method to create credentials based on the secret.

byte[] key = securityMgr.computeKey(getInitialPinField().getString());
securityMgr.setKey(key);
securityMgr.storeCredentials(getSecretField().getString());

The getInitialPinField and getSecretField methods are UI methods that obtain the needed string values.

The secret and PIN provide security in addition to the username and password credentials required by the gateway in order to perform synchronization (as described in Setting User Credentials).

Working with Business Objects on the File System

The MIDlet code typically allows users to create new objects and to edit or delete existing objects in disconnected mode, using the mobile device's file system without being connected to a server. The code commonly uses a combination of BusinessObject and BusinessObjectStorage methods to perform the following tasks:

Typically, a user on a client device performs a number of operations on the client device in disconnected mode, then logs in to the server and synchronizes the data.

Retrieving Objects for Editing

To allow users to view existing objects, the code commonly displays a list of names returned by the BusinessObjectStorage.listBusinessObjectNames method. This method retrieves a list of the names of all the business objects that have the file extension specified by the SyncManager constructor method. For example, the SecureJdbcMIDlet code calls the following method before populating a form with a list of albums:

Vector v = boStorage.listBusinessObjectNames();

To display a selected album, the SecureJdbcMIDlet code instantiates an Album object, using a name argument that represents the filename stripped of its ".alb" extension. The code then calls the BusinessObjectStorage.readBusinessObject method to read the data for the selected album from the file system into the Album object.

Album a = new Album(selectedAlbum.substring(0, selectedAlbum.length()-4));
boStorage.readBusinessObject(a);

The SecureJdbcMIDlet code then calls the getter methods for Album objects to retrieve the selected album's property values and display them in a form for editing.

Deleting Objects

To allow users to delete a selected album, the SecureJdbcMIDlet code calls the BusinessObjectStorage.deleteBusinessObject method with a String argument, the name of the album:

boStorage.deleteBusinessObject(selectedAlbum);

Saving Objects

To save a newly created or edited album, the SecureJdbcMIDlet code calls its saveAlbum method. This method instantiates an Album object and then calls the methods that set the album's properties, using Java ME GUI code to retrieve the values. Finally, the saveAlbum method calls the BusinessObjectStorage.writeBusinessObject method to save the album to the file system:

Album a = new Album();
...
boStorage.writeBusinessObject(a);

Synchronizing Data with the Server

Once users have created or modified objects on the client using BusinessObjectStorage methods, they can use SyncManager methods to synchronize the modified data with the server. Synchronization includes the following tasks:

Setting User Credentials

The gateway requires username/password authentication for secure access. Before performing a synchronization, the MIDlet must call the SyncManager.setCredentials method, which takes three arguments: the username, the password, and the HTTP/S URL of the gateway. In SecureJdbcMIDlet.java, the arguments are supplied by three GUI methods, as follows:

syncMgr.setCredentials(
        getUserName().getString(),
        getPassword().getString(),
        getSyncServer().getString());

These methods obtain input from the user and return TextField values.

The initial creation of users is a Sun GlassFish Mobility Platform administrative task, described in the Sun GlassFish Mobility Platform 1.1 Administration Guide

Performing Synchronization

Once user credentials are established, synchronization can take place. The SecureJdbcMIDlet code calls the SyncManager.sync method, which takes a SyncType argument. In this case, the code calls a method that returns a SyncType value:

syncMgr.sync(getSelectedSyncType());

The getSelectedSyncType method in turn uses the value returned by a GUI method, getSyncType.

Retrieving Synchronization Results

After a successful synchronization, you can retrieve and display information about the synchronization results. The SecureJdbcMIDlet code retrieves the results using the SyncManager.getSyncResults method, which returns a SyncResults value:

SyncResults results = syncMgr.getSyncResults();

It then displays the results in a GUI form by calling SyncResults methods. These methods can return either the number of items changed or a list of the actual business objects that were changed. The SecureJdbcMIDlet code displays only the number of items changed.