Software Engineer's Notes

If you’ve worked with Java’s Optional<T>, you’ve probably also seen OptionalInt, OptionalLong, and OptionalDouble. Why does Java have both Optional<Integer> and OptionalInt? Which should you choose—and when?

This guide breaks it down with clear examples and a simple decision checklist.

• Optional<Integer> is the generic Optional for reference types. It’s flexible, works everywhere generics are needed, but boxes the int (adds memory & CPU overhead).
• OptionalInt is a primitive specialization for int. It avoids boxing, is faster and lighter, and integrates nicely with IntStream, but is less flexible (no generics, fewer methods).

Use OptionalInt inside performance-sensitive code and with primitive streams; use Optional<Integer> when APIs require Optional<T> or you need a uniform type.

What Are They?

Optional<Integer>

A container that may or may not hold an Integer value:

Optional<Integer> maybeCount = Optional.of(42);     // present
Optional<Integer> emptyCount = Optional.empty();    // absent

OptionalInt

A container specialized for the primitive int:

OptionalInt maybeCount = OptionalInt.of(42);     // present
OptionalInt emptyCount = OptionalInt.empty();    // absent

Both types model “a value might be missing” without using null.

Why Do We Have Two Types?

1. Performance vs. Flexibility
   • Optional<Integer> requires boxing (int → Integer). This allocates objects and adds GC pressure.
   • OptionalInt stores the primitive directly—no boxing.
2. Stream Ecosystem
   • Primitive streams (IntStream, LongStream, DoubleStream) return primitive optionals (OptionalInt, etc.) for terminal ops like max(), min(), average().

Key Differences at a Glance

How to Choose (Quick Decision Tree)

1. Are you working with IntStream / primitive stream results?
   → Use OptionalInt.
2. Do you need to pass the result through APIs that expect Optional<T> (e.g., repository/service interfaces, generic utilities)?
   → Use Optional<Integer>.
3. Is this code hot/performance-sensitive (tight loops, high volume)?
   → Prefer OptionalInt to avoid boxing.
4. Do you need to “map” the contained value using generic lambdas?
   → Optional<Integer> (richer map/flatMap).
   (With OptionalInt, use primitive operations or convert to Optional<Integer> when necessary.)

Common Usage Examples

With Streams (Primitive Path)

int[] nums = {1, 5, 2};
OptionalInt max = IntStream.of(nums).max();

int top = max.orElse(-1);          // -1 if empty
max.ifPresent(m -> System.out.println("Max: " + m));

With Collections / Generic APIs

List<Integer> ages = List.of(18, 21, 16);
Optional<Integer> firstAdult =
    ages.stream().filter(a -> a >= 18).findFirst();  // Optional<Integer>

int age = firstAdult.orElseThrow(); // throws if empty

Converting Between Them (when needed)

OptionalInt oi = OptionalInt.of(10);
Optional<Integer> o = oi.isPresent() ? Optional.of(oi.getAsInt()) : Optional.empty();

Optional<Integer> og = Optional.of(20);
OptionalInt op = og.isPresent() ? OptionalInt.of(og.get()) : OptionalInt.empty();

Benefits of Using Optional (Either Form)

• Eliminates fragile null contracts: Callers are forced to handle absence.
• Self-documenting APIs: Return type communicates “might not exist.”
• Safer refactoring: Missing values become compile-time-visible.

Extra Benefit of OptionalInt

• Performance: No boxing/unboxing. Less GC. Better fit for numeric pipelines.

When to Use Them

Good fits:

• Return types where absence is valid (e.g., findById, max, “maybe present” queries).
• Stream terminal results (IntStream → OptionalInt).
• Public APIs where you want to make “might be empty” explicit.

Avoid or be cautious:

• Fields in entities/DTOs: Prefer plain fields with domain defaults; Optional fields complicate serialization and frameworks.
• Method parameters: Usually model “optional input” with method overloading or builders, not Optional parameters.
• Collections of Optional: Prefer filtering to keep collections of concrete values.
• Overuse in internal code paths where a simple sentinel (like -1) is a clear domain default.

Practical Patterns

Pattern: Prefer Domain Defaults for Internals

If your domain has a natural default (e.g., “unknown count” = 0), returning int may be simpler than OptionalInt.

Pattern: Optional for Query-Like APIs

When a value may not be found and absence is legitimate, return an Optional:

OptionalInt findWinningScore(Game g) { ... }

Pattern: Keep Boundaries Clean

• At primitive stream boundaries → OptionalInt.
• At generic/service boundaries → Optional<Integer>.

Pitfalls & Tips

• Don’t call get()/getAsInt() without checking. Prefer orElse, orElseGet, orElseThrow, or ifPresentOrElse.
• Consider readability. If every call site immediately does orElse(-1), a plain int with a documented default may be clearer.
• Measure before optimizing. Choose OptionalInt for hot paths, but don’t prematurely micro-optimize.

Cheatsheet

• Need performance + primitives? OptionalInt
• Need generic compatibility or richer ops? Optional<Integer>
• Returning from IntStream ops? OptionalInt
• Public service/repo interfaces? Often Optional<Integer>
• Don’t use as fields/parameters/inside collections (usually).

Mini Examples: Correct vs. Avoid

Good (return type)

public OptionalInt findTopScore(UserId id) { ... }

Avoid (parameter)

// Hard to use and read
public void updateScore(OptionalInt maybeScore) { ... }

Prefer overloads or builder/setter methods.

Avoid (entity field)

class Player {
  OptionalInt age; // complicates frameworks/serialization
}

Prefer int age with a domain default or a nullable wrapper managed at the edges.

Conclusion

• Use OptionalInt when you’re in the primitive/stream world or performance matters.
• Use Optional<Integer> when you need generality, compatibility with Optional<T> APIs, or richer functional methods.
• Keep Optionals at API boundaries, not sprinkled through fields and parameters.

Pick the one that keeps your code clear, fast, and explicit about absence.