public final class Optional<T> extends Object
isPresent()
will return true
and
get()
will return the value.
Additional methods that depend on the presence or absence of a contained
value are provided, such as orElse()
(return a default value if value not present) and
ifPresent()
(execute a block
of code if the 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(Object obj)
Indicates whether some other object is "equal to" this Optional.
|
Optional<T> |
filter(Predicate<? super T> predicate)
If a value is present, and the value matches the given predicate,
return an
Optional describing the value, otherwise return an
empty Optional . |
<U> Optional<U> |
flatMap(Function<? super T,Optional<U>> mapper)
If a value is present, apply the provided
Optional -bearing
mapping function to it, return that result, otherwise return an empty
Optional . |
T |
get()
If a value is present in this
Optional , returns the value,
otherwise throws NoSuchElementException . |
int |
hashCode()
Returns the hash code value of the present value, if any, or 0 (zero) if
no value is present.
|
void |
ifPresent(Consumer<? super T> consumer)
If a value is present, invoke the specified consumer with the value,
otherwise do nothing.
|
boolean |
isPresent()
Return
true if there is a value present, otherwise false . |
<U> Optional<U> |
map(Function<? super T,? extends U> mapper)
If a value is present, apply the provided mapping function to it,
and if the result is non-null, return an
Optional describing the
result. |
static <T> Optional<T> |
of(T value)
Returns an
Optional with the specified present non-null value. |
static <T> Optional<T> |
ofNullable(T value)
Returns an
Optional describing the specified value, if non-null,
otherwise returns an empty Optional . |
T |
orElse(T other)
Return the value if present, otherwise return
other . |
T |
orElseGet(Supplier<? extends T> other)
Return the value if present, otherwise invoke
other and return
the result of that invocation. |
<X extends Throwable> |
orElseThrow(Supplier<? extends X> exceptionSupplier)
Return the contained value, if present, otherwise throw an exception
to be created by the provided supplier.
|
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
Option.empty()
. There is no guarantee that it is a singleton.
Instead, use isPresent()
.T
- Type of the non-existent valueOptional
public static <T> Optional<T> of(T value)
Optional
with the specified present non-null value.T
- the class of the valuevalue
- the value to be present, which must be non-nullOptional
with the value presentNullPointerException
- if value is nullpublic static <T> Optional<T> ofNullable(T value)
Optional
describing the specified value, if non-null,
otherwise returns an empty Optional
.T
- the class 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()
Optional
, returns the value,
otherwise throws NoSuchElementException
.Optional
NoSuchElementException
- if there is no value presentisPresent()
public boolean isPresent()
true
if there is a value present, otherwise false
.true
if there is a value present, otherwise false
public void ifPresent(Consumer<? super T> consumer)
consumer
- block to be executed if a value is presentNullPointerException
- if value is present and consumer
is
nullpublic Optional<T> filter(Predicate<? super T> predicate)
Optional
describing the value, otherwise return an
empty Optional
.predicate
- a predicate to apply to the 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
NullPointerException
- if the predicate is nullpublic <U> Optional<U> map(Function<? super T,? extends U> mapper)
Optional
describing the
result. Otherwise return an empty Optional
.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 result of the mapping functionmapper
- a mapping function to apply to the 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
NullPointerException
- if the mapping function is nullpublic <U> Optional<U> flatMap(Function<? super T,Optional<U>> mapper)
Optional
-bearing
mapping function to it, return that result, otherwise return an empty
Optional
. This method is similar to map(Function)
,
but the provided mapper is one whose result is already an Optional
,
and if invoked, flatMap
does not wrap it with an additional
Optional
.U
- The type parameter to the Optional
returned bymapper
- a mapping function to apply to the value, if present
the mapping functionOptional
-bearing mapping
function to the value of this Optional
, if a value is present,
otherwise an empty Optional
NullPointerException
- if the mapping function is null or returns
a null resultpublic T orElse(T other)
other
.other
- the value to be returned if there is no value present, may
be nullother
public T orElseGet(Supplier<? extends T> other)
other
and return
the result of that invocation.other
- a Supplier
whose result is returned if no value
is presentother.get()
NullPointerException
- if value is not present and other
is
nullpublic <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X extends Throwable
IllegalStateException::new
X
- Type of the exception to be thrownexceptionSupplier
- The supplier which will return the exception to
be thrownX
- if there is no value presentNullPointerException
- if no value is present and
exceptionSupplier
is nullX extends Throwable
public boolean equals(Object obj)
Optional
and;
equals()
.
equals
in class Object
obj
- an object to be tested for equalityfalse
Object.hashCode()
,
HashMap
public int hashCode()
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public String toString()
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, 2024, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
Scripting on this page tracks web page traffic, but does not change the content in any way.