Using Apache Commons Lang3 Pair and Triple Classes to Return Multiple Values in Java

In everyday Java development you often encounter methods that need to return more than one value. Instead of creating custom wrapper classes or using generic collections such as Map , the org.apache.commons.lang3.tuple package offers Pair and Triple classes that provide a clean, type‑safe way to bundle related values.

Adding the Dependency

Before using Pair or Triple , add the Apache Commons Lang3 library to your Maven project:

<dependency>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-lang3</artifactId>
  <version>3.12.0</version>
</dependency>

Pair Class – A Convenient Key‑Value Container

Overview

The abstract Pair<L,R> class implements Map.Entry<L,R> and Comparable<Pair<L,R>> , making it usable in collections and sortable. It is serializable and provides static factory methods such as Pair.of(left, right) and Pair.of(Map.Entry) .

Key Source Snippet

/**
 * Abstract class representing a simple key‑value pair.
 * Implements Map.Entry, Comparable, and Serializable.
 */
public abstract class Pair
implements Map.Entry
, Comparable
>, Serializable {
    private static final long serialVersionUID = 4954918890077093841L;
    public static final Pair
[] EMPTY_ARRAY = new PairAdapter[0];
    public static
Pair
[] emptyArray() { return (Pair
[]) EMPTY_ARRAY; }
    public static
Pair
of(L left, R right) { return ImmutablePair.of(left, right); }
    public static
Pair
of(Map.Entry
entry) { return ImmutablePair.of(entry); }
    public abstract L getLeft();
    public abstract R getRight();
    public final L getKey() { return getLeft(); }
    public final R getValue() { return getRight(); }
}

ImmutablePair (Immutable Key‑Value Pair)

ImmutablePair is a final subclass of Pair . Once created, its left and right values cannot be changed, making it thread‑safe. Attempting to call setValue throws UnsupportedOperationException .

public final class ImmutablePair
extends Pair
{
    public final L left;
    public final R right;
    public ImmutablePair(L left, R right) { this.left = left; this.right = right; }
    @Override public L getLeft() { return left; }
    @Override public R getRight() { return right; }
    // setValue throws UnsupportedOperationException
}

MutablePair (Mutable Key‑Value Pair)

MutablePair allows the left and right values to be changed after construction. Its fields are public , so they can also be accessed directly. It is not thread‑safe.

public class MutablePair
extends Pair
{
    public L left;
    public R right;
    public MutablePair() {}
    public MutablePair(L left, R right) { this.left = left; this.right = right; }
    @Override public L getLeft() { return left; }
    @Override public R getRight() { return right; }
    public void setLeft(L left) { this.left = left; }
    public void setRight(R right) { this.right = right; }
}

Triple Class – A Powerful Three‑Element Tuple

Overview

The abstract Triple<L,M,R> represents an ordered trio of values: left, middle, and right. It implements Comparable<Triple<L,M,R>> and Serializable . Like Pair , it provides static factory methods such as Triple.of(left, middle, right) .

/**
 * Abstract class for a triple (left, middle, right).
 */
public abstract class Triple
implements Comparable
>, Serializable {
    public static final Triple
[] EMPTY_ARRAY = new TripleAdapter[0];
    public static
Triple
[] emptyArray() { return (Triple
[]) EMPTY_ARRAY; }
    public static
Triple
of(L left, M middle, R right) { return new ImmutableTriple<>(left, middle, right); }
    public abstract L getLeft();
    public abstract M getMiddle();
    public abstract R getRight();
}

ImmutableTriple (Immutable Three‑Element Tuple)

ImmutableTriple is a final subclass whose three components are declared final . Once instantiated, the tuple cannot be altered, providing thread‑safety when the contained objects are themselves immutable.

public final class ImmutableTriple
extends Triple
{
    public final L left;
    public final M middle;
    public final R right;
    public ImmutableTriple(L left, M middle, R right) { this.left = left; this.middle = middle; this.right = right; }
    @Override public L getLeft() { return left; }
    @Override public M getMiddle() { return middle; }
    @Override public R getRight() { return right; }
}

MutableTriple (Mutable Three‑Element Tuple)

MutableTriple allows each element to be changed via setLeft , setMiddle , and setRight . Its fields are public and mutable, but the class is not thread‑safe.

public class MutableTriple
extends Triple
{
    public L left;
    public M middle;
    public R right;
    public MutableTriple() {}
    public MutableTriple(L left, M middle, R right) { this.left = left; this.middle = middle; this.right = right; }
    @Override public L getLeft() { return left; }
    @Override public M getMiddle() { return middle; }
    @Override public R getRight() { return right; }
    public void setLeft(L left) { this.left = left; }
    public void setMiddle(M middle) { this.middle = middle; }
    public void setRight(R right) { this.right = right; }
}

Usage Examples

Below is a simple data object and how ImmutablePair and MutablePair can be used to return multiple fields from a method.

class UserDO {
    private String userId;
    private Integer age;
    // getters and setters omitted for brevity
}

// Returning an immutable pair
ImmutablePair
result = ImmutablePair.of(user.getUserId(), user.getAge());
// result.getLeft() -> userId, result.getRight() -> age

Similarly, a Triple can be used to return three related values:

class UserInfo {
    private String userId;
    private String userName;
    private Integer sex;
    // getters and setters omitted
}

ImmutableTriple
info = ImmutableTriple.of(user.getUserId(), user.getUserName(), user.getSex());
// info.getLeft() -> userId, info.getMiddle() -> userName, info.getRight() -> sex

Conclusion

By leveraging Pair and Triple from Apache Commons Lang3, Java code becomes more concise, type‑safe, and easier to read. The library offers both mutable and immutable variants, allowing developers to choose the appropriate level of safety and flexibility for their specific use cases.