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