PriorityQueue iterator() Method in Java

1. Introduction

One of the essential methods in PriorityQueue is the iterator() method. This method allows seamless traversal of the elements stored in the queue. In this tutorial, we’ll explore the iterator() method’s functionality and demonstrate its effective use in various scenarios.

2. Overview of PriorityQueue

The PriorityQueue class in Java functions as a data structure, enabling the storage of elements in a queue based on their priority.

PriorityQueue internally utilizes a binary heap, a tree-like structure where elements are arranged based on priority. The highest-priority element resides at the root, and child nodes inherit their parent’s priority. This arrangement ensures that the highest-priority element is positioned at the front while the lowest is placed at the back.

Additionally, the PriorityQueue class implements the Queue interface and offers a range of methods for manipulating the elements within the queue, including the iterator() method. The iterator() method is a part of the Iterable interface, and it is used to obtain an iterator over a collection of elements. The signature of the iterator() method is defined as:

public Iterator<E> iterator()

The iterator() method returns an Iterator over the elements in the queue. The type of parameter E specifies the type of elements in the queue. This method does not take any arguments

3. Iterator Characteristics

Let’s delve into the key characteristics of the iterator:

3.1. Fail-Fast Guarantee

The iterator returned by the iterator() method is a fail-fast iterator. This means that if we attempt to modify the queue (add or remove elements) while an iterator is in use, a ConcurrentModificationException will be thrown. This behavior ensures that the iterator will always reflect the current state of the queue.

In the code, we modify the PriorityQueue by adding one more element after we obtain the iterator:

PriorityQueue<Integer> numbers = new PriorityQueue<>();
numbers.add(3);
numbers.add(1);
numbers.add(2);
Iterator<Integer> iterator = numbers.iterator();
numbers.add(4);
try {
    while (iterator.hasNext()) {
        System.out.println(iterator.next());
    }
} catch (ConcurrentModificationException e) {
    System.out.println("ConcurrentModificationException occurred during iteration.");
}

The output of this program will be:

ConcurrentModificationException occurred during iteration.

3.2. Traversal Order

The iterator() method traverses the heap structure in a specific way, often based on the level-order traversal method. This means it visits elements level by level, starting from the top of the heap and working its way down. This approach is efficient for accessing elements but might not always produce a strictly priority-based order.

Let’s look at an example of how to use the iterator() method to iterate over the elements in a PriorityQueue:

PriorityQueue<Integer> queue = new PriorityQueue<>();
queue.add(3);
queue.add(1);
queue.add(2);
Iterator<Integer> iterator = queue.iterator();
while (iterator.hasNext()) {
    Integer element = iterator.next();
    System.out.println(element);
}

In this example, we create a PriorityQueue of integers and add three elements to it. We then obtain an iterator over the elements in the queue and use a while loop to iterate over the elements, printing each one to the console. The output of this program will be:

1
3
2

Internally, the PriorityQueue looks like:

   1
  / \
 3   2

During iteration, the iterator traverses the elements in level order, producing the order 1, 3, and 2. While this order maintains the general structure of the heap, it does not strictly adhere to the priority-based ordering.

4. Comparator Interface

In certain scenarios, we might want to order elements in the PriorityQueue based on a custom criterion. This can be achieved by utilizing the Comparator interface. This interface allows us to define a comparison function that can be used to order the elements in the queue.

The Comparator interface has a single compare() method, which takes two arguments of the same type and returns an integer value. The value returned by the compare() method determines the ordering of the elements in the queue.

Let’s consider the following example, where we have a Person class, and the requirement is to prioritize individuals based on their age. To address this, we’ll create a custom comparator:

class PersonAgeComparator implements Comparator<Person> {
    @Override
    public int compare(Person p1, Person p2) {
        return p1.age - p2.age; 
    }
}

Subsequently, we’ll create a PriorityQueue with custom ordering. We need to pass an instance of the PersonAgeComparator interface to the constructor of the PriorityQueue. The elements in the queue will then be ordered according to the comparison function defined by the Comparator:

PriorityQueue<Person> priorityQueue = new PriorityQueue<>(new PersonAgeComparator());
priorityQueue.add(new Person("Alice", 25));
priorityQueue.add(new Person("Bob", 30));
priorityQueue.add(new Person("Charlie", 22));
Iterator<Person> iterator = priorityQueue.iterator();
while (iterator.hasNext()) {
    Person person = iterator.next();
    System.out.println("Name: " + person.name + ", Age: " + person.age);
}

The output of this program will be:

Name: Charlie, Age: 22
Name: Bob, Age: 30
Name: Alice, Age: 25

5. Ordered Retrieval

The previous example didn’t display elements in strict ascending age order, even though we used a custom Comparator. The internal structure of PriorityQueue might lead to unexpected outcomes during direct iteration. This is because the iterator follows a level-order traversal, which results in a different sequence during iteration, as it visits elements level by level. 

To ensure elements are retrieved in the exact order of their priority, we can use the poll() method. This method specifically removes the element with the highest priority (in this case, the lowest age) from the PriorityQueue and returns it.

Let’s see how to use the poll() method to retrieve the element in ordering:

while (!priorityQueue.isEmpty()) {
    Person person = priorityQueue.poll();
    System.out.println("Name: " + person.name + ", Age: " + person.age);
}

The output of this program will now be:

Name: Charlie, Age: 22
Name: Alice, Age: 25
Name: Bob, Age: 30

6. Use Case

Although iterator() might not be ideal for strictly-ordered retrieval, it excels in scenarios where the priority order isn’t crucial — for instance, capitalizing the person’s name in PriorityQueue or calculating statistics like average age, regardless of priority. Let’s illustrate the use case with an example:

while (iterator.hasNext()) {
    Person person = iterator.next();
    person.setName(person.getName().toUpperCase());
}

7. Conclusion

In this article, we’ve explored the PriorityQueue class in Java, emphasizing the role of the iterator() method. It’s important to note that while the PriorityQueue maintains sorted order internally, the iterator() method does not guarantee traversal in that order. Therefore, we use the iterator() method to perform operations that don’t rely on the priority order.

As always, the code is available over on GitHub.