Optional (Guava: Google Core Libraries for Java 24.0-jre API)

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)
public abstract class Optional<T>
extends Object
implements Serializable
```
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.
Comparison to java.util.Optional (JDK 8 and higher): A new Optional class was added for Java 8. The two classes are extremely similar, but incompatible (they cannot share a common supertype). All known differences are listed either here or with the relevant methods below.
- This class is serializable; java.util.Optional is not.
- java.util.Optional has the additional methods ifPresent, filter, flatMap, and orElseThrow.
- java.util offers the primitive-specialized versions OptionalInt, OptionalLong and OptionalDouble, the use of which is recommended; Guava does not have these.
There are no plans to deprecate this class in the foreseeable future. However, we do gently recommend that you prefer the new, standard Java class whenever possible.
See the Guava User Guide article on using Optional.
Since:

10.0

Author:

Kurt Alfred Kluever, Kevin Bourrillion

See Also:

Serialized Form

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static <T> Optional<T>`	`absent()` Returns an `Optional` instance with no contained reference.
`abstract Set<T>`	`asSet()` 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)` 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>`	`fromJavaUtil(Optional<T> javaUtilOptional)` Returns the equivalent `com.google.common.base.Optional` value to the given `java.util.Optional`, or `null` if the argument is null.
`static <T> Optional<T>`	`fromNullable(T nullableReference)` If `nullableReference` is non-null, returns an `Optional` instance containing that reference; otherwise returns `absent()`.
`abstract T`	`get()` Returns the contained instance, which must be present.
`abstract int`	`hashCode()` Returns a hash code for this instance.
`abstract boolean`	`isPresent()` Returns `true` if this holder contains a (non-null) instance.
`static <T> Optional<T>`	`of(T reference)` Returns an `Optional` instance containing the given non-null reference.
`abstract Optional<T>`	`or(Optional<? extends T> secondChoice)` Returns this `Optional` if it has a value present; `secondChoice` otherwise.
`abstract T`	`or(Supplier<? extends T> supplier)` Returns the contained instance if it is present; `supplier.get()` otherwise.
`abstract T`	`or(T defaultValue)` Returns the contained instance if it is present; `defaultValue` otherwise.
`abstract T`	`orNull()` Returns the contained instance if it is present; `null` otherwise.
`static <T> Iterable<T>`	`presentInstances(Iterable<? extends Optional<? extends T>> optionals)` Returns the value of each present instance from the supplied `optionals`, in order, skipping over occurrences of `absent()`.
`Optional<T>`	`toJavaUtil()` Returns the equivalent `java.util.Optional` value to this optional.
`static <T> Optional<T>`	`toJavaUtil(Optional<T> googleOptional)` Returns the equivalent `java.util.Optional` value to the given `com.google.common.base.Optional`, or `null` if the argument is null.
`abstract String`	`toString()` Returns a string representation for this instance.
`abstract <V> Optional<V>`	`transform(Function<? super T,V> function)` If the instance is present, it is transformed with the given `Function`; otherwise, `absent()` is returned.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - absent
```
public static <T> Optional<T> absent()
```
    Returns an Optional instance with no contained reference.
    Comparison to java.util.Optional: this method is equivalent to Java 8's Optional.empty.
  - of
```
public static <T> Optional<T> of(T reference)
```
    Returns an Optional instance containing the given non-null reference. To have null treated as absent(), use fromNullable(T) instead.
    Comparison to java.util.Optional: no differences.
    
    Throws:
    
    NullPointerException - if reference is null
  - fromNullable
```
public static <T> Optional<T> fromNullable(@NullableDecl
                                           T nullableReference)
```
    If nullableReference is non-null, returns an Optional instance containing that reference; otherwise returns absent().
    Comparison to java.util.Optional: this method is equivalent to Java 8's Optional.ofNullable.
  - fromJavaUtil
```
@NullableDecl
public static <T> Optional<T> fromJavaUtil(@NullableDecl
                                                         Optional<T> javaUtilOptional)
```
    Returns the equivalent com.google.common.base.Optional value to the given java.util.Optional, or null if the argument is null.
    
    Since:
    
    21.0
  - toJavaUtil
```
@NullableDecl
public static <T> Optional<T> toJavaUtil(@NullableDecl
                                                       Optional<T> googleOptional)
```
    Returns the equivalent java.util.Optional value to the given com.google.common.base.Optional, or null if the argument is null.
    If googleOptional is known to be non-null, use googleOptional.toJavaUtil() instead.
    Unfortunately, the method reference Optional::toJavaUtil will not work, because it could refer to either the static or instance version of this method. Write out the lambda expression o -> Optional.toJavaUtil(o) instead.
    
    Since:
    
    21.0
  - isPresent
