|
MID Profile | |||||||||
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 all the record stores associated with its MIDlets will also be removed. MIDlets within a MIDlet suite can access each other's record stores directly. New APIs in MIDP 2.0 allow for the explicit sharing of record stores if the MIDlet creating the RecordStore chooses to give such permission.
Sharing is accomplished through the ability to name a RecordStore created by another MIDlet suite.
RecordStores are uniquely named using the unique name of the MIDlet suite plus the name of the RecordStore. MIDlet suites are identified by the MIDlet-Vendor and MIDlet-Name attributes from the application descriptor.
Access controls are defined when RecordStores to be shared are created. Access controls are enforced when RecordStores are opened. The access modes allow private use or shareable with any other MIDlet suite.
Record store names are case sensitive and may consist of any combination of between one and 32 Unicode characters inclusive. 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 in one MIDlet suite 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 one (1). 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
sequences of the records in the RecordStore 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 number, 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.
Field Summary | |
static int |
AUTHMODE_ANY
Authorization to allow access to any MIDlet suites. |
static int |
AUTHMODE_PRIVATE
Authorization to allow access only to the current MIDlet suite. |
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 a copy of 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 amount of space, in bytes, that the record store occupies. |
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 (by addRecord , setRecord , or
deleteRecord methods) 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 MIDlet suite. |
static RecordStore |
openRecordStore(String recordStoreName,
boolean createIfNecessary,
int authmode,
boolean writable)
Open (and possibly create) a record store that can be shared with other MIDlet suites. |
static RecordStore |
openRecordStore(String recordStoreName,
String vendorName,
String suiteName)
Open a record store associated with the named MIDlet suite. |
void |
removeRecordListener(RecordListener listener)
Removes the specified RecordListener. |
void |
setMode(int authmode,
boolean writable)
Changes the access mode for this RecordStore. |
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, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int AUTHMODE_PRIVATE
public static final int AUTHMODE_ANY
Method Detail |
public static void deleteRecordStore(String recordStoreName) throws RecordStoreException, RecordStoreNotFoundException
recordStoreName
- the MIDlet suite unique record store to
deleteRecordStoreException
- if a record store-related
exception occurredRecordStoreNotFoundException
- if the record store
could not be foundpublic static RecordStore openRecordStore(String recordStoreName, boolean createIfNecessary) throws RecordStoreException, RecordStoreFullException, RecordStoreNotFoundException
recordStoreName
- the MIDlet suite unique name for the
record store, consisting of between one and 32 Unicode
characters inclusive.createIfNecessary
- if true, the record store will be
created if necessaryRecordStore
object for the record storeRecordStoreException
- if a record store-related
exception occurredRecordStoreNotFoundException
- if the record store
could not be foundRecordStoreFullException
- if the operation cannot be
completed because the record store is fullIllegalArgumentException
- if
recordStoreName is invalidpublic static RecordStore openRecordStore(String recordStoreName, boolean createIfNecessary, int authmode, boolean writable) throws RecordStoreException, RecordStoreFullException, RecordStoreNotFoundException
AUTHMODE_PRIVATE
- Only allows the MIDlet
suite that created the RecordStore to access it. This
case behaves identically to
openRecordStore(recordStoreName,
createIfNecessary)
.AUTHMODE_ANY
- Allows any MIDlet to access the
RecordStore. Note that this makes your recordStore
accessible by any other MIDlet on the device. This
could have privacy and security issues depending on
the data being shared. Please use carefully.The owning MIDlet suite may always access the RecordStore and always has access to write and update the store.
If this method is called by a MIDlet when the record store is already open by a MIDlet in the MIDlet suite, this method returns a reference to the same RecordStore object.
recordStoreName
- the MIDlet suite unique name for the
record store, consisting of between one and 32 Unicode
characters inclusive.createIfNecessary
- if true, the record store will be
created if necessaryauthmode
- the mode under which to check or create access.
Must be one of AUTHMODE_PRIVATE or AUTHMODE_ANY.
This argument is ignored if the RecordStore exists.writable
- true if the RecordStore is to be writable by
other MIDlet suites that are granted access.
This argument is ignored if the RecordStore exists.RecordStore
object for the record storeRecordStoreException
- if a record store-related
exception occurredRecordStoreNotFoundException
- if the record store
could not be foundRecordStoreFullException
- if the operation
cannot be completed because the record store is fullIllegalArgumentException
- if authmode or
recordStoreName is invalidpublic static RecordStore openRecordStore(String recordStoreName, String vendorName, String suiteName) throws RecordStoreException, RecordStoreNotFoundException
AUTHMODE_PRIVATE
- Succeeds only if vendorName
and suiteName identify the current MIDlet suite; this
case behaves identically to
openRecordStore(recordStoreName,
createIfNecessary)
.AUTHMODE_ANY
- Always succeeds.
Note that this makes your recordStore
accessible by any other MIDlet on the device. This
could have privacy and security issues depending on
the data being shared. Please use carefully.
Untrusted MIDlet suites are allowed to share data but
this is not recommended. The authenticity of the
origin of untrusted MIDlet suites cannot be verified
so shared data may be used unscrupulously.If this method is called by a MIDlet when the record store is already open by a MIDlet in the MIDlet suite, this method returns a reference to the same RecordStore object.
If a MIDlet calls this method to open a record store from
its own suite, the behavior is identical to calling:
openRecordStore(recordStoreName, false)
recordStoreName
- the MIDlet suite unique name for the
record store, consisting of between one and 32 Unicode
characters inclusive.vendorName
- the vendor of the owning MIDlet suitesuiteName
- the name of the MIDlet suiteRecordStore
object for the record storeRecordStoreException
- if a record store-related
exception occurredRecordStoreNotFoundException
- if the record store
could not be foundSecurityException
- if this MIDlet Suite is not
allowed to open the specified RecordStore.IllegalArgumentException
- if recordStoreName is
invalidpublic void setMode(int authmode, boolean writable) throws RecordStoreException
AUTHMODE_PRIVATE
- Only allows the MIDlet
suite that created the RecordStore to access it. This
case behaves identically to
openRecordStore(recordStoreName,
createIfNecessary)
.AUTHMODE_ANY
- Allows any MIDlet to access the
RecordStore. Note that this makes your recordStore
accessible by any other MIDlet on the device. This
could have privacy and security issues depending on
the data being shared. Please use carefully.The owning MIDlet suite may always access the RecordStore and always has access to write and update the store. Only the owning MIDlet suite can change the mode of a RecordStore.
authmode
- the mode under which to check or create access.
Must be one of AUTHMODE_PRIVATE or AUTHMODE_ANY.writable
- true if the RecordStore is to be writable by
other MIDlet suites that are granted accessRecordStoreException
- if a record store-related
exception occurredSecurityException
- if this MIDlet Suite is not
allowed to change the mode of the RecordStoreIllegalArgumentException
- if authmode is invalidpublic void closeRecordStore() throws RecordStoreNotOpenException, RecordStoreException
When the record store is closed, all listeners are removed and all RecordEnumerations associated with it become invalid. If the MIDlet attempts to perform operations on the RecordStore object after it has been closed, the methods will throw a RecordStoreNotOpenException.
RecordStoreNotOpenException
- if the record store is
not openRecordStoreException
- if a different record
store-related exception occurredpublic static String[] listRecordStores()
public String getName() throws RecordStoreNotOpenException
RecordStoreNotOpenException
- if the record store is not openpublic int getVersion() throws RecordStoreNotOpenException
addRecord
, setRecord
, or
deleteRecord
methods) its version is
incremented. This can be used by MIDlets to quickly tell if
anything has been modified.
The initial version number is implementation dependent.
The increment is a positive integer greater than 0.
The version number increases only when the RecordStore is updated.
The increment value need not be constant and may vary with each
update.RecordStoreNotOpenException
- if the record store is
not openpublic int getNumRecords() throws RecordStoreNotOpenException
RecordStoreNotOpenException
- if the record store is
not openpublic int getSize() throws RecordStoreNotOpenException
RecordStoreNotOpenException
- if the record store is
not openpublic int getSizeAvailable() throws RecordStoreNotOpenException
RecordStoreNotOpenException
- if the record store is
not openpublic long getLastModified() throws RecordStoreNotOpenException
RecordStoreNotOpenException
- if the record store is
not openpublic void addRecordListener(RecordListener listener)
listener
- the RecordChangedListenerremoveRecordListener(javax.microedition.rms.RecordListener)
public void removeRecordListener(RecordListener listener)
listener
- the RecordChangedListeneraddRecordListener(javax.microedition.rms.RecordListener)
public int getNextRecordID() throws RecordStoreNotOpenException, RecordStoreException
addRecord()
.RecordStoreNotOpenException
- if the record store is
not openRecordStoreException
- if a different record
store-related exception occurredpublic int addRecord(byte[] data, int offset, int numBytes) throws RecordStoreNotOpenException, RecordStoreException, RecordStoreFullException
data
- the data to be stored in this record. If the record
is to have zero-length data (no data), this parameter may be
null.offset
- the index into the data buffer of the first
relevant byte for this recordnumBytes
- the number of bytes of the data buffer to use
for this record (may be zero)RecordStoreNotOpenException
- if the record store is
not openRecordStoreException
- if a different record
store-related exception occurredRecordStoreFullException
- if the operation cannot be
completed because the record store has no more roomSecurityException
- if the MIDlet has read-only access
to the RecordStorepublic void deleteRecord(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- the ID of the record to deleteRecordStoreNotOpenException
- if the record store is
not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store
exception occursSecurityException
- if the MIDlet has read-only access
to the RecordStorepublic int getRecordSize(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- the ID of the record to use in this operationRecordStoreNotOpenException
- if the record store is
not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store
exception occurspublic int getRecord(int recordId, byte[] buffer, int offset) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- the ID of the record to use in this operationbuffer
- the byte array in which to copy the dataoffset
- the index into the buffer in which to start copyingoffset
RecordStoreNotOpenException
- if the record store is
not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store
exception occursArrayIndexOutOfBoundsException
- if the record is
larger than the buffer suppliedsetRecord(int, byte[], int, int)
public byte[] getRecord(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- the ID of the record to use in this operationRecordStoreNotOpenException
- if the record store is
not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store
exception occurssetRecord(int, byte[], int, int)
public void setRecord(int recordId, byte[] newData, int offset, int numBytes) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException, RecordStoreFullException
getRecord(int recordId)
will return an array of numBytes size containing the data
supplied here.recordId
- the ID of the record to use in this operationnewData
- the new data to store in the recordoffset
- the index into the data buffer of the first
relevant byte for this recordnumBytes
- the number of bytes of the data buffer to use
for this recordRecordStoreNotOpenException
- if the record store is
not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store
exception occursRecordStoreFullException
- if the operation cannot be
completed because the record store has no more roomSecurityException
- if the MIDlet has read-only access
to the RecordStoregetRecord(int, byte[], int)
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 is 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. If a filter is used with a null
comparator, the enumeration will traverse the filtered records
in an undefined order.
The first call to RecordEnumeration.nextRecord()
returns the record data from the first record in the sequence.
Subsequent calls to RecordEnumeration.nextRecord()
return the next consecutive record's data. To return the record
data from the previous consecutive from any
given point in the enumeration, call previousRecord()
.
On the other hand, if after creation the first call is to
previousRecord()
, the record data of the last element
of the enumeration will be returned. Each subsequent call to
previousRecord()
will step backwards through the
sequence.
filter
- if non-null, will be used to determine what
subset of the record store records will be usedcomparator
- if non-null, will be used to determine the
order in which the records are returnedkeepUpdated
- if true, the enumerator will keep its enumeration
current with any changes in the records of the record
store. 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. Note that any changes to records in the
record store are accurately reflected when the record
is later retrieved, either directly or through the
enumeration. The thing that is risked by setting this
parameter false is the filtering and sorting order of
the enumeration when records are modified, added, or
deleted.RecordStoreNotOpenException
- if the record store is
not openRecordEnumeration.rebuild()
|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |