MIDP3.0

javax.microedition.rms
Class RecordStore

java.lang.Object
  extended by javax.microedition.rms.RecordStore

public class RecordStore
extends java.lang.Object

A class representing a record store. MIDlets can use this API to persistently store data and later retrieve it. A record store consists of a collection of records that will remain persistent across multiple invocations of a MIDlet. For further information and examples of usage, see the Persistent Storage section of the package summary.

Since:
MIDP 1.0

Field Summary
static int AUTHMODE_ANY
          Authorization to allow access to any MIDlet suites.
static int AUTHMODE_APPLEVEL
          Authorization to allow access to only certain identified MIDlets.
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, and returns the recordId for this new record.
 int addRecord(byte[] data, int offset, int numBytes, int tag)
          Adds a new record to the record store and associates the record with the given tag.
 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; the recordId for this record MUST NOT be reused.
static void deleteRecordStore(java.lang.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.
 RecordEnumeration enumerateRecords(RecordFilter filter, RecordComparator comparator, boolean keepUpdated, int[] tags)
          Returns an enumeration for traversing a set of records in the record store in an optionally specified order.
static void exportRecordStore(java.io.OutputStream os, java.lang.String recordStoreName, java.lang.String internalPassword, java.lang.String exportPassword)
          Exports the record store to an RMS stream (see RMS Interchange Format).
 long getLastModified()
          Returns the last time the record store was modified, in the format used by System.currentTimeMillis().
 java.lang.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.
 RecordStoreInfo getRecordStoreInfo()
           Gets a RecordStoreInfo instance for this RecordStore.
 int getSize()
          Deprecated. Previously calls to getSize() could not accommodate a RecordStore larger than Integer.MAX_VALUE. To query the size of a RecordStore, use getRecordStoreInfo() and RecordStoreInfo.getSize(), which returns a long and can accommodate RecordStore sizes up to Long.MAX_VALUE.
 int getSizeAvailable()
          Deprecated. Previously calls to getSizeAvailable() could not accommodate a RecordStore larger than Integer.MAX_VALUE. To query the available size of a RecordStore, use getRecordStoreInfo() and RecordStoreInfo.getSizeAvailable(), which returns a long and can accommodate RecordStore sizes up to Long.MAX_VALUE.
 int getTag(int recordId)
          Returns the tag associated with the recordId.
 int getVersion()
          Each time a record store is modified (by addRecord, setRecord, or deleteRecord methods) its version is incremented.
static RecordStore importRecordStore(java.io.InputStream is, java.lang.String importPassword, java.lang.String internalPassword)
          Imports the record store from an encrypted or plaintext RMS stream (see RMS Interchange Format).
static java.lang.String[] listRecordStores()
          Returns an array of the names of record stores owned by the MIDlet suite.
static RecordStore openRecordStore(java.lang.String recordStoreName, boolean createIfNecessary)
          Open (and possibly create) a record store associated with the current MIDlet suite.
static RecordStore openRecordStore(java.lang.String recordStoreName, boolean createIfNecessary, int authmode, boolean writeable)
          Open (and possibly create) a record store that can be shared with other MIDlet suites.
static RecordStore openRecordStore(java.lang.String recordStoreName, boolean createIfNecessary, int authmode, boolean writeable, java.lang.String password)
          Open (and possibly create) a record store that can be shared with other MIDlet suites.
static RecordStore openRecordStore(java.lang.String recordStoreName, java.lang.String vendorName, java.lang.String suiteName)
          Open a record store associated with the named MIDlet suite.
static RecordStore openRecordStore(java.lang.String recordStoreName, java.lang.String vendorName, java.lang.String suiteName, java.lang.String password)
           Open a record store associated with the named MIDlet suite.
 void removeRecordListener(RecordListener listener)
          Removes the specified RecordListener.
 void setMode(int authmode, boolean writeable)
          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 the provided new data.
 void setRecord(int recordId, byte[] newData, int offset, int numBytes, int tag)
          Sets the data in the given record to the provided new data.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

AUTHMODE_PRIVATE

public static final int AUTHMODE_PRIVATE
Authorization to allow access only to the current MIDlet suite. AUTHMODE_PRIVATE has a value of 0.

See Also:
Constant Field Values

AUTHMODE_ANY

public static final int AUTHMODE_ANY
Authorization to allow access to any MIDlet suites. AUTHMODE_ANY has a value of 1.

See Also:
Constant Field Values

AUTHMODE_APPLEVEL

public static final int AUTHMODE_APPLEVEL
Authorization to allow access to only certain identified MIDlets. These MIDlets are identified using the application level access control mechanism. AUTHMODE_APPLEVEL has a value of 2.

Since:
MIDP 3.0
See Also:
Constant Field Values
Method Detail

deleteRecordStore

public static void deleteRecordStore(java.lang.String recordStoreName)
                              throws RecordStoreException,
                                     RecordStoreNotFoundException
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 to delete
Throws:
RecordStoreException - if a record store-related exception occurred
RecordStoreNotFoundException - if the record store could not be found

openRecordStore

public static RecordStore openRecordStore(java.lang.String recordStoreName,
                                          boolean createIfNecessary)
                                   throws RecordStoreException,
                                          RecordStoreFullException,
                                          RecordStoreNotFoundException
Open (and possibly create) a record store associated with the current MIDlet suite. If this method is called by the MIDlet when the record store is already open by the same MIDlet, this method returns a reference to the same RecordStore object.

Parameters:
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 necessary
Returns:
RecordStore object for the record store
Throws:
RecordStoreException - if a record store-related exception occurred
RecordStoreNotFoundException - if the record store could not be found
RecordStoreFullException - if the operation cannot be completed because the record store is full
java.lang.IllegalArgumentException - if recordStoreName is invalid

openRecordStore

public static RecordStore openRecordStore(java.lang.String recordStoreName,
                                          boolean createIfNecessary,
                                          int authmode,
                                          boolean writeable)
                                   throws RecordStoreException,
                                          RecordStoreFullException,
                                          RecordStoreNotFoundException
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:

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 the same MIDlet, this method returns a reference to the same RecordStore object.

Parameters:
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 necessary
authmode - the mode under which to check or create access. Must be one of AUTHMODE_PRIVATE, AUTHMODE_APPLEVEL, or AUTHMODE_ANY. This argument is ignored if the RecordStore exists.
writeable - true if the RecordStore is to be writeable by other MIDlet suites that are granted access. This argument is ignored if the RecordStore exists.
Returns:
RecordStore object for the record store
Throws:
RecordStoreException - if a record store-related exception occurred
RecordStoreNotFoundException - if the record store could not be found
RecordStoreFullException - if the operation cannot be completed because the record store is full
java.lang.IllegalArgumentException - if authmode or recordStoreName is invalid
Since:
MIDP 2.0

openRecordStore

public static RecordStore openRecordStore(java.lang.String recordStoreName,
                                          java.lang.String vendorName,
                                          java.lang.String suiteName)
                                   throws RecordStoreException,
                                          RecordStoreNotFoundException
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. If authorization mode is used:

If this method is called by a MIDlet when the record store is already open by the same MIDlet, 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)

