javax.microedition.rms
Class RecordStore

java.lang.Object
  |
  +--javax.microedition.rms.RecordStore

public abstract class RecordStore

extends java.lang.Object

Incomplete Experimental Implementation

Constructor Summary

RecordStore()

Method Summary

abstract int	addRecord(byte[] data, int offset, int count) Adds a new record to the record store.
abstract void	addRecordListener(RecordListener listener) Adds the specified RecordListener.
abstract void	closeRecordStore() This method is called when the MIDlet requests to have the record store closed.
abstract void	deleteRecord(int recordId) The record is deleted from the record store.
static void	deleteRecordStore(java.lang.String recordStoreName) Deletes the named record store.
abstract long	getLastModified() Returns the last time the record store was modified, in the format used by System.currentTimeMillis().
abstract java.lang.String	getName() Returns the name of this RecordStore.
abstract int	getNextRecordID() Returns the recordId of the next record to be added to the record store.
abstract int	getNumRecords() Returns the number of records currently in the record store.
abstract byte[]	getRecord(int recordId) Returns a copy of the data stored in the given record.
abstract int	getRecord(int recordId, byte[] buffer, int offset) Returns the data stored in the given record.
abstract int	getRecordSize(int recordId) Returns the size (in bytes) of the application data available in the given record.
abstract int	getSize() Returns the amount of space, in bytes, that the record store occupies.
abstract int	getSizeAvailable() Returns the amount of additional room (in bytes) available for this record store to grow.
abstract int	getVersion() Each time a record store is modified (record added, modified, deleted), it's version is incremented.
static java.lang.String[]	listRecordStores() Returns an arry of names of record stores owned by the application if the stores are private.
static RecordStore	openRecordStore(java.lang.String recordStoreName, boolean createIfNecessary) Open (and possibly create) a record store.
abstract void	removeRecordListener(RecordListener listener) Removes the specified RecordListener.
abstract void	setRecord(int recordId, byte[] newData, int offset, int count) 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

Constructor Detail

RecordStore

public RecordStore()

Method Detail

addRecord

public abstract int addRecord(byte[] data,
                              int offset,
                              int count)
                       throws RecordStoreNotOpenException,
                              RecordStoreException,
                              RecordStoreFullException

Adds a new record to the record store.

Parameters:

data - The data to be stored in this record. If the record should have zero-length - no data - this parameter may be set to null

offset - The index of the data buffer of the first databyte for this record

Returns:

The recordid of the new record

Throws:

RecordStoreNotOpenException - if the record store is not yet open.

InvalidRecordIDException - if the recordId is invalid.

RecordStoreException - if a general recordstoreexception occurs.

addRecordListener

public abstract void addRecordListener(RecordListener listener)

Adds the specified RecordListener. NOT YET IMPLEMENTED

Parameters:

listener - The RecordChangedListener

closeRecordStore

public abstract void closeRecordStore()
                               throws RecordStoreNotOpenException,
                                      RecordStoreException

This method is called when the MIDlet requests to have the record store closed.

Throws:

RecordStoreNotOpenException - if the record store is not open

RecordStoreException - if another record store related Exception occurs

deleteRecord

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

The record is deleted from the record store.

Parameters:

recordId - The ID of the record to be deleted

Throws:

RecordStoreNotOpenException - if the record store is not open

RecordStoreException - if a different record store-related exception occurs

deleteRecordStore

public static void deleteRecordStore(java.lang.String recordStoreName)
                              throws RecordStoreException,
                                     RecordStoreNotFoundException

Deletes the named record store. NOT YET IMPLEMENTED

Parameters:

recordStoreName - The record store to be deleted

Throws:

RecordStoreNotFoundException - if the record store could not be found.

RecordStoreException - if a record store related exception occurs.

getLastModified

public abstract long getLastModified()
                              throws RecordStoreNotOpenException

Returns the last time the record store was modified, in the format used by System.currentTimeMillis(). NOT YET IMPLEMENTED

Returns:

the last time the record store was modified, in the same format used by System.currentTimeMillis ();

Throws:

RecordStoreNotOpenException - if the record store is not open.

getName

public abstract java.lang.String getName()
                                  throws RecordStoreNotOpenException

Returns the name of this RecordStore.

Returns:

the name of this record store

Throws:

