|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
An interface representing a bidirectional record store Record enumerator. The RecordEnumeration logically maintains a sequence of the recordId's of the records in a record store. The enumerator will iterate over all (or a subset, if an optional record filter has been supplied) of the records in an order determined by an optional record comparator.
By using an optional RecordFilter
, a subset of the
records can be chosen that match the supplied filter. This can be
used for providing search capabilities.
By using an optional RecordComparator
, the
enumerator can index through the records in an order determined by
the comparator. This can be used for providing sorting
capabilities.
If, while indexing through the enumeration, some records are deleted from the record store, the recordId's returned by the enumeration may no longer represent valid records. To avoid this problem, the RecordEnumeration can optionally become a listener of the RecordStore and react to record additions and deletions by recreating its internal index. Use special care when using this option however, in that every record addition, change and deletion will cause the index to be rebuilt, which may have serious performance impacts.
If the RecordStore used by this RecordEnumeration is closed,
this RecordEnumeration becomes invalid and all subsequent
operations performed on it may give invalid results or throw a
RecordStoreNotOpenException, even if the same RecordStore is later
opened again. In addition, calls to hasNextElement()
and hasPreviousElement()
will return false.
The first call to nextRecord()
returns the record
data from the first record in the sequence. Subsequent calls to
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 until the beginning is
reached.
Final note, to do record store searches, create a RecordEnumeration with no RecordComparator, and an appropriate RecordFilter with the desired search criterion.
Method Summary | |
void |
destroy()
Frees internal resources used by this RecordEnumeration. |
boolean |
hasNextElement()
Returns true if more elements exist in the next direction. |
boolean |
hasPreviousElement()
Returns true if more elements exist in the previous direction. |
boolean |
isKeptUpdated()
Returns true if the enumeration keeps its enumeration current with any changes in the records. |
void |
keepUpdated(boolean keepUpdated)
Used to set whether the enumeration will be keep its internal index up to date with the record store record additions/deletions/changes. |
byte[] |
nextRecord()
Returns a copy of the next record in this enumeration, where next is defined by the comparator and/or filter supplied in the constructor of this enumerator. |
int |
nextRecordId()
Returns the recordId of the next record in this enumeration, where next is defined by the comparator and/or filter supplied in the constructor of this enumerator. |
int |
numRecords()
Returns the number of records available in this enumeration's set. |
byte[] |
previousRecord()
Returns a copy of the previous record in this enumeration, where previous is defined by the comparator and/or filter supplied in the constructor of this enumerator. |
int |
previousRecordId()
Returns the recordId of the previous record in this enumeration, where previous is defined by the comparator and/or filter supplied in the constructor of this enumerator. |
void |
rebuild()
Request that the enumeration be updated to reflect the current record set. |
void |
reset()
Returns the enumeration index to the same state as right after the enumeration was created. |
Method Detail |
public int numRecords()
public byte[] nextRecord() throws InvalidRecordIDException, RecordStoreNotOpenException, RecordStoreException
InvalidRecordIDException
- when no more records are
available. Subsequent calls to this method will
continue to throw this exception until
reset()
has been called to reset the
enumeration.RecordStoreNotOpenException
- if the record store is
not openRecordStoreException
- if a general record store
exception occurspublic int nextRecordId() throws InvalidRecordIDException
InvalidRecordIDException
- when no more records are
available. Subsequent calls to this method will
continue to throw this exception until
reset()
has been called to reset the
enumeration.public byte[] previousRecord() throws InvalidRecordIDException, RecordStoreNotOpenException, RecordStoreException
InvalidRecordIDException
- when no more records are
available. Subsequent calls to this method will
continue to throw this exception until
reset()
has been called to reset the
enumeration.RecordStoreNotOpenException
- if the record store is
not openRecordStoreException
- if a general record store
exception occurs.public int previousRecordId() throws InvalidRecordIDException
InvalidRecordIDException
- when no more records are
available. Subsequent calls to this method will
continue to throw this exception until
reset()
has been called to reset the
enumeration.public boolean hasNextElement()
public boolean hasPreviousElement()
public void reset()
public void rebuild()
keepUpdated(boolean)
public void keepUpdated(boolean keepUpdated)
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. Calling
keepUpdated(true)
has the same effect as
calling RecordEnumeration.rebuild
: the
enumeration will be updated to reflect the current
record set. 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.rebuild()
public boolean isKeptUpdated()
public void destroy()
IllegalStateException
. Note that this method is
used for manually aiding in the minimization of immediate
resource requirements when this enumeration is no longer
needed.
|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |