1 /*
2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 package java.util;
26 
27 import java.util.function.Consumer;
28 import java.util.function.Function;
29 import java.util.function.Predicate;
30 import java.util.function.Supplier;
31 
32 // Android-changed: removed ValueBased paragraph.
33 /**
34  * A container object which may or may not contain a non-null value.
35  * If a value is present, {@code isPresent()} will return {@code true} and
36  * {@code get()} will return the value.
37  *
38  * <p>Additional methods that depend on the presence or absence of a contained
39  * value are provided, such as {@link #orElse(java.lang.Object) orElse()}
40  * (return a default value if value not present) and
41  * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block
42  * of code if the value is present).
43  *
44  * @since 1.8
45  */
46 public final class Optional<T> {
47     /**
48      * Common instance for {@code empty()}.
49      */
50     private static final Optional<?> EMPTY = new Optional<>();
51 
52     /**
53      * If non-null, the value; if null, indicates no value is present
54      */
55     private final T value;
56 
57     /**
58      * Constructs an empty instance.
59      *
60      * @implNote Generally only one empty instance, {@link Optional#EMPTY},
61      * should exist per VM.
62      */
Optional()63     private Optional() {
64         this.value = null;
65     }
66 
67     /**
68      * Returns an empty {@code Optional} instance.  No value is present for this
69      * Optional.
70      *
71      * @apiNote Though it may be tempting to do so, avoid testing if an object
72      * is empty by comparing with {@code ==} against instances returned by
73      * {@code Option.empty()}. There is no guarantee that it is a singleton.
74      * Instead, use {@link #isPresent()}.
75      *
76      * @param <T> Type of the non-existent value
77      * @return an empty {@code Optional}
78      */
empty()79     public static<T> Optional<T> empty() {
80         @SuppressWarnings("unchecked")
81         Optional<T> t = (Optional<T>) EMPTY;
82         return t;
83     }
84 
85     /**
86      * Constructs an instance with the value present.
87      *
88      * @param value the non-null value to be present
89      * @throws NullPointerException if value is null
90      */
Optional(T value)91     private Optional(T value) {
92         this.value = Objects.requireNonNull(value);
93     }
94 
95     /**
96      * Returns an {@code Optional} with the specified present non-null value.
97      *
98      * @param <T> the class of the value
99      * @param value the value to be present, which must be non-null
100      * @return an {@code Optional} with the value present
101      * @throws NullPointerException if value is null
102      */
of(T value)103     public static <T> Optional<T> of(T value) {
104         return new Optional<>(value);
105     }
106 
107     /**
108      * Returns an {@code Optional} describing the specified value, if non-null,
109      * otherwise returns an empty {@code Optional}.
110      *
111      * @param <T> the class of the value
112      * @param value the possibly-null value to describe
113      * @return an {@code Optional} with a present value if the specified value
114      * is non-null, otherwise an empty {@code Optional}
115      */
ofNullable(T value)116     public static <T> Optional<T> ofNullable(T value) {
117         return value == null ? empty() : of(value);
118     }
119 
120     /**
121      * If a value is present in this {@code Optional}, returns the value,
122      * otherwise throws {@code NoSuchElementException}.
123      *
124      * @return the non-null value held by this {@code Optional}
125      * @throws NoSuchElementException if there is no value present
126      *
127      * @see Optional#isPresent()
128      */
get()129     public T get() {
130         if (value == null) {
131             throw new NoSuchElementException("No value present");
132         }
133         return value;
134     }
135 
136     /**
137      * Return {@code true} if there is a value present, otherwise {@code false}.
138      *
139      * @return {@code true} if there is a value present, otherwise {@code false}
140      */
isPresent()141     public boolean isPresent() {
142         return value != null;
143     }
144 
145     /**
146      * If a value is present, invoke the specified consumer with the value,
147      * otherwise do nothing.
148      *
149      * @param consumer block to be executed if a value is present
150      * @throws NullPointerException if value is present and {@code consumer} is
151      * null
152      */
ifPresent(Consumer<? super T> consumer)153     public void ifPresent(Consumer<? super T> consumer) {
154         if (value != null)
155             consumer.accept(value);
156     }
157 
158     /**
159      * If a value is present, and the value matches the given predicate,
160      * return an {@code Optional} describing the value, otherwise return an
161      * empty {@code Optional}.
162      *
163      * @param predicate a predicate to apply to the value, if present
164      * @return an {@code Optional} describing the value of this {@code Optional}
165      * if a value is present and the value matches the given predicate,
166      * otherwise an empty {@code Optional}
167      * @throws NullPointerException if the predicate is null
168      */
filter(Predicate<? super T> predicate)169     public Optional<T> filter(Predicate<? super T> predicate) {
170         Objects.requireNonNull(predicate);
171         if (!isPresent())
172             return this;
173         else
174             return predicate.test(value) ? this : empty();
175     }
176 
177     /**
178      * If a value is present, apply the provided mapping function to it,
179      * and if the result is non-null, return an {@code Optional} describing the
180      * result.  Otherwise return an empty {@code Optional}.
181      *
182      * @apiNote This method supports post-processing on optional values, without
183      * the need to explicitly check for a return status.  For example, the
184      * following code traverses a stream of file names, selects one that has
185      * not yet been processed, and then opens that file, returning an
186      * {@code Optional<FileInputStream>}:
187      *
188      * <pre>{@code
189      *     Optional<FileInputStream> fis =
190      *         names.stream().filter(name -> !isProcessedYet(name))
191      *                       .findFirst()
192      *                       .map(name -> new FileInputStream(name));
193      * }</pre>
194      *
195      * Here, {@code findFirst} returns an {@code Optional<String>}, and then
196      * {@code map} returns an {@code Optional<FileInputStream>} for the desired
197      * file if one exists.
198      *
199      * @param <U> The type of the result of the mapping function
200      * @param mapper a mapping function to apply to the value, if present
201      * @return an {@code Optional} describing the result of applying a mapping
202      * function to the value of this {@code Optional}, if a value is present,
203      * otherwise an empty {@code Optional}
204      * @throws NullPointerException if the mapping function is null
205      */
map(Function<? super T, ? extends U> mapper)206     public<U> Optional<U> map(Function<? super T, ? extends U> mapper) {
207         Objects.requireNonNull(mapper);
208         if (!isPresent())
209             return empty();
210         else {
211             return Optional.ofNullable(mapper.apply(value));
212         }
213     }
214 
215     /**
216      * If a value is present, apply the provided {@code Optional}-bearing
217      * mapping function to it, return that result, otherwise return an empty
218      * {@code Optional}.  This method is similar to {@link #map(Function)},
219      * but the provided mapper is one whose result is already an {@code Optional},
220      * and if invoked, {@code flatMap} does not wrap it with an additional
221      * {@code Optional}.
222      *
223      * @param <U> The type parameter to the {@code Optional} returned by
224      * @param mapper a mapping function to apply to the value, if present
225      *           the mapping function
226      * @return the result of applying an {@code Optional}-bearing mapping
227      * function to the value of this {@code Optional}, if a value is present,
228      * otherwise an empty {@code Optional}
229      * @throws NullPointerException if the mapping function is null or returns
230      * a null result
231      */
flatMap(Function<? super T, Optional<U>> mapper)232     public<U> Optional<U> flatMap(Function<? super T, Optional<U>> mapper) {
233         Objects.requireNonNull(mapper);
234         if (!isPresent())
235             return empty();
236         else {
237             return Objects.requireNonNull(mapper.apply(value));
238         }
239     }
240 
241     /**
242      * Return the value if present, otherwise return {@code other}.
243      *
244      * @param other the value to be returned if there is no value present, may
245      * be null
246      * @return the value, if present, otherwise {@code other}
247      */
orElse(T other)248     public T orElse(T other) {
249         return value != null ? value : other;
250     }
251 
252     /**
253      * Return the value if present, otherwise invoke {@code other} and return
254      * the result of that invocation.
255      *
256      * @param other a {@code Supplier} whose result is returned if no value
257      * is present
258      * @return the value if present otherwise the result of {@code other.get()}
259      * @throws NullPointerException if value is not present and {@code other} is
260      * null
261      */
orElseGet(Supplier<? extends T> other)262     public T orElseGet(Supplier<? extends T> other) {
263         return value != null ? value : other.get();
264     }
265 
266     /**
267      * Return the contained value, if present, otherwise throw an exception
268      * to be created by the provided supplier.
269      *
270      * @apiNote A method reference to the exception constructor with an empty
271      * argument list can be used as the supplier. For example,
272      * {@code IllegalStateException::new}
273      *
274      * @param <X> Type of the exception to be thrown
275      * @param exceptionSupplier The supplier which will return the exception to
276      * be thrown
277      * @return the present value
278      * @throws X if there is no value present
279      * @throws NullPointerException if no value is present and
280      * {@code exceptionSupplier} is null
281      */
orElseThrow(Supplier<? extends X> exceptionSupplier)282     public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X {
283         if (value != null) {
284             return value;
285         } else {
286             throw exceptionSupplier.get();
287         }
288     }
289 
290     /**
291      * Indicates whether some other object is "equal to" this Optional. The
292      * other object is considered equal if:
293      * <ul>
294      * <li>it is also an {@code Optional} and;
295      * <li>both instances have no value present or;
296      * <li>the present values are "equal to" each other via {@code equals()}.
297      * </ul>
298      *
299      * @param obj an object to be tested for equality
300      * @return {code true} if the other object is "equal to" this object
301      * otherwise {@code false}
302      */
303     @Override
equals(Object obj)304     public boolean equals(Object obj) {
305         if (this == obj) {
306             return true;
307         }
308 
309         if (!(obj instanceof Optional)) {
310             return false;
311         }
312 
313         Optional<?> other = (Optional<?>) obj;
314         return Objects.equals(value, other.value);
315     }
316 
317     /**
318      * Returns the hash code value of the present value, if any, or 0 (zero) if
319      * no value is present.
320      *
321      * @return hash code value of the present value or 0 if no value is present
322      */
323     @Override
hashCode()324     public int hashCode() {
325         return Objects.hashCode(value);
326     }
327 
328     /**
329      * Returns a non-empty string representation of this Optional suitable for
330      * debugging. The exact presentation format is unspecified and may vary
331      * between implementations and versions.
332      *
333      * @implSpec If a value is present the result must include its string
334      * representation in the result. Empty and present Optionals must be
335      * unambiguously differentiable.
336      *
337      * @return the string representation of this instance
338      */
339     @Override
toString()340     public String toString() {
341         return value != null
342             ? String.format("Optional[%s]", value)
343             : "Optional.empty";
344     }
345 }
346