001: /* Copyright (C) 2003 Internet Archive.
002: *
003: * This file is part of the Heritrix web crawler (crawler.archive.org).
004: *
005: * Heritrix is free software; you can redistribute it and/or modify
006: * it under the terms of the GNU Lesser Public License as published by
007: * the Free Software Foundation; either version 2.1 of the License, or
008: * any later version.
009: *
010: * Heritrix is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013: * GNU Lesser Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser Public License
016: * along with Heritrix; if not, write to the Free Software
017: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018: *
019: * Queue.java
020: * Created on Oct 14, 2003
021: *
022: * $Header$
023: */
024: package org.archive.queue;
025:
026: import java.util.Iterator;
027: import java.util.NoSuchElementException;
028:
029: import org.apache.commons.collections.Predicate;
030:
031: /**
032: * An Abstract queue. It should implement FIFO semantics.
033: *
034: * @author gojomo
035: *
036: */
037: public interface Queue<T> {
038:
039: /** Add an entry to the end of queue
040: * @param obj the entry to queue
041: */
042: void enqueue(T obj);
043:
044: /** is the queue empty?
045: *
046: * @return <code>true</code> if the queue has no elements
047: */
048: boolean isEmpty();
049:
050: /** remove an entry from the start of the queue
051: *
052: * @return the object
053: * @throws java.util.NoSuchElementException
054: */
055: T dequeue() throws NoSuchElementException;
056:
057: /** get the number of elements in the queue
058: *
059: * @return the number of elements in the queue
060: */
061: long length();
062:
063: /**
064: * release any OS/IO resources associated with Queue
065: */
066: void release();
067:
068: /**
069: * Give the top object in the queue, leaving it in place to be
070: * returned by future peek() or dequeue() invocations.
071: *
072: * @return top object, without removing it
073: */
074: T peek();
075:
076: /**
077: * Releases queue from the obligation to return in the
078: * next peek()/dequeue() the same object as returned by
079: * any previous peek().
080: */
081: void unpeek();
082:
083: /**
084: * Returns an iterator for the queue.
085: * <p>
086: * The returned iterator's <code>remove</code> method is considered
087: * unsafe.
088: * <p>
089: * Editing the queue while using the iterator is not safe.
090: * @param inCacheOnly
091: * @return an iterator for the queue
092: */
093: Iterator<T> getIterator(boolean inCacheOnly);
094:
095: /**
096: * All objects in the queue where <code>matcher.match(object)</code>
097: * returns true will be deleted from the queue.
098: * <p>
099: * Making other changes to the queue while this method is being
100: * processed is not safe.
101: * @param matcher a predicate
102: * @return the number of deleted items
103: */
104: long deleteMatchedItems(Predicate matcher);
105: }
|