This may be used to open a plaintext record store owned by a LIBlet.

Parameters:
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 suite
suiteName - the name of the MIDlet suite
Returns:
RecordStore object for the record store
Throws:
RecordStoreException - if a record store-related exception occurred
RecordStoreNotFoundException - if the record store could not be found
java.lang.SecurityException - if this MIDlet suite is not allowed to open the specified RecordStore.
java.lang.IllegalArgumentException - if recordStoreName is invalid
Since:
MIDP 2.0

openRecordStore

public static RecordStore openRecordStore(java.lang.String recordStoreName,
                                          boolean createIfNecessary,
                                          int authmode,
                                          boolean writeable,
                                          java.lang.String password)
                                   throws RecordStoreException,
                                          RecordStoreFullException,
                                          RecordStoreNotFoundException,
                                          SecureRecordStoreException
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 encryption password for the record store is provided as a String. The implementation MUST use the provided password to derive a key and encrypt records before they are persisted. Retrieving a record MUST decrypt the data using the same key. See Locally Encrypted Record Stores).

No copies of the records in plaintext form will be retained by the implementation. The MIDlet suite accessing the secure record store should also release references to plaintext records as soon as possible.

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 the same MIDlet, this method returns a reference to the same RecordStore object.

Parameters:
recordStoreName - The MIDlet suite unique name for the record store, consisting of between 1 and 32 Unicode characters inclusive.
createIfNecessary - If true, the record store will be created if necessary.
authmode - the mode under which to check or create access. Must be one of AUTHMODE_PRIVATE, AUTHMODE_APPLEVEL, or AUTHMODE_ANY. This argument is ignored if the RecordStore exists.
writeable - true if the RecordStore is to be writeable by other MIDlet suites that are granted access. This argument is ignored if the RecordStore exists.
password - The password to be used for generation of an encryption key for encryption of records, consisting of Unicode characters with a recommended minimum length of eight characters.
Returns:
RecordStore object for the record store
Throws:
RecordStoreException - If a record store-related exception occurred
RecordStoreNotFoundException - If the record store could not be found
RecordStoreFullException - If the operation cannot be completed because the record store is full
SecureRecordStoreException - If there is an internal error while making the record store secure (e.g. an error occurs while initializing cryptographic functions)
java.lang.IllegalArgumentException - if recordStoreName is invalid
Since:
MIDP 3.0

