fixed some formatting typos

[vimdoclet.git] / sample / java.util.concurrent.PriorityBlockingQueue.txt

*java.util.concurrent.PriorityBlockingQueue* *PriorityBlockingQueue* An unbounde

public class PriorityBlockingQueue<E>
  extends    |java.util.AbstractQueue|
  implements |java.util.concurrent.BlockingQueue|
             |java.io.Serializable|

|java.util.concurrent.PriorityBlockingQueue_Description|
|java.util.concurrent.PriorityBlockingQueue_Fields|
|java.util.concurrent.PriorityBlockingQueue_Constructors|
|java.util.concurrent.PriorityBlockingQueue_Methods|

================================================================================

*java.util.concurrent.PriorityBlockingQueue_Constructors*
|java.util.concurrent.PriorityBlockingQueue()|Creates a PriorityBlockingQueue w
|java.util.concurrent.PriorityBlockingQueue(Collection<?extendsE>)|Creates a Pr
|java.util.concurrent.PriorityBlockingQueue(int)|Creates a PriorityBlockingQueu
|java.util.concurrent.PriorityBlockingQueue(int,Comparator<?superE>)|Creates a 

*java.util.concurrent.PriorityBlockingQueue_Methods*
|java.util.concurrent.PriorityBlockingQueue.add(E)|Inserts the specified elemen
|java.util.concurrent.PriorityBlockingQueue.clear()|Atomically removes all of t
|java.util.concurrent.PriorityBlockingQueue.comparator()|Returns the comparator
|java.util.concurrent.PriorityBlockingQueue.contains(Object)|Returnstrueif this
|java.util.concurrent.PriorityBlockingQueue.drainTo(Collection<?superE>)|
|java.util.concurrent.PriorityBlockingQueue.drainTo(Collection<?superE>,int)|
|java.util.concurrent.PriorityBlockingQueue.iterator()|Returns an iterator over
|java.util.concurrent.PriorityBlockingQueue.offer(E)|Inserts the specified elem
|java.util.concurrent.PriorityBlockingQueue.offer(E,long,TimeUnit)|Inserts the 
|java.util.concurrent.PriorityBlockingQueue.peek()|
|java.util.concurrent.PriorityBlockingQueue.poll()|
|java.util.concurrent.PriorityBlockingQueue.poll(long,TimeUnit)|
|java.util.concurrent.PriorityBlockingQueue.put(E)|Inserts the specified elemen
|java.util.concurrent.PriorityBlockingQueue.remainingCapacity()|Always returns 
|java.util.concurrent.PriorityBlockingQueue.remove(Object)|Removes a single ins
|java.util.concurrent.PriorityBlockingQueue.size()|
|java.util.concurrent.PriorityBlockingQueue.take()|
|java.util.concurrent.PriorityBlockingQueue.toArray()|Returns an array containi
|java.util.concurrent.PriorityBlockingQueue.toArray(T[])|Returns an array conta
|java.util.concurrent.PriorityBlockingQueue.toString()|

*java.util.concurrent.PriorityBlockingQueue_Description*

An unbounded blocking queue(|java.util.concurrent.BlockingQueue|) that uses the 
same ordering rules as class (|java.util.PriorityQueue|) and supplies blocking 
retrieval operations. While this queue is logically unbounded, attempted 
additions may fail due to resource exhaustion (causing OutOfMemoryError). This 
class does not permit null elements. A priority queue relying on natural 
ordering(|java.lang.Comparable|) also does not permit insertion of 
non-comparable objects (doing so results in ClassCastException). 

This class and its iterator implement all of the optional methods of the 
(|java.util.Collection|) and (|java.util.Iterator|) interfaces. The Iterator 
provided in method (|java.util.concurrent.PriorityBlockingQueue|) is not 
guaranteed to traverse the elements of the PriorityBlockingQueue in any 
particular order. If you need ordered traversal, consider using 
Arrays.sort(pq.toArray()). Also, method drainTo can be used to remove some or 
all elements in priority order and place them in another collection. 

Operations on this class make no guarantees about the ordering of elements with 
equal priority. If you need to enforce an ordering, you can define custom 
classes or comparators that use a secondary key to break ties in primary 
priority values. For example, here is a class that applies first-in-first-out 
tie-breaking to comparable elements. To use it, you would insert a new 
FIFOEntry(anEntry) instead of a plain entry object. 



