KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > archive > queue > Queue


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: /cvsroot/archive-crawler/ArchiveOpenCrawler/src/java/org/archive/queue/Queue.java,v 1.4.18.1 2007/01/13 01:31:39 stack-sf Exp $
23  */
24 package org.archive.queue;
25
26 import java.util.Iterator JavaDoc;
27 import java.util.NoSuchElementException JavaDoc;
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 JavaDoc;
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 JavaDoc<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 }
107
Popular Tags