openRecordStore

public static RecordStore openRecordStore(java.lang.String recordStoreName,
                                          java.lang.String vendorName,
                                          java.lang.String suiteName,
                                          java.lang.String password)
                                   throws RecordStoreException,
                                          RecordStoreNotFoundException,
                                          SecureRecordStoreException

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.

If this method is called by a MIDlet when the record store is already open by the same MIDlet, 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, AUTHMODE_PRIVATE, true, password). (Note: The values of authmode and writeable are ignored for an existing record store)

This may be used to open an encrypted record store owned by a LIBlet.

Parameters:
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 suite
suiteName - the name of the MIDlet suite.
password - the password for use in decrypting the record store.
Returns:
RecordStore object for the record store
Throws:
RecordStoreException - if a record store-related exception occurred
RecordStoreNotFoundException - if the record store could not be found
java.lang.SecurityException - if the calling MIDlet suite is not allowed to open the specified RecordStore
java.lang.IllegalArgumentException - if any of the vendor name, suite name or record store name are invalid
SecureRecordStoreException - If there is an internal error while making the record store secure (e.g. an error occurs while initializing cryptographic functions)
Since:
MIDP 3.0

getRecordStoreInfo

public RecordStoreInfo getRecordStoreInfo()
                                   throws RecordStoreNotOpenException

Gets a RecordStoreInfo instance for this RecordStore.

Returns:
RecordStoreInfo object for the RecordStore
Throws:
RecordStoreNotOpenException - if the record store is not open
Since:
MIDP 3.0

importRecordStore

public static RecordStore importRecordStore(java.io.InputStream is,
                                            java.lang.String importPassword,
                                            java.lang.String internalPassword)
                                     throws java.io.IOException,
                                            RecordStoreException,
                                            SecureRecordStoreException
Imports the record store from an encrypted or plaintext RMS stream (see RMS Interchange Format). The Key for decrypting the stream is derived from the provided "importPassword" parameter as specified by PKCS#5 v 2.0. If a non-null value is passed in for internalPassword, then the RecordStore MUST be encrypted locally on device. See Locally Encrypted Record Stores. If a record store with the same name already exists, a RecordStoreException will be thrown. Record store import is an atomic operation: if an exception occurs while reading from the stream or decrypting the data, no record store will be created.

