|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.rms.RecordStore
A class representing a record store. A record store consists of a collection of records which will remain persistent across multiple invocations of the MIDlet. The platform is responsible for making its best effort to maintain the integrity of the MIDlet's record stores throughout the normal use of the platform, including reboots, battery changes, etc.
Record stores are created in platform-dependent locations, which are not exposed to the MIDlets. The naming space for record stores is controlled at the MIDlet suite granularity. MIDlets within a MIDlet suite are allowed to create multiple record stores, as long as they are each given different names. When a MIDlet suite is removed from a platform install record stores associated with its MIDlets will also be removed. These APIs only allow the manipulation of the MIDlet suite's own record stores, and do not provide any mechanism for record sharing between MIDlets in different MIDlet suites. MIDlets within a MIDlet suite can access each other's record stores directly.
Record store names are case sensitive and may consist of any combinations of up to 32 unicode characters. Record store names must be unique within the scope of a given MIDlet suite. In other words, MIDlets within a MIDlet suite are not allowed to create more than one record store with the same name. However, a MIDlet is allowed to have a record store with the same name as a MIDlet in another MIDlet suite. In that case, the record stores are still distinct and separate.
No locking operations are provided in this API. Record store implementations ensure that all individual record store operations are atomic, synchronous, and serialized, so no corruption will occur with multiple accesses. However, if a MIDlet uses multiple threads to access a record store, it is the MIDlet's responsibility to coordinate this access or unintended consequences may result. Similarly, if a platform performs transparent synchronization of a record store, it is the platform's responsibility to enforce exclusive access to the record store between the MIDlet and synchronization engine.
Records are uniquely identified within a given record store by their
recordId, which is an integer value. This recordId is used as the
primary key for the records. The first record created in a record
store will have recordId equal to zero (0). Each subsequent
record added to a RecordStore will be assigned a recordId one greater
than the record added before it. That is, if two records are added
to a record store, and the first has a recordId of 'n', the next will
have a recordId of 'n + 1'. MIDlets can create other indices
by using the RecordEnumeration
class.
This record store uses long integers for time/date stamps, in the format used by System.currentTimeMillis(). The record store is time stamped with the last time it was modified. The record store also maintains a version, which is an integer that is incremented for each operation that modifies the contents of the RecordStore. These are useful for synchronization engines as well as other things. This document and the information contained in it are CONFIDENTIAL AND PROPRIETARY INFORMATION of Motorola, Inc. and shall not be used, published, disclosed, or disseminated outside of Motorola in whole or in part without Motorola's consent. This document contains trade secrets of Motorola. Reverse engineering of any or all of the information in this document in prohibited.
© Copyright 1999-2000 Motorola, Inc. All Rights Reserved. This notice does not imply publication
Method Summary | |
int |
addRecord(byte[] data,
int offset,
int numBytes)
Adds a new record to the record store. |
void |
addRecordListener(RecordListener listener)
Adds the specified RecordListener. |
void |
closeRecordStore()
This method is called when the MIDlet requests to have the record store closed. |
void |
deleteRecord(int recordId)
The record is deleted from the record store. |
static void |
deleteRecordStore(String recordStoreName)
Deletes the named record store. |
RecordEnumeration |
enumerateRecords(RecordFilter filter,
RecordComparator comparator,
boolean keepUpdated)
Returns an enumeration for traversing a set of records in the record store in an optionally specified order. |
long |
getLastModified()
Returns the last time the record store was modified, in the format used by System.currentTimeMillis(). |
String |
getName()
Returns the name of this RecordStore. |
int |
getNextRecordID()
Returns the recordId of the next record to be added to the record store. |
int |
getNumRecords()
Returns the number of records currently in the record store. |
byte[] |
getRecord(int recordId)
Returns the data stored in the given record. |
int |
getRecord(int recordId,
byte[] buffer,
int offset)
Returns the data stored in the given record. |
int |
getRecordSize(int recordId)
Returns the size (in bytes) of the MIDlet data available in the given record. |
int |
getSize()
Returns the size of the record store in bytes. |
int |
getSizeAvailable()
Returns the amount of additional room (in bytes) available for this record store to grow. |
int |
getVersion()
Each time a record store is modified (record added, modified, deleted), its version is incremented. |
static String[] |
listRecordStores()
Returns an array of the names of record stores owned by the MIDlet suite. |
static RecordStore |
openRecordStore(String recordStoreName,
boolean createIfNecessary)
Open (and possibly create) a record store associated with the given application. |
void |
removeRecordListener(RecordListener listener)
Removes the specified RecordListener. |
void |
setRecord(int recordId,
byte[] newData,
int offset,
int numBytes)
Sets the data in the given record to that passed in. |
Methods inherited from class java.lang.Object |
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Method Detail |
public static void deleteRecordStore(String recordStoreName) throws RecordStoreException, RecordStoreNotFoundException
recordStoreName
- The MIDlet suite-unique record store to delete.public static RecordStore openRecordStore(String recordStoreName, boolean createIfNecessary) throws RecordStoreException, RecordStoreFullException, RecordStoreNotFoundException
recordStoreName
- The MIDlet suite unique name, not to exceed 32
characterscreateIfNecessary
- If true, the record store will be created if
necessary.RecordStore
object for the record store, or
null if the record store could not be found.public void closeRecordStore() throws RecordStoreNotOpenException, RecordStoreException
When the record store is closed, all listeners are removed. If the MIDlet attempts to perform operations on the RecordStore object after it has been closed, the methods will throw a RecordStoreNotOpenException.
public static String[] listRecordStores()
public String getName() throws RecordStoreNotOpenException
public int getVersion() throws RecordStoreNotOpenException
public int getNumRecords() throws RecordStoreNotOpenException
public int getSize() throws RecordStoreNotOpenException
public int getSizeAvailable() throws RecordStoreNotOpenException
public long getLastModified() throws RecordStoreNotOpenException
public void addRecordListener(RecordListener listener)
listener
- the RecordChangedListener.public void removeRecordListener(RecordListener listener)
listener
- the RecordChangedListener.public int getNextRecordID() throws RecordStoreNotOpenException, RecordStoreException
addRecord()
. Also note that you cannot assume
the exact sequencing of recordId's. Each platform can implement
its own policy.public int addRecord(byte[] data, int offset, int numBytes) throws RecordStoreNotOpenException, RecordStoreException, RecordStoreFullException
data
- The contents of this record.offset
- The index into the data buffer of the first relevant byte
for this record.numBytes
- The number of bytes of the data buffer to use for this
record.public void deleteRecord(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- The ID of the record to delete.public int getRecordSize(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- The ID of the record to use in this operation.public int getRecord(int recordId, byte[] buffer, int offset) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException, ArrayIndexOutOfBoundsException
recordId
- The ID of the record to use in this operation.buffer
- The byte array in which to copy the data.offset
- The index into the buffer in which to start copying.offset
.public byte[] getRecord(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- The ID of the record to use in this operation.public void setRecord(int recordId, byte[] newData, int offset, int numBytes) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException, RecordStoreFullException
getRecordSize()
will return numBytes, a call to getRecordData()
will return the data supplied here.recordId
- The ID of the record to use in this operation.newData
- The new data to store in the record.offset
- The index into the data buffer of the first relevant
byte for this record.numBytes
- The number of bytes of the data buffer to use for this
record.public RecordEnumeration enumerateRecords(RecordFilter filter, RecordComparator comparator, boolean keepUpdated) throws RecordStoreNotOpenException
The filter, if non-null, will be used to determine what subset of the record store records will be used.
The comparator, if non-null, will be used to determine the order in which the records are returned.
If both the filter and comparator are null, the enumeration will traverse all records in the record store in an undefined order. This is the most efficient way to traverse all of the records in a record store.
filter
- if non-null, will be used to determine what
subset of the record store records will be used.comparator
- if non-null, will be used to determine the
order in which the records are returned.keepUpdated
- If true, the enumerator will register itself as
a listener of the record store, and rebuild its internal index
whenever records in the record store are added or deleted. Use with
caution as there are possible performance consequences. If false
the enumeration will not be kept current and may return recordIds
for records that have been deleted or miss records that are added
later. It may also return records out of order that have been
modified after the enumeration was built.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |