Pair Class in Java: Practical Patterns for 2026
A small container that shows up everywhere
I keep running into the same kind of micro‑problem: I have two values that belong together, but they do not deserve a full‑blown class yet. Think of a student name and a score, a graph node and its distance, or a parsed token and its position. In C++ I can reach for std::pair without a second thought. In Java, the story has always been more fragmented. There is no Pair in java.lang, and for years the most common answers were “use a small class” or “abuse a map entry.” That still works, but modern Java has expanded the menu in useful ways.
I’m going to walk you through the main options I recommend in 2026: javafx.util.Pair, AbstractMap.SimpleEntry, Map.entry, and a tiny custom type (now easy with records). I’ll show you how these options behave, when each one is the right fit, and the mistakes I keep seeing in production code. I’ll also show a realistic example where a pair is the simplest solution. By the end, you should be able to pick the right tool fast, wire it into real code, and avoid the typical surprises around equality, mutability, and dependencies.
What “pair” means in Java terms
A “pair” is just two values treated as a single logical unit. When you code in Java, you usually model relationships with classes. That is great for domain objects like Invoice, Order, or Customer. But it is overkill when the relationship is fleeting or mechanical. When I say “pair,” I mean a compact container for two values, with clear semantics for equality and hashing.
Java does not ship a built‑in Pair type in the core libraries. That absence is intentional: the language leans toward explicit, named types. Still, the platform quietly provides several types that behave like a pair. You can think of these as a toolbox:
javafx.util.Pair: a straightforward pair from JavaFX. It hasgetKey(),getValue(),equals(),hashCode(), andtoString().AbstractMap.SimpleEntry: a mutable key/value pair used by the map APIs.Map.entry(K,V)andMap.Entry: a lightweight pair from the map world, often immutable, and available since Java 9.- Custom pair: a tiny class or record with meaningful names.
The hardest part is not the syntax; it is choosing a pair type that is stable for your environment and consistent with your data model. For example, some pairs are mutable, some are not, and some sit in modules that are not on your classpath by default.
The JavaFX Pair: simple, but not always on the classpath
javafx.util.Pair is the closest to a classic pair: it is small, generic, and easy to read. Here is the canonical pattern:
import javafx.util.Pair;
public class PairBasics {
public static void main(String[] args) {
Pair p = new Pair(10, "Hello Java!");
System.out.println("First value: " + p.getKey());
System.out.println("Second value: " + p.getValue());
}
}
The API is intentionally tiny:
new Pair(K key, V value)creates a pair.getKey()returns the first value.getValue()returns the second value.equals()compares both values.hashCode()uses both values.toString()returns a readable representation.
I like this class for quick experiments, small scripts, and algorithm practice. The equality semantics are also what you expect: two pairs are equal if both elements are equal. That makes it safe to use in sets or as map keys.
The big caveat is availability. JavaFX was separated from the JDK starting with Java 11, which means javafx.util.Pair may not be available unless you add JavaFX yourself. On many systems JavaFX is not in the default runtime image. That makes this class risky for library code or server services where you cannot assume JavaFX is present.
If you do want it, add JavaFX as a dependency via OpenJFX. In Maven, you typically add javafx-base and then run with the proper module path. In Gradle, you can use the JavaFX plugin. I avoid hard‑coding versions in blog examples because you should match the version to your JDK and build setup.
When I recommend JavaFX Pair
- You already use JavaFX in a desktop client.
- The app is a teaching project or a small tool where extra deps are acceptable.
- You need a dead‑simple pair and want a clear, readable class name.
When I avoid it
- Server apps where you want minimal runtime modules.
- Libraries that should work in many environments.
- Android projects that have no JavaFX.
Think of it like a Swiss Army knife: useful in the right context, but you do not carry it into every environment.
Map entries as pairs: SimpleEntry and Map.entry
If you are not using JavaFX, the next most common pair is a map entry. A map entry is literally a key and a value, and in most cases you can treat it as a pair.
AbstractMap.SimpleEntry
This is the classic fallback. It is part of java.util, and it is available everywhere. The catch is that it is mutable. You can call setValue() and change the value later.
import java.util.AbstractMap;
public class SimpleEntryExample {
public static void main(String[] args) {
AbstractMap.SimpleEntry score =
new AbstractMap.SimpleEntry("Alicia", 92);
System.out.println("Key: " + score.getKey());
System.out.println("Value: " + score.getValue());
// Mutating the value
score.setValue(95);
System.out.println("Updated: " + score.getValue());
}
}
Mutability is a double‑edged sword. It helps in some algorithms, but it can also break the assumptions of sets or maps if you change a key or value after using the pair as a map key. I always keep SimpleEntry scoped tightly to a method or local algorithm to avoid accidental mutation across threads or layers.
Map.entry(K,V) and Map.Entry
Since Java 9, you can create a small, immutable map entry with Map.entry(K,V). It gives you an entry that throws if you try to mutate it. That is often exactly what you want.
import java.util.Map;
public class MapEntryExample {
public static void main(String[] args) {
Map.Entry score = Map.entry("Alicia", 92);
System.out.println(score.getKey());
System.out.println(score.getValue());
}
}
I treat Map.entry as the best “pair” option when I do not want JavaFX and do not need a custom type. It is in the core library, it is clean, and it is immutable.
A quick comparison
Here is how I think about it when choosing between the two:
Mutability
Typical use
—
—
SimpleEntry Mutable
Local algorithms, quick hacks
Map.entry Immutable
Safe temporary pairs, stream pipelinesIf your code runs on Java 8, Map.entry is not available. If you are on Java 11+ (which is the default for most teams in 2026), I recommend Map.entry over SimpleEntry in almost all cases.
The modern default: custom Pair as a record
Java records changed how I think about small data holders. When I want a pair that is portable, explicit, and stable across environments, I define a record. It gives you a tiny immutable carrier with a real name and a predictable API.
public record ScoreEntry(String student, int score) { }
Yes, this is still a “pair,” but it is a pair with meaning. You get student() and score() instead of getKey() and getValue(). That alone reduces bugs, because you stop mixing up element positions. Records also give you equals(), hashCode(), and toString() for free.
If you cannot use records (older Java), a short final class works fine:
public final class ScoreEntry {
private final String student;
private final int score;
public ScoreEntry(String student, int score) {
this.student = student;
this.score = score;
}
public String getStudent() {
return student;
}
public int getScore() {
return score;
}
}
I reach for this approach when:
- The pair appears in public APIs or crosses module boundaries.
- The elements are easy to mix up and deserve names.
- I want strong compile‑time clarity without extra dependencies.
It is slightly more code, but it saves real time later. A named pair is like labeling two boxes on a shelf: you stop opening the wrong one.
A realistic example: find the top score
Here is a concrete problem I’ve seen in interview screens and real systems: you have a list of students and their quiz scores, and you need the student with the max score. A pair is a neat fit because you want to carry name + score together.
Below is a runnable example using javafx.util.Pair. I am showing this version because it mirrors classic algorithm examples, but you can swap in Map.entry or a record with very small changes.
import java.util.ArrayList;
import java.util.List;
import javafx.util.Pair;
public class MaxScorePair {
public static void main(String[] args) {
List<Pair> scores = new ArrayList();
scores.add(new Pair("Alicia", 92));
scores.add(new Pair("Ben", 84));
scores.add(new Pair("Chen", 97));
Pair max = maxScore(scores);
System.out.println("Top student: " + max.getKey());
System.out.println("Top score: " + max.getValue());
}
private static Pair maxScore(List<Pair> list) {
int max = Integer.MIN_VALUE;
Pair best = new Pair("", 0);
for (Pair entry : list) {
int score = entry.getValue();
if (score > max) {
max = score;
best = entry;
}
}
return best;
}
}
If you want to avoid JavaFX, use Map.Entry instead:
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
public class MaxScoreEntry {
public static void main(String[] args) {
List<Map.Entry> scores = new ArrayList();
scores.add(Map.entry("Alicia", 92));
scores.add(Map.entry("Ben", 84));
scores.add(Map.entry("Chen", 97));
Map.Entry max = maxScore(scores);
System.out.println("Top student: " + max.getKey());
System.out.println("Top score: " + max.getValue());
}
private static Map.Entry maxScore(List<Map.Entry> list) {
int max = Integer.MIN_VALUE;
Map.Entry best = Map.entry("", 0);
for (Map.Entry entry : list) {
int score = entry.getValue();
if (score > max) {
max = score;
best = entry;
}
}
return best;
}
}
Notice the only difference is the pair type. That is a good hint: if your algorithm reads clearly and the pair type can be swapped, you are using it correctly.
Common mistakes I keep seeing
Pairs are easy to grab, but I routinely see the same mistakes. Here is how I steer around them.
Mistake 1: treating a pair like a domain model
If your data has meaning, name it. I have seen APIs that return Pair for "first name" and "last name". It is extremely easy to swap those values by accident. A record or small class keeps the semantics strong.
Mistake 2: mutating a pair used as a key
If you drop a SimpleEntry into a HashSet or use it as a HashMap key and then mutate it, you can corrupt the structure. The hash code changes, and the entry becomes “lost.” If you need a pair as a key, use an immutable pair.
Mistake 3: assuming JavaFX is always present
Server images that start from slim JRE builds often do not include JavaFX. If your code depends on javafx.util.Pair, you can get a ClassNotFoundException at runtime. That is a bad surprise late in deployment.
Mistake 4: confusing key/value with map semantics
A pair is just two values. It does not enforce map rules such as unique keys. I often see people pass pairs around and then treat them as if there is a map behind them. There is not. That can lead to subtle logic errors.
Mistake 5: mixing pairs in streams without clarity
When you use stream pipelines and introduce pairs, it is easy to lose meaning. I suggest using method references and named variables so the pipeline stays readable. If it starts to feel like a math formula, move to a record.
When to use a pair and when not to
You should use a pair when the relationship is mechanical and short‑lived. You should avoid it when the relationship is part of your domain vocabulary.
Use a pair when:
- You need to return two values from a helper method.
- You are prototyping an algorithm and want to keep code short.
- You are building a temporary structure in a stream pipeline.
Avoid a pair when:
- The data crosses module or service boundaries.
- The elements are easy to mix up without names.
- You expect the structure to grow beyond two values.
I also consider the team. If the codebase has junior developers or rotates across teams, a named type is a safer bet. It pays for itself the first time someone reads the code six months later.
Performance and memory notes
Pairs are light, but they are still objects. If you are creating millions of pairs in a tight loop, you will feel it. For most business apps, the overhead is small, but in data‑heavy pipelines it shows up in allocation pressure and GC time.
I aim for these rough heuristics:
- If you create a few thousand pairs per request, it is fine.
- If you create millions per second in a hot loop, consider a custom structure, primitive arrays, or a record that the JIT can better inline.
Map.entryandSimpleEntryare small, but they are still heap allocations.
On modern JVMs, the overhead often shows as a few milliseconds in high‑throughput code paths, especially when you allocate in bursts. If the pair is only a local temporary, it may be optimized away in some cases, but I never assume that. When performance matters, I measure.
Modern workflows: pairs in streams and AI‑assisted refactors
In 2026 I see pairs mostly in stream pipelines and data transformations. A common pattern is to map a list into a pair and then sort or group by one element.
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
public class PairStreamExample {
public static void main(String[] args) {
List names = List.of("Alicia", "Ben", "Chen", "Daria");
List<Map.Entry> nameLengths = names.stream()
.map(name -> Map.entry(name, name.length()))
.collect(Collectors.toList());
nameLengths.forEach(e ->
System.out.println(e.getKey() + " -> " + e.getValue()));
}
}
This is readable and compact. But there is a point where the pipeline becomes dense, and you lose meaning. If you add another step that also depends on the name length, I usually switch to a record:
public record NameLength(String name, int length) { }
Then the stream is self‑documenting:
List data = names.stream()
.map(name -> new NameLength(name, name.length()))
.toList();
AI‑assisted refactors help here. When I see a Map.Entry chain in a pipeline, I often ask my refactoring tools to suggest a record. That shift reduces the mental load in complex pipelines, and it is usually a mechanical change.
A deeper example: Dijkstra’s algorithm with pairs
If you want to see where pairs really shine, try a classic algorithm like Dijkstra’s shortest path. You need to track a node and its current distance. That is a textbook pair. You can implement it with Map.Entry, but I prefer a small record for clarity.
import java.util.*;
public class DijkstraPairDemo {
public record NodeDist(String node, int dist) { }
public static Map dijkstra(Map<String, List> graph, String start) {
Map dist = new HashMap();
PriorityQueue pq = new PriorityQueue(Comparator.comparingInt(NodeDist::dist));
for (String node : graph.keySet()) {
dist.put(node, Integer.MAX_VALUE);
}
dist.put(start, 0);
pq.offer(new NodeDist(start, 0));
while (!pq.isEmpty()) {
NodeDist current = pq.poll();
if (current.dist() > dist.get(current.node())) {
continue; // stale entry
}
for (NodeDist edge : graph.getOrDefault(current.node(), List.of())) {
int newDist = current.dist() + edge.dist();
if (newDist < dist.get(edge.node())) {
dist.put(edge.node(), newDist);
pq.offer(new NodeDist(edge.node(), newDist));
}
}
}
return dist;
}
public static void main(String[] args) {
Map<String, List> graph = new HashMap();
graph.put("A", List.of(new NodeDist("B", 4), new NodeDist("C", 2)));
graph.put("B", List.of(new NodeDist("C", 5), new NodeDist("D", 10)));
graph.put("C", List.of(new NodeDist("E", 3)));
graph.put("D", List.of(new NodeDist("F", 11)));
graph.put("E", List.of(new NodeDist("D", 4)));
graph.put("F", List.of());
Map result = dijkstra(graph, "A");
System.out.println(result);
}
}
This example reveals a subtle detail: I use the same record for edges (neighbor + weight) and for queue entries (node + distance). That is acceptable because the semantics line up. If the meanings diverge, I split the types. That is the balance: pairs are short, but meaning still matters.
Edge cases: nulls, equality, and ordering
Pairs feel trivial until you hit edge cases. Here are a few that show up often.
Null values
Most pair implementations allow null elements. That is convenient but also risky. If you use a pair as a key in a map, and you let nulls slip in, you need to be consistent. The moment you compare pairs with nulls, your code relies on a correct equals() implementation. JavaFX and map entries do a null‑safe comparison, but your custom pair should do the same. Records handle this correctly by delegating to Objects.equals.
If nulls are illegal in your context, enforce it in the constructor or use Objects.requireNonNull. I often add a compact constructor to a record:
public record Range(int start, int end) {
public Range {
if (start > end) {
throw new IllegalArgumentException("start must be <= end");
}
}
}
This is not pair‑specific, but it’s a reminder: when you create a custom pair, you can encode invariants that generic pairs cannot.
Equality and hashing
Map.entry and SimpleEntry follow the Map.Entry contract: entries are equal if keys and values are equal. JavaFX Pair follows the same general rule. Records also compare by component values. That means you can safely use them as keys in maps or members in sets.
The problem is mutation. If the pair can change, the hash code can change, and the data structure breaks. This is the reason I recommend immutable pairs for anything that escapes a local algorithm. If you must mutate, do it before you insert into a hash‑based collection.
Ordering and sorting
Pairs are not Comparable by default. If you want to sort them, you need to supply a comparator. This is easy with Map.Entry:
List<Map.Entry> list = new ArrayList();
list.sort(Map.Entry.comparingByValue());
If you use a record, just write a comparator:
list.sort(Comparator.comparingInt(ScoreEntry::score));
Always state the sort intent. It is too easy to sort by the wrong component if you just use Comparator.comparing(x -> x.getKey()) without a clear name.
Practical scenarios: where pairs save time
Here are common real‑world places I use pairs today.
Scenario 1: returning two values from a method
Java does not have multiple return values, and creating a full class for a short‑lived result is often too much. A pair makes it obvious:
public static Map.Entry minMax(List data) {
int min = Integer.MAX_VALUE;
int max = Integer.MIN_VALUE;
for (int v : data) {
min = Math.min(min, v);
max = Math.max(max, v);
}
return Map.entry(min, max);
}
If the method is part of a library, I switch to a record so the returned values are named.
Scenario 2: caching computed results
Suppose you cache a computation by two parameters, such as userId and week. A pair is a natural cache key:
Map<Map.Entry, Report> cache = new HashMap();
Map.Entry key = Map.entry(userId, week);
cache.computeIfAbsent(key, k -> generateReport(k.getKey(), k.getValue()));
This is safe only because Map.entry is immutable. If you used SimpleEntry and mutated it later, your cache would break.
Scenario 3: stream grouping and ranking
Pairs are useful when you need to preserve something during a transformation. For example, rank words by frequency but keep the word:
Map counts = words.stream()
.collect(Collectors.groupingBy(w -> w, Collectors.counting()));
List<Map.Entry> top = counts.entrySet().stream()
.sorted(Map.Entry.comparingByValue().reversed())
.limit(10)
.toList();
Here, Map.Entry is already the pair you need. No extra classes required.
Scenario 4: parsing and tokenization
When I parse a string, I often want the token and its offset. A pair keeps it light, but a record makes it clearer:
public record TokenPos(String token, int pos) { }
You can then build a list of TokenPos and feed it into a parser or analyzer.
Alternative approaches: when a pair is not enough
Even when pairs are tempting, there are cases where alternatives are better.
Use a small class if you need behavior
Pairs are pure data. The moment you need behavior, a class or record with methods is cleaner. For example, a Range type that checks containment or intersection should be a real type, not a pair of integers.
Use a tuple library if you need many sizes
Some teams use tuple libraries (like those from functional programming ecosystems) when they need Tuple2, Tuple3, etc. This is fine in a functional‑style codebase, but I avoid it in mixed teams because it reduces readability for developers who expect domain types.
Use Map or List when semantics are key
If your data is “one key to many values,” use a Map<K, List> and skip the pairs. Forcing pairs can create duplicate keys and extra work to consolidate them later.
Comparison table: traditional vs modern pair usage
Here is a compact view of how I see pair usage evolving in modern Java:
Traditional approach
Why it matters
—
—
SimpleEntry
Map.entry Immutable, core API
Custom class
Clear naming, fewer bugs
JavaFX Pair
Already on classpath
Map.Entry
Map.entry or record Safer and clearerThis is not rigid; it is just how I navigate the options when I am in a code review.
Pair pitfalls in production (and how I avoid them)
Here are practical issues I have seen in production systems with fixes that actually stick.
Pitfall: Pair type leaks into API boundaries
If your API returns Map.Entry, you are making a pair look like a map entry. It is okay for internal utilities but confusing for public APIs. The fix is a named record. Even a small name reduces confusion for consumers.
Pitfall: unclear ordering of pair elements
A pair is positional. If you swap the values, the compiler does not help you. This causes real bugs in mapping code. My rule: if I ever see Pair in code, I replace it with a record. The cost is low, and the safety is high.
Pitfall: using pairs to fake multiple returns everywhere
Returning two values is fine, but if every method returns a pair, you are designing a tuple‑oriented API. That is a conscious style choice. If your codebase is not already in that style, this becomes an inconsistency. I keep pairs as a local tool, not the default output type.
Pitfall: relying on toString in logs
Pairs have generic toString() output, often something like key=value or [key,value] depending on the implementation. That might be fine, but if you depend on log parsing or analytics, it is fragile. If logs matter, print explicit fields or use a named type with a stable toString format.
Pitfall: serialization surprises
Some pair types are serializable, some are not, and some are module‑restricted. If you serialize pairs across services, use a named record and version it as part of your API contracts. Do not rely on a random library class for serialized payloads.
Testing considerations
Pair logic is often small, but tests still help when the pair is used in tricky places.
- If the pair is a key in a map, test that key equality works the way you expect.
- If the pair is mutable, add a test that verifies behavior before and after mutation (or just avoid mutation).
- If you use a record with invariants, test the constructor behavior with valid and invalid inputs.
Tests for pairs are usually lightweight, and they reveal misuse early.
Interoperability: pairs across JVM languages
If you interop with Kotlin or Scala, pairs can show up via kotlin.Pair or scala.Tuple2. These are different types, and you cannot use them interchangeably with Java pairs without conversion. In mixed JVM projects, I prefer Java records for internal APIs and then convert at the boundary. It keeps the core codebase consistent and avoids accidental dependency on another language’s pair type.
A practical recipe: refactoring a messy pair
Let me show a simple refactor path that I actually use. Suppose you have this code:
public Map.Entry parseScore(String line) {
String[] parts = line.split(",");
return Map.entry(parts[0], Integer.parseInt(parts[1]));
}
It works, but the meaning is not explicit. If this method is used widely, I refactor to:
public record ScoreEntry(String student, int score) { }
public ScoreEntry parseScore(String line) {
String[] parts = line.split(",");
return new ScoreEntry(parts[0], Integer.parseInt(parts[1]));
}
The change is tiny, and the clarity pays for itself. I still use Map.entry in local code, but for APIs I prefer the record. This is the difference between “pair as a tool” and “pair as a type.”
Pairs in concurrent code
Pairs appear in concurrent code when you track a task and its result, or a queue element and its timestamp. If the pair is mutable, concurrency makes it dangerous. I avoid SimpleEntry in concurrent code because mutation plus visibility rules are a recipe for weird bugs.
When I need a concurrent pair, I use an immutable record or Map.entry. It keeps the data stable and removes a whole class of race conditions. If the data needs to be updated, I replace the entire pair with a new instance, which is predictable and thread‑safe in common data structures.
Generics and type inference gotchas
Pairs are generic, and that can bite you in small ways.
Inference in Map.entry
Sometimes type inference doesn’t do what you expect, especially with primitives. For example:
Map.Entry e = Map.entry("count", 5);
This fails because 5 is an Integer. You either add a suffix (5L) or explicitly cast. This is not unique to pairs, but it is a frequent annoyance in examples.
Wildcards and covariance
If you have List<Map.Entry>, you cannot add Map.entry("x", 3) because of generics rules. In those cases, I avoid wildcards or create a helper method to simplify the types. Again, not a pair‑specific bug, but it shows up often because pairs are generic.
Guidance for API design
If you expose a pair in a public API, you are making a decision that can be hard to undo. Here is my checklist:
- Is the pair part of your domain vocabulary? If yes, name it.
- Will external consumers be confused by
getKey()andgetValue()? If yes, name it. - Will you ever add a third field? If yes, name it now.
- Is the pair only an internal utility? If yes,
Map.entryorSimpleEntryis fine.
This small checklist prevents the majority of misuse I see.
Practical use cases with code
To add more depth, here are two more complete examples that use pairs in real‑world style.
Example 1: Running statistics with a pair return
Suppose you want the mean and variance of a dataset. You can return them as a pair:
import java.util.List;
import java.util.Map;
public class Stats {
public static Map.Entry meanVariance(List data) {
double mean = 0.0;
double m2 = 0.0;
int n = 0;
for (double x : data) {
n++;
double delta = x - mean;
mean += delta / n;
m2 += delta * (x - mean);
}
double variance = n > 1 ? m2 / (n - 1) : 0.0;
return Map.entry(mean, variance);
}
public static void main(String[] args) {
List data = List.of(1.0, 2.0, 3.0, 4.0, 5.0);
Map.Entry result = meanVariance(data);
System.out.println("mean = " + result.getKey());
System.out.println("variance = " + result.getValue());
}
}
If this method becomes part of a public library, I convert the return type to a StatsResult record. But for internal utilities, the pair is perfectly fine.
Example 2: Parsing HTTP logs
Suppose you parse a log line and want the HTTP method and status. This is a classic pair situation:
public record MethodStatus(String method, int status) { }
public MethodStatus parseLogLine(String line) {
String[] parts = line.split(" ");
String method = parts[0];
int status = Integer.parseInt(parts[parts.length - 2]);
return new MethodStatus(method, status);
}
I could return Map.entry(method, status), but the record reads better. This is the kind of scenario where I use a pair in spirit but not in literal type.
Performance comparisons (ranges, not exact numbers)
I avoid exact numbers because they shift with JVM versions and workloads, but here is the pattern I see in benchmarks:
- Allocating
Map.entryor a small record tends to be in the same rough range for small workloads. SimpleEntryis similar, but mutability can add unexpected costs if it disables certain optimizations in your code.- The JIT can inline record accessors efficiently; in hot paths, they often perform as well as “manual” field access.
- If you allocate pairs at very high rates, allocation and GC overhead dominate regardless of which pair type you pick.
The key takeaway is not which pair is “fastest” but whether you should allocate at all in a tight loop. If you’re in a performance‑critical path, try to eliminate temporary pairs or move to a custom primitive structure.
The “pair vs record” decision in practice
Here is a quick mental model I use, and it keeps me consistent:
- Local scope, short‑lived →
Map.entry(orSimpleEntryif Java 8) - Cross‑method, still internal → record if it improves readability
- Public API → record with a domain name
- UI app with JavaFX → JavaFX
Pairis fine
This is not a rule, just a habit that prevents confusion later.
Migration tips for older codebases
If you maintain a legacy Java 8 codebase, you still have good options:
- Use
SimpleEntryas a pair when you need it, but avoid mutating it after insertion into collections. - Create a small
Pairclass for internal use. Keep it immutable and simple. - Consider adding a tiny “pair utils” package that your team uses consistently.
When the codebase moves to Java 17 or later, you can refactor to records incrementally. That migration is mechanical and easy to automate with refactoring tools.
A compact DIY Pair (if you really need one)
Sometimes you want a classic Pair in your own code without pulling a dependency. This is how I define it when I truly need it:
public record Pair(K first, V second) { }
This is almost trivial, but it gives you a stable, explicit type. If you use it widely, consider naming the components left/right or key/value depending on your use case. The names matter because they guide readers.
Wrapping up: the quick decision guide
I like to end with a simple decision guide that I actually use when I’m in a hurry:
- If it’s a quick local pairing and you’re on Java 9+: use
Map.entry. - If it’s local and you’re on Java 8: use
SimpleEntry(but don’t mutate in sets or maps). - If it’s a UI desktop app that already uses JavaFX:
javafx.util.Pairis fine. - If it’s a public API or domain‑level concept: create a record with real names.
Pairs are not bad; they are a tool. The trick is to use them where they are strong: short‑lived, mechanical relationships. When meaning grows, give it a name. That’s the balance I aim for in 2026 Java code, and it has saved me from a lot of confusion.
Final thought
The absence of a built‑in Pair in core Java sometimes feels like a missing convenience, but it also nudges you toward clarity. When you really need the convenience, you have good options today. When you need clarity, records make it easy. That’s a good place to be. If you choose intentionally, pairs in Java can be clean, safe, and productive—without the usual surprises.