Parameters:
is - Input stream with the encrypted content
importPassword - password to be used in decrypting the serialized stream. If the stream is not encrypted the parameter should be null. For unencrypted streams, if a non-null value for this parameter is passed in, it will be ignored.
internalPassword - password to be used to encrypt entries in the new record store. If null, the record store will not be encrypted
Returns:
RecordStore object for the record store
Throws:
java.io.IOException - is the stream cannot be read
SecureRecordStoreException - if there is any error while decrypting a Secure inputStream or locally encrypting the RecordStore (e.g. cipher is unsupported or key has invalid length).
RecordStoreException - if record store cannot be created (for example if a record store with the same name already exists)
Since:
MIDP 3.0
See Also:
exportRecordStore(java.io.OutputStream, java.lang.String, java.lang.String, java.lang.String)

exportRecordStore

public static void exportRecordStore(java.io.OutputStream os,
                                     java.lang.String recordStoreName,
                                     java.lang.String internalPassword,
                                     java.lang.String exportPassword)
                              throws java.io.IOException,
                                     RecordStoreException,
                                     java.lang.IllegalArgumentException,
                                     RecordStoreNotFoundException,
                                     SecureRecordStoreException
Exports the record store to an RMS stream (see RMS Interchange Format). The RMS-interchange-formatted stream MUST be encrypted using the AES block cipher, if a non-null value for exportpassword is passed in. The key for encrypting the stream MUST be derived from the parameter "exportPassword" as specified by PKCS#5 v 2.0. The parameter "internalPassword" is to be used for decrypting the locally encrypted RecordStore (see Locally Encrypted Record Stores).

Parameters:
os - Output stream where serialized input is to be written
recordStoreName - Name of the record store to serialize
internalPassword - Password for decryption of the record store entries. If the record store is not encrypted the parameter should be null. If a non-null value is passed in for a plaintext record store, this parameter will be ignored.
exportPassword - Password for encryption of the serialized stream. If null, the stream is not encrypted.
Throws:
java.io.IOException - if there was an stream output error
RecordStoreException - if record store cannot be read
java.lang.IllegalArgumentException - - if the recordStoreName is invalid.
RecordStoreNotFoundException - if a recordstore with name recordStoreName cannot be found
SecureRecordStoreException - if there is an error while locally decrypting a record store or encrypting an OutputStream.
Since:
MIDP 3.0
See Also:
importRecordStore(java.io.InputStream, java.lang.String, java.lang.String)

setMode

public void setMode(int authmode,
                    boolean writeable)
             throws RecordStoreException
Changes the access mode for this RecordStore. Please use this method carefully. The authorization mode choices are:

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.

This method can only be called if this recordstore is NOT open by a MIDlet in this suite or in a different MIDlet suite. If this recordStore is open by any MIDlet, an IllegalStateException will be thrown by the method.

Parameters:
authmode - the mode under which to check or create access. Must be one of AUTHMODE_PRIVATE, AUTHMODE_APPLEVEL, or AUTHMODE_ANY.
writeable - true if the RecordStore is to be writeable by other MIDlet suites that are granted access
Throws:
RecordStoreException - if a record store-related exception occurred
java.lang.SecurityException - if this MIDlet suite is not allowed to change the mode of the RecordStore
java.lang.IllegalArgumentException - if authmode is invalid
java.lang.IllegalStateException - if any MIDlet from this MIDlet suite or a different MIDlet suite has this RecordStore open.
Since:
MIDP 2.0

closeRecordStore

public void closeRecordStore()
                      throws RecordStoreNotOpenException,
                             RecordStoreException
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.

Throws:
RecordStoreNotOpenException - if the record store is not open
RecordStoreException - if a different record store-related exception occurred

