1. Overview
In this quick tutorial, 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
2.1. The Pair Class
We can find the Pair class 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.
Here we can find two sub-classes representing immutable and mutable pairs, Imm**utablePair 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.
However, 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 article, we discussed the concept of Pairs in Java and the different implementations available in core Java as well as other third-party libraries.
As always, the code for this article is available on GitHub.