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

rev 14279 : [mq]: 8140281-deprecation-optional.get

*** 105,129 ****
--- 105,162 ----
      public static OptionalLong of(long value) {
          return new OptionalLong(value);
      }
  
      /**
+      * Equivalent to {@link #getWhenPresent()}.
       * If a value is present, returns the value, otherwise throws
       * {@code NoSuchElementException}.
       *
+      * @deprecated
+      * This method's name {@code getAsLong} makes it the obvious method to
+      * call to retrieve the value from this {@code OptionalLong}. However, it has
+      * no mechanism to avoid an exception if this {@code OptionalLong} is empty.
+      * This tends to lead to code that mishandles empty {@code OptionalLong}
+      * values. Consider using other methods that handle the case where
+      * the {@code OptionalLong} might be empty, such as
+      * {@link #ifPresent(java.util.function.LongConsumer) ifPresent()}
+      * and related methods, and
+      * {@link #orElse(long) orElse()} and related methods.
+      * Use {@link getWhenPresent()} when it is known that a value is
+      * always present.
+      *
       * @return the value described by this {@code OptionalLong}
       * @throws NoSuchElementException if no value is present
       * @see OptionalLong#isPresent()
       */
+     @Deprecated(since="9")
      public long getAsLong() {
          if (!isPresent) {
              throw new NoSuchElementException("No value present");
          }
          return value;
      }
  
      /**
+      * If a value is present, returns the value, otherwise throws
+      * {@code NoSuchElementException}.
+      *
+      * @apiNote
+      * Use this method only when it is known that a value is always present.
+      *
+      * @return the value described by this {@code OptionalLong}
+      * @throws NoSuchElementException if no value is present
+      * @see OptionalLong#isPresent()
+      */
+     public long getWhenPresent() {
+         if (!isPresent) {
+             throw new NoSuchElementException("No value present");
+         }
+         return value;
+     }
+ 
+     /**
       * If a value is present, returns {@code true}, otherwise {@code false}.
       *
       * @return {@code true} if a value is present, otherwise {@code false}
       */
      public boolean isPresent() {