1. Overview

In this quick article, we discuss the highly useful programming concept known as a Pair. Pairs provide a convenient way of handling simple key to value association and are particularly useful when we want to return two values from a method.

A simple implementation of a Pair is available in the core Java libraries. Beyond that, certain third-party libraries such as Apache Commons and Vavr have exposed this functionality in their respective APIs.

Further reading:

The Java HashMap Under the Hood

A quick and practical guide to Hashmap's internals

Iterate over a Map in Java

Learn different ways of iterating through the entries of a Map in Java.

Java – Combine Multiple Collections

A quick and practical guide to combining multiple collections in Java

2. Core Java Implementation

2.1. The Pair Class

The Pair class can be found in the javafx.util package. The constructor of this class takes two arguments, a key and its corresponding value:

Pair<Integer, String> pair = new Pair<>(1, "One");
Integer key = pair.getKey();
String value = pair.getValue();

This example illustrates a simple Integer to String mapping using the Pair concept.

As shown, the key in the pair object is retrieved by invoking a getKey() method while the value is retrieved by calling getValue().

2.2. AbstractMap.SimpleEntry and AbstractMap.SimpleImmutableEntry

SimpleEntry is defined as a nested class inside the AbstractMap class. To create an object of this type we can provide a key and value to the constructor:

AbstractMap.SimpleEntry<Integer, String> entry 
  = new AbstractMap.SimpleEntry<>(1, "one");
Integer key = entry.getKey();
String value = entry.getValue();

The key and value can be accessed through standard getter and setter methods.

Additionally, the AbstractMap class also contains a nested class that represents an immutable pair: the SimpleImmutableEntry class:

AbstractMap.SimpleImmutableEntry<Integer, String> entry
  = new AbstractMap.SimpleImmutableEntry<>(1, "one");

This works in a similar way to the mutable pair class, except the value of the pair cannot be changed. Attempting to do so will result in an UnsupportedOperationException.

3. Apache Commons

In the Apache Commons library, we can find the Pair class in the org.apache.commons.lang3.tuple package. This is an abstract class, so it cannot be instantiated directly.

We can find here, two subclasses – representing immutable and mutable pairs: ImmutablePair and MutablePair.

Both implementations have access to key/value getter/setter methods:

ImmutablePair<Integer, String> pair = new ImmutablePair<>(2, "Two");
Integer key = pair.getKey();
String value = pair.getValue();

Unsurprisingly, an attempt to invoke setValue() on the ImmutablePair results in an UnsupportedOperationException.

But the operation is entirely valid for a mutable implementation:

Pair<Integer, String> pair = new MutablePair<>(3, "Three");
pair.setValue("New Three");

4. Vavr

In the Vavr library, the pair functionality is provided by the immutable Tuple2 class:

Tuple2<Integer, String> pair = new Tuple2<>(4, "Four");
Integer key = pair._1();
String value = pair._2();

In this implementation, we can't modify the object after creation, so mutating methods are returning a new instance that includes the provided change:

tuplePair = pair.update2("New Four");

5. Alternative I – Simple Container Class

Either by user preference or in the absence of any of the aforementioned libraries, a standard workaround for the pair functionality is creating a simple container class that wraps desired return values.

The biggest advantage here is an ability to provide our name which helps in avoiding having the same class representing different domain objects:

public class CustomPair {
    private String key;
    private String value;

    // standard getters and setters

6. Alternative II – Arrays

Another common workaround is by using a simple array with two elements to achieve similar results:

private Object[] getPair() {
    // ...
    return new Object[] {key, value};

Typically, the key is located at index zero of the array while its corresponding value is located at index one.

7. Conclusion

In this tutorial, we have discussed the concept of Pairs in Java and the different implementations available in core Java as well as other third-party libraries.

As always, you can find the code backing this tutorial on GitHub.

Java bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

Newest Most Voted
Inline Feedbacks
View all comments
3 years ago

java.util.AbstractMap.SimpleEntry and java.util.AbstractMap.SimpleImmutableEntry is also worth to mention.

Grzegorz Piwowarek
3 years ago
Reply to  ilya.bystrov

Sure, not super comfortable to use, though

Comments are closed on this article!