recordenumeration.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)RecordEnumeration.java	1.17 02/09/06 @(#)
 *
 * Portiona Copyright (c) 2000-2002 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Copyright 2000 Motorola, Inc. All Rights Reserved.
 * This notice does not imply publication.
 */

package javax.microedition.rms; 

/**
 * 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.
 *
 * <p>By using an optional <code>RecordFilter</code>, a subset of the
 * records can be chosen that match the supplied filter. This can be
 * used for providing search capabilities.</p>
 *
 * <p>By using an optional <code>RecordComparator</code>, the
 * enumerator can index through the records in an order determined by
 * the comparator. This can be used for providing sorting
 * capabilities.</p>
 *
 * <p>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.</p>
 *
 * <p>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 <code>hasNextElement()</code>
 * and <code>hasPreviousElement()</code> will return false.</p>
 *
 * <p>The first call to <code>nextRecord()</code> returns the record
 * data from the first record in the sequence. Subsequent calls to
 * <code>nextRecord()</code> return the next consecutive record's
 * data. To return the record data from the previous consecutive from
 * any given point in the enumeration, call
 * <code>previousRecord()</code>. On the other hand, if after
 * creation, the first call is to <code>previousRecord()</code>, the
 * record data of the last element of the enumeration will be
 * returned. Each subsequent call to <code>previousRecord()</code>
 * will step backwards through the sequence until the beginning is
 * reached.</p>
 *
 * <p>Final note, to do record store searches, create a
 * RecordEnumeration with no RecordComparator, and an appropriate
 * RecordFilter with the desired search criterion.</p>
 *
 * @since MIDP 1.0
 */

public interface RecordEnumeration
{
    /**
     * 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.
     *
     * @return the number of records available in this enumeration's
     *          set. That is, the number of records that have matched
     *          the filter criterion.
     */
    public int numRecords();

    /**
     * Returns a copy of the <em>next</em> record in this enumeration,
     * where <em>next</em> 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.
     *
     * @exception InvalidRecordIDException when no more records are
     *          available. Subsequent calls to this method will
     *          continue to throw this exception until
     *          <code>reset()</code> has been called to reset the
     *          enumeration.
     * @exception RecordStoreNotOpenException if the record store is
     *          not open
     * @exception RecordStoreException if a general record store
     *          exception occurs
     *
     * @return the next record in this enumeration
     */
    public byte[] nextRecord()
	throws InvalidRecordIDException, RecordStoreNotOpenException,
	RecordStoreException;

    /**
     * Returns the recordId of the <em>next</em> record in this enumeration,
     * where <em>next</em> 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.
     *
     * @exception InvalidRecordIDException when no more records are
     *          available. Subsequent calls to this method will
     *          continue to throw this exception until
     *          <code>reset()</code> has been called to reset the
     *          enumeration.
     *
     * @return the recordId of the next record in this enumeration
     */
    public int nextRecordId()
	throws InvalidRecordIDException;

    /**
     * Returns a copy of the <em>previous</em> record in this enumeration,
     * where <em>previous</em> 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.
     *
     * @exception InvalidRecordIDException when no more records are
     *          available. Subsequent calls to this method will
     *          continue to throw this exception until
     *          <code>reset()</code> has been called to reset the
     *          enumeration.
     * @exception RecordStoreNotOpenException if the record store is
     *          not open
     * @exception RecordStoreException if a general record store
     *          exception occurs.
     *
     * @return the previous record in this enumeration
     */
    public byte[] previousRecord()
	throws InvalidRecordIDException, RecordStoreNotOpenException,
	RecordStoreException;

    /**
     * Returns the recordId of the <em>previous</em> record in this
     * enumeration, where <em>previous</em> 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.
     *
     * @exception InvalidRecordIDException when no more records are
     *          available. Subsequent calls to this method will
     *          continue to throw this exception until
     *          <code>reset()</code> has been called to reset the
     *          enumeration.
     *
     * @return the recordId of the previous record in this enumeration
     */
    public int previousRecordId()
	throws InvalidRecordIDException;

    /**
     * Returns true if more elements exist in the <em>next</em> direction.
     *
     * @return true if more elements exist in the <em>next</em>
     *         direction
     */
    public boolean hasNextElement();

    /**
     * Returns true if more elements exist in the <em>previous</em> direction.
     *
     * @return true if more elements exist in the <em>previous</em>
     *         direction
     */
    public boolean hasPreviousElement();

    /**
     * Returns the enumeration index to the same state as right
     * after the enumeration was created.
     */
    public void reset();

    /**
     * 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 #keepUpdated
     */
    public void rebuild();

    /**
     * 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.
     *
     * @param 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
     *          <code>keepUpdated(true)</code> has the same effect as
     *          calling <code>RecordEnumeration.rebuild</code>: 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 #rebuild
     */
    public void keepUpdated(boolean keepUpdated);

    /**
     * Returns true if the enumeration keeps its enumeration
     * current with any changes in the records.
     *
     * @return true if the enumeration keeps its enumeration
     *          current with any changes in the records
     */
    public boolean isKeptUpdated();

    /**
     * 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
     * <code>IllegalStateException</code>. Note that this method is
     * used for manually aiding in the minimization of immediate
     * resource requirements when this enumeration is no longer
     * needed.
     */
    public void destroy();

}