src/java.base/share/classes/java/util/OptionalLong.java

rev 17011 : 8167981: Optional: add notes explaining intended use
Reviewed-by: XXX

*** 1,7 ****
  /*
!  * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
--- 1,7 ----
  /*
!  * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
*** 43,52 ****
--- 43,59 ----
   * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
   * class; use of identity-sensitive operations (including reference equality
   * ({@code ==}), identity hash code, or synchronization) on instances of
   * {@code OptionalLong} may have unpredictable results and should be avoided.
   *
+  * @apiNote
+  * {@code OptionalLong} is primarily intended for use as a method return type where
+  * there is a clear need to represent "no result," and where using {@code null}
+  * is likely to cause errors. A variable whose type is {@code OptionalLong} should
+  * never itself be {@code null}; it should always point to an {@code OptionalLong}
+  * instance.
+  *
   * @since 1.8
   */
  public final class OptionalLong {
      /**
       * Common instance for {@code empty()}.
*** 108,117 ****
--- 115,130 ----
  
      /**
       * If a value is present, returns the value, otherwise throws
       * {@code NoSuchElementException}.
       *
+      * @apiNote
+      * The methods {@link #orElse(long) orElse()} and
+      * {@link #orElseGet(java.util.function.LongSupplier) orElseGet()}
+      * are generally preferable to this method, as they return a substitute
+      * value if the value is absent, instead of throwing an exception.
+      *
       * @return the value described by this {@code OptionalLong}
       * @throws NoSuchElementException if no value is present
       * @see OptionalLong#isPresent()
       */
      public long getAsLong() {