* Predicates.notNull())}, static importing as necessary.
   *
   * <p><b>Note:</b> if {@code first} is represented as an {@link Optional}, this can be
   * accomplished with {@link Optional#or(Object) first.or(second)}. That approach also allows for
   * lazy evaluation of the fallback instance, using {@link Optional#or(Supplier)
   * first.or(supplier)}.
   *

   * Predicates.notNull())}, static importing as necessary.
   *
   * <p><b>Note:</b> if {@code first} is represented as an {@link Optional}, this can be
   * accomplished with {@link Optional#or(Object) first.or(second)}. That approach also allows for
   * lazy evaluation of the fallback instance, using {@link Optional#or(Supplier)
   * first.or(supplier)}.
   *

# ADR-0008 - Use NullAway for null checking

## Status

- ACCEPTED on 2025-08-06

## Context

Our codebase uses `null` extensively to represent an absence of value or optionality of the argument.
We utilize nullness annotations in Java code and somewhat rely on IDE warnings to guide us.
However, the Java code we have is not fully annotated, which causes several consequences:
* IDE warnings can be misleading

            .add("field11", Arrays.asList("Hello"))
            .add("field12", new ArrayList<>())
            .add("field13", new HashMap<>())
            // Optionals
            .add("field26", Optional.of("World"))
            .add("field27", Optional.absent())
            // Arrays
            .add("field31", new Object[] {"!!!"})
            .add("field32", new boolean[0])
            .add("field33", new byte[0])

    throw new IllegalStateException("Optional.get() cannot be called on an absent value");
  }

  @Override
  public T or(T defaultValue) {
    return checkNotNull(defaultValue, "use Optional.orNull() instead of Optional.or(null)");
  }

  @SuppressWarnings("unchecked") // safe covariant cast
  @Override
  public Optional<T> or(Optional<? extends T> secondChoice) {
    return (Optional<T>) checkNotNull(secondChoice);
  }

  public void testEmptiesFirst() {
    Optional<String> empty = Optional.empty();
    Optional<String> abc = Optional.of("abc");
    Optional<String> z = Optional.of("z");

    Comparator<Optional<String>> comparator = emptiesFirst(comparing(String::length));
    testComparator(comparator, empty, z, abc);

    // Just demonstrate that no explicit type parameter is required
    Comparator<Optional<String>> unused = emptiesFirst(naturalOrder());

  @Override
  public T get() {
    return reference;
  }

  @Override
  public T or(T defaultValue) {
    checkNotNull(defaultValue, "use Optional.orNull() instead of Optional.or(null)");
    return reference;
  }

  @Override
  public Optional<T> or(Optional<? extends T> secondChoice) {
    checkNotNull(secondChoice);
    return this;
  }

  @Override
  public T or(Supplier<? extends T> supplier) {

  @Override
  public T get() {
    return reference;
  }

  @Override
  public T or(T defaultValue) {
    checkNotNull(defaultValue, "use Optional.orNull() instead of Optional.or(null)");
    return reference;
  }

  @Override
  public Optional<T> or(Optional<? extends T> secondChoice) {
    checkNotNull(secondChoice);
    return this;
  }

  @Override
  public T or(Supplier<? extends T> supplier) {

   *
   * <p><b>Java 9 users:</b> use {@code optional.stream()} instead.
   */
  @Beta
  @InlineMe(replacement = "optional.stream()")
  @InlineMeValidationDisabled("Java 9+ API only")
  public static <T> Stream<T> stream(java.util.Optional<T> optional) {
    return optional.isPresent() ? Stream.of(optional.get()) : Stream.empty();
  }

  /**
   * If a value is present in {@code optional}, returns a stream containing only that element,

  }

  @AndroidIncompatible
  public void testJavaOptional() {
    FreshValueGenerator generator = new FreshValueGenerator();
    assertEquals(Optional.empty(), generator.generateFresh(new TypeToken<Optional<String>>() {}));
    assertEquals(Optional.of("2"), generator.generateFresh(new TypeToken<Optional<String>>() {}));