001    /*
002     * Copyright (C) 2011 The Guava Authors
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    
017    package com.google.common.base;
018    
019    import static com.google.common.base.Preconditions.checkNotNull;
020    
021    import com.google.common.annotations.Beta;
022    import com.google.common.annotations.GwtCompatible;
023    
024    import java.io.Serializable;
025    import java.util.Iterator;
026    import java.util.Set;
027    
028    import javax.annotation.Nullable;
029    
030    /**
031     * An immutable object that may contain a non-null reference to another object. Each
032     * instance of this type either contains a non-null reference, or contains nothing (in
033     * which case we say that the reference is "absent"); it is never said to "contain {@code
034     * null}".
035     *
036     * <p>A non-null {@code Optional<T>} reference can be used as a replacement for a nullable
037     * {@code T} reference. It allows you to represent "a {@code T} that must be present" and
038     * a "a {@code T} that might be absent" as two distinct types in your program, which can
039     * aid clarity.
040     *
041     * <p>Some uses of this class include
042     *
043     * <ul>
044     * <li>As a method return type, as an alternative to returning {@code null} to indicate
045     *     that no value was available
046     * <li>To distinguish between "unknown" (for example, not present in a map) and "known to
047     *     have no value" (present in the map, with value {@code Optional.absent()})
048     * <li>To wrap nullable references for storage in a collection that does not support
049     *     {@code null} (though there are
050     *     <a href="http://code.google.com/p/guava-libraries/wiki/LivingWithNullHostileCollections">
051     *     several other approaches to this</a> that should be considered first)
052     * </ul>
053     *
054     * <p>A common alternative to using this class is to find or create a suitable
055     * <a href="http://en.wikipedia.org/wiki/Null_Object_pattern">null object</a> for the
056     * type in question.
057     *
058     * <p>This class is not intended as a direct analogue of any existing "option" or "maybe"
059     * construct from other programming environments, though it may bear some similarities.
060     *
061     * <p>See the Guava User Guide article on <a
062     * href="http://code.google.com/p/guava-libraries/wiki/UsingAndAvoidingNullExplained#Optional">
063     * using {@code Optional}</a>.
064     *
065     * @param <T> the type of instance that can be contained. {@code Optional} is naturally
066     *     covariant on this type, so it is safe to cast an {@code Optional<T>} to {@code
067     *     Optional<S>} for any supertype {@code S} of {@code T}.
068     * @author Kurt Alfred Kluever
069     * @author Kevin Bourrillion
070     * @since 10.0
071     */
072    @Beta
073    @GwtCompatible(serializable = true)
074    public abstract class Optional<T> implements Serializable {
075      /**
076       * Returns an {@code Optional} instance with no contained reference.
077       */
078      @SuppressWarnings("unchecked")
079      public static <T> Optional<T> absent() {
080        return (Optional<T>) Absent.INSTANCE;
081      }
082    
083      /**
084       * Returns an {@code Optional} instance containing the given non-null reference.
085       */
086      public static <T> Optional<T> of(T reference) {
087        return new Present<T>(checkNotNull(reference));
088      }
089    
090      /**
091       * If {@code nullableReference} is non-null, returns an {@code Optional} instance containing that
092       * reference; otherwise returns {@link Optional#absent}.
093       */
094      public static <T> Optional<T> fromNullable(@Nullable T nullableReference) {
095        return (nullableReference == null)
096            ? Optional.<T>absent()
097            : new Present<T>(nullableReference);
098      }
099    
100      Optional() {}
101    
102      /**
103       * Returns {@code true} if this holder contains a (non-null) instance.
104       */
105      public abstract boolean isPresent();
106    
107      /**
108       * Returns the contained instance, which must be present. If the instance might be
109       * absent, use {@link #or(Object)} or {@link #orNull} instead.
110       *
111       * @throws IllegalStateException if the instance is absent ({@link #isPresent} returns
112       *     {@code false})
113       */
114      public abstract T get();
115    
116      /**
117       * Returns the contained instance if it is present; {@code defaultValue} otherwise. If
118       * no default value should be required because the instance is known to be present, use
119       * {@link #get()} instead. For a default value of {@code null}, use {@link #orNull}.
120       *
121       * <p>Note about generics: The signature {@code public T or(T defaultValue)} is overly
122       * restrictive. However, the ideal signature, {@code public <S super T> S or(S)}, is not legal
123       * Java. As a result, some sensible operations involving subtypes are compile errors:
124       * <pre>   {@code
125       *
126       *   Optional<Integer> optionalInt = getSomeOptionalInt();
127       *   Number value = optionalInt.or(0.5); // error
128       *
129       *   FluentIterable<? extends Number> numbers = getSomeNumbers();
130       *   Optional<? extends Number> first = numbers.first();
131       *   Number value = first.or(0.5); // error}</pre>
132       *
133       * As a workaround, it is always safe to cast an {@code Optional<? extends T>} to {@code
134       * Optional<T>}. Casting either of the above example {@code Optional} instances to {@code
135       * Optional<Number>} (where {@code Number} is the desired output type) solves the problem:
136       * <pre>   {@code
137       *
138       *   Optional<Number> optionalInt = (Optional) getSomeOptionalInt();
139       *   Number value = optionalInt.or(0.5); // fine
140       *
141       *   FluentIterable<? extends Number> numbers = getSomeNumbers();
142       *   Optional<Number> first = (Optional) numbers.first();
143       *   Number value = first.or(0.5); // fine}</pre>
144       */
145      public abstract T or(T defaultValue);
146    
147      /**
148       * Returns this {@code Optional} if it has a value present; {@code secondChoice}
149       * otherwise.
150       */
151      public abstract Optional<T> or(Optional<? extends T> secondChoice);
152    
153      /**
154       * Returns the contained instance if it is present; {@code supplier.get()} otherwise. If the
155       * supplier returns {@code null}, a {@link NullPointerException} is thrown.
156       *
157       * @throws NullPointerException if the supplier returns {@code null}
158       */
159      public abstract T or(Supplier<? extends T> supplier);
160    
161      /**
162       * Returns the contained instance if it is present; {@code null} otherwise. If the
163       * instance is known to be present, use {@link #get()} instead.
164       */
165      @Nullable public abstract T orNull();
166    
167      /**
168       * Returns an immutable singleton {@link Set} whose only element is the contained instance
169       * if it is present; an empty immutable {@link Set} otherwise.
170       *
171       * @since 11.0
172       */
173      public abstract Set<T> asSet();
174    
175      /**
176       * If the instance is present, it is transformed with the given {@link Function}; otherwise,
177       * {@link Optional#absent} is returned. If the function returns {@code null}, a
178       * {@link NullPointerException} is thrown.
179       *
180       * @throws NullPointerException if the function returns {@code null}
181       *
182       * @since 12.0
183       */
184      public abstract <V> Optional<V> transform(Function<? super T, V> function);
185    
186      /**
187       * Returns {@code true} if {@code object} is an {@code Optional} instance, and either
188       * the contained references are {@linkplain Object#equals equal} to each other or both
189       * are absent. Note that {@code Optional} instances of differing parameterized types can
190       * be equal.
191       */
192      @Override public abstract boolean equals(@Nullable Object object);
193    
194      /**
195       * Returns a hash code for this instance.
196       */
197      @Override public abstract int hashCode();
198    
199      /**
200       * Returns a string representation for this instance. The form of this string
201       * representation is unspecified.
202       */
203      @Override public abstract String toString();
204    
205      /**
206       * Returns the value of each present instance from the supplied {@code optionals}, in order,
207       * skipping over occurrences of {@link Optional#absent}. Iterators are unmodifiable and are
208       * evaluated lazily.
209       *
210       * @since 11.0
211       */
212      public static <T> Iterable<T> presentInstances(final Iterable<Optional<T>> optionals) {
213        checkNotNull(optionals);
214        return new Iterable<T>() {
215          @Override public Iterator<T> iterator() {
216            return new AbstractIterator<T>() {
217              private final Iterator<Optional<T>> iterator = checkNotNull(optionals.iterator());
218    
219              @Override protected T computeNext() {
220                while (iterator.hasNext()) {
221                  Optional<T> optional = iterator.next();
222                  if (optional.isPresent()) {
223                    return optional.get();
224                  }
225                }
226                return endOfData();
227              }
228            };
229          };
230        };
231      }
232    
233      private static final long serialVersionUID = 0;
234    }