class FIFOEntry<E extends Comparable<? super E>> implements 
Comparable<FIFOEntry<E>> { final static AtomicLong seq = new AtomicLong(); 
final long seqNum; final E entry; public FIFOEntry(E entry) { seqNum = 
seq.getAndIncrement(); this.entry = entry; } public E getEntry() { return 
entry; } public int compareTo(FIFOEntry<E> other) { int res = 
entry.compareTo(other.entry); if (res == 0 and and other.entry != this.entry) 
res = (seqNum < other.seqNum ? -1 : 1); return res; } } 

This class is a member of the <a 
href="/../technotes/guides/collections/index.html"> Java Collections Framework. 



*java.util.concurrent.PriorityBlockingQueue()*

public PriorityBlockingQueue()

Creates a PriorityBlockingQueue with the default initial capacity (11) that 
orders its elements according to their natural ordering(|java.lang.Comparable|) 
. 


*java.util.concurrent.PriorityBlockingQueue(Collection<?extendsE>)*

public PriorityBlockingQueue(java.util.Collection<? extends E> c)

Creates a PriorityBlockingQueue containing the elements in the specified 
collection. If the specified collection is a (|java.util.SortedSet|) or a 
(|java.util.PriorityQueue|) , this priority queue will be ordered according to 
the same ordering. Otherwise, this priority queue will be ordered according to 
the natural ordering(|java.lang.Comparable|) of its elements. 

    c - the collection whose elements are to be placed into this priority queue 

*java.util.concurrent.PriorityBlockingQueue(int)*

public PriorityBlockingQueue(int initialCapacity)

Creates a PriorityBlockingQueue with the specified initial capacity that orders 
its elements according to their natural ordering(|java.lang.Comparable|) . 

    initialCapacity - the initial capacity for this priority queue 

*java.util.concurrent.PriorityBlockingQueue(int,Comparator<?superE>)*

public PriorityBlockingQueue(
  int initialCapacity,
  java.util.Comparator<? super E> comparator)

Creates a PriorityBlockingQueue with the specified initial capacity that orders 
its elements according to the specified comparator. 

    initialCapacity - the initial capacity for this priority queue 
    comparator - the comparator that will be used to order this priority queue. If {@code null}, 
       the {@linkplain Comparable natural ordering} of the elements will be 
       used. 

*java.util.concurrent.PriorityBlockingQueue.add(E)*

public boolean add(E e)

