last modified August 22, 2026
In this article we learn how to create, inspect, transform, and read
Optional values in Java.
Optional is a container object that may or may not contain a value.
An Optional that contains no value is empty. We can test its state
with isPresent or isEmpty, and process a present value
with methods such as ifPresent, map, and
orElse.
Optional is primarily intended as a return type for a method that
may have no result. It does not eliminate null from Java, and it
is usually not useful as a field or method parameter.
The Optional type makes the possibility of a missing result
explicit in the method's return type. This encourages callers to choose what
should happen when no value is available instead of accidentally dereferencing
null.
The examples use Java 25's compact source-file syntax. With an earlier Java
version, place the code inside a class and use a conventional
public static void main(String[] args) method.
var empty = Optional.<String>empty();
We create an empty Optional with Optional.empty.
The explicit type witness is needed here because the expression is assigned to
var without another type context.
var word = Optional.of("falcon");
Optional.of is used when we are certain that the argument is not
null. It throws NullPointerException if the argument is
null.
var word = Optional.ofNullable(value);
Optional.ofNullable is used when the argument may be
null. It creates an empty Optional for a null argument.
In the following example, we have a simple example with Optional
type.
void main() {
var words = Arrays.asList("rock", null, "mountain",
null, "falcon", "sky");
for (var value : words) {
var word = Optional.ofNullable(value);
word.ifPresent(System.out::println);
}
}
We have a list of words; the list also contains null values. We
wrap each value in an Optional and print only the values that are
present.
Optional<String> word = Optional.ofNullable(words.get(i));
We know that we can get a null value from the list; therefore, we
wrap each element in an Optional with
Optional.ofNullable.
word.ifPresent(System.out::println);
We print the value only when the Optional is non-empty. The
ifPresent method accepts the action to run for a present value.
In the following example, we have three methods that return an
Optional type.
void main() {
if (getNullMessage().isPresent()) {
System.out.println(getNullMessage().get());
} else {
System.out.println("n/a");
}
if (getEmptyMessage().isPresent()) {
System.out.println(getEmptyMessage().get());
} else {
System.out.println("n/a");
}
if (getCustomMessage().isPresent()) {
System.out.println(getCustomMessage().get());
} else {
System.out.println("n/a");
}
}
Optional<String> getNullMessage() {
return Optional.ofNullable(null);
}
Optional<String> getEmptyMessage() {
return Optional.empty();
}
Optional<String> getCustomMessage() {
return Optional.of("Hello there!");
}
The three methods return a null message, an empty message and a real message.
if (getNullMessage().isPresent()) {
System.out.println(getNullMessage().get());
} else {
System.out.println("n/a");
}
First, we check if the value returned by the method contains a value with
isPresent. If true, we get the value with get.
Otherwise we print "n/a" message.
The isEmpty method returns true when the
Optional contains no value. It is the logical opposite of
isPresent.
void main() {
var words = Arrays.asList("rock", null, "mountain",
null, "falcon", "sky");
for (var value : words) {
var word = Optional.ofNullable(value);
if (word.isEmpty()) {
System.out.println("n/a");
} else {
System.out.println(word.get());
}
}
}
In the example, we print n/a for empty values and the contained
word for non-empty values. Although get is safe after the
isEmpty check, orElse is usually clearer when a
default value is available.
The orElse method allows us to quickly return a value if it is not
present.
void main() {
System.out.println(getNullMessage().orElse("n/a"));
System.out.println(getEmptyMessage().orElse("n/a"));
System.out.println(getCustomMessage().orElse("n/a"));
}
Optional<String> getNullMessage() {
return Optional.ofNullable(null);
}
Optional<String> getEmptyMessage() {
return Optional.empty();
}
Optional<String> getCustomMessage() {
return Optional.of("Hello there!");
}
We managed to shorten the example a bit with orElse method.
The expression passed to orElse is evaluated even when the
Optional already contains a value. Use orElseGet when
the fallback is expensive to create or requires a method call; its supplier is
evaluated only when the Optional is empty.
var word = Optional.of("falcon");
var result = word.orElseGet(() -> "n/a");
Use orElseThrow() when an empty Optional represents an
error. It throws NoSuchElementException for an empty value. An
overload also accepts a supplier for a more specific exception.
var word = Optional.of("falcon").orElseThrow();
The map method applies a function to the contained value when it
is present. The function returns an ordinary value, which Java wraps in a new
Optional. An empty Optional remains empty.
void main() {
var word = Optional.of("falcon");
var length = word.map(String::length);
length.ifPresent(System.out::println);
}
Here, map changes an Optional<String> into an
Optional<Integer> containing the length of the word.
The flatMap method applies the provided mapping function to a
value if it is present. It returns that result or otherwise an empty
Optional. If the result is already an Optional,
flatMap does not wrap it within an additional
Optional.
void main() {
Function<String, Optional<String>> upperCase = s -> Optional.of(s.toUpperCase());
var words = Arrays.asList("rock", null, "mountain",
null, "falcon", "sky");
for (var value : words) {
var word = Optional.ofNullable(value);
var res = word.flatMap(upperCase);
res.ifPresent(System.out::println);
}
}
In this example, we apply the upperCase function on the list of
words. flatMap returns the Optional from the function
without creating an Optional<Optional<String>>.
In the following example, we use JSoup library to parse and modify an HTML document.
For the project, we need the jsoup artifact.
import org.jsoup.Jsoup;
import org.jsoup.nodes.Element;
void main() {
String htmlString = """
<html>
<head>
<title>My title</title>
</head>
<body>
<main></main>
</body>
</html>
""";
var doc = Jsoup.parse(htmlString);
var mainEl = Optional.ofNullable(doc.select("main").first());
mainEl.ifPresent(e -> {
e.append("<p>hello there!</p>");
e.prepend("<h1>Heading</h1>");
});
System.out.println(doc);
}
We parse an HTML string and look for the main tag. If it is
present, we append p and h1 tags to the document.
var doc = Jsoup.parse(htmlString);
Optional<Element> mainEl = Optional.ofNullable(doc.select("main").first());
The main tag might not be present and the first method
in this case will return null. Therefore, we use the
Optional.ofNullable method.
mainEl.ifPresent(e -> {
e.append("<p>hello there!</p>");
e.prepend("<h1>Heading</h1>");
});
We only call append and prepend methods if the
Optional contains the main tag.
The findOne method returns the only row in the result set, if any.
It returns Optional.empty() if zero rows are returned, or if the
row itself is null.
For the example, we need the jdbi3-core and the
postgresql artifacts.
import org.jdbi.v3.core.Jdbi;
void main() {
var jdbcUrl = "jdbc:postgresql://localhost:5432/testdb";
var user = "postgres";
var password = "your-password";
var jdbi = Jdbi.create(jdbcUrl, user, password);
var id = 3;
var query = "SELECT name FROM cars WHERE id = ?";
var res = jdbi.withHandle(handle -> handle.select(query, id)
.mapTo(String.class)
.findOne());
res.ifPresentOrElse(System.out::println, () -> System.out.println("N/A"));
}
In the example, we select a single cell from a row in a table. We print the data
if it is present or N/A if not.
Java Optional - language reference
My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.
List all Java tutorials.