|
MIDP3.0 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface RecordEnumeration
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. |
int |
getRecordId(int index)
Used to quickly find a record present at the specified index of the record enumeration. |
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. |
Method Detail |
---|
int numRecords()
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 open
RecordStoreException
- 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 open
RecordStoreException
- 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()
boolean hasPreviousElement()
void reset()
void rebuild()
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()
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.
int getRecordId(int index) throws java.lang.IllegalArgumentException
index
- The value of index is 0 to numRecords()-1.
java.lang.IllegalArgumentException
- If the value of index is less than 0 or greater than
numRecords()-1.
|
MIDP3.0 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |