Package com.google.common.base

Class Optional<T>

java.lang.Object
com.google.common.base.Optional<T>
Type Parameters:
T - the type of instance that can be contained. Optional is naturally covariant on this type, so it is safe to cast an Optional<T> to Optional<S> for any supertype S of T.
All Implemented Interfaces:
Serializable
@GwtCompatible(serializable=true) @Deprecated(since="2022-12-01") public abstract class Optional<T> extends Object implements Serializable
Deprecated.
The Google Guava Core Libraries are deprecated and will not be part of the AEM SDK after April 2023
An immutable object that may contain a non-null reference to another object. Each instance of this type either contains a non-null reference, or contains nothing (in which case we say that the reference is "absent"); it is never said to "contain null".

A non-null Optional<T> reference can be used as a replacement for a nullable T reference. It allows you to represent "a T that must be present" and a "a T that might be absent" as two distinct types in your program, which can aid clarity.

Some uses of this class include

  • As a method return type, as an alternative to returning null to indicate that no value was available
  • To distinguish between "unknown" (for example, not present in a map) and "known to have no value" (present in the map, with value Optional.absent())
  • To wrap nullable references for storage in a collection that does not support null (though there are several other approaches to this that should be considered first)

A common alternative to using this class is to find or create a suitable null object for the type in question.

This class is not intended as a direct analogue of any existing "option" or "maybe" construct from other programming environments, though it may bear some similarities.

See the Guava User Guide article on using Optional.

Since:
10.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Optional<T>
    absent()
    Deprecated.
    Returns an Optional instance with no contained reference.
    abstract Set<T>
    asSet()
    Deprecated.
    Returns an immutable singleton Set whose only element is the contained instance if it is present; an empty immutable Set otherwise.
    abstract boolean
    equals(Object object)
    Deprecated.
    Returns true if object is an Optional instance, and either the contained references are equal to each other or both are absent.
    static <T> Optional<T>
    fromNullable(T nullableReference)
    Deprecated.
    If nullableReference is non-null, returns an Optional instance containing that reference; otherwise returns absent().
    abstract T
    get()
    Deprecated.
    Returns the contained instance, which must be present.
    abstract int
    hashCode()
    Deprecated.
    Returns a hash code for this instance.
    abstract boolean
    isPresent()
    Deprecated.
    Returns true if this holder contains a (non-null) instance.
    static <T> Optional<T>
    of(T reference)
    Deprecated.
    Returns an Optional instance containing the given non-null reference.
    abstract Optional<T>
    or(Optional<? extends T> secondChoice)
    Deprecated.
    Returns this Optional if it has a value present; secondChoice otherwise.
    abstract T
    or(Supplier<? extends T> supplier)
    Deprecated.
    Returns the contained instance if it is present; supplier.get() otherwise.
    abstract T
    or(T defaultValue)
    Deprecated.
    Returns the contained instance if it is present; defaultValue otherwise.
    abstract T
    orNull()
    Deprecated.
    Returns the contained instance if it is present; null otherwise.
    static <T> Iterable<T>
    presentInstances(Iterable<? extends Optional<? extends T>> optionals)
    Deprecated.
    Returns the value of each present instance from the supplied optionals, in order, skipping over occurrences of absent().
    abstract String
    toString()
    Deprecated.
    Returns a string representation for this instance.
    abstract <V> Optional<V>
    transform(Function<? super T,V> function)
    Deprecated.
    If the instance is present, it is transformed with the given Function; otherwise, absent() is returned.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • absent

      public static <T> Optional<T> absent()
      Deprecated.
      Returns an Optional instance with no contained reference.

    • of

      public static <T> Optional<T> of(T reference)
      Deprecated.
      Returns an Optional instance containing the given non-null reference.

    • fromNullable

      public static <T> Optional<T> fromNullable(@Nullable T nullableReference)
      Deprecated.
      If nullableReference is non-null, returns an Optional instance containing that reference; otherwise returns absent().

    • isPresent

      public abstract boolean isPresent()
      Deprecated.
      Returns true if this holder contains a (non-null) instance.

    • get

      public abstract T get()
      Deprecated.
      Returns the contained instance, which must be present. If the instance might be absent, use or(Object) or orNull() instead.
      Throws:
      IllegalStateException - if the instance is absent (isPresent() returns false)

    • or

      public abstract T or(T defaultValue)
      Deprecated.
      Returns the contained instance if it is present; defaultValue otherwise. If no default value should be required because the instance is known to be present, use get() instead. For a default value of null, use orNull().

      Note about generics: The signature public T or(T defaultValue) is overly restrictive. However, the ideal signature, public <S super T> S or(S), is not legal Java. As a result, some sensible operations involving subtypes are compile errors: 

         

   Optional<Integer> optionalInt = getSomeOptionalInt();
   Number value = optionalInt.or(0.5); // error

   FluentIterable<? extends Number> numbers = getSomeNumbers();
   Optional<? extends Number> first = numbers.first();
   Number value = first.or(0.5); // error

      As a workaround, it is always safe to cast an Optional<? extends T> to Optional<T>. Casting either of the above example Optional instances to Optional<Number> (where Number is the desired output type) solves the problem: 

         

   Optional<Number> optionalInt = (Optional) getSomeOptionalInt();
   Number value = optionalInt.or(0.5); // fine

   FluentIterable<? extends Number> numbers = getSomeNumbers();
   Optional<Number> first = (Optional) numbers.first();
   Number value = first.or(0.5); // fine

    • or

      public abstract Optional<T> or(Optional<? extends T> secondChoice)
      Deprecated.
      Returns this Optional if it has a value present; secondChoice otherwise.

    • or

      @Beta public abstract T or(Supplier<? extends T> supplier)
      Deprecated.
      Returns the contained instance if it is present; supplier.get() otherwise. If the supplier returns null, a NullPointerException is thrown.
      Throws:
      NullPointerException - if the supplier returns null

    • orNull

      @Nullable public abstract T orNull()
      Deprecated.
      Returns the contained instance if it is present; null otherwise. If the instance is known to be present, use get() instead.

    • asSet

      public abstract Set<T> asSet()
      Deprecated.
      Returns an immutable singleton Set whose only element is the contained instance if it is present; an empty immutable Set otherwise.
      Since:
      11.0

    • transform

      public abstract <V> Optional<V> transform(Function<? super T,V> function)
      Deprecated.
      If the instance is present, it is transformed with the given Function; otherwise, absent() is returned. If the function returns null, a NullPointerException is thrown.
      Throws:
      NullPointerException - if the function returns null
      Since:
      12.0

    • equals

      public abstract boolean equals(@Nullable Object object)
      Deprecated.
      Returns true if object is an Optional instance, and either the contained references are equal to each other or both are absent. Note that Optional instances of differing parameterized types can be equal.
      Overrides:
      equals in class Object

    • hashCode

      public abstract int hashCode()
      Deprecated.
      Returns a hash code for this instance.
      Overrides:
      hashCode in class Object

    • toString

      public abstract String toString()
      Deprecated.
      Returns a string representation for this instance. The form of this string representation is unspecified.
      Overrides:
      toString in class Object

    • presentInstances

      @Beta public static <T> Iterable<T> presentInstances(Iterable<? extends Optional<? extends T>> optionals)
      Deprecated.
      Returns the value of each present instance from the supplied optionals, in order, skipping over occurrences of absent(). Iterators are unmodifiable and are evaluated lazily.
      Since:
      11.0 (generics widened in 13.0)