Guide to Apache Commons CircularFifoQueue

1. Overview

In this quick tutorial, we’ll have a look at the CircularFifoQueue data structure provided in the collections4.queue package of the Apache Commons Collections library.

CircularFifoQueue<E> implements the Queue<E> interface and is a fixed-size, non-blocking queue — when you add an element to a queue that is full, the oldest element is removed to make room for the new element.

2. Maven Dependency

For Maven projects, we need to add the required dependency:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-collections4</artifactId>
    <version>4.5.0-M2</version>
</dependency>

You can find the latest version of this library on Maven Central.

3. Constructors

To create a CircularFifoQueue object, we can use the default constructor, which creates a queue with the default size of 32:

CircularFifoQueue<String> bits = new CircularFifoQueue();

If we know the desired maximum size of our queue, we can use the constructor that takes an int as an argument to specify the size:

CircularFifoQueue<String> colors = new CircularFifoQueue<>(5);

There is also an option to create a CircularFifoQueue object by giving the constructor a collection as an argument.

In this case, the queue will be filled with the elements of the collection, and its size will be the same as the size of the collection:

CircularFifoQueue<String> daysOfWeek = new CircularFifoQueue<>(days);

Note: since this queue is already full when constructed, any addition will cause the first created element to be discarded.

4. Adding Elements

As with any Queue implementation, we can add elements by using the add and offer methods. The Queue JavaDoc specifies that the offer method is intended to be used when operating with a queue that is capacity-restricted.

However, since the CircularFifoQueue is nonblocking, inserts cannot fail. As a result, its add and offer methods exhibit the same behavior.

Let’s see how we can add elements to our colors queue using the add method:

colors.add("Red");
colors.add("Blue");
colors.add("Green");

And let’s add some elements using the offer method:

colors.offer("White");
colors.offer("Black");

5. Removing and Retrieving Elements

The CircularFifoQueue class offers us a few methods that can be useful when we need to manipulate the queue’s elements. Some methods are used for getting elements from the queue, some for removing elements, and some for doing both operations at the same time.

5.1. Peek Method

The peek method is nondestructive and returns the head of the queue.

This method will always return the same element as long as there haven’t been any changes to the elements in the queue between calls. If the queue is empty, peek will return null:

String colorsHead = colors.peek();

5.2. Element Method

The element method is similar to peek — it returns the current head of the queue.

However, the element method throws an exception if the queue is empty:

colorsHead = colors.element();

5.3. Get Method

When we need to get a certain element from the queue, we can use the get method. This method takes the index of the desired element as an argument. The index of the queue is zero-based.

Let’s get an element from the colors queue that we filled with elements earlier:

String color = colors.get(1);

This will return “Blue“.

Now let’s add three elements to our queue and check this result again:

colors.add("Orange");
colors.add("Violet");
colors.add("Pink");
		
color = colors.get(1);

This time, the get method returns “Black“. This is because our queue was created with a limited size of five, and the first three elements (“Red“, “Blue“, “Green“) were removed with the addition of the new ones.

5.4. Poll Method

The poll method removes the head element of the queue and returns that element. If the queue has no elements, the poll method returns null:

colorsHead = colors.poll();

5.5. Remove Method

The remove method operates much like the poll method — it returns the head of the queue and removes the returned element. However, if the queue is empty, remove will throw an exception:

colorsHead = colors.remove();

5.6. Clear Method

We can use the clear method when we want to empty our queue:

colors.clear();

6. Checking Methods

After seeing how we can add, remove and retrieve elements of the queue, let’s see what the class has to offer regarding checking its size and capacity. We will use the queues created in previous sections in our examples.

In general, we have at our disposal two methods for checking the size of our queue — one for getting the maximum size of the object, and one for checking its current element count.

The maxSize method will return an integer value of the queue maximum size:

int maxSize = bits.maxSize();

This will return 32, as the bits queue was created with the default constructor.

The size method will return the number of elements currently stored in the queue:

int size = colors.size();

To check the capacity of the queue object, we can use the isEmpty and isAtFullCapacity methods.

The isEmpty method will return a boolean value that indicates whether the queue is empty or not:

boolean isEmpty = bits.isEmpty();

To check if our queue is full, we can use the isAtFullCapacity method. This method returns true only if the maximum size of elements in the queue has been reached:

boolean isFull = daysOfWeek.isAtFullCapacity();

You should note that this method is available as of version 4.1.

Another method of the Queue interface that we can use to check whether our queue is full is the isFull method. For CircularFifoQueue, the isFull method will always return false, because the queue can always accept new elements:

boolean isFull = daysOfWeek.isFull();

7. Conclusion

In this article, we saw how to use the Apache Commons CircularFifoQueue. We saw some examples that illustrate how to instantiate a queue object, how to fill it, how to empty it, how to get and remove elements from it, and how to check its size and capacity.