| java.lang.Object
 javax.microedition.rms.RecordStore
| RecordStore | | public class RecordStore (Code) | | 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
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.
since:
MIDP 1.0 |
| Field Summary | |
| final public static int | AUTHMODE_ANY
Authorization to allow access to any MIDlet
suites. | | final public static int | AUTHMODE_PRIVATE
Authorization to allow access only to the current MIDlet
suite. |
| Method Summary | |
| public int | addRecord(byte[] data, int offset, int numBytes)
Adds a new record to the record store. | | public void | addRecordListener(RecordListener listener)
Adds the specified RecordListener. | | public void | closeRecordStore()
This method is called when the MIDlet requests to have the
record store closed. | | public void | deleteRecord(int recordId)
The record is deleted from the record store. | | public static void | deleteRecordStore(String recordStoreName)
Deletes the named record store. | | public 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.
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. | | public long | getLastModified()
Returns the last time the record store was modified, in the
format used by System.currentTimeMillis(). | | public String | getName()
Returns the name of this RecordStore. | | public int | getNextRecordID()
Returns the recordId of the next record to be added to the
record store. | | public int | getNumRecords()
Returns the number of records currently in the record store. | | public int | getRecord(int recordId, byte[] buffer, int offset)
Returns the data stored in the given record. | | public byte[] | getRecord(int recordId)
Returns a copy of the data stored in the given record.
Parameters:
recordId - the ID of the record to use in this operation
exception:
RecordStoreNotOpenException - if the record store isnot open
exception:
InvalidRecordIDException - if the recordId is invalid
exception:
RecordStoreException - if a general record storeexception occurs the data stored in the given record. | | int[] | getRecordIDs()
Returns all of the recordId's currently in the record store. | | public int | getRecordSize(int recordId)
Returns the size (in bytes) of the MIDlet data available
in the given record. | | public int | getSize()
Returns the amount of space, in bytes, that the record store
occupies. | | public int | getSizeAvailable()
Returns the amount of additional room (in bytes) available for
this record store to grow. | | public int | getVersion()
Each time a record store is modified (by
addRecord, setRecord, or
deleteRecord methods) its version is
incremented. | | boolean | isOpen()
Get the open status of this record store. | | public static String[] | listRecordStores()
Returns an array of the names of record stores owned by the
MIDlet suite. | | static RecordStore | openForLockTesting(String recordStoreName)
Internal method to open a record store for lock testing. | | public static RecordStore | openRecordStore(String recordStoreName, boolean createIfNecessary)
Open (and possibly create) a record store associated with the
given MIDlet suite. | | public 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. | | public static RecordStore | openRecordStore(String recordStoreName, String vendorName, String suiteName)
Open a record store associated with the named MIDlet suite.
The MIDlet suite is identified by MIDlet vendor and MIDlet
name. | | public void | removeRecordListener(RecordListener listener)
Removes the specified RecordListener. | | public void | setMode(int authmode, boolean writable)
Changes the access mode for this RecordStore. | | public void | setRecord(int recordId, byte[] newData, int offset, int numBytes)
Sets the data in the given record to that passed in. |
| AUTHMODE_ANY | | final public static int AUTHMODE_ANY(Code) | | Authorization to allow access to any MIDlet
suites. AUTHMODE_ANY has a value of 1.
|
| AUTHMODE_PRIVATE | | final public static int AUTHMODE_PRIVATE(Code) | | Authorization to allow access only to the current MIDlet
suite. AUTHMODE_PRIVATE has a value of 0.
|
| addRecord | | public int addRecord(byte[] data, int offset, int numBytes) throws RecordStoreNotOpenException, RecordStoreException, RecordStoreFullException(Code) | | Adds a new record to the record store. The recordId for this
new record is returned. This is a blocking atomic operation.
The record is written to persistent storage before the
method returns.
Parameters:
data - the data to be stored in this record. If the recordis to have zero-length data (no data), this parameter may benull.
Parameters:
offset - the index into the data buffer of the firstrelevant byte for this record
Parameters:
numBytes - the number of bytes of the data buffer to usefor this record (may be zero) the recordId for the new record
exception:
RecordStoreNotOpenException - if the record store isnot open
exception:
RecordStoreException - if a different recordstore-related exception occurred
exception:
RecordStoreFullException - if the operation cannot becompleted because the record store has no more room
exception:
SecurityException - if the MIDlet has read-only accessto the RecordStore |
| addRecordListener | | public void addRecordListener(RecordListener listener)(Code) | | Adds the specified RecordListener. If the specified listener
is already registered, it will not be added a second time.
When a record store is closed, all listeners are removed.
Parameters:
listener - the RecordChangedListener
See Also: RecordStore.removeRecordListener |
| closeRecordStore | | public void closeRecordStore() throws RecordStoreNotOpenException, RecordStoreException(Code) | | This method is called when the MIDlet requests to have the
record store closed. Note that the record store will not
actually be closed until closeRecordStore() is called as many
times as openRecordStore() was called. In other words, the
MIDlet needs to make a balanced number of close calls as open
calls before the record store is closed.
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.
exception:
RecordStoreNotOpenException - if the record store isnot open
exception:
RecordStoreException - if a different recordstore-related exception occurred |
| deleteRecordStore | | public static void deleteRecordStore(String recordStoreName) throws RecordStoreException, RecordStoreNotFoundException(Code) | | Deletes the named record store. MIDlet suites are only allowed
to delete their own record stores. If the named record store is
open (by a MIDlet in this suite or a MIDlet in a different
MIDlet suite) when this method is called, a
RecordStoreException will be thrown. If the named record store
does not exist a RecordStoreNotFoundException will be
thrown. Calling this method does NOT result in recordDeleted
calls to any registered listeners of this RecordStore.
Parameters:
recordStoreName - the MIDlet suite unique record store todelete
exception:
RecordStoreException - if a record store-relatedexception occurred
exception:
RecordStoreNotFoundException - if the record storecould not be found |
| enumerateRecords | | public RecordEnumeration enumerateRecords(RecordFilter filter, RecordComparator comparator, boolean keepUpdated) throws RecordStoreNotOpenException(Code) | | Returns an enumeration for traversing a set of records in the
record store in an optionally specified order.
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.
Parameters:
filter - if non-null, will be used to determine whatsubset of the record store records will be used
Parameters:
comparator - if non-null, will be used to determine theorder in which the records are returned
Parameters:
keepUpdated - if true, the enumerator will keep its enumerationcurrent with any changes in the records of the recordstore. Use with caution as there are possibleperformance consequences. If false the enumerationwill not be kept current and may return recordIds forrecords that have been deleted or miss records thatare added later. It may also return records out oforder that have been modified after the enumerationwas built. Note that any changes to records in therecord store are accurately reflected when the recordis later retrieved, either directly or through theenumeration. The thing that is risked by setting thisparameter false is the filtering and sorting order ofthe enumeration when records are modified, added, ordeleted.
exception:
RecordStoreNotOpenException - if the record store isnot open
See Also: RecordEnumeration.rebuild an enumeration for traversing a set of records in therecord store in an optionally specified order |
| getLastModified | | public long getLastModified() throws RecordStoreNotOpenException(Code) | | Returns the last time the record store was modified, in the
format used by System.currentTimeMillis().
the last time the record store was modified, in theformat used by System.currentTimeMillis()
exception:
RecordStoreNotOpenException - if the record store isnot open |
| getNextRecordID | | public int getNextRecordID() throws RecordStoreNotOpenException, RecordStoreException(Code) | | Returns the recordId of the next record to be added to the
record store. This can be useful for setting up pseudo-relational
relationships. That is, if you have two or more
record stores whose records need to refer to one another, you can
predetermine the recordIds of the records that will be created
in one record store, before populating the fields and allocating
the record in another record store. Note that the recordId returned
is only valid while the record store remains open and until a call
to addRecord().
the recordId of the next record to be added to therecord store
exception:
RecordStoreNotOpenException - if the record store isnot open
exception:
RecordStoreException - if a different recordstore-related exception occurred |
| getRecordIDs | | int[] getRecordIDs()(Code) | | Returns all of the recordId's currently in the record store.
an array of the recordId's currently in the record storeor null if the record store is closed. |
| getSize | | public int getSize() throws RecordStoreNotOpenException(Code) | | Returns the amount of space, in bytes, that the record store
occupies. The size returned includes any overhead associated
with the implementation, such as the data structures
used to hold the state of the record store, etc.
exception:
RecordStoreNotOpenException - if the record store isnot open the size of the record store in bytes |
| getSizeAvailable | | public int getSizeAvailable() throws RecordStoreNotOpenException(Code) | | Returns the amount of additional room (in bytes) available for
this record store to grow. Note that this is not necessarily
the amount of extra MIDlet-level data which can be stored,
as implementations may store additional data structures with
each record to support integration with native applications,
synchronization, etc.
exception:
RecordStoreNotOpenException - if the record store isnot open the amount of additional room (in bytes) available forthis record store to grow |
| getVersion | | public int getVersion() throws RecordStoreNotOpenException(Code) | | Each time a record store is modified (by
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.
the current record store version
exception:
RecordStoreNotOpenException - if the record store isnot open |
| isOpen | | boolean isOpen()(Code) | | Get the open status of this record store. (Package accessible
for use by record enumeration objects.)
true if record store is open, false otherwise. |
| listRecordStores | | public static String[] listRecordStores()(Code) | | Returns an array of the names of record stores owned by the
MIDlet suite. Note that if the MIDlet suite does not
have any record stores, this function will return null.
The order of RecordStore names returned is implementation
dependent.
array of the names of record stores owned by theMIDlet suite. Note that if the MIDlet suite does nothave any record stores, this function will return null. |
| openRecordStore | | public static RecordStore openRecordStore(String recordStoreName, boolean createIfNecessary) throws RecordStoreException, RecordStoreFullException, RecordStoreNotFoundException(Code) | | Open (and possibly create) a record store associated with the
given MIDlet suite. 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.
Parameters:
recordStoreName - the MIDlet suite unique name for therecord store, consisting of between one and 32 Unicodecharacters inclusive.
Parameters:
createIfNecessary - if true, the record store will becreated if necessary RecordStore object for the record store
exception:
RecordStoreException - if a record store-relatedexception occurred
exception:
RecordStoreNotFoundException - if the record storecould not be found
exception:
RecordStoreFullException - if the operation cannot becompleted because the record store is full
exception:
IllegalArgumentException - ifrecordStoreName is invalid |
| openRecordStore | | public static RecordStore openRecordStore(String recordStoreName, boolean createIfNecessary, int authmode, boolean writable) throws RecordStoreException, RecordStoreFullException, RecordStoreNotFoundException(Code) | | Open (and possibly create) a record store that can be shared
with other MIDlet suites. The RecordStore is owned by the
current MIDlet suite. The authorization mode is set when the
record store is created, as follows:
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.
Parameters:
recordStoreName - the MIDlet suite unique name for therecord store, consisting of between one and 32 Unicodecharacters inclusive.
Parameters:
createIfNecessary - if true, the record store will becreated if necessary
Parameters:
authmode - 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.
Parameters:
writable - true if the RecordStore is to be writable byother MIDlet suites that are granted access.This argument is ignored if the RecordStore exists. RecordStore object for the record store
exception:
RecordStoreException - if a record store-relatedexception occurred
exception:
RecordStoreNotFoundException - if the record storecould not be found
exception:
RecordStoreFullException - if the operationcannot be completed because the record store is full
exception:
IllegalArgumentException - if authmode orrecordStoreName is invalid |
| openRecordStore | | public static RecordStore openRecordStore(String recordStoreName, String vendorName, String suiteName) throws RecordStoreException, RecordStoreNotFoundException(Code) | | Open a record store associated with the named MIDlet suite.
The MIDlet suite is identified by MIDlet vendor and MIDlet
name. Access is granted only if the authorization mode of the
RecordStore allows access by the current MIDlet suite. Access
is limited by the authorization mode set when the record store
was created:
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:
RecordStore.openRecordStore(String,boolean)openRecordStore(recordStoreName, false)
Parameters:
recordStoreName - the MIDlet suite unique name for therecord store, consisting of between one and 32 Unicodecharacters inclusive.
Parameters:
vendorName - the vendor of the owning MIDlet suite
Parameters:
suiteName - the name of the MIDlet suite RecordStore object for the record store
exception:
RecordStoreException - if a record store-relatedexception occurred
exception:
RecordStoreNotFoundException - if the record storecould not be found
exception:
SecurityException - if this MIDlet Suite is notallowed to open the specified RecordStore.
exception:
IllegalArgumentException - if recordStoreName isinvalid |
| removeRecordListener | | public void removeRecordListener(RecordListener listener)(Code) | | Removes the specified RecordListener. If the specified listener
is not registered, this method does nothing.
Parameters:
listener - the RecordChangedListener
See Also: RecordStore.addRecordListener |
| setMode | | public void setMode(int authmode, boolean writable) throws RecordStoreException(Code) | | Changes the access mode for this RecordStore. The authorization
mode choices are:
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.
Parameters:
authmode - the mode under which to check or create access.Must be one of AUTHMODE_PRIVATE or AUTHMODE_ANY.
Parameters:
writable - true if the RecordStore is to be writable byother MIDlet suites that are granted access
exception:
RecordStoreException - if a record store-relatedexception occurred
exception:
SecurityException - if this MIDlet Suite is notallowed to change the mode of the RecordStore
exception:
IllegalArgumentException - if authmode is invalid |
|
|