Guide to the Java Queue Interface

1. Introduction

In this tutorial, we’ll be discussing Java’s Queue interface.

First, we’ll take a peek at what a Queue does, and some of its core methods. Next, we’ll dive into a number of implementations that Java provides as standard.

Finally, we’ll talk about thread safety before wrapping it all up.

2. Visualizing the Queue

Let’s start with a quick analogy.

Imagine we’ve just opened our first business – a hot dog stand. We want to serve our new potential clients in the most efficient way possible for our small business; one at a time. First, we ask them to form an orderly line in front of our stand, with new customers joining at the rear. Thanks to our organization skills, we can now distribute our tasty hot dogs in a fair way.

Queues in Java work in a similar way. After we declare our Queue, we can add new elements to the back, and remove them from the front.

In fact, most Queues we’ll encounter in Java work in this first in, first out manner – often abbreviated to FIFO.

However, there’s one exception that we’ll touch upon later.

3. Core Methods

The Queue declares a number of methods that need to be coded by all implementing classes. Let’s outline a few of the more important ones now:

1. offer() – Inserts a new element onto the Queue
2. poll() – Removes an element from the front of the Queue
3. peek() – Inspects the element at the front of the Queue, without removing it

4. AbstractQueue

AbstractQueue is the simplest possible Queue implementation that Java provides. It includes a skeletal implementation of some of the Queue interface’s methods, excluding offer.

When we create a custom queue extending the AbstractQueue class, we must provide an implementation of the offer method which does not allow the insertion of null elements.

Additionally, we must provide the methods peek, poll, size, and java.util‘s iterator.

Let’s put together a simple Queue implementation using AbstractQueue.

First, let’s define our class with a LinkedList to store our Queue’s elements:

public class CustomBaeldungQueue<T> extends AbstractQueue<T> {

    private LinkedList<T> elements;

    public CustomBaeldungQueue() {
      this.elements = new LinkedList<T>();
    }

}

Next, let’s override the required methods and provide the code:

@Override
public Iterator<T> iterator() {
    return elements.iterator();
}

@Override
public int size() {
    return elements.size();
}

@Override
public boolean offer(T t) {
    if(t == null) return false;
    elements.add(t);
    return true;
}

@Override
public T poll() {
    Iterator<T> iter = elements.iterator();
    T t = iter.next();
    if(t != null){
        iter.remove();
        return t;
    }
    return null;
}

@Override
public T peek() {
    return elements.getFirst();
}

Excellent, let’s check that it works with a quick unit test:

customQueue.add(7);
customQueue.add(5);

int first = customQueue.poll();
int second = customQueue.poll();

assertEquals(7, first);
assertEquals(5, second);

4. Sub-interfaces

Generally, the Queue interface is inherited by 3 main sub-interfaces. Blocking Queues, Transfer Queues, and Deques.

Together, these 3 interfaces are implemented by the vast majority of Java’s available Queues. Let’s take a quick look at what these interfaces have been set out to do.

4.1. Blocking Queues

The BlockingQueue interface supports additional operations which force threads to wait on the Queue depending on the current state. A thread may wait on the Queue to be non-empty when attempting a retrieval, or for it to become empty when adding a new element.

Standard Blocking Queues include LinkedBlockingQueue, SynchronousQueue, and ArrayBlockingQueue.

For more information, head over to our article on Blocking Queues.

4.2. Transfer Queues

The TransferQueue interface extends the BlockingQueue interface but is tailored toward the producer-consumer pattern. It controls the flow of information from producer to consumer, creating backpressure in the system.

Java ships with one implementation of the TransferQueue interface, LinkedTransferQueue.

4.3. Deques

Deque is short for Double-Ended Queue and is analogous to a deck of cards – elements may be taken from both the start and end of the Deque. Much like the traditional Queue, the Deque provides methods to add, retrieve and peek at elements held at both the top and bottom.

For a detailed guide on how the Deque works, check out our ArrayDeque article.

5. Priority Queues

We saw earlier that most of the Queues that we come across in Java follow the FIFO principle.

One such exception to this rule is the PriorityQueue. When new elements are inserted into the PriorityQueue, they are ordered based on their natural ordering, or by a defined Comparator provided when we construct the PriorityQueue.

Let’s take a look at how this works with a simple unit test:

PriorityQueue<Integer> integerQueue = new PriorityQueue<>();

integerQueue.add(9);
integerQueue.add(2);
integerQueue.add(4);

int first = integerQueue.poll();
int second = integerQueue.poll();
int third = integerQueue.poll();

assertEquals(2, first);
assertEquals(4, second);
assertEquals(9, third);

Despite the order in which our integers were added to the PriorityQueue, we can see that the retrieval order is changed according to the natural order of the numbers.

We can see that the same is also true when applied to Strings:

PriorityQueue<String> stringQueue = new PriorityQueue<>();

stringQueue.add("blueberry");
stringQueue.add("apple");
stringQueue.add("cherry");

String first = stringQueue.poll();
String second = stringQueue.poll();
String third = stringQueue.poll();

assertEquals("apple", first);
assertEquals("blueberry", second);
assertEquals("cherry", third);

6. Thread Safety

Adding items to Queues is particularly useful in multi-threaded environments. A Queue can be shared amongst threads, and be used to block progress until space is available – helping us overcome some common multi-threaded problems.

For example, writing to a single disk from multiple threads creates resource contention and can lead to slow writing times. Creating a single writer thread with a BlockingQueue can alleviate this issue and lead to vastly improved write speeds.

Luckily, Java offers ConcurrentLinkedQueue, ArrayBlockingQueue, and ConcurrentLinkedDeque which are thread-safe and perfect for multi-threaded programs.

7. Conclusion

In this tutorial, we’ve taken a deep dive into the Java Queue interface.

Firstly, we explored what a Queue does, as well as the implementations that Java provides.

Next, we looked at a Queue’s usual FIFO principle, as well as the PriorityQueue which differs in its ordering.

Finally, we explored thread safety and how Queues can be used in a multi-threaded environment.

As always, the code is available over on GitHub.