Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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)
    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.

See the Guava User Guide article on using `Optional`.

Since:
  10.0
Author:
  Kurt Alfred Kluever, Kevin Bourrillion
See Also:
  Serialized Form

Method Summary
`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>`
` | `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()`.
`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.

### of

    public static <T> Optional<T> of(T reference)

  Returns an `Optional` instance containing the given non-null reference.

### fromNullable

    public static <T> Optional<T> fromNullable(@Nullable
                                               T nullableReference)

  If `nullableReference` is non-null, returns an `Optional` instance containing that reference; otherwise returns `absent()`.

### isPresent

    public abstract boolean isPresent()

  Returns `true` if this holder contains a (non-null) instance.

### 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.

  Throws:
    `IllegalStateException` - if the instance is absent (`isPresent()` returns `false`)

### 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

### or

    @Beta
    public abstract Optional<T> or(Optional<? extends T> secondChoice)

  Returns this `Optional` if it has a value present; `secondChoice` otherwise.

### or

    @Beta
    public abstract T or(Supplier<? extends T> supplier)

  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()

  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()

  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

    @Beta
    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. 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)

  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()

  Returns a hash code for this instance.

  Overrides:
    `hashCode` in class `Object`

### toString

    public abstract String toString()

  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)

  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)

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010-2012. All Rights Reserved.