/* * Copyright (C) 2011 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.base; import static com.google.common.base.Preconditions.checkNotNull; import java.io.Serializable; import java.util.Iterator; import java.util.Set; import javax.annotation.Nullable; import com.google.common.annotations.Beta; import com.google.common.annotations.GwtCompatible; /** * 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 {@code * null}". * *

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

* Some uses of this class include * *

* *

* 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 {@code Optional}. * * @param the type of instance that can be contained. {@code Optional} is * naturally covariant on this type, so it is safe to cast an * {@code Optional} to {@code * Optional} for any supertype {@code S} of {@code T}. * @author Kurt Alfred Kluever * @author Kevin Bourrillion * @since 10.0 */ @GwtCompatible(serializable = true) public abstract class Optional implements Serializable { /** * Returns an {@code Optional} instance with no contained reference. */ public static Optional absent() { return Absent.withType(); } /** * Returns an {@code Optional} instance containing the given non-null reference. */ public static Optional of(T reference) { return new Present(checkNotNull(reference)); } /** * If {@code nullableReference} is non-null, returns an {@code Optional} * instance containing that reference; otherwise returns * {@link Optional#absent}. */ public static Optional fromNullable(@Nullable T nullableReference) { return (nullableReference == null) ? Optional.absent() : new Present(nullableReference); } Optional() { } /** * Returns {@code true} if this holder contains a (non-null) instance. */ public abstract boolean isPresent(); /** * Returns the contained instance, which must be present. If the instance might * be absent, use {@link #or(Object)} or {@link #orNull} instead. * * @throws IllegalStateException if the instance is absent ({@link #isPresent} * returns {@code false}) */ public abstract T get(); /** * Returns the contained instance if it is present; {@code defaultValue} * otherwise. If no default value should be required because the instance is * known to be present, use {@link #get()} instead. For a default value of * {@code null}, use {@link #orNull}. * *

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

	 *    {@code
	 *
	 *   Optional optionalInt = getSomeOptionalInt();
	 *   Number value = optionalInt.or(0.5); // error
	 *
	 *   FluentIterable numbers = getSomeNumbers();
	 *   Optional first = numbers.first();
	 *   Number value = first.or(0.5); // error}
	 * 
* *

* As a workaround, it is always safe to cast an {@code Optional} * to {@code * Optional}. Casting either of the above example {@code Optional} instances * to {@code * Optional} (where {@code Number} is the desired output type) solves * the problem: * *

	 *    {@code
	 *
	 *   Optional optionalInt = (Optional) getSomeOptionalInt();
	 *   Number value = optionalInt.or(0.5); // fine
	 *
	 *   FluentIterable numbers = getSomeNumbers();
	 *   Optional first = (Optional) numbers.first();
	 *   Number value = first.or(0.5); // fine}
	 * 
*/ public abstract T or(T defaultValue); /** * Returns this {@code Optional} if it has a value present; {@code secondChoice} * otherwise. */ public abstract Optional or(Optional secondChoice); /** * Returns the contained instance if it is present; {@code supplier.get()} * otherwise. If the supplier returns {@code null}, a * {@link NullPointerException} is thrown. * * @throws NullPointerException if the supplier returns {@code null} */ @Beta public abstract T or(Supplier supplier); /** * Returns the contained instance if it is present; {@code null} otherwise. If * the instance is known to be present, use {@link #get()} instead. */ @Nullable public abstract T orNull(); /** * Returns an immutable singleton {@link Set} whose only element is the * contained instance if it is present; an empty immutable {@link Set} * otherwise. * * @since 11.0 */ public abstract Set asSet(); /** * If the instance is present, it is transformed with the given * {@link Function}; otherwise, {@link Optional#absent} is returned. If the * function returns {@code null}, a {@link NullPointerException} is thrown. * * @throws NullPointerException if the function returns {@code null} * * @since 12.0 */ public abstract Optional transform(Function function); /** * Returns {@code true} if {@code object} is an {@code Optional} instance, and * either the contained references are {@linkplain Object#equals equal} to each * other or both are absent. Note that {@code Optional} instances of differing * parameterized types can be equal. */ @Override public abstract boolean equals(@Nullable Object object); /** * Returns a hash code for this instance. */ @Override public abstract int hashCode(); /** * Returns a string representation for this instance. The form of this string * representation is unspecified. */ @Override public abstract String toString(); /** * Returns the value of each present instance from the supplied * {@code optionals}, in order, skipping over occurrences of * {@link Optional#absent}. Iterators are unmodifiable and are evaluated lazily. * * @since 11.0 (generics widened in 13.0) */ @Beta public static Iterable presentInstances(final Iterable> optionals) { checkNotNull(optionals); return new Iterable() { @Override public Iterator iterator() { return new AbstractIterator() { private final Iterator> iterator = checkNotNull( optionals.iterator()); @Override protected T computeNext() { while (iterator.hasNext()) { Optional optional = iterator.next(); if (optional.isPresent()) { return optional.get(); } } return endOfData(); } }; } }; } private static final long serialVersionUID = 0; }