Package org.apache.commons.collections.buffer

Class PriorityBuffer

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable, java.util.Collection, Buffer
    @Deprecated(since="2021-04-30")
public class PriorityBuffer
extends java.util.AbstractCollection
implements Buffer, java.io.Serializable
    Deprecated.
    Commons Collections 3 is in maintenance mode. Commons Collections 4 should be used instead.
    Binary heap implementation of Buffer that provides for removal based on Comparator ordering.

    The removal order of a binary heap is based on either the natural sort order of its elements or a specified Comparator. The remove() method always returns the first element as determined by the sort order. (The ascendingOrder flag in the constructors can be used to reverse the sort order, in which case remove() will always remove the last element.) The removal order is not the same as the order of iteration; elements are returned by the iterator in no particular order.

    The add(Object) and remove() operations perform in logarithmic time. The get() operation performs in constant time. All other operations perform in linear time or worse.

    Note that this implementation is not synchronized. Use BufferUtils.synchronizedBuffer(Buffer) or SynchronizedBuffer.decorate(Buffer) to provide synchronized access to a PriorityBuffer: 

      Buffer heap = SynchronizedBuffer.decorate(new PriorityBuffer());

    This class is Serializable from Commons Collections 3.2.

    Since:
    Commons Collections 3.0 (previously BinaryHeap v1.0)
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      PriorityBuffer()
      Deprecated.
      Constructs a new empty buffer that sorts in ascending order by the natural order of the objects added.
      PriorityBuffer​(boolean ascendingOrder)
      Deprecated.
      Constructs a new empty buffer specifying the sort order and using the natural order of the objects added.
      PriorityBuffer​(boolean ascendingOrder, java.util.Comparator comparator)
      Deprecated.
      Constructs a new empty buffer specifying the sort order and comparator.
      PriorityBuffer​(int capacity)
      Deprecated.
      Constructs a new empty buffer that sorts in ascending order by the natural order of the objects added, specifying an initial capacity.
      PriorityBuffer​(int capacity, boolean ascendingOrder)
      Deprecated.
      Constructs a new empty buffer that specifying initial capacity and sort order, using the natural order of the objects added.
      PriorityBuffer​(int capacity, boolean ascendingOrder, java.util.Comparator comparator)
      Deprecated.
      Constructs a new empty buffer that specifying initial capacity, sort order and comparator.
      PriorityBuffer​(int capacity, java.util.Comparator comparator)
      Deprecated.
      Constructs a new empty buffer that sorts in ascending order using the specified comparator and initial capacity.
      PriorityBuffer​(java.util.Comparator comparator)
      Deprecated.
      Constructs a new empty buffer that sorts in ascending order using the specified comparator.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean add​(java.lang.Object element)
      Deprecated.
      Adds an element to the buffer.
      void clear()
      Deprecated.
      Clears all elements from the buffer.
      java.util.Comparator comparator()
      Deprecated.
      Gets the comparator being used for this buffer, null is natural order.
      java.lang.Object get()
      Deprecated.
      Gets the next element to be removed without actually removing it (peek).
      boolean isAscendingOrder()
      Deprecated.
      Checks whether the heap is ascending or descending order.
      java.util.Iterator iterator()
      Deprecated.
      Returns an iterator over this heap's elements.
      java.lang.Object remove()
      Deprecated.
      Gets and removes the next element (pop).
      int size()
      Deprecated.
      Returns the number of elements in this buffer.
      java.lang.String toString()
      Deprecated.
      Returns a string representation of this heap.

      • Methods inherited from class java.util.AbstractCollection

        addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.util.Collection

        addAll, contains, containsAll, equals, hashCode, isEmpty, parallelStream, remove, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray, toArray

      • Methods inherited from interface java.lang.Iterable

        forEach

    • Constructor Detail

      • PriorityBuffer

        public PriorityBuffer()
        Deprecated.
        Constructs a new empty buffer that sorts in ascending order by the natural order of the objects added.

      • PriorityBuffer

        public PriorityBuffer​(java.util.Comparator comparator)
        Deprecated.
        Constructs a new empty buffer that sorts in ascending order using the specified comparator.
        Parameters:
        comparator - the comparator used to order the elements, null means use natural order

      • PriorityBuffer

        public PriorityBuffer​(boolean ascendingOrder)
        Deprecated.
        Constructs a new empty buffer specifying the sort order and using the natural order of the objects added.
        Parameters:
        ascendingOrder - if true the heap is created as a minimum heap; otherwise, the heap is created as a maximum heap

      • PriorityBuffer

        public PriorityBuffer​(boolean ascendingOrder,
                      java.util.Comparator comparator)
        Deprecated.
        Constructs a new empty buffer specifying the sort order and comparator.
        Parameters:
        ascendingOrder - true to use the order imposed by the given comparator; false to reverse that order
        comparator - the comparator used to order the elements, null means use natural order

      • PriorityBuffer

        public PriorityBuffer​(int capacity)
        Deprecated.
        Constructs a new empty buffer that sorts in ascending order by the natural order of the objects added, specifying an initial capacity.
        Parameters:
        capacity - the initial capacity for the buffer, greater than zero
        Throws:
        java.lang.IllegalArgumentException - if capacity is <= 0

      • PriorityBuffer

        public PriorityBuffer​(int capacity,
                      java.util.Comparator comparator)
        Deprecated.
        Constructs a new empty buffer that sorts in ascending order using the specified comparator and initial capacity.
        Parameters:
        capacity - the initial capacity for the buffer, greater than zero
        comparator - the comparator used to order the elements, null means use natural order
        Throws:
        java.lang.IllegalArgumentException - if capacity is <= 0

      • PriorityBuffer

        public PriorityBuffer​(int capacity,
                      boolean ascendingOrder)
        Deprecated.
        Constructs a new empty buffer that specifying initial capacity and sort order, using the natural order of the objects added.
        Parameters:
        capacity - the initial capacity for the buffer, greater than zero
        ascendingOrder - if true the heap is created as a minimum heap; otherwise, the heap is created as a maximum heap.
        Throws:
        java.lang.IllegalArgumentException - if capacity is <= 0

      • PriorityBuffer

        public PriorityBuffer​(int capacity,
                      boolean ascendingOrder,
                      java.util.Comparator comparator)
        Deprecated.
        Constructs a new empty buffer that specifying initial capacity, sort order and comparator.
        Parameters:
        capacity - the initial capacity for the buffer, greater than zero
        ascendingOrder - true to use the order imposed by the given comparator; false to reverse that order
        comparator - the comparator used to order the elements, null means use natural order
        Throws:
        java.lang.IllegalArgumentException - if capacity is <= 0

    • Method Detail

      • isAscendingOrder

        public boolean isAscendingOrder()
        Deprecated.
        Checks whether the heap is ascending or descending order.
        Returns:
        true if ascending order (a min heap)

      • comparator

        public java.util.Comparator comparator()
        Deprecated.
        Gets the comparator being used for this buffer, null is natural order.
        Returns:
        the comparator in use, null is natural order

      • size

        public int size()
        Deprecated.
        Returns the number of elements in this buffer.
        Specified by:
        size in interface java.util.Collection
        Specified by:
        size in class java.util.AbstractCollection
        Returns:
        the number of elements in this buffer

      • clear

        public void clear()
        Deprecated.
        Clears all elements from the buffer.
        Specified by:
        clear in interface java.util.Collection
        Overrides:
        clear in class java.util.AbstractCollection

      • add

        public boolean add​(java.lang.Object element)
        Deprecated.
        Adds an element to the buffer.

        The element added will be sorted according to the comparator in use.

        Specified by:
        add in interface java.util.Collection
        Overrides:
        add in class java.util.AbstractCollection
        Parameters:
        element - the element to be added
        Returns:
        true always

      • get

        public java.lang.Object get()
        Deprecated.
        Gets the next element to be removed without actually removing it (peek).
        Specified by:
        get in interface Buffer
        Returns:
        the next element
        Throws:
        BufferUnderflowException - if the buffer is empty

      • remove

        public java.lang.Object remove()
        Deprecated.
        Gets and removes the next element (pop).
        Specified by:
        remove in interface Buffer
        Returns:
        the next element
        Throws:
        BufferUnderflowException - if the buffer is empty

      • iterator

        public java.util.Iterator iterator()
        Deprecated.
        Returns an iterator over this heap's elements.
        Specified by:
        iterator in interface java.util.Collection
        Specified by:
        iterator in interface java.lang.Iterable
        Specified by:
        iterator in class java.util.AbstractCollection
        Returns:
        an iterator over this heap's elements

      • toString

        public java.lang.String toString()
        Deprecated.
        Returns a string representation of this heap. The returned string is similar to those produced by standard JDK collections.
        Overrides:
        toString in class java.util.AbstractCollection
        Returns:
        a string representation of this heap