listRecordStores

public static java.lang.String[] listRecordStores()
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.

Returns:
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.

getName

public java.lang.String getName()
                         throws RecordStoreNotOpenException
Returns the name of this RecordStore.

Returns:
the name of this RecordStore
Throws:
RecordStoreNotOpenException - if the record store is not open

getVersion

public int getVersion()
               throws RecordStoreNotOpenException
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.

Returns:
the current record store version
Throws:
RecordStoreNotOpenException - if the record store is not open

getNumRecords

public int getNumRecords()
                  throws RecordStoreNotOpenException
Returns the number of records currently in the record store. The maximum number of records that a RecordStore can contain is Integer.MAX_VALUE.

Returns:
the number of records currently in the record store.
Throws:
RecordStoreNotOpenException - if the record store is not open

getSize

public int getSize()
            throws RecordStoreNotOpenException
Deprecated. Previously calls to getSize() could not accommodate a RecordStore larger than Integer.MAX_VALUE. To query the size of a RecordStore, use getRecordStoreInfo() and RecordStoreInfo.getSize(), which returns a long and can accommodate RecordStore sizes up to Long.MAX_VALUE.

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, tags etc.

Returns:
the size of the record store in bytes. If the size of the record store exceeds java.lang.Integer.MAX_VALUE, then java.lang.Integer.MAX_VALUE MUST be returned.
Throws:
RecordStoreNotOpenException - if the record store is not open

getSizeAvailable

public int getSizeAvailable()
                     throws RecordStoreNotOpenException
Deprecated. Previously calls to getSizeAvailable() could not accommodate a RecordStore larger than Integer.MAX_VALUE. To query the available size of a RecordStore, use getRecordStoreInfo() and RecordStoreInfo.getSizeAvailable(), which returns a long and can accommodate RecordStore sizes up to Long.MAX_VALUE.

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, tag data etc.

Returns:
the amount of additional room (in bytes) available for this record store to grow. If the amount of additional room available for this record store to grow exceeds java.lang.Integer.MAX_VALUE, then java.lang.Integer.MAX_VALUE MUST be returned.
Throws:
RecordStoreNotOpenException - if the record store is not open

getLastModified

public long getLastModified()
                     throws RecordStoreNotOpenException
Returns the last time the record store was modified, in the format used by System.currentTimeMillis().

Returns:
the last time the record store was modified, in the format used by System.currentTimeMillis()
Throws:
RecordStoreNotOpenException - if the record store is not open

addRecordListener

public void addRecordListener(RecordListener listener)
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. If the record store is not open, this method does nothing.

Parameters:
listener - the RecordChangedListener
See Also:
removeRecordListener(javax.microedition.rms.RecordListener)

removeRecordListener

public void removeRecordListener(RecordListener listener)
Removes the specified RecordListener. If the specified listener is not registered, this method does nothing.

Parameters:
listener - the RecordChangedListener
See Also:
addRecordListener(javax.microedition.rms.RecordListener)

getNextRecordID

public int getNextRecordID()
                    throws RecordStoreNotOpenException,
                           RecordStoreException
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().

Returns:
the recordId of the next record to be added to the record store
Throws:
RecordStoreNotOpenException - if the record store is not open
RecordStoreException - if a different record store-related exception occurred

addRecord

public int addRecord(byte[] data,
                     int offset,
                     int numBytes)
              throws RecordStoreNotOpenException,
                     RecordStoreException,
                     RecordStoreFullException
Adds a new record to the record store, and returns the recordId for this new record. This is a blocking atomic operation. The record data MUST be queued to be persisted before the method returns, and MUST be available for retrieval after the method returns. However, the record data MAY be written to persistent storage by the implementation after the method returns. If this method is used to add records to the record store, the records have a tag value of 0.

