001: /*--
002:
003: Copyright (C) 2002-2005 Adrian Price.
004: All rights reserved.
005:
006: Redistribution and use in source and binary forms, with or without
007: modification, are permitted provided that the following conditions
008: are met:
009:
010: 1. Redistributions of source code must retain the above copyright
011: notice, this list of conditions, and the following disclaimer.
012:
013: 2. Redistributions in binary form must reproduce the above copyright
014: notice, this list of conditions, and the disclaimer that follows
015: these conditions in the documentation and/or other materials
016: provided with the distribution.
017:
018: 3. The names "OBE" and "Open Business Engine" must not be used to
019: endorse or promote products derived from this software without prior
020: written permission. For written permission, please contact
021: adrianprice@sourceforge.net.
022:
023: 4. Products derived from this software may not be called "OBE" or
024: "Open Business Engine", nor may "OBE" or "Open Business Engine"
025: appear in their name, without prior written permission from
026: Adrian Price (adrianprice@users.sourceforge.net).
027:
028: THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
029: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
030: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
031: DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
032: INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
033: (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
034: SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
035: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
036: STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
037: IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
038: POSSIBILITY OF SUCH DAMAGE.
039:
040: For more information on OBE, please see
041: <http://obe.sourceforge.net/>.
042:
043: */
044:
045: package org.obe.spi.model;
046:
047: import java.io.Serializable;
048: import java.util.ConcurrentModificationException;
049: import java.util.Iterator;
050:
051: /**
052: * Supports persistent iteration over arbitrary content. This iterator can be
053: * serialized, deserialized, and used to continue iteration. The target content
054: * is not persisted, and the caller must check whether it is still available by
055: * calling {@link #hasContent}, and restore the original content if necessary
056: * by calling {@link #setContent}.
057: *
058: * @author Adrian Price
059: */
060: public interface PersistentIterator extends Serializable, Iterator {
061: /**
062: * Checks whether the target content is available. The target content is
063: * cleared during object serialization, and must be restored externally
064: * by calling {@link #setContent} before continuing iteration over a
065: * deserialized instance of this class.
066: *
067: * @return <code>true</code> if the content is available.
068: */
069: boolean hasContent();
070:
071: /**
072: * Returns whether the iterator has changed since it was created or last
073: * deserialized. The modified flag is set by {@link #next}, {@link #reset},
074: * and {@link #setContent}, and cleared only be serialization. The flag
075: * indicates that the iterator's persistent state needs to be updated.
076: *
077: * @return <code>true</code> if the iterator has changed.
078: */
079: boolean isModified();
080:
081: /**
082: * Resets the iterator, clearing the content, index and internal fields.
083: * The iterator must be re-initialied by calling {@link #setContent} before
084: * it can be used to perform further iterations. This method sets the
085: * {@link #isModified modified flag}.
086: */
087: void reset();
088:
089: /**
090: * Sets the content over which to iterate (or continue iteration). This
091: * method sets the {@link #isModified modified flag}.
092: *
093: * @param content The target array.
094: * @throws IllegalArgumentException if the object is not of the expected
095: * class.
096: * @throws ConcurrentModificationException
097: * if the content has
098: * changed since it was first set.
099: */
100: void setContent(Object content);
101: }
|