com.atlassian.plugin.util
Class Option<A>

java.lang.Object
  com.atlassian.plugin.util.Option<A>

Type Parameters:

A - the value type.

All Implemented Interfaces:

com.google.common.base.Supplier<A>, Iterable<A>

public abstract class Option<A>
extends Object
implements Iterable<A>, com.google.common.base.Supplier<A>

A class that encapsulates null (missing) values. An Option may be either some value or not.

If it is a value it may be tested with the isDefined() method, but more often it is useful to either return the value or an alternative if not set, or map or filter.

Mapping a None of type A to type B will simply return None of type B if performed on a None of type A. Similarly, filtering will always fail on a None.

While this class is public and abstract it does not expose a constructor as only the concrete Some and None subclasses are meant to be used.

Method Summary

static <T> com.google.common.base.Predicate<T>	defined() Filters defined options only.
boolean	equals(Object obj)
boolean	exists(com.google.common.base.Predicate<A> p) Returns this Option if it is nonempty and applying the predicate to this option's value returns true.
Option<A>	filter(com.google.common.base.Predicate<? super A> p) Returns this Option if it is nonempty and applying the predicate to this option's value returns true.
static <T> Iterable<Option<T>>	filterNone(Iterable<Option<T>> options) Filter out undefined options.
static <T> Option<T>	find(Iterable<Option<T>> options) Find the first option that isDefined, or if there aren't any, then none.
<B> Option<B>	flatMap(com.google.common.base.Function<? super A,Option<B>> f) Apply f to the value if defined.
abstract <B> B	fold(com.google.common.base.Supplier<? extends B> none, com.google.common.base.Function<? super A,B> some) If this is a some value apply the some function, otherwise get the none value.
abstract A	get() Get the value if defined.
<B extends A> A	getOrElse(B other) Get the value if defined, otherwise returns other.
A	getOrElse(com.google.common.base.Supplier<A> supplier) Get the value if defined or call the supplier and return its value if not.
A	getOrNull() Get the value if defined or null if not.
int	hashCode()
abstract boolean	isDefined()
boolean	isEmpty()
Iterator<A>	iterator()
<B> Option<B>	map(com.google.common.base.Function<? super A,B> f) Apply f to the value if defined.
static <A> Option<A>	none() Factory method for None instances.
static <A> Option<A>	none(Class<A> type) Factory method for None instances where the type token is handy.
static <A> com.google.common.base.Supplier<Option<A>>	noneSupplier() Supplies None as required.
static <A> Option<A>	option(A a) Factory method for Option instances.
static <A> Option<A>	some(A value) Factory method for Some instances.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

option

public static <A> Option<A> option(A a)

Factory method for Option instances.

Type Parameters:

A - the held type

Parameters:

a - the value to hold

Returns:

a Some if the parameter is not null or a None if it is

some

public static <A> Option<A> some(A value)

Factory method for Some instances.

Type Parameters:

A - the held type

Parameters:

value - the value to hold

Returns:

a Some if the parameter is not null

Throws:

NullPointerException - if the parameter is null

none

public static <A> Option<A> none()

Factory method for None instances.

Type Parameters:

A - the held type

Returns:

a None

none

public static <A> Option<A> none(Class<A> type)

Factory method for None instances where the type token is handy. Allows calling in-line where the type inferencer would otherwise complain.

Type Parameters:

A - the held type

Parameters:

type - token of the right type, unused, only here for the type inferencer

Returns:

a None

find

public static <T> Option<T> find(Iterable<Option<T>> options)

Find the first option that isDefined, or if there aren't any, then none.

Type Parameters:

T - the held type

Parameters:

options - an Iterable of options to search through

filterNone

public static <T> Iterable<Option<T>> filterNone(Iterable<Option<T>> options)

Filter out undefined options.

Type Parameters:

T - the held type

Parameters:

options - many options that may or may not be defined

Returns:

the filtered options

defined

public static <T> com.google.common.base.Predicate<T> defined()

Filters defined options only.

Type Parameters:

T - the held type

Returns:

the filtered options

noneSupplier

public static <A> com.google.common.base.Supplier<Option<A>> noneSupplier()

Supplies None as required. Useful as the zero value for folds.

Type Parameters:

A - the held type

Returns:

a Supplier of None instances

fold

public abstract <B> B fold(com.google.common.base.Supplier<? extends B> none,
                           com.google.common.base.Function<? super A,B> some)

If this is a some value apply the some function, otherwise get the none value.

Type Parameters:

B - the result type

Parameters:

none - the supplier of the None type

some - the function to apply if this is a Some

Returns:

the appropriate value

get

public abstract A get()

Get the value if defined. Throw an exception otherwise.

Specified by:

get in interface com.google.common.base.Supplier<A>

Returns:

the wrapped value

Throws:

NoSuchElementException - if this is a none

isDefined

public abstract boolean isDefined()

Returns:

true if this is a Some, false otherwise.

getOrElse

public final <B extends A> A getOrElse(B other)

Get the value if defined, otherwise returns other.

Parameters:

other - value to return if this is a none

Returns:

wrapped value if this is a Some, otherwise returns other

getOrElse

public final A getOrElse(com.google.common.base.Supplier<A> supplier)

Get the value if defined or call the supplier and return its value if not.

Returns:

the wrapped value or the value from the Supplier

getOrNull

public final A getOrNull()

Get the value if defined or null if not.

Although the use of null is discouraged, code written to use Option must often interface with code that expects and returns nulls.

map

public final <B> Option<B> map(com.google.common.base.Function<? super A,B> f)

Apply f to the value if defined.

Transforms to an option of the functions result type.

Type Parameters:

B - return type of f

Parameters:

f - function to apply to wrapped value

Returns:

new wrapped value

flatMap

public final <B> Option<B> flatMap(com.google.common.base.Function<? super A,Option<B>> f)

Apply f to the value if defined.

Transforms to an option of the functions result type.

Type Parameters:

B - return type of f

Parameters:

f - function to apply to wrapped value

Returns:

value returned from f

filter

public final Option<A> filter(com.google.common.base.Predicate<? super A> p)

Returns this Option if it is nonempty and applying the predicate to this option's value returns true. Otherwise, return none().

Parameters:

p - the predicate to test

exists

public final boolean exists(com.google.common.base.Predicate<A> p)

Returns this Option if it is nonempty and applying the predicate to this option's value returns true. Otherwise, return none().

Parameters:

p - the predicate to test

isEmpty

public final boolean isEmpty()

Returns:

false if this is a Some, true otherwise.

iterator

public final Iterator<A> iterator()

Specified by:

iterator in interface Iterable<A>

Returns:

a single element iterator if this is a Some, an empty one otherwise.

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

equals

public final boolean equals(Object obj)

Overrides:

equals in class Object

toString

public final String toString()

Overrides:

toString in class Object