Parameters:
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 record
numBytes - the number of bytes of the data buffer to use for this record (may be zero)
Returns:
the recordId for the new record
Throws:
RecordStoreNotOpenException - if the record store is not open
RecordStoreException - if a different record store-related exception occurred
RecordStoreFullException - if the operation cannot be completed because the record store has no more room
java.lang.SecurityException - if the MIDlet has read-only access to the RecordStore

addRecord

public int addRecord(byte[] data,
                     int offset,
                     int numBytes,
                     int tag)
              throws RecordStoreNotOpenException,
                     RecordStoreException,
                     RecordStoreFullException
Adds a new record to the record store and associates the record with the given tag. This is a blocking atomic operation. The record data MUST be queued to be persisted before the method returns, and MUST be available for retrieval after the method returns. However, the record data MAY be written to persistent storage by the implementation after the method returns.

Parameters:
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 record
numBytes - the number of bytes of the data buffer to use for this record (may be zero)
tag - a tag value to identify the record.
Returns:
the recordId for the new record
Throws:
RecordStoreNotOpenException - if the record store is not open
RecordStoreException - if a different record store-related exception occurred
RecordStoreFullException - if the operation cannot be completed because the record store has no more room
java.lang.SecurityException - if the MIDlet has read-only access to the RecordStore
Since:
MIDP 3.0

deleteRecord

public void deleteRecord(int recordId)
                  throws RecordStoreNotOpenException,
                         InvalidRecordIDException,
                         RecordStoreException
The record is deleted from the record store; the recordId for this record MUST NOT be reused. This is a blocking atomic operation. The deletion operation MUST be queued to be persisted before the method returns, and the record associated with the recordId MUST NOT be available for retrieval after the method returns. However, the record deletion MAY be reflected in persistent storage by the implementation after the method returns. All the information related to the tag associated with the recordId MUST be removed as a result of this method call.

Parameters:
recordId - the ID of the record to delete
Throws:
RecordStoreNotOpenException - if the record store is not open
InvalidRecordIDException - if the recordId is invalid
RecordStoreException - if a general record store exception occurs
java.lang.SecurityException - if the MIDlet has read-only access to the RecordStore

getRecordSize

public int getRecordSize(int recordId)
                  throws RecordStoreNotOpenException,
                         InvalidRecordIDException,
                         RecordStoreException
Returns the size (in bytes) of the MIDlet data available in the given record.

Parameters:
recordId - the ID of the record to use in this operation
Returns:
the size (in bytes) of the MIDlet data available in the given record
Throws:
RecordStoreNotOpenException - if the record store is not open
InvalidRecordIDException - if the recordId is invalid
RecordStoreException - if a general record store exception occurs

getRecord

public int getRecord(int recordId,
                     byte[] buffer,
                     int offset)
              throws RecordStoreNotOpenException,
                     InvalidRecordIDException,
                     RecordStoreException
Returns the data stored in the given record.

Parameters:
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
Returns:
the number of bytes copied into the buffer, starting at index offset
Throws:
RecordStoreNotOpenException - if the record store is not open
InvalidRecordIDException - if the recordId is invalid
RecordStoreException - if a general record store exception occurs
java.lang.ArrayIndexOutOfBoundsException - if the record is larger than the buffer supplied
See Also:
setRecord(int, byte[], int, int)

getRecord

public byte[] getRecord(int recordId)
                 throws RecordStoreNotOpenException,
                        InvalidRecordIDException,
                        RecordStoreException
Returns a copy of the data stored in the given record.

Parameters:
recordId - the ID of the record to use in this operation
Returns:
the data stored in the given record. Note that if the record has no data, this method will return null.
Throws:
RecordStoreNotOpenException - if the record store is not open
InvalidRecordIDException - if the recordId is invalid
RecordStoreException - if a general record store exception occurs
See Also:
setRecord(int, byte[], int, int)

setRecord

