T
- the type of valuepublic final class Optional<T>
extends java.lang.Object
null
value.
If a value is present, isPresent()
returns true
and
get()
returns the value.
Additional methods that depend on the presence or absence of a contained
value are provided, such as orElse()
(returns a default value if no value is present) and
ifPresent()
(performs an
action if a value is present).
This is a value-based
class; use of identity-sensitive operations (including reference equality
(==
), identity hash code, or synchronization) on instances of
Optional
may have unpredictable results and should be avoided.
Modifier and Type | Method and Description |
---|---|
static <T> Optional<T> |
empty()
Returns an empty
Optional instance. |
boolean |
equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this
Optional . |
Optional<T> |
filter(java.util.function.Predicate<? super T> predicate)
If a value is present, and the value matches the given predicate,
returns an
Optional describing the value, otherwise returns an
empty Optional . |
<U> Optional<U> |
flatMap(java.util.function.Function<? super T,Optional<U>> mapper)
If a value is present, returns the result of applying the given
Optional -bearing mapping function to the value, otherwise returns
an empty Optional . |
T |
get()
If a value is present, returns the value, otherwise throws
NoSuchElementException . |
int |
hashCode()
Returns the hash code of the value, if present, otherwise
0
(zero) if no value is present. |
void |
ifPresent(java.util.function.Consumer<? super T> action)
If a value is present, performs the given action with the value,
otherwise does nothing.
|
void |
ifPresentOrElse(java.util.function.Consumer<? super T> action,
java.lang.Runnable emptyAction)
If a value is present, performs the given action with the value,
otherwise performs the given empty-based action.
|
boolean |
isPresent()
If a value is present, returns
true , otherwise false . |
<U> Optional<U> |
map(java.util.function.Function<? super T,? extends U> mapper)
If a value is present, returns an
Optional describing (as if by
ofNullable(T) ) the result of applying the given mapping function to
the value, otherwise returns an empty Optional . |
static <T> Optional<T> |
of(T value)
Returns an
Optional describing the given non-null
value. |
static <T> Optional<T> |
ofNullable(T value)
Returns an
Optional describing the given value, if
non-null , otherwise returns an empty Optional . |
Optional<T> |
or(java.util.function.Supplier<Optional<T>> supplier)
If a value is present, returns an
Optional describing the value,
otherwise returns an Optional produced by the supplying function. |
T |
orElse(T other)
If a value is present, returns the value, otherwise returns
other . |
T |
orElseGet(java.util.function.Supplier<? extends T> supplier)
If a value is present, returns the value, otherwise returns the result
produced by the supplying function.
|
<X extends java.lang.Throwable> |
orElseThrow(java.util.function.Supplier<? extends X> exceptionSupplier)
If a value is present, returns the value, otherwise throws an exception
produced by the exception supplying function.
|
java.util.stream.Stream<T> |
stream()
If a value is present, returns a sequential
Stream containing
only that value, otherwise returns an empty Stream . |
java.lang.String |
toString()
Returns a non-empty string representation of this
Optional
suitable for debugging. |
public static <T> Optional<T> empty()
Optional
instance. No value is present for this
Optional
.==
against instances returned by
Optional.empty()
. There is no guarantee that it is a singleton.
Instead, use isPresent()
.T
- The type of the non-existent valueOptional
public static <T> Optional<T> of(T value)
Optional
describing the given non-null
value.T
- the type of the valuevalue
- the value to describe, which must be non-null
Optional
with the value presentjava.lang.NullPointerException
- if value is null
public static <T> Optional<T> ofNullable(T value)
Optional
describing the given value, if
non-null
, otherwise returns an empty Optional
.T
- the type of the valuevalue
- the possibly-null
value to describeOptional
with a present value if the specified value
is non-null
, otherwise an empty Optional
public T get()
NoSuchElementException
.null
value described by this Optional
NoSuchElementException
- if no value is presentisPresent()
public boolean isPresent()
true
, otherwise false
.true
if a value is present, otherwise false
public void ifPresent(java.util.function.Consumer<? super T> action)
action
- the action to be performed, if a value is presentjava.lang.NullPointerException
- if value is present and the given action is
null
public void ifPresentOrElse(java.util.function.Consumer<? super T> action, java.lang.Runnable emptyAction)
action
- the action to be performed, if a value is presentemptyAction
- the empty-based action to be performed, if no value is
presentjava.lang.NullPointerException
- if a value is present and the given action
is null
, or no value is present and the given empty-based
action is null
.public Optional<T> filter(java.util.function.Predicate<? super T> predicate)
Optional
describing the value, otherwise returns an
empty Optional
.predicate
- the predicate to apply to a value, if presentOptional
describing the value of this
Optional
, if a value is present and the value matches the
given predicate, otherwise an empty Optional
java.lang.NullPointerException
- if the predicate is null
public <U> Optional<U> map(java.util.function.Function<? super T,? extends U> mapper)
Optional
describing (as if by
ofNullable(T)
) the result of applying the given mapping function to
the value, otherwise returns an empty Optional
.
If the mapping function returns a null
result then this method
returns an empty Optional
.
Optional
values, without
the need to explicitly check for a return status. For example, the
following code traverses a stream of file names, selects one that has not
yet been processed, and then opens that file, returning an
Optional<FileInputStream>
:
Optional<FileInputStream> fis =
names.stream().filter(name -> !isProcessedYet(name))
.findFirst()
.map(name -> new FileInputStream(name));
Here, findFirst
returns an Optional<String>
, and then
map
returns an Optional<FileInputStream>
for the desired
file if one exists.U
- The type of the value returned from the mapping functionmapper
- the mapping function to apply to a value, if presentOptional
describing the result of applying a mapping
function to the value of this Optional
, if a value is
present, otherwise an empty Optional
java.lang.NullPointerException
- if the mapping function is null
public <U> Optional<U> flatMap(java.util.function.Function<? super T,Optional<U>> mapper)
Optional
-bearing mapping function to the value, otherwise returns
an empty Optional
.
This method is similar to map(Function)
, but the mapping
function is one whose result is already an Optional
, and if
invoked, flatMap
does not wrap it within an additional
Optional
.
U
- The type of value of the Optional
returned by the
mapping functionmapper
- the mapping function to apply to a value, if presentOptional
-bearing mapping
function to the value of this Optional
, if a value is
present, otherwise an empty Optional
java.lang.NullPointerException
- if the mapping function is null
or
returns a null
resultpublic Optional<T> or(java.util.function.Supplier<Optional<T>> supplier)
Optional
describing the value,
otherwise returns an Optional
produced by the supplying function.supplier
- the supplying function that produces an Optional
to be returnedOptional
describing the value of this
Optional
, if a value is present, otherwise an
Optional
produced by the supplying function.java.lang.NullPointerException
- if the supplying function is null
or
produces a null
resultpublic java.util.stream.Stream<T> stream()
Stream
containing
only that value, otherwise returns an empty Stream
.Stream
of optional
elements to a Stream
of present value elements:
Stream<Optional<T>> os = ..
Stream<T> s = os.flatMap(Optional::stream)
Stream
public T orElse(T other)
other
.other
- the value to be returned, if no value is present.
May be null
.other
public T orElseGet(java.util.function.Supplier<? extends T> supplier)
supplier
- the supplying function that produces a value to be returnedjava.lang.NullPointerException
- if no value is present and the supplying
function is null
public <X extends java.lang.Throwable> T orElseThrow(java.util.function.Supplier<? extends X> exceptionSupplier) throws X extends java.lang.Throwable
IllegalStateException::new
X
- Type of the exception to be thrownexceptionSupplier
- the supplying function that produces an
exception to be thrownX
- if no value is presentjava.lang.NullPointerException
- if no value is present and the exception
supplying function is null
X extends java.lang.Throwable
public boolean equals(java.lang.Object obj)
Optional
.
The other object is considered equal if:
Optional
and;
equals()
.
equals
in class java.lang.Object
obj
- an object to be tested for equalitytrue
if the other object is "equal to" this object
otherwise false
Object.hashCode()
,
HashMap
public int hashCode()
0
(zero) if no value is present.hashCode
in class java.lang.Object
0
if no value is
presentObject.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public java.lang.String toString()
Optional
suitable for debugging. The exact presentation format is unspecified and
may vary between implementations and versions.toString
in class java.lang.Object
Optional
s must be unambiguously
differentiable. Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.
DRAFT internal-b00