Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.microedition.rms
Interface RecordEnumeration

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.

Since:
  MIDP 1.0

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

### numRecords

    public int numRecords()

  Returns the number of records available in this enumeration's set. That is, the number of records that have matched the filter criterion. Note that this forces the 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.

  Returns:
    the number of records available in this enumeration's set. That is, the number of records that have matched the filter criterion.

### nextRecord

    public byte[] nextRecord()
                      throws InvalidRecordIDException,
                             RecordStoreNotOpenException,
                             RecordStoreException

  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. The byte array returned is a copy of the record. Any changes made to this array will NOT be reflected in the record store. After calling this method, the enumeration is advanced to the next available record.

  Returns:
    the next record in this enumeration
  Throws:
    `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

### nextRecordId

    public int nextRecordId()
                     throws InvalidRecordIDException

  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. After calling this method, the enumeration is advanced to the next available record.

  Returns:
    the recordId of the next record in this enumeration
  Throws:
    `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.

### previousRecord

    public byte[] previousRecord()
                          throws InvalidRecordIDException,
                                 RecordStoreNotOpenException,
                                 RecordStoreException

  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. The byte array returned is a copy of the record. Any changes made to this array will NOT be reflected in the record store. After calling this method, the enumeration is advanced to the next (previous) available record.

  Returns:
    the previous record in this enumeration
  Throws:
    `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.

### previousRecordId

    public int previousRecordId()
                         throws InvalidRecordIDException

  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. After calling this method, the enumeration is advanced to the next (previous) available record.

  Returns:
    the recordId of the previous record in this enumeration
  Throws:
    `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.

### hasNextElement

    public boolean hasNextElement()

  Returns true if more elements exist in the next direction.

  Returns:
    true if more elements exist in the next direction

### hasPreviousElement

    public boolean hasPreviousElement()

  Returns true if more elements exist in the previous direction.

  Returns:
    true if more elements exist in the previous direction

### reset

    public void reset()

  Returns the enumeration index to the same state as right after the enumeration was created.

### rebuild

    public void rebuild()

  Request that the enumeration be updated to reflect the current record set. Useful for when a MIDlet makes a number of changes to the record store, and then wants an existing RecordEnumeration to enumerate the new changes.

  See Also:
    `keepUpdated(boolean)`

### keepUpdated

    public 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. Note that this should be used carefully due to the potential performance problems associated with maintaining the enumeration with every change.

  Parameters:
    `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.
  See Also:
    `rebuild()`

### isKeptUpdated

    public boolean isKeptUpdated()

  Returns true if the enumeration keeps its enumeration current with any changes in the records.

  Returns:
    true if the enumeration keeps its enumeration current with any changes in the records

### destroy

    public void destroy()

  Frees internal resources used by this RecordEnumeration. MIDlets should call this method when they are done using a RecordEnumeration. If a MIDlet tries to use a RecordEnumeration after this method has been called, it will throw a `IllegalStateException`. Note that this method is used for manually aiding in the minimization of immediate resource requirements when this enumeration is no longer needed.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 2.0 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright (c) 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.