public interface RecordEnumeration
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.
Modifier and Type | Method and Description |
---|---|
void |
destroy()
Frees internal resources used by this
RecordEnumeration . |
int |
getRecordId(int index)
Used to quickly find a record present at the specified index of the
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()
Resets the iteration index back to 0, it does not rollback
the changes if records were deleted.
|
int numRecords()
RecordEnumeration
to fully build the enumeration by applying the filter to all
records, which may take a non-trivial amount
of time if there are a lot of records in the record store.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 occursint 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.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.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.boolean hasNextElement()
true
if more elements exist in the next direction.true
if more elements exist in the next direction,
otherwise false
boolean hasPreviousElement()
true
if more elements exist in the previous direction.true
if more elements exist in the previous
direction, otherwise false
void reset()
void rebuild()
RecordEnumeration
to enumerate the new
changes.
The rebuild
method updates the existing enumeration and it doesn't
create a new enumeration.
This method is useful when keepUpdated == false
.keepUpdated(boolean)
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()
boolean isKeptUpdated()
true
if the enumeration keeps its enumeration
current with any changes in the records.true
if the enumeration keeps its enumeration
current with any changes in the records, false
otherwisevoid destroy()
RecordEnumeration
.
Applications should call this method when they are done using a
RecordEnumeration
. If an application tries to use a
RecordEnumeration
after this method has been
called, it will throw an IllegalStateException
. Note that
this method is used for manually aiding in the minimization of immediate
resource requirements when this enumeration is no longer needed.int getRecordId(int index) throws java.lang.IllegalArgumentException
RecordEnumeration
.
It is recommended to use keepUpdated = false
with this method. The
behavior when keepUpdated == true
is used is implementation dependent.
Calling this method doesn't change the current iteration index of the
enumeration.index
- The value of index is 0 to numRecords()-1.RecordEnumeration
java.lang.IllegalArgumentException
- If the value of index is less than 0 or greater than
numRecords()-1.Copyright (c) 2014, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.