public void setRecord(int recordId,
                      byte[] newData,
                      int offset,
                      int numBytes)
               throws RecordStoreNotOpenException,
                      InvalidRecordIDException,
                      RecordStoreException,
                      RecordStoreFullException
Sets the data in the given record to the provided new data. After this method returns, a call to getRecord(int recordId) will return an array of numBytes size containing the data supplied here. The record data MUST be queued to be persisted before the method returns, and MUST be available for retrieval after the method returns. However, the record data MAY be written to persistent storage by the implementation after the method returns. The tag value associated with the record is unchanged when this method is used to set the record data.

Parameters:
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
Throws:
RecordStoreNotOpenException - if the record store is not open
InvalidRecordIDException - if the recordId is invalid
RecordStoreException - if a general record store exception occurs
RecordStoreFullException - if the operation cannot be completed because the record store has no more room
java.lang.SecurityException - if the MIDlet has read-only access to the RecordStore
See Also:
getRecord(int, byte[], int)

setRecord

public void setRecord(int recordId,
                      byte[] newData,
                      int offset,
                      int numBytes,
                      int tag)
               throws RecordStoreNotOpenException,
                      InvalidRecordIDException,
                      RecordStoreException,
                      RecordStoreFullException
Sets the data in the given record to the provided new data. After this method returns, a call to getRecord(int recordId) will return an array of numBytes size containing the data supplied here. The record data MUST be queued to be persisted before the method returns, and MUST be available for retrieval after the method returns. However, the record data MAY be written to persistent storage by the implementation after the method returns. The existing tag is replaced with the new tag value.

Parameters:
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
tag - a tag value to identify the record.
Throws:
RecordStoreNotOpenException - if the record store is not open
InvalidRecordIDException - if the recordId is invalid
RecordStoreException - if a general record store exception occurs
RecordStoreFullException - if the operation cannot be completed because the record store has no more room
java.lang.SecurityException - if the MIDlet has read-only access to the RecordStore
Since:
MIDP 3.0
See Also:
getRecord(int, byte[], int)

enumerateRecords

public RecordEnumeration enumerateRecords(RecordFilter filter,
                                          RecordComparator comparator,
                                          boolean keepUpdated)
                                   throws RecordStoreNotOpenException
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 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. 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 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 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.
Returns:
an enumeration for traversing a set of records in the record store in an optionally specified order
Throws:
RecordStoreNotOpenException - if the record store is not open
See Also:
RecordEnumeration.rebuild()

enumerateRecords

public RecordEnumeration enumerateRecords(RecordFilter filter,
                                          RecordComparator comparator,
                                          boolean keepUpdated,
                                          int[] tags)
                                   throws RecordStoreNotOpenException
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 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. 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 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 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.
tags - An integer array of the tags that need to be matched. This is effectively an OR operation, since each record can contain only one tag. If tags is null, the filter and comparator are applied on all the records of the record store. If tags is empty, no records are selected and an empty RecordEnumeration is returned. For all other cases, the filter and comparator are applied on any record that matches any one of the tags in the tags array.
Returns:
an enumeration for traversing a set of records in the record store in an optionally specified order
Throws:
RecordStoreNotOpenException - if the record store is not open
Since:
MIDP 3.0
See Also:
RecordEnumeration.rebuild()

getTag

public int getTag(int recordId)
           throws RecordStoreNotOpenException,
                  InvalidRecordIDException,
                  RecordStoreException
Returns the tag associated with the recordId.

Parameters:
recordId - the ID of the record to use in this operation
Returns:
the tag associated with the recordId. If the record was added by addRecord(data,offset,numBytes), then 0 is returned.
Throws:
RecordStoreNotOpenException - if the record store is not open
InvalidRecordIDException - if the recordId is invalid
RecordStoreException - if a general record store exception occurs
Since:
MIDP 3.0

MIDP3.0

Send a comment or suggestionVersion 3.0 of Mobile Information Device Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-2009 Motorola Inc. Portions copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved.