archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 07:14:30 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8167981: Optional: add notes explaining intended use

Browse source 
Reviewed-by: martin, psandoz
This commit is contained in:
Stuart Marks 2017-04-20 11:40:57 -07:00
parent c629c3c1d6
commit d87636bed7
4 changed files with 58 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

19
jdk/src/java.base/share/classes/java/util/Optional.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2016, 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
@ -36,9 +36,9 @@ import java.util.stream.Stream;
* {@code get()} returns the value.
*
* <p>Additional methods that depend on the presence or absence of a contained
* value are provided, such as {@link #orElse(java.lang.Object) orElse()}
* value are provided, such as {@link #orElse(Object) orElse()}
* (returns a default value if no value is present) and
* {@link #ifPresent(java.util.function.Consumer) ifPresent()} (performs an
* {@link #ifPresent(Consumer) ifPresent()} (performs an
* action if a value is present).
*
* <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
@ -46,6 +46,13 @@ import java.util.stream.Stream;
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code Optional} may have unpredictable results and should be avoided.
*
* @apiNote
* {@code Optional} 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 Optional} should
* never itself be {@code null}; it should always point to an {@code Optional}
* instance.
*
* @param <T> the type of value
* @since 1.8
*/
@ -129,6 +136,12 @@ public final class Optional<T> {
* If a value is present, returns the value, otherwise throws
* {@code NoSuchElementException}.
*
* @apiNote
* The methods {@link #orElse(Object) orElse} and
* {@link #orElseGet(Supplier) 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 non-{@code null} value described by this {@code Optional}
* @throws NoSuchElementException if no value is present
* @see Optional#isPresent()