001    /*
002     * @(#)ConcurrentList.java  0.1 03/05/19
003     *
004     * Copyright (c) 2003 Arno Formella and Jose B. Gonzalez Lopez.
005     * All Rights Reserved.
006     *
007     * LGPL
008     * 
009     */
010    
011    /* a possible package location */
012    // package es.uvigo.ei.cd.java.util.concurrent;
013    
014    import java.util.*;
015    
016    /**
017       Interface to iterate over a concurrent list.
018    
019       The class extends the Iterator interface, because the implementation of the
020       concurrent list provides access to the items (containers) of the list as
021       well.
022       Further, an iteration over a concurrent list needs to maintain certain
023       information at each item, which makes an explicit finishing of an
024       iteration necessary (avoids that a threads is delayed until the
025       garbage collector finalizes iterators which are not used any more, but
026       which still block an item.
027    
028       @author  Arno Formella and José B. González López
029       @version 0.1, 05/19/03
030       @see     Iterator
031      */
032    public interface ConcurrentIterator extends Iterator {
033      /**
034         Returns the next item in the list.
035    
036         @return the next item in the list, or null if there are no more
037                 items.
038        */
039      public ConcurrentItem nextItem();
040      /**
041         Returns the next item and element in the list.
042    
043         Allows for an atomic access to an item of the list. If one uses
044         the separate forms of first accessing the item then accessing
045         the element, another thread might have changed the element of the
046         item in the mean while.
047    
048         @param item the item where to place the corresponding element, item will
049                be unchanged if there are no more elements.
050         @return the next item in the list, or null if there are no more
051                 elements.
052       */
053      public ConcurrentItem nextItem(ConcurrentItem item);
054      /**
055         Removes the item currently held by the iterator.
056    
057         The iterator is placed to the previous item. The method can be
058         called several times without calling a <tt>next()</tt>-method
059         as long as the iterator does not recover its initial state,
060         that is, being placed as after construction.
061    
062         @throws NoSuchElementException if there is no current item,
063                 i.e., if still none of the <tt>next()</tt>-methods has
064                 been executed or if the iteration already has completed.
065         @throws InterruptedException if the thread is interrupted while
066                 waiting for iterators releasing the current item.
067       */ 
068      public void removeCurrent() throws InterruptedException;
069      /**
070         Finishes an iteration.
071    
072         Because an iteration over a ConcurrentList needs to maintain some
073         state information, one should call this method whenever an iterator
074         is not used any more.
075         Once finish() has been called, the state of the iteration is
076         the same as if one had iterated to the end of the list.
077         If this advice is not followed, other threads might get blocked
078         until the garbage collector finalizes the iterator.
079       */
080      public void finish();
081    }