Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

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.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW