Maybe: Representing Optional Values
Return a value that may be missing, without ever handing back null.
| Models | A value, or nothing, and never null |
| Replaces | A method that may return null |
| Effect Path | MaybePath |
| Instances | Functor, Applicative, Selective, Monad, MonadError<Unit>, Alternative, MonadZero, Foldable, Traverse |
| Choose it when | Absence needs no reason; otherwise Either, or compare every type in Choosing a Type |
- Turn a lookup that may return
nullinto aMaybe, once, where the value comes in - Chain lookups that may each find nothing, and say when a later one runs
- Read a
Maybewith a fallback, or give its absence a reason withtoEither - Hand a
Maybeto code that takes anOptionalor aStream - Use
Maybein generic code through itsMonadErrorinstance
The code on this page is MaybeBook.java: the page includes it, so the build compiles and runs it. MaybeBookTest.java holds what the page says each method does.
Absence without null
Map.get returns null for a key it does not hold, and so do many older APIs. Nothing in the signature says so, and code that forgets to check fails later with a NullPointerException. A Maybe<T> is a value that may be missing, with the missing case in the type: a Just holds a value, which is never null, and Nothing holds none. It is close to Java's Optional, which Optional covers, and treats null the same way: Maybe.just, like Optional.of, refuses it.
The code on this page uses these imports, with Order, Consignment and Address from the order records the Optics chapter introduces:
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.UUID;
import java.util.stream.Stream;
import org.higherkindedj.example.book.foundations.OrderError;
import org.higherkindedj.example.book.optics.cast.Address;
import org.higherkindedj.example.book.optics.cast.Consignment;
import org.higherkindedj.example.book.optics.cast.Order;
import org.higherkindedj.hkt.either.Either;
import org.higherkindedj.hkt.maybe.Maybe;
ORDERS and CONSIGNMENTS are Maps keyed by order id, and only an order that has shipped has a consignment. Each lookup turns Map.get's null into Nothing, once, where the value comes in:
// Map.get gives null for a missing key, and fromNullable turns that null into Nothing
static Maybe<Order> findOrder(UUID id) {
return Maybe.fromNullable(ORDERS.get(id));
}
static Maybe<Consignment> findConsignment(Order order) {
return Maybe.fromNullable(CONSIGNMENTS.get(order.id()));
}
static Maybe<Order> findArchived(UUID id) {
return Maybe.fromNullable(ARCHIVE.get(id));
}
Chaining lookups
flatMap runs the next lookup on a Just's value, and map changes the value. On Nothing, neither runs, and Nothing reaches the end:
static Maybe<Address> deliveryAddress(UUID id) {
return findOrder(id).flatMap(MaybeBook::findConsignment).map(Consignment::to);
}
PLACED has not shipped, SHIPPED has, and no order has the id UNKNOWN:
Maybe<Address> dispatched = deliveryAddress(SHIPPED.id());
// Just(Address[street=1 High Street, city=Leeds, postcode=LS1 4AP])
Maybe<Address> notDispatched = deliveryAddress(PLACED.id());
// Nothing
Maybe<Address> noSuchOrder = deliveryAddress(UNKNOWN);
// Nothing
The two Nothing results look the same: one order has not shipped, and the other does not exist. Maybe says only that something is missing, not why.
Reading a Maybe
orElse gives a fallback for Nothing, but its text cannot say why the value is missing: an unknown order reads "not dispatched yet" too. When the caller needs the reason, toEither gives the absence one, and the chain continues as an Either:
String city = deliveryAddress(PLACED.id()).map(Address::city).orElse("not dispatched yet");
Either<OrderError, Order> withReason =
findOrder(UNKNOWN).toEither(OrderError.notFound(UNKNOWN));
// Left(NotFound[orderId=00000000-0000-0000-0000-000000000009])
city is "not dispatched yet". get() returns a Just's value and throws NoSuchElementException on Nothing, so keep it for tests. Just and Nothing are not public types, so a switch cannot name them: read a Maybe through its methods, such as fold, which turns either case into one result.
Bridging to the JDK
toOptional() hands a Maybe to code that takes an Optional, and Maybe.fromOptional brings one back. Neither conversion can fail, because neither type holds null. stream() gives a stream of zero or one element, so flatMap(Maybe::stream) keeps only the lookups that found something:
Optional<Address> forJdkCode = deliveryAddress(SHIPPED.id()).toOptional();
// Optional[Address[street=1 High Street, city=Leeds, postcode=LS1 4AP]]
// Keep only the ids that find an order
List<UUID> found =
Stream.of(PLACED.id(), UNKNOWN, SHIPPED.id())
.map(MaybeBook::findOrder)
.flatMap(Maybe::stream)
.map(Order::id)
.toList();
// [00000000-0000-0000-0000-000000000001, 00000000-0000-0000-0000-000000000002]
Among the library's types that can fail, only Maybe has stream(), as Optional does. An empty stream says that a value is missing, while the same conversion on Either or Try would drop the error it holds.
Creating instances
Maybe.just(value) builds a Just, and throws NullPointerException for null. Maybe.fromNullable(value) gives Nothing for null, and Maybe.nothing() gives Nothing directly. Maybe's map gives Nothing, rather than failing, when its function returns null, and its instance's of(null) gives Nothing too, as Values, never null sets out.
On a MaybePath
Application code can hold the same chain on a MaybePath. Path.maybe takes a Maybe, or a value that may be null, via chains the next lookup, and getOrElse reads it. These are the extra imports:
import org.higherkindedj.hkt.effect.MaybePath;
import org.higherkindedj.hkt.effect.Path;
static MaybePath<String> deliveryCity(UUID id) {
return Path.maybe(findOrder(id))
.via(order -> Path.maybe(findConsignment(order)))
.map(consignment -> consignment.to().city());
}
MaybePath<String> leeds = deliveryCity(SHIPPED.id());
// MaybePath(Just(Leeds))
String unknownCity = deliveryCity(UNKNOWN).getOrElse("unknown");
unknownCity is "unknown".
Methods
| Method | What it does |
|---|---|
Maybe.just(value), Maybe.nothing() | Build a Just, throwing NullPointerException for null, or Nothing |
Maybe.fromNullable(value) | Gives Nothing for null, and a Just otherwise |
Maybe.fromOptional(optional), toOptional() | Convert from and to Java's Optional |
Maybe.fromEither(either) | Keeps a Right's value as a Just, and gives Nothing for a Left, dropping its error |
isJust(), isNothing() | Say which case it holds |
map(f) | Changes a Just's value; a function that returns null gives Nothing |
flatMap(f) | Runs a step that gives a Maybe on a Just's value; Nothing passes through |
orElse(other), orElseGet(supplier) | Return the value, or a fallback |
fold(onNothing, onJust) | Turns either case into one result |
toEither(error), toEither(supplier) | Give an Either whose Left says why the value is missing |
stream() | Gives a stream of zero or one element |
get() | Returns the value, or throws NoSuchElementException on Nothing |
Working with Kind
Generic code, written once for any container, takes Maybe through its MonadError instance, as MonadError shows. Its error type is Unit: Nothing is the error, and it carries no detail. The instance works over Kind<MaybeKind.Witness, A>, so you widen a Maybe to pass it in, and narrow the result to read it. These are the extra imports:
import static org.higherkindedj.hkt.instances.Witnesses.maybe;
import static org.higherkindedj.hkt.maybe.MaybeKindHelper.MAYBE;
import org.higherkindedj.hkt.Kind;
import org.higherkindedj.hkt.MonadError;
import org.higherkindedj.hkt.Unit;
import org.higherkindedj.hkt.instances.Instances;
import org.higherkindedj.hkt.maybe.MaybeKind;
ARCHIVED is an order that has moved to the archive, so findOrder misses it and findArchived finds it there:
MonadError<MaybeKind.Witness, Unit> absence = Instances.monadError(maybe());
Kind<MaybeKind.Witness, Order> lookedUp = MAYBE.widen(findOrder(ARCHIVED.id()));
Kind<MaybeKind.Witness, Order> orArchived =
absence.handleErrorWith(lookedUp, unit -> MAYBE.widen(findArchived(ARCHIVED.id())));
Maybe<Order> fromArchive = MAYBE.narrow(orArchived);
// Just(Order[id=00000000-0000-0000-0000-000000000003, ...])
Maybe<Order> raised = MAYBE.narrow(absence.raiseError(Unit.INSTANCE));
// Nothing
Widening allocates nothing: Maybe implements MaybeKind itself, so widen checks for null and returns the same object, and Nothing is one shared instance. Maybe has instances of other type classes too, such as Selective and Traverse, each an object of its own, and Maybe at a glance, at the head of the page, lists them.
Back to the one-liner
static EitherPath<OrderError, Order> changeEmail(
OrderRepository orders, UUID id, String newEmail) {
return orders
.find(id)
.toEitherPath(OrderError.notFound(id))
.map(order -> OrderFocus.customer().email().value().set(newEmail, order))
.via(orders::save);
}
The one-liner starts with orders.find(id), which gives a MaybePath: the order, or nothing. toEitherPath(OrderError.notFound(id)) gives that absence a reason, so the rest of the line can fail with an OrderError. A MaybePath holds a Maybe and calls its methods directly.
When to use Maybe
| You need | Use |
|---|---|
| A value that may be missing, in code you control | Maybe |
| The same lookups as a fluent chain in application code | MaybePath |
To work with an API that returns Optional | Optional, or bridge with fromOptional and toOptional |
| A missing value that must say why | Either, converting with toEither |
Practise Maybe.just, Maybe.nothing and converting to Either, beside Either and Validated, in Tutorial 06: Concrete Types (7 exercises).
Benchmarks: MaybeBenchmark measures how cheaply Nothing passes along a chain, and the cost of fromNullable. Benchmarks & Performance says how to run it.
Previous: NonEmptyList Next: Optional