Using Pairs in Java

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.

2. Core Java Implementation

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().

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.