rev 7727 : 8020539: Clean up doclint problems in java.util package, part 2
Summary: Clean up doclint errors and warnings in classes in java.util
Reviewed-by: darcy,chegar
Contributed-by: Brian Burkhalter <brian.burkhalter@oracle.com>

   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 /**
  33  * A container object which may or may not contain a non-null value.
  34  * If a value is present, {@code isPresent()} will return {@code true} and
  35  * {@code get()} will return the value.
  36  *
  37  * <p>Additional methods that depend on the presence or absence of a contained
  38  * value are provided, such as {@link #orElse(java.lang.Object) orElse()}
  39  * (return a default value if value not present) and
  40  * {@link #ifPresent(java.util.function.Consumer) ifPresent()} (execute a block
  41  * of code if the value is present).
  42  *
  43  * @since 1.8
  44  */
  45 public final class Optional<T> {
  46     /**
  47      * Common instance for {@code empty()}.
  48      */
  49     private static final Optional<?> EMPTY = new Optional<>();
  50 
  51     /**
  52      * If non-null, the value; if null, indicates no value is present
  53      */
  54     private final T value;
  55 
  56     /**
  57      * Constructs an empty instance.
  58      *
  59      * @implNote Generally only one empty instance, {@link Optional#EMPTY},
  60      * should exist per VM.
  61      */
  62     private Optional() {
  63         this.value = null;
  64     }
  65 
  66     /**
  67      * Returns an empty {@code Optional} instance.  No value is present for this
  68      * Optional.
  69      *
  70      * @apiNote Though it may be tempting to do so, avoid testing if an object
  71      * is empty by comparing with {@code ==} against instances returned by
  72      * {@code Option.empty()}. There is no guarantee that it is a singleton.
  73      * Instead, use {@link #isPresent()}.
  74      *
  75      * @param <T> Type of the non-existent value
  76      * @return an empty {@code Optional}
  77      */
  78     public static<T> Optional<T> empty() {
  79         @SuppressWarnings("unchecked")
  80         Optional<T> t = (Optional<T>) EMPTY;
  81         return t;
  82     }
  83 
  84     /**
  85      * Constructs an instance with the value present.
  86      *
  87      * @param value the non-null value to be present
  88      */
  89     private Optional(T value) {
  90         this.value = Objects.requireNonNull(value);
  91     }
  92 
  93     /**
  94      * Returns an {@code Optional} with the specified present non-null value.
  95      *

  96      * @param value the value to be present, which must be non-null
  97      * @return an {@code Optional} with the value present
  98      */
  99     public static <T> Optional<T> of(T value) {
 100         return new Optional<>(value);
 101     }
 102 
 103     /**
 104      * Returns an {@code Optional} describing the specified value, if non-null,
 105      * otherwise returns an empty {@code Optional}.
 106      *

 107      * @param value the possibly-null value to describe
 108      * @return an {@code Optional} with a present value if the specified value
 109      * is non-null, otherwise an empty {@code Optional}
 110      */
 111     public static <T> Optional<T> ofNullable(T value) {
 112         return value == null ? empty() : of(value);
 113     }
 114 
 115     /**
 116      * If a value is present in this {@code Optional}, returns the value,
 117      * otherwise throws {@code NoSuchElementException}.
 118      *
 119      * @return the non-null value held by this {@code Optional}
 120      * @throws NoSuchElementException if there is no value present
 121      *
 122      * @see Optional#isPresent()
 123      */
 124     public T get() {
 125         if (value == null) {
 126             throw new NoSuchElementException("No value present");
 127         }
 128         return value;
 129     }
 130 
 131     /**
 132      * Return {@code true} if there is a value present, otherwise {@code false}.
 133      *
 134      * @return {@code true} if there is a value present, otherwise {@code false}
 135      */
 136     public boolean isPresent() {
 137         return value != null;
 138     }
 139 
 140     /**
 141      * If a value is present, invoke the specified consumer with the value,
 142      * otherwise do nothing.
 143      *
 144      * @param consumer block to be executed if a value is present
 145      * @throws NullPointerException if value is present and {@code consumer} is
 146      * null
 147      */
 148     public void ifPresent(Consumer<? super T> consumer) {
 149         if (value != null)
 150             consumer.accept(value);
 151     }
 152 
 153     /**
 154      * If a value is present, and the value matches the given predicate,
 155      * return an {@code Optional} describing the value, otherwise return an
 156      * empty {@code Optional}.
 157      *
 158      * @param predicate a predicate to apply to the value, if present
 159      * @return an {@code Optional} describing the value of this {@code Optional}
 160      * if a value is present and the value matches the given predicate,
 161      * otherwise an empty {@code Optional}
 162      * @throws NullPointerException if the predicate is null
 163      */
 164     public Optional<T> filter(Predicate<? super T> predicate) {
 165         Objects.requireNonNull(predicate);
 166         if (!isPresent())
 167             return this;
 168         else
 169             return predicate.test(value) ? this : empty();
 170     }
 171 
 172     /**
 173      * If a value is present, apply the provided mapping function to it,
 174      * and if the result is non-null, return an {@code Optional} describing the
 175      * result.  Otherwise return an empty {@code Optional}.
 176      *
 177      * @apiNote This method supports post-processing on optional values, without
 178      * the need to explicitly check for a return status.  For example, the
 179      * following code traverses a stream of file names, selects one that has
 180      * not yet been processed, and then opens that file, returning an
 181      * {@code Optional<FileInputStream>}:
 182      *
 183      * <pre>{@code
 184      *     Optional<FileInputStream> fis =
 185      *         names.stream().filter(name -> !isProcessedYet(name))
 186      *                       .findFirst()
 187      *                       .map(name -> new FileInputStream(name));
 188      * }</pre>
 189      *
 190      * Here, {@code findFirst} returns an {@code Optional<String>}, and then
 191      * {@code map} returns an {@code Optional<FileInputStream>} for the desired
 192      * file if one exists.
 193      *
 194      * @param <U> The type of the result of the mapping function
 195      * @param mapper a mapping function to apply to the value, if present
 196      * @return an {@code Optional} describing the result of applying a mapping
 197      * function to the value of this {@code Optional}, if a value is present,
 198      * otherwise an empty {@code Optional}
 199      * @throws NullPointerException if the mapping function is null
 200      */
 201     public<U> Optional<U> map(Function<? super T, ? extends U> mapper) {
 202         Objects.requireNonNull(mapper);
 203         if (!isPresent())
 204             return empty();
 205         else {
 206             return Optional.ofNullable(mapper.apply(value));
 207         }
 208     }
 209 
 210     /**
 211      * If a value is present, apply the provided {@code Optional}-bearing
 212      * mapping function to it, return that result, otherwise return an empty
 213      * {@code Optional}.  This method is similar to {@link #map(Function)},
 214      * but the provided mapper is one whose result is already an {@code Optional},
 215      * and if invoked, {@code flatMap} does not wrap it with an additional
 216      * {@code Optional}.
 217      *
 218      * @param <U> The type parameter to the {@code Optional} returned by
 219      * @param mapper a mapping function to apply to the value, if present
 220      *           the mapping function
 221      * @return the result of applying an {@code Optional}-bearing mapping
 222      * function to the value of this {@code Optional}, if a value is present,
 223      * otherwise an empty {@code Optional}
 224      * @throws NullPointerException if the mapping function is null or returns
 225      * a null result
 226      */
 227     public<U> Optional<U> flatMap(Function<? super T, Optional<U>> mapper) {
 228         Objects.requireNonNull(mapper);
 229         if (!isPresent())
 230             return empty();
 231         else {
 232             return Objects.requireNonNull(mapper.apply(value));
 233         }
 234     }
 235 
 236     /**
 237      * Return the value if present, otherwise return {@code other}.
 238      *
 239      * @param other the value to be returned if there is no value present, may
 240      * be null
 241      * @return the value, if present, otherwise {@code other}
 242      */
 243     public T orElse(T other) {
 244         return value != null ? value : other;
 245     }
 246 
 247     /**
 248      * Return the value if present, otherwise invoke {@code other} and return
 249      * the result of that invocation.
 250      *
 251      * @param other a {@code Supplier} whose result is returned if no value
 252      * is present
 253      * @return the value if present otherwise the result of {@code other.get()}
 254      * @throws NullPointerException if value is not present and {@code other} is
 255      * null
 256      */
 257     public T orElseGet(Supplier<? extends T> other) {
 258         return value != null ? value : other.get();
 259     }
 260 
 261     /**
 262      * Return the contained value, if present, otherwise throw an exception
 263      * to be created by the provided supplier.
 264      *
 265      * @apiNote A method reference to the exception constructor with an empty
 266      * argument list can be used as the supplier. For example,
 267      * {@code IllegalStateException::new}
 268      *
 269      * @param <X> Type of the exception to be thrown
 270      * @param exceptionSupplier The supplier which will return the exception to
 271      * be thrown
 272      * @return the present value
 273      * @throws X if there is no value present
 274      * @throws NullPointerException if no value is present and
 275      * {@code exceptionSupplier} is null
 276      */
 277     public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X {
 278         if (value != null) {
 279             return value;
 280         } else {
 281             throw exceptionSupplier.get();
 282         }
 283     }
 284 
 285     /**
 286      * Indicates whether some other object is "equal to" this Optional. The
 287      * other object is considered equal if:
 288      * <ul>
 289      * <li>it is also an {@code Optional} and;
 290      * <li>both instances have no value present or;
 291      * <li>the present values are "equal to" each other via {@code equals()}.
 292      * </ul>
 293      *
 294      * @param obj an object to be tested for equality
 295      * @return {code true} if the other object is "equal to" this object
 296      * otherwise {@code false}
 297      */
 298     @Override
 299     public boolean equals(Object obj) {
 300         if (this == obj) {
 301             return true;
 302         }
 303 
 304         if (!(obj instanceof Optional)) {
 305             return false;
 306         }
 307 
 308         Optional other = (Optional) obj;
 309         return Objects.equals(value, other.value);
 310     }
 311 
 312     /**
 313      * Returns the hash code value of the present value, if any, or 0 (zero) if
 314      * no value is present.
 315      *
 316      * @return hash code value of the present value or 0 if no value is present
 317      */
 318     @Override
 319     public int hashCode() {
 320         return Objects.hashCode(value);
 321     }
 322 
 323     /**
 324      * Returns a non-empty string representation of this Optional suitable for
 325      * debugging. The exact presentation format is unspecified and may vary
 326      * between implementations and versions.
 327      *
 328      * @implSpec If a value is present the result must include its string
 329      * representation in the result. Empty and present Optionals must be
 330      * unambiguously differentiable.
 331      *
 332      * @return the string representation of this instance
 333      */
 334     @Override
 335     public String toString() {
 336         return value != null
 337             ? String.format("Optional[%s]", value)
 338             : "Optional.empty";
 339     }
 340 }
--- EOF ---