Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IM Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.rms
Class RecordStore

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

public class RecordStore
extends Object

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.

Since:
  MIDP 1.0

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

### 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

Method Detail

### deleteRecordStore

    public static void deleteRecordStore(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(String recordStoreName,
                                              boolean createIfNecessary)
                                       throws RecordStoreException,
                                              RecordStoreFullException,
                                              RecordStoreNotFoundException

  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 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
    `IllegalArgumentException` - if recordStoreName is invalid

### openRecordStore

    public static RecordStore openRecordStore(String recordStoreName,
                                              boolean createIfNecessary,
                                              int authmode,
                                              boolean writable)
                                       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:
  - `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 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 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.
  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
    `SecurityException` - if this MIDlet Suite is not allowed to open or create the specified RecordStore
    `IllegalArgumentException` - if authmode or recordStoreName is invalid
  Since:
    MIDP 2.0 [Siemens WM]
    In TC65 the params authmode and writable have no effect.

### openRecordStore

    public static RecordStore openRecordStore(String recordStoreName,
                                              String vendorName,
                                              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:
  - `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)``

  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
    `SecurityException` - if this MIDlet Suite is not allowed to open the specified RecordStore.
    `IllegalArgumentException` - if recordStoreName is invalid
  Since:
    MIDP 2.0

### setMode

    public void setMode(int authmode,
                        boolean writable)
                 throws RecordStoreException

  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.
    `writable` - true if the RecordStore is to be writable by other MIDlet suites that are granted access
  Throws:
    `RecordStoreException` - if a record store-related exception occurred
    `SecurityException` - if this MIDlet Suite is not allowed to change the mode of the RecordStore
    `IllegalArgumentException` - if authmode is invalid
  Since:
    MIDP 2.0 [Siemens WM]
    In TC65 the params authmode and writable have no effect.

### 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 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 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.

  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

  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.

  Returns:
    the size of the record store in bytes
  Throws:
    `RecordStoreNotOpenException` - if the record store is not open

### getSizeAvailable

    public int getSizeAvailable()
                         throws RecordStoreNotOpenException

  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.

  Returns:
    the amount of additional room (in bytes) available for this record store to grow
  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.

  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. 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 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
    `SecurityException` - if the MIDlet has read-only access to the RecordStore

### deleteRecord

    public void deleteRecord(int recordId)
                      throws RecordStoreNotOpenException,
                             InvalidRecordIDException,
                             RecordStoreException

  The record is deleted from the record store. The recordId for this record is NOT reused.

  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
    `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
    `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 that passed in. After this method returns, a call to `getRecord(int recordId)` will return an array of numBytes size containing the data supplied here.

  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
    `SecurityException` - if the MIDlet has read-only access to the RecordStore
  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 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 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()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| IM Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 2.0 of IM Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.