net.sf.staccatocommons.lang
Class Option<A>

java.lang.Object
  net.sf.staccatocommons.lang.Option<A>

Type Parameters:

A - the type of optional value

All Implemented Interfaces:

Serializable, Iterable<A>, net.sf.staccatocommons.defs.partial.ContainsAware<A>, net.sf.staccatocommons.defs.partial.EmptyAware, net.sf.staccatocommons.defs.partial.SizeAware, net.sf.staccatocommons.defs.ProtoMonad<Option,A>, net.sf.staccatocommons.defs.Thunk<A>

Direct Known Subclasses:

None, Some

@Value
@Conditionally(value={net.sf.staccatocommons.restrictions.value.Immutable.class,java.io.Serializable.class})
public abstract class Option<A>
extends Object
implements net.sf.staccatocommons.defs.Thunk<A>, Iterable<A>, net.sf.staccatocommons.defs.partial.SizeAware, net.sf.staccatocommons.defs.partial.ContainsAware<A>, net.sf.staccatocommons.defs.ProtoMonad<Option,A>, Serializable

Option represent optional values, that can either be instances of Some or None.

There are three possible scenarios where Option type should be used

• When a method may fail without throwing an exception and returns an unusable value. Traditionally, this problem is solved using null as centinel value. For example, Map.get(Object), returns null if there is no object mapped for the given key. This kind of code can be tricky, as clients may ignore this and continue using the returned value without checking it. What is more, such client code can even consider null values valid and usable, and then a return value of null has an ambiguous meaning. Using Options removes ambiguity.
• When there are uninitialized attributes, but null is already a valid initialized value, and should not be treated the same way. Traditionally, this is solved with extra boolean variables, but this is error prone. Again, use Option instead, which traits nulls and not-set values not the same way
• When properties may be unset as a valid state, and null is not a valid value for the property if set. Client code may forget to check this condition, and causing NullPointerException.

Option subclasses redefine Object.equals(Object) and Object.hashCode(), so that two instances are equal as long they values are equal, or as long they are undefined.

Author:

flbulgarelli

See Also:

Serialized Form

Method Summary

Option<A>	filter(net.sf.staccatocommons.defs.Evaluable<? super A> predicate) Answers this option if defined and the given predicate evaluates to true.
void	forEach(net.sf.staccatocommons.defs.Executable<? super A> block)
abstract void	ifDefined(net.sf.staccatocommons.defs.Executable<? super A> block) Executed the given block if this option is defined
abstract boolean	isDefined() Returns if the value has been defined or not.
boolean	isUndefined()
<T2> Option<T2>	map(net.sf.staccatocommons.defs.Applicable<? super A,? extends T2> function) Applies the given function to the Option's value and wraps it into an Option, if defined.
static <T> None<T>	none() Factory method for creating an undefined value.
static <T> Option<T>	nullToNone(T value) Creates an option (defined or not), mapping null values to undefined options, and non nulls to defined option.
static <T> Some<T>	some(T value) Factory method for creating defined values.This method does not guarantee either to return the same or different instances for the same argument.
static <T> Some<T>	someNull() Factory method for creating defined, null values.
abstract A	value() Gets the optional value, if defined, or throws an NoSuchElementException, otherwise.
abstract A	valueOrElse(A other) Returns the value of this Option, or the provided object if undefined
abstract A	valueOrElse(net.sf.staccatocommons.defs.Thunk<? extends A> other) Returns the value of this Option, or the provided object if undefined
abstract A	valueOrNull() Returns the value of this Option, or null, if undefined.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

iterator

Methods inherited from interface net.sf.staccatocommons.defs.partial.SizeAware

isEmpty, size

Methods inherited from interface net.sf.staccatocommons.defs.partial.ContainsAware

contains

Methods inherited from interface net.sf.staccatocommons.defs.ProtoMonad

skip

Method Detail

value

public abstract A value()
                 throws NoSuchElementException

Gets the optional value, if defined, or throws an NoSuchElementException, otherwise.

Specified by:

value in interface net.sf.staccatocommons.defs.Thunk<A>

Returns:

The optional value. This value is nullable, if client code considers null as possible, valid values. Non null otherwise. Please prefer the second approach, as normally, null values are there in code to represent optional data, so nullable values in optional values is in most scenarios completely redundant, unnecessary an error prone.

Throws:

NoSuchElementException - if this option is undefined, and thus there is no value.

isDefined

public abstract boolean isDefined()

Returns if the value has been defined or not.

Returns:

true is the value is defined. False otherwise

isUndefined

public boolean isUndefined()

Returns:

!isDefined()

map

public final <T2> Option<T2> map(net.sf.staccatocommons.defs.Applicable<? super A,? extends T2> function)

Applies the given function to the Option's value and wraps it into an Option, if defined. Returns none(), otherwise

Specified by:

map in interface net.sf.staccatocommons.defs.ProtoMonad<Option,A>

Type Parameters:

T2 -

Parameters:

function -

Returns:

the mapped Option

filter

public final Option<A> filter(net.sf.staccatocommons.defs.Evaluable<? super A> predicate)

Answers this option if defined and the given predicate evaluates to true. Answers none(), otherwise

Specified by:

filter in interface net.sf.staccatocommons.defs.ProtoMonad<Option,A>

Parameters:

predicate -

Returns:

the filtered Option

none

@Constant
public static <T> None<T> none()

Factory method for creating an undefined value. This method guarantees to return always the same instance.

Type Parameters:

T - the type of optional value

Returns:

A constant None instance

valueOrElse

public abstract A valueOrElse(A other)

Returns the value of this Option, or the provided object if undefined

Parameters:

other - the return value in case this Option is undefined

Returns:

this.value() if defined, other otherwise

valueOrElse

public abstract A valueOrElse(net.sf.staccatocommons.defs.Thunk<? extends A> other)

Returns the value of this Option, or the provided object if undefined

Parameters:

other - the thunk of the return value in case this Option is undefined

Returns:

this.value() if defined, other.value() otherwise

valueOrNull

public abstract A valueOrNull()

Returns the value of this Option, or null, if undefined.

Returns:

this.value() if defined, or null, otherwise

ifDefined

public abstract void ifDefined(@NonNull
                               net.sf.staccatocommons.defs.Executable<? super A> block)

Executed the given block if this option is defined

Parameters:

block -

forEach

public void forEach(@NonNull
                    net.sf.staccatocommons.defs.Executable<? super A> block)

Specified by:

forEach in interface net.sf.staccatocommons.defs.ProtoMonad<Option,A>

some

public static <T> Some<T> some(T value)

Factory method for creating defined values.This method does not guarantee either to return the same or different instances for the same argument.

Type Parameters:

T - the type of optional value

Parameters:

value - May be null (although is discouraged). See value() for details

Returns:

Some(value)

someNull

public static <T> Some<T> someNull()

Factory method for creating defined, null values. This method is just a shortcut for some(null). Guaranteed to return always the same instance.

Type Parameters:

T -

Returns:

A shared null instance

nullToNone

public static <T> Option<T> nullToNone(T value)

Creates an option (defined or not), mapping null values to undefined options, and non nulls to defined option. This method lets client code to convert between null-as-undefined and

Type Parameters:

T -

Parameters:

value -

Returns:

value != null ? Option.some(value) : Option.none()