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.
Table 4–5 Class
com.sun.mep.client.api.SecurityManager
|
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.
|
Télécharger cet ouvrage au format PDF (680 Ko)