View Javadoc

1   /* Copyright (C) 2003 Internet Archive.
2    *
3    * This file is part of the Heritrix web crawler (crawler.archive.org).
4    *
5    * Heritrix is free software; you can redistribute it and/or modify
6    * it under the terms of the GNU Lesser Public License as published by
7    * the Free Software Foundation; either version 2.1 of the License, or
8    * any later version.
9    *
10   * Heritrix is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13   * GNU Lesser Public License for more details.
14   *
15   * You should have received a copy of the GNU Lesser Public License
16   * along with Heritrix; if not, write to the Free Software
17   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18   *
19   * Queue.java
20   * Created on Oct 14, 2003
21   *
22   * $Header$
23   */
24  package org.archive.queue;
25  
26  import java.util.Iterator;
27  import java.util.NoSuchElementException;
28  
29  import org.apache.commons.collections.Predicate;
30  
31  
32  /*** 
33   * An Abstract queue.  It should implement FIFO semantics.
34   * 
35   * @author gojomo
36   *
37   */
38  public interface Queue<T> {
39  
40      /*** Add an entry to the end of queue
41       * @param obj the entry to queue
42       */
43      void enqueue(T obj);
44  
45      /*** is the queue empty?
46       *
47       * @return <code>true</code> if the queue has no elements
48       */
49      boolean isEmpty();
50  
51      /*** remove an entry from the start of the  queue
52       *
53       * @return the object
54       * @throws java.util.NoSuchElementException
55       */
56      T dequeue() throws NoSuchElementException;
57  
58      /*** get the number of elements in the queue
59       *
60       * @return the number of elements in the queue
61       */
62      long length();
63  
64      /***
65       * release any OS/IO resources associated with Queue
66       */
67      void release();
68  
69      /***
70       * Give the top object in the queue, leaving it in place to be
71       * returned by future peek() or dequeue() invocations.
72       * 
73       * @return top object, without removing it
74       */
75      T peek();
76  
77      /***
78       * Releases queue from the obligation to return in the
79       * next peek()/dequeue() the same object as returned by
80       * any previous peek(). 
81       */
82      void unpeek();
83      
84      /***
85       * Returns an iterator for the queue.
86       * <p>
87       * The returned iterator's <code>remove</code> method is considered
88       * unsafe.
89       * <p>
90       * Editing the queue while using the iterator is not safe.
91       * @param inCacheOnly
92       * @return an iterator for the queue
93       */
94      Iterator<T> getIterator(boolean inCacheOnly);
95  
96      /***
97       * All objects in the queue where <code>matcher.match(object)</code>
98       * returns true will be deleted from the queue.
99       * <p>
100      * Making other changes to the queue while this method is being
101      * processed is not safe.
102      * @param matcher a predicate
103      * @return the number of deleted items
104      */
105     long deleteMatchedItems(Predicate matcher);
106 }