```
public abstract boolean isPresent()
```
    Returns true if this holder contains a (non-null) instance.
    Comparison to java.util.Optional: no differences.
  - get
```
public abstract T get()
```
    Returns the contained instance, which must be present. If the instance might be absent, use or(Object) or orNull() instead.
    Comparison to java.util.Optional: when the value is absent, this method throws IllegalStateException, whereas the Java 8 counterpart throws NoSuchElementException.
    
    Throws:
    
    IllegalStateException - if the instance is absent (isPresent() returns false); depending on this specific exception type (over the more general RuntimeException) is discouraged
  - or
```
public abstract T or(T defaultValue)
```
    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
 
```
    Comparison to java.util.Optional: this method is similar to Java 8's Optional.orElse, but will not accept null as a defaultValue (orNull() must be used instead). As a result, the value returned by this method is guaranteed non-null, which is not the case for the java.util equivalent.
  - or
```
public abstract Optional<T> or(Optional<? extends T> secondChoice)
```
    Returns this Optional if it has a value present; secondChoice otherwise.
    Comparison to java.util.Optional: this method has no equivalent in Java 8's Optional class; write thisOptional.isPresent() ? thisOptional : secondChoice instead.
  - or
```
@Beta
public abstract T or(Supplier<? extends T> supplier)
```
    Returns the contained instance if it is present; supplier.get() otherwise.
    Comparison to java.util.Optional: this method is similar to Java 8's Optional.orElseGet, except when supplier returns null. In this case this method throws an exception, whereas the Java 8 method returns the null to the caller.
    
    Throws:
    
    NullPointerException - if this optional's value is absent and the supplier returns null
  - orNull
```
@NullableDecl
public abstract T orNull()
```
    Returns the contained instance if it is present; null otherwise. If the instance is known to be present, use get() instead.
    Comparison to java.util.Optional: this method is equivalent to Java 8's Optional.orElse(null).
  - asSet
```
public abstract Set<T> asSet()
```
    Returns an immutable singleton Set whose only element is the contained instance if it is present; an empty immutable Set otherwise.
    Comparison to java.util.Optional: this method has no equivalent in Java 8's Optional class. However, this common usage:
```
 for (Foo foo : possibleFoo.asSet()) {
   doSomethingWith(foo);
 }
 
```
    ... can be replaced with:
```
 possibleFoo.ifPresent(foo -> doSomethingWith(foo));
 
```
    Since:
    
    11.0
  - transform
```
public abstract <V> Optional<V> transform(Function<? super T,V> function)
```
    If the instance is present, it is transformed with the given Function; otherwise, absent() is returned.
    Comparison to java.util.Optional: this method is similar to Java 8's Optional.map, except when function returns null. In this case this method throws an exception, whereas the Java 8 method returns Optional.absent().
    
    Throws:
    
    NullPointerException - if the function returns null
    
    Since:
    
    12.0
  - toJavaUtil
```
public Optional<T> toJavaUtil()
```
    Returns the equivalent java.util.Optional value to this optional.
    Unfortunately, the method reference Optional::toJavaUtil will not work, because it could refer to either the static or instance version of this method. Write out the lambda expression o -> o.toJavaUtil() instead.
    
    Since:
    
    21.0
  - equals
```
public abstract boolean equals(@NullableDecl
                               Object object)
```
    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.
    Comparison to java.util.Optional: no differences.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    object - the reference object with which to compare.
    
    Returns:
    
    true if this object is the same as the obj argument; false otherwise.
    
    See Also:
    
    Object.hashCode(), HashMap
  - hashCode
```
public abstract int hashCode()
```
    Returns a hash code for this instance.
    Comparison to java.util.Optional: this class leaves the specific choice of hash code unspecified, unlike the Java 8 equivalent.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    a hash code value for this object.
    
    See Also:
    
    Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)
  - toString
```
public abstract String toString()
```
    Returns a string representation for this instance.
    Comparison to java.util.Optional: this class leaves the specific string representation unspecified, unlike the Java 8 equivalent.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string representation of the object.
  - presentInstances
```
@Beta
public static <T> Iterable<T> presentInstances(Iterable<? extends Optional<? extends T>> optionals)
```
    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.
    Comparison to java.util.Optional: this method has no equivalent in Java 8's Optional class; use optionals.stream().filter(Optional::isPresent).map(Optional::get) instead.
    
    Since:
    
    11.0 (generics widened in 13.0)

Class Optional<T>

Method Summary

Methods inherited from class java.lang.Object

Method Detail

absent

of

fromNullable

fromJavaUtil

toJavaUtil

isPresent

get

or

or

or

orNull

asSet

transform

toJavaUtil

equals

hashCode

toString

presentInstances