jdsl
Class BTHeap

java.lang.Object
  |
  +--jdsl.BTHeap

public class BTHeap

extends java.lang.Object

implements PriorityQueue, ComparatorBased

A Heap implementation of PriorityQueue. This heap is based on a Binary Tree.

Constructor Summary

BTHeap()
comparator().

BTHeap(Comparator comparator)
comparator().

Method Summary

Comparator	comparator() Retrieves the Comparator.
protected void	downheap(Position p) Performs the downheap operation starting at p.
java.util.Iterator	elements() Returns an Iterator of all the elements within this Container.
BinaryTree	getBinaryTree() Returns the underlying binary tree() in this heap.
BinaryTree	getTree() Returns the underlying BinaryTree.
void	insert(Locator locator) Inserts a Locator into this Container.
Locator	insert(java.lang.Object key, java.lang.Object element) Inserts a <key, element> pair into this Container.
void	insertItem(java.lang.Object key, java.lang.Object element) Add a (key,element) pair to the set maintained by the priority queue, making whatever internal adjustments are necessary.
boolean	isEmpty() Tests if the container is empty.
java.util.Iterator	keys() Returns an Iterator of all the keys within this Container.
java.util.Iterator	locators() Returns an Iterator of all the Locators within this Container.
Locator	makeLocator(java.lang.Object key, java.lang.Object element) For when you need a locator that can be inserted into this KeyBasedContainer but don't want to insert it quite yet.
Locator	min() Allows access to element with first priority without removing it from the PriorityQueue.
java.lang.Object	minElement() Inspect the element (not the key) with first priority, without modifying the priority queue.
java.lang.Object	minKey() Inspect the key with first priority, without modifying the priority queue.
Container	newContainer()
protected Position	nextInsert() Retrieves the Position that the Heap will insert at next.
protected void	nextInsert(Position p) Changes the position that the Heap will insert at next
void	remove(Locator locator) Removes an element from this Container.
java.lang.Object	removeMinElement() Remove a (key,element) pair with first priority, making whatever internal adjustments are necessary.
java.lang.Object	replaceElement(Locator loc, java.lang.Object newElement) Takes constant time -- even in key-based containers, since the element can be changed independently of the key.
java.lang.Object	replaceKey(Locator locator, java.lang.Object key) Changes the mapping of a Locator's element to a new key.
Comparator	setComparator(Comparator c) This method establishes a ContainerInterfaces.Comparator that an ordered container should use to compare its elements.
int	size() Number of elements in the container.
protected void	size(int size) Changes the current size.
protected BinaryTree	tree() Retrieve the BinaryTree.
protected void	upheap(Position p) Performs the upheap operation starting at p.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BTHeap

public BTHeap()

comparator().

BTHeap

public BTHeap(Comparator comparator)

comparator().

Method Detail

tree

protected BinaryTree tree()

Retrieve the BinaryTree. Different from getBinaryTree because it is not part of the BinaryTreeBased interface and the return type is different.

Returns:

The underlying BinaryTree

See Also:

getBinaryTree

comparator

public Comparator comparator()

Retrieves the Comparator.

Specified by:

comparator in interface ComparatorBased

Returns:

the Comparator that is used by this PriorityQueue.

nextInsert

protected Position nextInsert()

Retrieves the Position that the Heap will insert at next.

Returns:

The current Position to insert at.

nextInsert

protected void nextInsert(Position p)

Changes the position that the Heap will insert at next

Parameters:

p - The new next insertion Position

size

protected void size(int size)

Changes the current size.

Parameters:

size - The new size.

min

public Locator min()
            throws EmptyContainerException

Allows access to element with first priority without removing it from the PriorityQueue.

Specified by:

min in interface PriorityQueue

Returns:

Locator to the element with first priority

Throws:

BoundaryViolationException - if the container is empty

minElement

public java.lang.Object minElement()
                            throws EmptyContainerException

Inspect the element (not the key) with first priority, without modifying the priority queue.

Specified by:

minElement in interface PriorityQueue

Returns:

The client element associated with a key of first priority

Throws:

EmptyContainerException - if the container is empty

minKey

public java.lang.Object minKey()
                        throws EmptyContainerException

Inspect the key with first priority, without modifying the priority queue.

Specified by:

minKey in interface PriorityQueue

Returns:

A key of first priority among those in the priority queue

Throws:

EmptyContainerException - if the container is empty

insertItem

public void insertItem(java.lang.Object key,
                       java.lang.Object element)
                throws InvalidKeyException

Add a (key,element) pair to the set maintained by the priority queue, making whatever internal adjustments are necessary.

Specified by:

insertItem in interface PriorityQueue

Parameters:

key - An object comparable under the implementation's comparison scheme

element - An arbitrary object the client associates with the key

Throws:

InvalidKeyException - if the key is not comparable by this container's comparator().

removeMinElement

public java.lang.Object removeMinElement()
                                  throws EmptyContainerException

Remove a (key,element) pair with first priority, making whatever internal adjustments are necessary.

Specified by:

removeMinElement in interface PriorityQueue

Returns:

The client element (not the key) removed

Throws:

EmptyContainerException - if the container is empty

getTree

public BinaryTree getTree()