RecordStoreNotOpenException - if the record store is not open.

getNextRecordID

public abstract int getNextRecordID()
                             throws RecordStoreNotOpenException,
                                    RecordStoreException

Returns the recordId of the next record to be added to the record store.

Returns:

the recordId of the record store to be added to this record store.

Throws:

RecordStoreNotOpenException - if the record store is not open.

RecordStoreException - if another record store related exception occurs

getNumRecords

public abstract int getNumRecords()
                           throws RecordStoreNotOpenException

Returns the number of records currently in the record store.

Returns:

the number of records currently in the opened record store

Throws:

RecordStoreNotOpenException - if the record store is not open.

getRecord

public abstract 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

Throws:

RecordStoreNotOpenException - if the record store is not open.

InvalidRecordIDException - if the record store is invalid.

RecordStoreException - if a general record store exception occurs.

getRecord

public abstract int getRecord(int recordId,
                              byte[] buffer,
                              int offset)
                       throws RecordStoreNotOpenException,
                              InvalidRecordIDException,
                              RecordStoreException,
                              java.lang.ArrayIndexOutOfBoundsException

Returns the data stored in the given record. NOT YET IMPLEMENTED

Parameters:

recordId - The ID of the record to be used in this operation.

buffer - The byte array to copy the data.

offset - The index index into the buffer i which to start copiying.

Returns:

the number of bytes copied into the buffer, startting at index offset

Throws:

RecordStoreNotOpenException - if the record store is not open.

InvalidRecordIDException - if the record store is invalid.

RecordStoreException - if a general record store exception occurs.

java.lang.ArrayIndexOutOfBoundsException - if the record is larger that the buffer supplied

getRecordSize

public abstract int getRecordSize(int recordId)
                           throws RecordStoreNotOpenException,
                                  InvalidRecordIDException,
                                  RecordStoreException

Returns the size (in bytes) of the application data available in the given record.

Parameters:

recordId - The ID of the record to be used in this operation.

Returns:

the size in bytes of the data available in the record

Throws:

RecordStoreNotOpenException - if the record store is not open.

InvalidRecordIDException - if the record store is invalid.

RecordStoreException - if a general record store exception occurs.

getSize

public abstract int getSize()
                     throws RecordStoreNotOpenException

Returns the amount of space, in bytes, that the record store occupies.

Returns:

the size of the record store in bytes

Throws:

RecordStoreNotOpenException - if the record store is not open.

getSizeAvailable

public abstract int getSizeAvailable()
                              throws RecordStoreNotOpenException

Returns the amount of additional room (in bytes) available for this record store to grow.

getVersion

public abstract int getVersion()
                        throws RecordStoreNotOpenException

Each time a record store is modified (record added, modified, deleted), it's version is incremented.

listRecordStores

public static java.lang.String[] listRecordStores()

Returns an arry of names of record stores owned by the application if the stores are private. Note that the function returns NULL if the application does not have any record stores.

Returns:

an array of the names of record stores.

openRecordStore

public static RecordStore openRecordStore(java.lang.String recordStoreName,
                                          boolean createIfNecessary)
                                   throws RecordStoreException,
                                          RecordStoreFullException,
                                          RecordStoreNotFoundException

Open (and possibly create) a record store. If this record store is already opened, this method returns a reference to the same RecordStore object.

Parameters:

recordStoreName - The unique name, not to exceed 32 characters, of the record store.

createIfNecesarry - If true, the record store will be created if necessary.

Returns:

The RecordStore object for the record store.

Throws:

RecordStoreException - if a record store-related exception occurs.

RecordStoreNotFoundException - if the record store could not be found

removeRecordListener

public abstract void removeRecordListener(RecordListener listener)

Removes the specified RecordListener.

Parameters:

listener - the RecordChangedListener

setRecord

public abstract void setRecord(int recordId,
                               byte[] newData,
                               int offset,
                               int count)
                        throws RecordStoreNotOpenException,
                               InvalidRecordIDException,
                               RecordStoreException,
                               RecordStoreFullException

Sets the data in the given record to that passed in.

Parameters:

recordId - The ID of the record store.

newdata - The new data buffer to store in the record.

offset - The index into the data buffer of the first new byte to be stored in the record.

count - The number of bytes of the data buffer to use for this record.