Inserts the specified element into this priority queue. 


    e - the element to add 

    Returns: true (as specified by {@link Collection#add}) 

*java.util.concurrent.PriorityBlockingQueue.clear()*

public void clear()

Atomically removes all of the elements from this queue. The queue will be empty 
after this call returns. 



*java.util.concurrent.PriorityBlockingQueue.comparator()*

public |java.util.Comparator|<? super E> comparator()

Returns the comparator used to order the elements in this queue, or null if 
this queue uses the natural ordering(|java.lang.Comparable|) of its elements. 



    Returns: the comparator used to order the elements in this queue, or null if this queue 
             uses the natural ordering of its elements 

*java.util.concurrent.PriorityBlockingQueue.contains(Object)*

public boolean contains(java.lang.Object o)

Returnstrueif this queue contains the specified element. More formally, 
returnstrueif and only if this queue contains at least one elementesuch 
thato.equals(e). 


    o - object to be checked for containment in this queue 

    Returns: true if this queue contains the specified element 

*java.util.concurrent.PriorityBlockingQueue.drainTo(Collection<?superE>)*

public int drainTo(java.util.Collection<? super E> c)





*java.util.concurrent.PriorityBlockingQueue.drainTo(Collection<?superE>,int)*

public int drainTo(
  java.util.Collection<? super E> c,
  int maxElements)





*java.util.concurrent.PriorityBlockingQueue.iterator()*

public |java.util.Iterator|<E> iterator()

Returns an iterator over the elements in this queue. The iterator does not 
return the elements in any particular order. The returned Iterator is a "weakly 
consistent" iterator that will never throw 
(|java.util.ConcurrentModificationException|) , and guarantees to traverse 
elements as they existed upon construction of the iterator, and may (but is not 
guaranteed to) reflect any modifications subsequent to construction. 



    Returns: an iterator over the elements in this queue 

*java.util.concurrent.PriorityBlockingQueue.offer(E)*

public boolean offer(E e)

Inserts the specified element into this priority queue. 


    e - the element to add 

    Returns: true (as specified by {@link Queue#offer}) 

*java.util.concurrent.PriorityBlockingQueue.offer(E,long,TimeUnit)*

public boolean offer(
  E e,
  long timeout,
  java.util.concurrent.TimeUnit unit)

Inserts the specified element into this priority queue. As the queue is 
unbounded this method will never block. 


    e - the element to add 
    timeout - This parameter is ignored as the method never blocks 
    unit - This parameter is ignored as the method never blocks 

    Returns: 

*java.util.concurrent.PriorityBlockingQueue.peek()*

public |E| peek()





*java.util.concurrent.PriorityBlockingQueue.poll()*

public |E| poll()





*java.util.concurrent.PriorityBlockingQueue.poll(long,TimeUnit)*

public |E| poll(
  long timeout,
  java.util.concurrent.TimeUnit unit)
  throws |java.lang.InterruptedException|
         




*java.util.concurrent.PriorityBlockingQueue.put(E)*

public void put(E e)

Inserts the specified element into this priority queue. As the queue is 
unbounded this method will never block. 


    e - the element to add 

*java.util.concurrent.PriorityBlockingQueue.remainingCapacity()*

public int remainingCapacity()

Always returns Integer.MAX_VALUE because a PriorityBlockingQueue is not 
capacity constrained. 



    Returns: Integer.MAX_VALUE 

*java.util.concurrent.PriorityBlockingQueue.remove(Object)*

public boolean remove(java.lang.Object o)

Removes a single instance of the specified element from this queue, if it is 
present. More formally, removes an elementesuch thato.equals(e), if this queue 
contains one or more such elements. Returnstrueif and only if this queue 
contained the specified element (or equivalently, if this queue changed as a 
result of the call). 


    o - element to be removed from this queue, if present 

    Returns: true if this queue changed as a result of the call 

*java.util.concurrent.PriorityBlockingQueue.size()*

public int size()





*java.util.concurrent.PriorityBlockingQueue.take()*

public |E| take()
  throws |java.lang.InterruptedException|
         




*java.util.concurrent.PriorityBlockingQueue.toArray()*

public |java.lang.Object|[] toArray()

Returns an array containing all of the elements in this queue. The returned 
array elements are in no particular order. 

The returned array will be "safe" in that no references to it are maintained by 
this queue. (In other words, this method must allocate a new array). The caller 
is thus free to modify the returned array. 

This method acts as bridge between array-based and collection-based APIs. 



    Returns: an array containing all of the elements in this queue 

*java.util.concurrent.PriorityBlockingQueue.toArray(T[])*

public |T|[] toArray(T[] a)

Returns an array containing all of the elements in this queue; the runtime type 
of the returned array is that of the specified array. The returned array 
elements are in no particular order. If the queue fits in the specified array, 
it is returned therein. Otherwise, a new array is allocated with the runtime 
type of the specified array and the size of this queue. 

If this queue fits in the specified array with room to spare (i.e., the array 
has more elements than this queue), the element in the array immediately 
following the end of the queue is set to null. 

Like the (|java.util.concurrent.PriorityBlockingQueue|) method, this method 
acts as bridge between array-based and collection-based APIs. Further, this 
method allows precise control over the runtime type of the output array, and 
may, under certain circumstances, be used to save allocation costs. 

Suppose x is a queue known to contain only strings. The following code can be 
used to dump the queue into a newly allocated array of String: 



String[] y = x.toArray(new String[0]); 

Note that toArray(new Object[0]) is identical in function to toArray(). 


    a - the array into which the elements of the queue are to be stored, if it is big 
       enough; otherwise, a new array of the same runtime type is allocated for 
       this purpose 

    Returns: an array containing all of the elements in this queue 

*java.util.concurrent.PriorityBlockingQueue.toString()*

public |java.lang.String| toString()