001: /*
002: *
003: *
004: * Portions Copyright 2000-2007 Sun Microsystems, Inc. All Rights
005: * Reserved. Use is subject to license terms.
006: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
007: *
008: * This program is free software; you can redistribute it and/or
009: * modify it under the terms of the GNU General Public License version
010: * 2 only, as published by the Free Software Foundation.
011: *
012: * This program is distributed in the hope that it will be useful, but
013: * WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * General Public License version 2 for more details (a copy is
016: * included at /legal/license.txt).
017: *
018: * You should have received a copy of the GNU General Public License
019: * version 2 along with this work; if not, write to the Free Software
020: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
021: * 02110-1301 USA
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
024: * Clara, CA 95054 or visit www.sun.com if you need additional
025: * information or have any questions.
026: *
027: * Copyright 2000 Motorola, Inc. All Rights Reserved.
028: * This notice does not imply publication.
029: */
030:
031: package javax.microedition.rms;
032:
033: /**
034: * An interface representing a bidirectional record store Record
035: * enumerator. The RecordEnumeration logically maintains a sequence of
036: * the recordId's of the records in a record store. The enumerator
037: * will iterate over all (or a subset, if an optional record filter
038: * has been supplied) of the records in an order determined by an
039: * optional record comparator.
040: *
041: * <p>By using an optional <code>RecordFilter</code>, a subset of the
042: * records can be chosen that match the supplied filter. This can be
043: * used for providing search capabilities.</p>
044: *
045: * <p>By using an optional <code>RecordComparator</code>, the
046: * enumerator can index through the records in an order determined by
047: * the comparator. This can be used for providing sorting
048: * capabilities.</p>
049: *
050: * <p>If, while indexing through the enumeration, some records are
051: * deleted from the record store, the recordId's returned by the
052: * enumeration may no longer represent valid records. To avoid this
053: * problem, the RecordEnumeration can optionally become a listener of
054: * the RecordStore and react to record additions and deletions by
055: * recreating its internal index. Use special care when using this
056: * option however, in that every record addition, change and deletion
057: * will cause the index to be rebuilt, which may have serious
058: * performance impacts.</p>
059: *
060: * <p>If the RecordStore used by this RecordEnumeration is closed,
061: * this RecordEnumeration becomes invalid and all subsequent
062: * operations performed on it may give invalid results or throw a
063: * RecordStoreNotOpenException, even if the same RecordStore is later
064: * opened again. In addition, calls to <code>hasNextElement()</code>
065: * and <code>hasPreviousElement()</code> will return false.</p>
066: *
067: * <p>The first call to <code>nextRecord()</code> returns the record
068: * data from the first record in the sequence. Subsequent calls to
069: * <code>nextRecord()</code> return the next consecutive record's
070: * data. To return the record data from the previous consecutive from
071: * any given point in the enumeration, call
072: * <code>previousRecord()</code>. On the other hand, if after
073: * creation, the first call is to <code>previousRecord()</code>, the
074: * record data of the last element of the enumeration will be
075: * returned. Each subsequent call to <code>previousRecord()</code>
076: * will step backwards through the sequence until the beginning is
077: * reached.</p>
078: *
079: * <p>Final note, to do record store searches, create a
080: * RecordEnumeration with no RecordComparator, and an appropriate
081: * RecordFilter with the desired search criterion.</p>
082: *
083: * @since MIDP 1.0
084: */
085:
086: public interface RecordEnumeration {
087: /**
088: * Returns the number of records available in this enumeration's
089: * set. That is, the number of records that have matched the
090: * filter criterion. Note that this forces the RecordEnumeration
091: * to fully build the enumeration by applying the filter to all
092: * records, which may take a non-trivial amount
093: * of time if there are a lot of records in the record store.
094: *
095: * @return the number of records available in this enumeration's
096: * set. That is, the number of records that have matched
097: * the filter criterion.
098: */
099: public int numRecords();
100:
101: /**
102: * Returns a copy of the <em>next</em> record in this enumeration,
103: * where <em>next</em> is defined by the comparator and/or filter
104: * supplied in the constructor of this enumerator. The byte array
105: * returned is a copy of the record. Any changes made to this array
106: * will NOT be reflected in the record store. After calling
107: * this method, the enumeration is advanced to the next available
108: * record.
109: *
110: * @exception InvalidRecordIDException when no more records are
111: * available. Subsequent calls to this method will
112: * continue to throw this exception until
113: * <code>reset()</code> has been called to reset the
114: * enumeration.
115: * @exception RecordStoreNotOpenException if the record store is
116: * not open
117: * @exception RecordStoreException if a general record store
118: * exception occurs
119: *
120: * @return the next record in this enumeration
121: */
122: public byte[] nextRecord() throws InvalidRecordIDException,
123: RecordStoreNotOpenException, RecordStoreException;
124:
125: /**
126: * Returns the recordId of the <em>next</em> record in this enumeration,
127: * where <em>next</em> is defined by the comparator and/or filter
128: * supplied in the constructor of this enumerator. After calling
129: * this method, the enumeration is advanced to the next available
130: * record.
131: *
132: * @exception InvalidRecordIDException when no more records are
133: * available. Subsequent calls to this method will
134: * continue to throw this exception until
135: * <code>reset()</code> has been called to reset the
136: * enumeration.
137: *
138: * @return the recordId of the next record in this enumeration
139: */
140: public int nextRecordId() throws InvalidRecordIDException;
141:
142: /**
143: * Returns a copy of the <em>previous</em> record in this enumeration,
144: * where <em>previous</em> is defined by the comparator and/or filter
145: * supplied in the constructor of this enumerator. The byte array
146: * returned is a copy of the record. Any changes made to this array
147: * will NOT be reflected in the record store. After calling
148: * this method, the enumeration is advanced to the next (previous)
149: * available record.
150: *
151: * @exception InvalidRecordIDException when no more records are
152: * available. Subsequent calls to this method will
153: * continue to throw this exception until
154: * <code>reset()</code> has been called to reset the
155: * enumeration.
156: * @exception RecordStoreNotOpenException if the record store is
157: * not open
158: * @exception RecordStoreException if a general record store
159: * exception occurs.
160: *
161: * @return the previous record in this enumeration
162: */
163: public byte[] previousRecord() throws InvalidRecordIDException,
164: RecordStoreNotOpenException, RecordStoreException;
165:
166: /**
167: * Returns the recordId of the <em>previous</em> record in this
168: * enumeration, where <em>previous</em> is defined by the
169: * comparator and/or filter supplied in the constructor of this
170: * enumerator. After calling this method, the enumeration is
171: * advanced to the next (previous) available record.
172: *
173: * @exception InvalidRecordIDException when no more records are
174: * available. Subsequent calls to this method will
175: * continue to throw this exception until
176: * <code>reset()</code> has been called to reset the
177: * enumeration.
178: *
179: * @return the recordId of the previous record in this enumeration
180: */
181: public int previousRecordId() throws InvalidRecordIDException;
182:
183: /**
184: * Returns true if more elements exist in the <em>next</em> direction.
185: *
186: * @return true if more elements exist in the <em>next</em>
187: * direction
188: */
189: public boolean hasNextElement();
190:
191: /**
192: * Returns true if more elements exist in the <em>previous</em> direction.
193: *
194: * @return true if more elements exist in the <em>previous</em>
195: * direction
196: */
197: public boolean hasPreviousElement();
198:
199: /**
200: * Returns the enumeration index to the same state as right
201: * after the enumeration was created.
202: */
203: public void reset();
204:
205: /**
206: * Request that the enumeration be updated to reflect the current
207: * record set. Useful for when a MIDlet
208: * makes a number of changes to the record store, and then wants an
209: * existing RecordEnumeration to enumerate the new changes.
210: *
211: * @see #keepUpdated
212: */
213: public void rebuild();
214:
215: /**
216: * Used to set whether the enumeration will be keep its internal
217: * index up to date with the record store record
218: * additions/deletions/changes. Note that this should
219: * be used carefully due to the potential performance problems
220: * associated with maintaining the enumeration with every change.
221: *
222: * @param keepUpdated if true, the enumerator will keep its
223: * enumeration current with any changes in the records of
224: * the record store. Use with caution as there are
225: * possible performance consequences. Calling
226: * <code>keepUpdated(true)</code> has the same effect as
227: * calling <code>RecordEnumeration.rebuild</code>: the
228: * enumeration will be updated to reflect the current
229: * record set. If false the enumeration will not be kept
230: * current and may return recordIds for records that have
231: * been deleted or miss records that are added later. It
232: * may also return records out of order that have been
233: * modified after the enumeration was built. Note that
234: * any changes to records in the record store are
235: * accurately reflected when the record is later
236: * retrieved, either directly or through the
237: * enumeration. The thing that is risked by setting this
238: * parameter false is the filtering and sorting order of
239: * the enumeration when records are modified, added, or
240: * deleted.
241: *
242: * @see #rebuild
243: */
244: public void keepUpdated(boolean keepUpdated);
245:
246: /**
247: * Returns true if the enumeration keeps its enumeration
248: * current with any changes in the records.
249: *
250: * @return true if the enumeration keeps its enumeration
251: * current with any changes in the records
252: */
253: public boolean isKeptUpdated();
254:
255: /**
256: * Frees internal resources used by this RecordEnumeration.
257: * MIDlets should call this method when they are done using a
258: * RecordEnumeration. If a MIDlet tries to use a RecordEnumeration
259: * after this method has been called, it will throw a
260: * <code>IllegalStateException</code>. Note that this method is
261: * used for manually aiding in the minimization of immediate
262: * resource requirements when this enumeration is no longer
263: * needed.
264: */
265: public void destroy();
266:
267: }
|