Returns the underlying BinaryTree.

Returns:

the underlying BinaryTree.

setComparator

public Comparator setComparator(Comparator c)

This method establishes a ContainerInterfaces.Comparator that an ordered container should use to compare its elements. It must be called after a container is instantiated. It should not be called thereafter, because containers are not guaranteed to update themselves if a new comparator() is installed.

Specified by:

setComparator in interface ComparatorBased

Parameters:

c - A ContainerInterfaces.Comparator appropriate to the elements stored by the container

Returns:

The old Comparator

getBinaryTree

public BinaryTree getBinaryTree()

Returns the underlying binary tree() in this heap.

Returns:

the binary tree().

upheap

protected void upheap(Position p)

Performs the upheap operation starting at p.

Parameters:

p - The Position to start upheaping at.

downheap

protected void downheap(Position p)

Performs the downheap operation starting at p.

Parameters:

p - The Position to start downheaping at.

insert

public void insert(Locator locator)
            throws InvalidKeyException,
                   InvalidLocatorException,
                   ContainedLocatorException

Inserts a Locator into this Container.

Parameters:

locator - The Locator that is inserted into this Container.

Throws:

InvalidkeyException - If the key referenced by locator is not a type accepted by this Container. (For instance, if the container's Comparator can't compare the element, or if the container should have a comparator() but doesn't.)

InvalidLocatorException - If locator cannot be inserted into this container.

insert

public Locator insert(java.lang.Object key,
                      java.lang.Object element)
               throws InvalidKeyException

Inserts a <key, element> pair into this Container. Here, key is an explicit key. That is, it is mapped to element and used to position element within this Container.

Parameters:

key - The key used to position the element within this Container.

element - The element to be inserted into this Container.

Returns:

A Locator which points to element within this Container.

Throws:

InvalidKeyException - If key is not a type accepted by this Container (For example: This Container is unable to use key as a key).

remove

public void remove(Locator locator)
            throws InvalidLocatorException,
                   UncontainedLocatorException

Removes an element from this Container. This method provides the only guaranteed way of removing a particular element from a KeyBasedContainer. The Container may make no guarantee about the uniqueness of its keys or stored elements. Many elements may be mapped to the same key and vice versa depending upon the particular implementaion.

Parameters:

locator - The Locator which points to a particular element within this Container.

Throws:

InvalidLocatorException - If locator is invalid (For example: It does not actually reference an element in this Container).

UncontainedLocatorException - if locator is not contained.

replaceKey

public java.lang.Object replaceKey(Locator locator,
                                   java.lang.Object key)
                            throws InvalidLocatorException,
                                   InvalidKeyException,
                                   UncontainedLocatorException

Changes the mapping of a Locator's element to a new key. That is, within this Container locator's element will now be mapped to key. The original key this element was mapped to is returned Note: this method does not necessarily remove the old key (other elements within this Container may be mapped to it).

Parameters:

locator - The Locator which points to a particular element within this Container.

key - The new key to which locator's element should be mapped.

Returns:

The old key to which locator's element was mapped.

Throws:

InvalidLocatorException - If locator is invalid (For example: It does not actually reference an element in this Container).

InvalidKeyException - If key is not a type accepted by this Container (e.g. If this Container is unable to use key as a key).

UncontainedLocatorException - if locator isn't contained.

replaceElement

public java.lang.Object replaceElement(Locator loc,
                                       java.lang.Object newElement)
                                throws InvalidLocatorException,
                                       UncontainedLocatorException

Takes constant time -- even in key-based containers, since the element can be changed independently of the key.

Parameters:

loc - Locator at which replacement should occur

newElement - Element now to be stored at Locator loc

Returns:

Old element, previously stored at Locator loc

Throws:

UncontainedLocatorException - if loc is uncontained.

locators

public java.util.Iterator locators()

Returns an Iterator of all the Locators within this Container. If this Container is empty then an empty Iterator is returned.

Returns:

An Iterator of all the Locators stored in the container. Note: this Iterator may be empty.

See Also:

elements, Iterator

keys

public java.util.Iterator keys()

Returns an Iterator of all the keys within this Container. If this Container is empty then an empty Iterator is returned.

Returns:

An Iterator of all the keys stored in the container. Note: this Iterator may be empty.

See Also:

elements, Iterator

makeLocator

public Locator makeLocator(java.lang.Object key,
                           java.lang.Object element)
                    throws InvalidKeyException

For when you need a locator that can be inserted into this KeyBasedContainer but don't want to insert it quite yet.

Parameters:

key - the key that represents the element in this locator.

element - the element for this locator.

elements

public java.util.Iterator elements()

Returns an Iterator of all the elements within this Container. If this Container is empty then an empty Iterator is returned.

Returns:

An Iterator of all the Locators stored in the container. Note: this Iterator may be empty.

See Also:

locators, Iterator

newContainer

public Container newContainer()

size

public int size()

Number of elements in the container. May be of order N, in containers that support split and splice operations.

Returns:

Number of elements in the container, where each occurrence of a duplicated element adds 1 to the size() of the container.

isEmpty

public boolean isEmpty()

Tests if the container is empty. Guaranteed to be a constant-time operation.

Returns:

Whether there are no elements in the container