The aim of the Maybe type is to avoid using 'null' references.

A Maybe represents a possibly non-existent value of type T. The Maybe type makes it impossible (without deliberate effort to circumvent the API) to use the value when it does not exist.

A Maybe is either unknown(), in which case a known value does not exist, or definitely(v), in which case the value is known to be v.

A Maybe is iterable, which means you can use it with the for statement to extract a value and do something with it only if there is a value.

class Customer { public Maybe emailAddress() { ... } ... }

for (String emailAddress : aCustomer.emailAddress()) { sendEmailTo(emailAddress); }

Maybe being iterable really comes into its own when combined with the Guava (previously google-collections) library, which has useful functions for working with iterables. You can then work in terms of entire collections of things that might or might not exist, without having to test for the existence of each one.

For example, if I have a collection of 'maybe' email addresses, some of which might exist and some might not:

Iterable<Maybe<String>> maybeEmailAddresses = ...

I can get a set of only the actual email addresses in a single expression:

Set<String> actualEmailAddresses = newHashSet(concat(maybeEmailAddresses));

The newHashSet and concat functions are defined by Guava. Concat creates an Iterable from an Iterable<Iterable>, concatenating the elements of each sequence into a single sequence. Because unknown() is an empty iterable, the concatenated iterable only returns the definite values.

More likely, I have an iterable collection of Customers. Using a Function, I can write a single expression to get the email addresses of all customers who have an email address:

Here's a function to map a customer to its 'maybe' email address:

Function<Customer,Maybe> toEmailAddress = new Function<Customer, Maybe>() { public Maybe apply(Customer c) { return c.emailAddress(); } };

And here's how to use it to get all the email addresses that my customers have, so I can send them product announcements:

Set emailAddresses = newHashSet( concat(transform(customers, toEmailAddress)));

If I just want to send emails, I don't need the hash set:

for (String emailAddress : concat(transform(customers, toEmailAddress))) { sendEmailTo(emailAddress); }

The name "concat" is a bit obscure, so I'd probably define an alias named, for example, "definite", to make the code more readable at the point of use. And the Function definition is a bit clunky, but Java doesn't have (and doesn't look likely to get) a clean syntax for referring to existing functions.

That's not to say that Maybe doesn't have useful methods to work with individual instances. For example, the otherwise method:

T otherwise(T defaultValue);

will return the Maybe's value if it is known and the defaultValue if it is not. E.g.

   assertThat(unknown().otherwise(""), equalTo(""));
   assertThat(definitely("foo").otherwise(""), equalTo("foo"));

Otherwise is overloaded to take a Maybe as a default:

Maybe otherwise(Maybe maybeDefaultValue);

which lets you chain otherwise expressions:

assertThat(unknown().otherwise(definitely("X")).otherwise(""), equalTo("X"));

Maybe also has a method that uses a function to map a Maybe to a Maybe

<U> Maybe<U> to(Function<T,U> mapping);