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 }