Using Pairs in Java

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. Difference Between Pair and HashMap

Both Pair and HashMap are used to associate keys with values in Java, but they serve distinct purposes and are suited to different use cases.

A Pair represents a single, fixed association between a key and a value. It’s typically used when only one key-value relationship is needed, such as when we must return two related values from a method or handle minimal, one-to-one mappings.

For example, we could create a Pair with a key of 1 and a value of “One”. In this case, the key in the pair object can be retrieved by calling a getKey() method, while the value can be retrieved by calling getValue(). This approach is ideal for cases where only a simple mapping is required.

A HashMap, on the other hand, is designed to store multiple key-value pairs, allowing for dynamic, scalable mappings. HashMaps are optimized for efficient retrieval, insertion, and deletion of elements based on keys, making them ideal for managing a collection of mappings.

For example, we might use a HashMap to store multiple key-value pairs, like associating the key 1 with the value “One,” the key 2 with “Two,” and the key 3 with “Three.” In this case, the HashMap allows us to retrieve any value by providing its corresponding key, making it a better choice for complex applications that require multiple associations and efficient lookups.

In summary, Pair is best suited for handling a single key-value association or when returning two related values from a method. HashMap, however, is more appropriate for cases that involve storing multiple key-value pairs and require efficient data retrieval and modification capabilities.

3. Core Java Implementation

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

3.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 similarly to the mutable pair class, except the value of the pair cannot be changed. Attempting to do so will result in an UnsupportedOperationException.

4. 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, 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.

However, the operation is entirely valid for a mutable implementation:

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

5. 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 return a new instance that includes the provided change:

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

6. 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 the 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
}

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

8. 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.