sample/java.util.Queue.txt

   1 *java.util.Queue* *Queue* A collection designed for holding elements prior to pr
   2
   3 public interface interface Queue<E>
   4
   5   implements |java.util.Collection|
   6
   7 |java.util.Queue_Description|
   8 |java.util.Queue_Fields|
   9 |java.util.Queue_Constructors|
  10 |java.util.Queue_Methods|
  11
  12 ================================================================================
  13
  14 *java.util.Queue_Methods*
  15 |java.util.Queue.add(E)|Inserts the specified element into this queue if it is
  16 |java.util.Queue.element()|Retrieves, but does not remove, the head of this que
  17 |java.util.Queue.offer(E)|Inserts the specified element into this queue if it i
  18 |java.util.Queue.peek()|Retrieves, but does not remove, the head of this queue,
  19 |java.util.Queue.poll()|Retrieves and removes the head of this queue,  or retur
  20 |java.util.Queue.remove()|Retrieves and removes the head of this queue.
  21
  22 *java.util.Queue_Description*
  23
  24 A collection designed for holding elements prior to processing. Besides basic
  25 Collection(|java.util.Collection|) operations, queues provide additional
  26 insertion, extraction, and inspection operations. Each of these methods exists
  27 in two forms: one throws an exception if the operation fails, the other returns
  28 a special value (either null or false, depending on the operation). The latter
  29 form of the insert operation is designed specifically for use with
  30 capacity-restricted Queue implementations; in most implementations, insert
  31 operations cannot fail.
  32
  33
  34
  35
  36
  37 Throws exception Returns special value
  38
  39 Insert add(e)(|java.util.Queue|) offer(e)(|java.util.Queue|)
  40
  41 Remove remove()(|java.util.Queue|) poll()(|java.util.Queue|)
  42
  43 Examine element()(|java.util.Queue|) peek()(|java.util.Queue|)
  44
  45
  46
  47 Queues typically, but do not necessarily, order elements in a FIFO
  48 (first-in-first-out) manner. Among the exceptions are priority queues, which
  49 order elements according to a supplied comparator, or the elements' natural
  50 ordering, and LIFO queues (or stacks) which order the elements LIFO
  51 (last-in-first-out). Whatever the ordering used, the head of the queue is that
  52 element which would be removed by a call to (|java.util.Queue|) or
  53 (|java.util.Queue|) . In a FIFO queue, all new elements are inserted at the
  54 tail of the queue. Other kinds of queues may use different placement rules.
  55 Every Queue implementation must specify its ordering properties.
  56
  57 The offer(|java.util.Queue|) method inserts an element if possible, otherwise
  58 returning false. This differs from the Collection.add(|java.util.Collection|)
  59 method, which can fail to add an element only by throwing an unchecked
  60 exception. The offer method is designed for use when failure is a normal,
  61 rather than exceptional occurrence, for example, in fixed-capacity (or bounded)
  62 queues.
  63
  64 The (|java.util.Queue|) and (|java.util.Queue|) methods remove and return the
  65 head of the queue. Exactly which element is removed from the queue is a
  66 function of the queue's ordering policy, which differs from implementation to
  67 implementation. The remove() and poll() methods differ only in their behavior
  68 when the queue is empty: the remove() method throws an exception, while the
  69 poll() method returns null.
  70
  71 The (|java.util.Queue|) and (|java.util.Queue|) methods return, but do not
  72 remove, the head of the queue.
  73
  74 The Queue interface does not define the blocking queue methods, which are
  75 common in concurrent programming. These methods, which wait for elements to
  76 appear or for space to become available, are defined in the
  77 (|java.util.concurrent.BlockingQueue|) interface, which extends this interface.
  78
  79 Queue implementations generally do not allow insertion of null elements,
  80 although some implementations, such as (|java.util.LinkedList|) , do not
  81 prohibit insertion of null. Even in the implementations that permit it, null
  82 should not be inserted into a Queue, as null is also used as a special return
  83 value by the poll method to indicate that the queue contains no elements.
  84
  85 Queue implementations generally do not define element-based versions of methods
  86 equals and hashCode but instead inherit the identity based versions from class
  87 Object, because element-based equality is not always well-defined for queues
  88 with the same elements but different ordering properties.
  89
  90 This interface is a member of the <a
  91 href="/../technotes/guides/collections/index.html"> Java Collections Framework.
  92
  93
  94
  95 *java.util.Queue.add(E)*
  96
  97 public boolean add(E e)
  98
  99 Inserts the specified element into this queue if it is possible to do so
 100 immediately without violating capacity restrictions, returning true upon
 101 success and throwing an IllegalStateException if no space is currently
 102 available.
 103
 104
 105     e - the element to add
 106
 107     Returns: true (as specified by {@link Collection#add})
 108
 109 *java.util.Queue.element()*
 110
 111 public |E| element()
 112
 113 Retrieves, but does not remove, the head of this queue. This method differs
 114 from peek(|java.util.Queue|) only in that it throws an exception if this queue
 115 is empty.
 116
 117
 118
 119     Returns: the head of this queue
 120
 121 *java.util.Queue.offer(E)*
 122
 123 public boolean offer(E e)
 124
 125 Inserts the specified element into this queue if it is possible to do so
 126 immediately without violating capacity restrictions. When using a
 127 capacity-restricted queue, this method is generally preferable to
 128 (|java.util.Queue|) , which can fail to insert an element only by throwing an
 129 exception.
 130
 131
 132     e - the element to add
 133
 134     Returns: true if the element was added to this queue, else false
 135
 136 *java.util.Queue.peek()*
 137
 138 public |E| peek()
 139
 140 Retrieves, but does not remove, the head of this queue, or returns null if this
 141 queue is empty.
 142
 143
 144
 145     Returns: the head of this queue, or null if this queue is empty
 146
 147 *java.util.Queue.poll()*
 148
 149 public |E| poll()
 150
 151 Retrieves and removes the head of this queue, or returns null if this queue is
 152 empty.
 153
 154
 155
 156     Returns: the head of this queue, or null if this queue is empty
 157
 158 *java.util.Queue.remove()*
 159
 160 public |E| remove()
 161
 162 Retrieves and removes the head of this queue. This method differs from
 163 poll(|java.util.Queue|) only in that it throws an exception if this queue is
 164 empty.
 165
 166
 167
 168     Returns: the head of this queue
 169
 170