< prev index next >
src/java.base/share/classes/java/util/OptionalInt.java
Print this page
rev 17011 : 8167981: Optional: add notes explaining intended use
Reviewed-by: XXX
@@ -1,7 +1,7 @@
/*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * 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,10 +43,17 @@
* <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 OptionalInt} may have unpredictable results and should be avoided.
*
+ * @apiNote
+ * {@code OptionalInt} 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 OptionalInt} should
+ * never itself be {@code null}; it should always point to an {@code OptionalInt}
+ * instance.
+ *
* @since 1.8
*/
public final class OptionalInt {
/**
* Common instance for {@code empty()}.
@@ -108,10 +115,16 @@
/**
* If a value is present, returns the value, otherwise throws
* {@code NoSuchElementException}.
*
+ * @apiNote
+ * The methods {@link #orElse(int) orElse()} and
+ * {@link #orElseGet(java.util.function.IntSupplier) 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 OptionalInt}
* @throws NoSuchElementException if no value is present
* @see OptionalInt#isPresent()
*/
public int getAsInt() {
< prev index next >