FileDocCategorySizeDatePackage
AbstractRecordStoreImpl.javaAPI DocphoneME MR2 API (J2ME)15880Wed May 02 18:00:12 BST 2007com.sun.midp.rms

AbstractRecordStoreImpl

public interface AbstractRecordStoreImpl
An interface for a record store implementation.

Fields Summary
static final int
RS0_SIGNATURE
RS_SIGNATURE offset
static final int
RS1_AUTHMODE
RS_AUTHMODE offset
static final int
RS2_NEXT_ID
RS_NEXT_ID offset
static final int
RS3_NUM_LIVE
RS_NUM_LIVE offset
static final int
RS4_VERSION
RS_VERSION offset
static final int
RS5_LAST_MODIFIED
RS_LAST_MODIFIED offset
static final int
RS6_DATA_SIZE
RS_START_OF_DATA offset
static final int
RS7_FREE_SIZE
RS_START_OF_DATA offset
static final int
DB_HEADER_SIZE
Size of the db header
static final byte[]
DB_SIGNATURE
pre initialized RecordStore header structure
static final int
COMPACT_BUFFER_SIZE
used to compact the records of the record store
static final int
BLOCK_HEADER_SIZE
Size of the block header
static final int
AUTHMODE_ANY_RO
Internal indicator for AUTHMODE_ANY with read only access AUTHMODE_ANY_RO has a value of 2.
Constructors Summary
Methods Summary
public intaddRecord(byte[] data, int offset, int numBytes)
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.

param
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.
param
offset the index into the data buffer of the first relevant byte for this record
param
numBytes the number of bytes of the data buffer to use for this record (may be zero)
return
the recordId for the new record
exception
RecordStoreNotOpenException if the record store is not open
exception
RecordStoreException if a different record store-related exception occurred
exception
RecordStoreFullException if the operation cannot be completed because the record store has no more room
exception
SecurityException if the MIDlet has read-only access to the RecordStore

public voidcloseRecordStore()
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 is not open
exception
RecordStoreException if a different record store-related exception occurred

public AbstractRecordStoreFilecreateIndexFile(int suiteId, java.lang.String name)
Creates data base index file associated with this record store

return
data base index file
exception
IOException if failed to create a file

public voiddeleteRecord(int recordId)
The record is deleted from the record store. The recordId for this record is NOT reused.

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

public intgetAuthMode()
Get the authorization mode for this record store.

return
authorization mode

public AbstractRecordStoreFilegetDbFile()
Returns data base file associated with this record store

return
data base file

public longgetLastModified()
Returns the last time the record store was modified, in the format used by System.currentTimeMillis().

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

public intgetNextRecordID()
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().

return
the recordId of the next record to be added to the record store

public intgetNumRecords()
Returns the number of records currently in the record store.

return
the number of records currently in the record store

public intgetRecord(int recordId, byte[] buffer, int offset)
Returns the data stored in the given record.

param
recordId the ID of the record to use in this operation
param
buffer the byte array in which to copy the data
param
offset the index into the buffer in which to start copying
exception
RecordStoreNotOpenException if the record store is not open
exception
InvalidRecordIDException if the recordId is invalid
exception
RecordStoreException if a general record store exception occurs
exception
ArrayIndexOutOfBoundsException if the record is larger than the buffer supplied
return
the number of bytes copied into the buffer, starting at index offset
see
#setRecord

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

param
recordId the ID of the record to use in this operation
exception
RecordStoreNotOpenException if the record store is not open
exception
InvalidRecordIDException if the recordId is invalid
exception
RecordStoreException if a general record store exception occurs
return
the data stored in the given record. Note that if the record has no data, this method will return null.
see
#setRecord

public int[]getRecordIDs()
Returns all of the recordId's currently in the record store.

return
an array of the recordId's currently in the record store or null if the record store is closed.

public intgetRecordSize(int recordId)
Returns the size (in bytes) of the MIDlet data available in the given record.

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

public intgetSize()
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.

return
the size of the record store in bytes

public intgetSizeAvailable()
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.

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

public intgetVersion()
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.

return
the current record store version

public voidsetMode(int authmode, boolean writable)
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.

param
authmode the mode under which to check or create access. Must be one of AUTHMODE_PRIVATE or AUTHMODE_ANY.
param
writable true if the RecordStore is to be writable by other MIDlet suites that are granted access
exception
RecordStoreException if a record store-related exception occurred
exception
SecurityException if this MIDlet Suite is not allowed to change the mode of the RecordStore
exception
IllegalArgumentException if authmode is invalid

public voidsetRecord(int recordId, byte[] newData, int offset, int numBytes)
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.

param
recordId the ID of the record to use in this operation
param
newData the new data to store in the record
param
offset the index into the data buffer of the first relevant byte for this record
param
numBytes the number of bytes of the data buffer to use for this record
exception
RecordStoreNotOpenException if the record store is not open
exception
InvalidRecordIDException if the recordId is invalid
exception
RecordStoreException if a general record store exception occurs
exception
RecordStoreFullException if the operation cannot be completed because the record store has no more room
exception
SecurityException if the MIDlet has read-only access to the RecordStore
see
#getRecord