Chapter 4 Classes and Methods in the Mobile Client Business Object API Package
The Mobile Client Business Object (MCBO) API contains one package, com.sun.mep.client.api, that developers must use. This chapter summarizes the classes and methods contained within this package.
The API documentation is included in the MEP client bundle. In the directory where you unzipped the client bundle (see the Sun Java System Mobile Enterprise Platform 1.0 Installation Guide for details), it is in the directory sjsmep_client_library-1_0_02-fcs/doc/mcbo/api.
The BusinessObject Class
Table 4–1 lists the constructors and methods belonging to the BusinessObject class. This class is the base type for objects that will be synchronized with the Gateway Engine. Each business object instance is identified by a name, which is also used to name the file holding the serialized form of the object on the device's filesystem. You can create a BusinessObject from scratch by instantiating a concrete subclass, or you can create an empty BusinessObject and deserialize the contents of a byte array into it. Use the latter technique when implementing the deserialize method.
Table 4–1 Class com.sun.mep.client.api.BusinessObject|
Method |
Description |
|---|---|
|
BusinessObject() |
No-argument constructor. |
|
BusinessObject(java.lang.String name) |
Constructor that takes the name of the object as an argument. |
|
public abstract void deserialize(byte[] data) |
Deserializes the supplied byte array into this empty BusinessObject. |
|
public abstract java.lang.String getExtension() |
Returns the default extension for business objects of this type. Extensions are used by the files holding these objects and must be part of the contract with the Enterprise Connectors. That is, clients and Enterprise Connectors must use the same extension for the same type of business object. Concrete subclasses should redefine this method. |
|
public java.lang.String getName() |
Returns the name of this BusinessObject. |
|
public abstract byte[] serialize() |
Serializes this BusinessObject into a byte array. |
|
public void setName(java.lang.String name) |
Sets the name of this BusinessObject. This method may only be called once, to initialize a new BusinessObject being deserialized. You may not change the name once it has been set. The name must be a unique identifier that can legally be used as a file name. |
The BusinessObjectStorage Class
Table 4–2 lists the methods belonging to the BusinessObjectStorage class. This class manages the storage and retrieval of BusinessObject instances in their serialized form on the device's filesystem. The factory method used to get an instance of this class is SyncManager.getBusinessObjectStorage.
Table 4–2 Class com.sun.mep.client.api.BusinessObjectStorage|
Method |
Description |
|---|---|
|
public boolean deleteAllBusinessObjects() |
Deletes all of the business objects from the device's file system. Returns true if the operation succeeded, false otherwise. |
|
public void deleteBusinessObject(java.lang.String name) |
Deletes the serialized form of the BusinessObject with the specified file name. |
|
public void deleteBusinessObject(BusinessObject obj) |
Convenience method equivalent to deleteBusinessObject(obj.getName() + extension). |
|
public java.util.Vector listBusinessObjectNames() |
Returns a list of file names for all of the serialized BusinessObject instances that match the extension. |
|
public void readBusinessObject(BusinessObject result) |
Reads a serialized BusinessObject from the device's filesystem and returns the result by reference in the result parameter. |
|
public void writeBusinessObject(BusinessObject obj) |
Writes the serialized form of the specified BusinessObject to the device's filesystem, possibly replacing any existing data. |
The DefaultSecurityManager Class
Table 4–3 lists the methods belonging to the DefaultSecurityManagerclass. This class provides a basic implementation of SecurityManager (see Table 4–5).
128–bit security keys are generated from the pin using MD5 digest. The key is used to reverse a basic pin derivatives algorithm for client authentication. It is also used as the symmetric key for Triple-DES encryption of data at rest on the device.
Table 4–3 Class com.sun.mep.client.api.DefaultSecurityManager|
Method |
Description |
|---|---|
|
public DefaultSecurityManager() |
No-argument constructor. |
|
public final byte[] computeKey(java.lang.String pin) |
Takes an arbitrary-length clear-text pin entered by the user and creates a fixed-length digest suitable for use by the encrypt and decrypt methods. |
|
public static final byte[] computeMD5Digest(byte[] dataBytes) |
Computes and returns an MD5 hash of the specified byte[]. |
|
public static final byte[] computeMD5Digest(java.lang.String data) |
Computes and returns an MD5 hash of the specified string. |
|
public final byte[] decrypt(byte[] cipherText) |
Callback handler to perform decryption of data on device. The MEP runtime will invoke this method whenever it is necessary to decrypt data. |
|
public final byte[] encrypt(byte[] plainText) |
Callback handler to perform encryption of data on device. The MEP runtime will invoke this method whenever it is necessary to encrypt data. |
|
public final byte[] getKey() |
Returns the encryption key computed by computeKey(String). |
|
public final int getValidationAttempts() |
Returns the number of validation attempts. |
|
public final boolean isPinSet() |
Returns true if the user has never logged into the application. Use this method to determine when the credentials need to be stored on the device. |
|
public void setKey(byte[] key) |
Sets the key on the SecurityManager so it can be used during callbacks to encrypt or decrypt data on the device. |
|
public final void storeCredentials(java.lang.String secret) |
Persists derivatives of the pin/key and the supplied secret on the device. These derivatives are used upon subsequent logins to validate the pin. The secret can be any non-null, non-zero length alphanumeric string. Typically, the application developer would prompt the user to enter a random sequence of key presses on the device and pass that value into this method. This is a single-use value, so the user does not need to remember it. This method should only be called once, when the user needs to set their pin number (if isFirstLogin() returns true). |
|
public final boolean validatePin(java.lang.String pin) |
Determines if the pin is able to recompute the derivatives stored on the device in storeCredentials(byte[], String). If so, it returns true; otherwise, it returns false. This method also keeps track of how many times it has been invoked. If it exceeds the maximum number of allowed attempts (getMaxValidationAttempts()), a SecurityException is thrown. |
The EncodingType Class
Table 4–4 lists the fields and the one method belonging to the EncodingType class. This class provides a simple enum for OMA DS encoding types. These values can be used to specify either simple XML encoding or WBXML encoding during synchronizations with the Gateway Engine.
The WBXML encoding is a binary WAP encoding standard developed by the Open Mobile Alliance (OMA) for compressing the OMA DS payloads in order to reduce bandwidth usage on mobile devices.
Table 4–4 Class com.sun.mep.client.api.EncodingType|
Field/Method |
Description |
|---|---|
|
public static final EncodingType WBXML |
WBXML encoding. |
|
public static final EncodingType XML |
Simple XML encoding. |
|
public java.lang.String getValue() |
Returns the value of the current encoding type. |
The SecurityManager Class
Table 4–5 lists the constructors and methods belonging to the SecurityManager class. This class manages all of the client-side security features. A default implementation is provided (DefaultSecurityManager), but you are free to supply your own implementation.
Security features include the following:
- Authentication
-
A simple form of pin-based authentication is provided. The isPinSet() method determines if the user of the application has set a pin yet. If not, you will need to prompt the user to enter a “secret”, which is just a long random alphanumeric string, and a pin, which is also an alphanumeric string. You must compute a security key from the pin using computeKey(String) and then set the key on the SecurityManager with setKey(byte[]). You then persist the user credentials using the storeCredentials(String) method. This method computes a hash of the unencrypted secret and stores this value along with the secret encrypted with the key into the device's RMS record store.
If the user has already set their pin, use the validatePin(String) method to determine if the pin is valid. This method computes an encryption key from the supplied pin and reverses the encryption and hash calculation on the encrypted secret stored in RMS. If the hash calculations match, the pin is valid.
The SecurityManager also keeps track of pin validation attempts (that is, how many times the MIDlet calls validatePin(String)). If the MIDlet exceeds the maximum number of attempts (getMaxValidationAttempts()), a SecurityException is thrown. The number of pin validation attempts is stored in RMS so they can be tracked across restarts of the MIDlet.
- Encryption
-
The encrypt(byte[]) and decrypt(byte[]) methods are callbacks used by the MEP synchronization library to perform encryption and decryption of the business objects as they are read from and written to the device file system. If security is enabled, the data is never written to the device in clear text.
- Data Fading
-
You can specify a maximum “quiet period” between successful synchronizations by using setMaxQuietPeriod(long). Using the getRemainingQuietTime(SyncManager) method, you can determine how much time is left before the quiet period expires. Based on this information, you could choose to destroy all of the business objects on the device.
- Data Destruction
-
In certain circumstances, you may choose to destroy all of the business objects stored on the device. For example, if the MIDlet has failed pin validation too many times, or if the quiet period has expired since the last sync. To destroy the data, call the destroyBusinessObjects(SyncManager) method for each type of business object you wish to destroy.
|
Method |
Description |
|---|---|
|
public SecurityManager() |
No-argument constructor. |
|
public abstract byte[] computeKey(java.lang.String pin) |
Computes an encryption key from the pin. There are no restrictions on the length of the pin or the key. It is up to the implementing class to produce the appropriate length key for the encryption algorithm being used. Calling this method will also set the key value so it can be retrieved using getKey(). |
|
public abstract byte[] decrypt(byte[] cipherText) |
Callback handler to perform decryption of data on device. The MEP runtime will invoke this method whenever it is necessary to decrypt data. |
|
public final boolean destroyBusinessObjects(SyncManager mgr) |
Activates data destruction on business objects managed by the specified SyncManager. All business objects managed by the specified SyncManager will be deleted from the device. |
|
public abstract byte[] encrypt(byte[] plainText) |
Callback handler to perform encryption of data on device. The MEP runtime will invoke this method whenever it is necessary to encrypt data. |
|
public abstract byte[] getKey() |
Returns the value of the key computed by computeKey(String). |
|
public final long getMaxQuietPeriod() |
Returns the maximum allowable quiet time. |
|
public final int getMaxValidationAttempts() |
Returns the maximum allowable validation attempts. |
|
public final long getRemainingQuietTime(SyncManager mgr) |
Returns the time remaining (in milliseconds) before the quiet period expires. If there is no specified quiet period (that is, if the value returned by getMaxQuietPeriod() is less than zero), this method returns a negative value. Otherwise, it returns the time remaining in milliseconds, or zero if the quiet period has been exceeded. If a sync has not been attempted yet, it returns getMaxQuietPeriod(). |
|
public abstract int getValidationAttempts() |
Returns the number of validation attempts. |
|
public abstract boolean isPinSet() |
Returns true if the user has never logged into the application. Use this method to determine when the credentials need to be stored on the device. |
|
public abstract void setKey(byte[] key) |
Sets the key on the SecurityManager so it can be used during callbacks to encrypt or decrypt data on the device. |
|
public final void setMaxQuietPeriod(long period) |
Sets the maximum allowable quiet time (in milliseconds) between sync requests. If the device has been quiet for too long, the application will be prevented from performing the sync. Additionally, the application can decide to perform data destruction by calling destroyBusinessObjects(SyncManager). Passing a negative value indicates that there should be no timeout. |
|
public final void setMaxValidationAttempts(int attempts) |
Sets the maximum allowable validation attempts. When the number of pin validation attempts exceeds this value, the application can decide to lock out the user and perform data destruction by calling destroyBusinessObjects(SyncManager). The default value is 10 validation attempts. An argument of 0 (zero) indicates that there is no maximum number of validation attempts. |
|
public abstract void storeCredentials(java.lang.String secret) |
Persists derivatives of the pin/key and the supplied secret on the device. These derivatives are used upon subsequent logins to validate the pin. The secret can be any non-null, non-zero length alphanumeric string. Typically, the application developer would prompt the user to enter a random sequence of key presses on the device and pass that value into this method. This is a single-use value, so the user does not need to remember it. This method should only be called once when the user needs to set their pin number (if isFirstLogin() returns true). |
|
public abstract boolean validatePin(java.lang.String pin) |
Determines if the pin is able to recompute the derivatives stored on the device in storeCredentials(byte[], String). If so, it returns true; otherwise, it returns false. This method also keeps track of how many times it has been invoked. If it exceeds the maximum number of allowed attempts (getMaxValidationAttempts()), then a SecurityException is thrown. |
The SMSMessageHandler Class
Table 4–6 lists the constructor and methods belonging to the SMSMessageHandler class. This class is a callback handler for SMS push notification messages sent from the Gateway Engine.
Table 4–6 Class com.sun.mep.client.api.SMSMessageHandler|
Method |
Description |
|---|---|
|
public SMSMessageHandler() |
No-argument constructor. |
|
public abstract void handlePoisonPill() |
Callback to allow client applications to respond to an SMS push poison pill request. Applications should immediately perform data destruction upon receiving this instruction. |
|
public abstract void handleSync(SyncType type) |
Callback to allow client applications to respond to an SMS push sync request. Applications should initiate a synchronization session of the requested type. |
|
public void processSMSMessagePayload(byte[] rawPayload, java.lang.String pin) |
Process the payload of the incoming SMS message and dispatch the instruction to the proper callback method (handlePoisonPill() or handleSync(com.sun.mep.client.api.SyncType)). The application's implementation of javax.messaging.MessageListener must call this method in order to decrypt and dispatch the instruction sent from the Gateway Engine. Make sure that this method is not invoked within the same thread that is delivering the SMS message. This method only supports processing SMS messages with text payloads. There is no support for binary SMS messages. If a pin is supplied, this method processes the payload as if it were encrypted. Otherwise, it is processed as clear text. |
The SyncException Class
Table 4–7 lists the constructors and methods belonging to the SyncException class. This class is a checked exception type that indicates an error during synchronization.
Table 4–7 Class com.sun.mep.client.api.SyncException|
Method |
Description |
|---|---|
|
public SyncException(java.lang.String pMessage) |
Constructor that takes a String argument. |
|
public SyncException(java.lang.Throwable pLinkedException) |
Constructor that takes a linked exception argument. |
|
public SyncException(java.lang.String pMessage, java.lang.Throwable pLinkedException) |
Constructor that takes both a String and a linked exception as arguments. |
|
public java.lang.Throwable getLinkedException() |
Retrieves the linked exception for this exception. |
|
public void printStackTrace() |
Prints a stack trace for this exception to the standard error stream. |
|
public void setLinkedException(java.lang.Throwable pLinkedException) |
Sets the linked exception for this exception. |
The SyncManager Class
Table 4–8 lists the constructors and methods belonging to the SyncManager class. This class is responsible for managing synchronizations with the Gateway Engine for a particular kind of BusinessObject (classified by a particular extension). There is a one-to-one mapping between SyncManager and kinds of BusinessObject instances. If you have an application that deals with two different BusinessObject types, then you would have an instance of SyncManager for each type.
You must specify a unique extension for your BusinessObject when you construct this class. The name field in the BusinessObject, combined with the extension, will determine the entire name of the file on the device's filesystem. For example, you might pass the string ".act" for account or ".ord" for orders, but it can be anything legally allowed in a file name.
You may optionally specify a simple alphanumeric pin which will be used to encrypt any data stored locally on the device.
When you invoke the sync(SyncType) method, this will initiate a synchronization session with the Gateway Engine. During this session, only BusinessObject instances whose extension fields match will be synchronized.
Table 4–8 Class com.sun.mep.client.api.SyncManager|
Method |
Description |
|---|---|
|
public SyncManager(java.lang.String extension) |
Constructor that creates a new SyncManager for the specified business object type (extension) with no SecurityManager. This method is the equivalent of calling new SyncManager(extension, null). |
|
public SyncManager(java.lang.String extension, SecurityManager sm) |
Constructor that creates a new SyncManager for the specified business object type (extension) and uses the specified SecurityManager. |
|
public void enableLogging(boolean value) |
Enables or disables debug logging in the MEP client APIs. If enabled, the MEP implementation library writes logging information to stdout and also to a log file (named meplog.txt) on the device. Logging is disabled by default. |
|
public BusinessObjectStorage getBusinessObjectStorage() |
Returns the BusinessObjectStorage manager associated with this SyncManager. There is a strict 1:1 relationship between SyncManager and BusinessObjectStorage. |
|
public EncodingType getEncoding() |
Returns the current transport encoding type. |
|
public java.lang.String getExtension() |
Returns the extension type associated with this SyncManager. |
|
public static final SecurityManager getSecurityManager() |
Returns a reference to the security manager, or null if one has not been set. |
|
public SyncResults getSyncResults() |
Returns the sync results for the latest successful sync. |
|
public long getTimeOfLastSync() |
Returns a time stamp of the last successful sync. This time stamp is recorded by calling System.currentTimeMillis(), so it is an offset from January 1, 1970 UTC. If a sync has not been performed yet, the method returns a negative value. |
|
public void setCredentials(java.lang.String username, java.lang.String password, java.lang.String url) |
Sets the credentials used during the synchronization process. |
|
public void setEncoding(EncodingType encoding) |
Sets the transport encoding type. |
|
public void sync(SyncType syncType) |
Performs the specified type of synchronization. |
The SyncResults Class
Table 4–9 lists the methods belonging to the SyncResults class. This class contains coarse-grained statistics about the most recent synchronization (additions, deletions, and modifications).
Table 4–9 Class com.sun.mep.client.api.SyncResults|
Method |
Description |
|---|---|
|
public int getClientAdditions() |
Returns the number of records added on the client and sent to the server. |
|
public int getClientDeletions() |
Returns the number of records deleted on the client and sent to the server. |
|
public int getClientUpdates() |
Returns the number of records updated on the client and sent to the server. |
|
public int getServerAdditions() |
Returns the number of records added on the server and sent to the client. |
|
public int getServerDeletions() |
Returns the number of records deleted on the server and sent to the client. |
|
public int getServerUpdates() |
Returns the number of records updated on the server and sent to the client. |
The SyncType Class
Table 4–10 lists the fields and methods belonging to the SyncType class. This class provides a simple enum for the available synchronization types.
Table 4–10 Class com.sun.mep.client.api.SyncType|
Field/Method |
Description |
|---|---|
|
public static final SyncType BACKUP_SYNC |
Refresh sync from client. All of the server data is replaced with the client data. Use with caution. |
|
public static final int BACKUP_SYNC_VALUE |
Constant enum value for BACKUP_SYNC. |
|
public static final SyncType FAST_SYNC |
Two-way fast sync. Client modifications since the last synchronization are sent to the server for reconciliation, and server modifications since the last synchronization are sent back to the client. |
|
public static final int FAST_SYNC_VALUE |
Constant enum value for FAST_SYNC. |
|
public static final SyncType ONE_WAY_CLIENT_SYNC |
One-way sync from client. Client modifications are sent to the server, but server modifications are not sent back to the client. |
|
public static final int ONE_WAY_CLIENT_SYNC_VALUE |
Constant enum value for ONE_WAY_CLIENT_SYNC. |
|
public static final SyncType ONE_WAY_SERVER_SYNC |
One-way sync from server. Server modifications are sent to the client, but client modifications are not sent to the server. |
|
public static final int ONE_WAY_SERVER_SYNC_VALUE |
Constant enum value for ONE_WAY_SERVER_SYNC. |
|
public static final SyncType RESTORE_SYNC |
Refresh sync from server. All of the client data is replaced with the server data. |
|
public static final int RESTORE_SYNC_VALUE |
Constant enum value for RESTORE_SYNC. |
|
public static final SyncType SLOW_SYNC |
Two-way slow sync. This is the same as a fast sync except that ALL client data (including unmodified records) is sent to the server for reconciliation. |
|
public static final int SLOW_SYNC_VALUE |
Constant enum value for SLOW_SYNC. |
|
public java.lang.String getDescription() |
Returns a description of the current SyncType. |
|
public int getValue() |
Returns the value of the current SyncType. |
- © 2010, Oracle Corporation and/or its affiliates