public class RecordStore
extends java.lang.Object
implements java.lang.AutoCloseable
Modifier and Type | Field and Description |
---|---|
static int |
AUTHMODE_ANY
Authorization to allow access to any application suites.
|
static int |
AUTHMODE_PRIVATE
Authorization to allow access only to the current application suite.
|
Modifier and Type | Method and Description |
---|---|
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 |
close()
Implementation of the
AutoCloseable interface. |
void |
closeRecordStore()
This method is called when the application requests to have the
record store closed.
|
void |
deleteRecord(int recordId)
The record is deleted from the record store.
|
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.
|
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 application data available
in the given record.
|
RecordStoreInfo |
getRecordStoreInfo()
Gets a
RecordStoreInfo instance for this RecordStore . |
int |
getSize()
Deprecated.
Previously calls to
getSize() could not
accomodate 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 accomodate 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. |
int |
getSizeAvailable()
Deprecated.
Previously calls to
getSize() could not
accomodate 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 accomodate 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 extran application-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. |
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 java.lang.String[] |
listRecordStores()
Returns an array of the names of record stores owned by the
application suite.
|
static RecordStore |
openRecordStore(java.lang.String recordStoreName,
boolean createIfNecessary)
Open (and possibly create) a record store associated with the current
application 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
application 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
application suites.
|
static RecordStore |
openRecordStore(java.lang.String recordStoreName,
java.lang.String vendorName,
java.lang.String suiteName)
Open a record store associated with the named application 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 application 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.
|
public static final int AUTHMODE_PRIVATE
AUTHMODE_PRIVATE
has a value of 0.public static final int AUTHMODE_ANY
AUTHMODE_ANY
has a value of 1.public static void deleteRecordStore(java.lang.String recordStoreName) throws RecordStoreException, RecordStoreNotFoundException
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
.recordStoreName
- the application suite unique record store to deleteRecordStoreException
- if a record store-related exception occurredRecordStoreNotFoundException
- if the record store could not be foundpublic static RecordStore openRecordStore(java.lang.String recordStoreName, boolean createIfNecessary) throws RecordStoreException, RecordStoreFullException, RecordStoreNotFoundException
RecordStore
object.recordStoreName
- the application 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 necessaryRecordStore
object for the record storeRecordStoreException
- if a record store-related exception occurredRecordStoreNotFoundException
- if the record store could not be foundRecordStoreFullException
- if the operation cannot be completed because the record
store is fulljava.lang.IllegalArgumentException
- if recordStoreName is invalidpublic static RecordStore openRecordStore(java.lang.String recordStoreName, boolean createIfNecessary, int authmode, boolean writeable) throws RecordStoreException, RecordStoreFullException, RecordStoreNotFoundException
The RecordStore
is owned by the
current application suite. The
authorization mode is set when the record store is created, as follows:
AUTHMODE_PRIVATE
- Only allows the application suite that
created the RecordStore
to access it.
This case behaves identically to
openRecordStore(recordStoreName, createIfNecessary)
.AUTHMODE_ANY
- Allows any application to access the
RecordStore
. Note that this makes your record store
accessible by any other application on the device. This
could have privacy and security issues depending on
the data being shared. Please use carefully.
The owning application suite may always access the RecordStore
and always
has access to write and update the store.
If this method is called by the application when the record store is already
open by the same application, this method returns a reference to the same
RecordStore
object.
recordStoreName
- the application 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 necessaryauthmode
- 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.writeable
- true if the RecordStore is to be writable by other application
suites that are granted access. This argument is ignored if
the RecordStore exists.RecordStore
object for the record storeRecordStoreException
- if a record store-related exception occurredRecordStoreNotFoundException
- if the record store could not be foundRecordStoreFullException
- if the operation cannot be completed because the record
store is fulljava.lang.IllegalArgumentException
- if authmode or recordStoreName is invalidpublic static RecordStore openRecordStore(java.lang.String recordStoreName, java.lang.String vendorName, java.lang.String suiteName) throws RecordStoreException, RecordStoreNotFoundException
AUTHMODE_PRIVATE
- Succeeds only if
vendorName
and suiteName
identify the
current application suite; this case behaves identically to
openRecordStore(recordStoreName,
createIfNecessary)
.AUTHMODE_ANY
- Always succeeds.
Note that this makes your recordStore
accessible by any other application on the device. This
could have privacy and security issues depending on
the data being shared. Please use carefully.
Untrusted application suites are allowed to share data but
this is not recommended. The authenticity of the
origin of untrusted application suites cannot be verified
so shared data may be used unscrupulously.
If this method is called by an application when the record store is already
open by the same application, this method returns a reference to the same
RecordStore
object.
If an application 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.
recordStoreName
- the application suite unique name for the record store, consisting
of between one and 32 Unicode characters inclusive.vendorName
- the vendor of the owning application suitesuiteName
- the name of the application suiteRecordStore
object for the record storeRecordStoreException
- if a record store-related exception occurredRecordStoreNotFoundException
- if the record store could not be foundjava.lang.SecurityException
- if this application suite is not allowed to open the specified
RecordStore.java.lang.IllegalArgumentException
- if recordStoreName is invalidpublic static RecordStore openRecordStore(java.lang.String recordStoreName, boolean createIfNecessary, int authmode, boolean writeable, java.lang.String password) throws RecordStoreException, RecordStoreFullException, RecordStoreNotFoundException, SecureRecordStoreException
RecordStore
is owned by the current application 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 application suite accessing the secure record store should also release references to plaintext records as soon as possible.
The owning application suite may always access the RecordStore
and
always has access to write and update the store.
If this method is called by an application when the record store is already
open by the same application, this method returns a reference to the same
RecordStore
object.
recordStoreName
- The application 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 or AUTHMODE_ANY. This
argument is ignored if the RecordStore exists.writeable
- true if the RecordStore is to be writeable by other application
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.RecordStore
object for the record storeRecordStoreException
- If a record store-related exception occurredRecordStoreNotFoundException
- If the record store could not be foundRecordStoreFullException
- If the operation cannot be completed because the record store is fullSecureRecordStoreException
- If there is an internal error while making the record store secure
(e.g. an error occurs while initializing cryptographic functions)java.lang.SecurityException
- if the recordStoreName
corresponds to an existing
RecordStore
in the current suite and the password
does not match that of the existing RecordStorejava.lang.IllegalArgumentException
- if recordStoreName is invalidpublic 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 application suite. The application
suite is identified by application vendor and application name. Access is granted
only if the authorization mode of the RecordStore
allows
access by the current application suite. Access is limited by the authorization
mode set when the record store was created.
If this method is called by an application when the record store is already
open by the same application, this method returns a reference to the same
RecordStore
object.
If an application 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)
recordStoreName
- the unique name for the record store, consisting of between one
and 32 Unicode characters inclusive.vendorName
- the vendor of the owning application suitesuiteName
- the name of the application suite.password
- the password for use in decrypting the record store.RecordStore
object for the record storeRecordStoreException
- if a record store-related exception occurredRecordStoreNotFoundException
- if the record store could not be foundjava.lang.SecurityException
- if the calling application suite is not allowed to open the specified RecordStore
, or
if the recordStoreName
corresponds to an existing
RecordStore
in the current application suite and the password
does not match that of the existing RecordStore
java.lang.IllegalArgumentException
- if any of the vendor name, suite name or record store name are invalidSecureRecordStoreException
- If there is an internal error while making the record store secure
(e.g. an error occurs while initializing cryptographic functions)public RecordStoreInfo getRecordStoreInfo() throws RecordStoreNotOpenException
RecordStoreInfo
instance for this RecordStore
.RecordStoreInfo
object for the RecordStore
RecordStoreNotOpenException
- if the record store is not openpublic void setMode(int authmode, boolean writeable) throws RecordStoreException
RecordStore
. Please use this
method carefully. The authorization mode choices are:
AUTHMODE_PRIVATE
- Only allows the application
suite that created the RecordStore
to access it.
This case behaves identically to
openRecordStore(recordStoreName, createIfNecessary)
.AUTHMODE_ANY
- Allows any application to access the
RecordStore
. Note that this makes your record store
accessible by any other application on the device. This
could have privacy and security issues depending on
the data being shared. Please use carefully.
The owning application suite may always access the RecordStore
and always has access to write and update the store. Only the
owning application suite can change the mode of a RecordStore
.
This method can only be called if this record store is NOT open by an
application in this suite or in a different application suite. If this record store
is open by any application, an IllegalStateException
will be
thrown by the method.
authmode
- the mode under which to check or create access.
Must be one of AUTHMODE_PRIVATE
or AUTHMODE_ANY
.writeable
- true
if the RecordStore
is to
be writable by other application suites that are granted accessRecordStoreException
- if a record store-related
exception occurredjava.lang.SecurityException
- if this application suite is not
allowed to change the mode of the RecordStore
java.lang.IllegalArgumentException
- if authmode
is invalidjava.lang.IllegalStateException
- if any application from this application suite or a
different application suite has the RecordStore
openpublic void closeRecordStore() throws RecordStoreNotOpenException, RecordStoreException
closeRecordStore()
is
called as many times as openRecordStore
was called.
In other words, the application 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 RecordEnumeration
s associated with it become invalid.
If the application attempts to perform operations on the
RecordStore
object after it has been closed,
the methods will throw a RecordStoreNotOpenException
.
RecordStoreNotOpenException
- if the record store is
not openRecordStoreException
- if a different record
store-related exception occurredpublic void close()
AutoCloseable
interface. This method
MUST close the RecordStore
by calling the
closeRecordStore()
method (there exist both method in order to
guarantee backward compatibility to IMP-NG).close
in interface java.lang.AutoCloseable
public static java.lang.String[] listRecordStores()
null
.
The order of RecordStore
names returned is implementation dependent.
null
.public java.lang.String getName() throws RecordStoreNotOpenException
RecordStoreNotOpenException
- if the record store is not openpublic int getVersion() throws RecordStoreNotOpenException
addRecord
,
setRecord
, or
deleteRecord
methods) its
version is incremented. This can be used by applications 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.
RecordStoreNotOpenException
- if the record store is not openpublic int getNumRecords() throws RecordStoreNotOpenException
RecordStore
can contain is
Integer.MAX_VALUE
.RecordStoreNotOpenException
- if the record store is not open@Deprecated public int getSize() throws RecordStoreNotOpenException
getSize()
could not
accomodate 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 accomodate 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.Integer.MAX-VALUE
, then
Integer.MAX-VALUE
MUST be returned.RecordStoreNotOpenException
- if the record store is
not open@Deprecated public int getSizeAvailable() throws RecordStoreNotOpenException
getSize()
could not
accomodate 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 accomodate 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 extran application-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.Integer.MAX-VALUE
, then Integer.MAX-VALUE
MUST be returned.RecordStoreNotOpenException
- if the record store is
not openpublic long getLastModified() throws RecordStoreNotOpenException
System.currentTimeMillis()
.System.currentTimeMillis()
RecordStoreNotOpenException
- if the record store is not openpublic void addRecordListener(RecordListener listener)
listener
- the RecordListenerremoveRecordListener(javax.microedition.rms.RecordListener)
public void removeRecordListener(RecordListener listener)
listener
- the RecordChangedListeneraddRecordListener(javax.microedition.rms.RecordListener)
public int getNextRecordID() throws RecordStoreNotOpenException, RecordStoreException
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()
.recordId
of the next record to be added to the
record storeRecordStoreNotOpenException
- if the record store is not openRecordStoreException
- if a different record store-related exception occurredpublic int addRecord(byte[] data, int offset, int numBytes) throws RecordStoreNotOpenException, RecordStoreException, RecordStoreFullException
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.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 recordnumBytes
- the number of bytes of the data buffer to use for this record
(may be zero)recordId
for the new recordRecordStoreNotOpenException
- if the record store is not openRecordStoreException
- if a different record store-related exception occurredRecordStoreFullException
- if the operation cannot be completed because the record
store has no more roomjava.lang.SecurityException
- if the application has read-only access to the RecordStorejava.lang.ArrayIndexOutOfBoundsException
- if either offset
or numBytes
is negative, or
if offset + numBytes > data.length
public int addRecord(byte[] data, int offset, int numBytes, int tag) throws RecordStoreNotOpenException, RecordStoreException, RecordStoreFullException
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.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 recordnumBytes
- the number of bytes of the data buffer to use for this record
(may be zero)tag
- a tag value to identify the record.RecordStoreNotOpenException
- if the record store is not openRecordStoreException
- if a different record store-related exception occurredRecordStoreFullException
- if the operation cannot be completed because the record
store has no more roomjava.lang.SecurityException
- if the application has read-only access to the RecordStorejava.lang.ArrayIndexOutOfBoundsException
- if either offset
or numBytes
is negative, or
if offset + numBytes > data.length
public void deleteRecord(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
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.recordId
- the ID of the record to deleteRecordStoreNotOpenException
- if the record store is not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store exception occursjava.lang.SecurityException
- if the application has read-only access to the RecordStorepublic int getRecordSize(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- the ID of the record to use in this operationRecordStoreNotOpenException
- if the record store is not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store exception occurspublic int getRecord(int recordId, byte[] buffer, int offset) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- the ID of the record to use in this operationbuffer
- the byte array in which to copy the dataoffset
- the index into the buffer in which to start copyingoffset
RecordStoreNotOpenException
- if the record store is not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store exception occursjava.lang.ArrayIndexOutOfBoundsException
- if the record is larger than the buffer supplied, or
if offset
is negative or greater than or equal to the buffer
lengthsetRecord(int, byte[], int, int)
public byte[] getRecord(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
- the ID of the record to use in this operationnull
.RecordStoreNotOpenException
- if the record store is not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store exception occurssetRecord(int, byte[], int, int)
public void setRecord(int recordId, byte[] newData, int offset, int numBytes) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException, RecordStoreFullException
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.recordId
- the ID of the record to use in this operationnewData
- the new data to store in the record. If the record is to become
zero-length data (no data, means existing data to be overwritten),
this parameter may be null.offset
- the index into the data buffer of the first relevant byte for
this recordnumBytes
- the number of bytes of the data buffer to use for this recordRecordStoreNotOpenException
- if the record store is not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store exception occursRecordStoreFullException
- if the operation cannot be completed because the record
store has no more roomjava.lang.SecurityException
- if the application has read-only access to the RecordStorejava.lang.ArrayIndexOutOfBoundsException
- if either offset
or numBytes
is negative, or
if offset + numBytes > newData.length
getRecord(int, byte[], int)
public void setRecord(int recordId, byte[] newData, int offset, int numBytes, int tag) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException, RecordStoreFullException
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.recordId
- the ID of the record to use in this operationnewData
- the new data to store in the record. If the record is to become
zero-length data (no data, means existing data to be overwritten),
this parameter may be null.offset
- the index into the data buffer of the first relevant byte for
this recordnumBytes
- the number of bytes of the data buffer to use for this recordtag
- a tag value to identify the record.RecordStoreNotOpenException
- if the record store is not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store exception occursRecordStoreFullException
- if the operation cannot be completed because the record
store has no more roomjava.lang.SecurityException
- if the application has read-only access to the RecordStorejava.lang.ArrayIndexOutOfBoundsException
- if either offset
or numBytes
is negative, or
if offset + numBytes > newData.length
getRecord(int, byte[], int)
public RecordEnumeration enumerateRecords(RecordFilter filter, RecordComparator comparator, boolean keepUpdated) throws RecordStoreNotOpenException
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.
filter
- if non-null, will be used to determine what subset of the
record store records will be usedcomparator
- if non-null, will be used to determine the order in which the
records are returnedkeepUpdated
- 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.RecordStoreNotOpenException
- if the record store is not openRecordEnumeration.rebuild()
public RecordEnumeration enumerateRecords(RecordFilter filter, RecordComparator comparator, boolean keepUpdated, int[] tags) throws RecordStoreNotOpenException
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.
filter
- if non-null, will be used to determine what subset of the
record store records will be usedcomparator
- if non-null, will be used to determine the order in which the
records are returnedkeepUpdated
- 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.RecordStoreNotOpenException
- if the record store is not openRecordEnumeration.rebuild()
public int getTag(int recordId) throws RecordStoreNotOpenException, InvalidRecordIDException, RecordStoreException
recordId
.recordId
- the ID of the record to use in this operationaddRecord(data,offset,numBytes)
, then 0 is returned.RecordStoreNotOpenException
- if the record store is not openInvalidRecordIDException
- if the recordId is invalidRecordStoreException
- if a general record store exception occursCopyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.