Package io.atlassian.fugue

Class Option<A>

java.lang.Object
io.atlassian.fugue.Option<A>
Type Parameters:
A - the value type the option contains
All Implemented Interfaces:
Effect.Applicant<A>, Maybe<A>, Serializable, Iterable<A>
Direct Known Subclasses:
Option.None, Option.Some
public abstract class Option<A> extends Object implements Iterable<A>, Maybe<A>, Serializable
A class that encapsulates missing values. An Option may be either some value or none.

If it is a value it may be tested with the Maybe.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 a none of type B if performed on a none of type A. Similarly, filtering will always fail on a none.

This class is often used as an alternative to null where null may be used to represent an optional value. There are however some situations where null may be a legitimate value, and that even though the option is defined, it still carries a null inside. Specifically, this will happen if a function is mapped across it returns null, as it is necessary to preserve the Functor composition law. Note however, that this should be rare as functions that return null is a bad idea anyway. Note that if a function returns null to indicate optionality, it can be lifted into a partial function and then flat mapped instead.

Note: while this class is public and abstract it does not expose a constructor as only the concrete internal subclasses are designed to be used.

Since:
1.0
See Also:

  • Field Details

  • Constructor Details

    • Option

      Option()
      do not constructor

  • Method Details

    • option

      public static <A> Option<A> option(A a)
      Factory method for Option instances.
      Type Parameters:
      A - the contained 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 contained type
      Parameters:
      value - the value to hold, must not be null
      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 contained type
      Parameters:
      type - token of the right type, unused, only here for the type inferencer
      Returns:
      a None

    • defined

      public static <A> Predicate<Option<A>> defined()
      Predicate for filtering defined options only.
      Type Parameters:
      A - the contained type
      Returns:
      a Predicate that returns true only for defined options

    • noneSupplier

      public static <A> Supplier<Option<A>> noneSupplier()
      Supplies None as required. Useful as the zero value for folds.
      Type Parameters:
      A - the contained type
      Returns:
      a Supplier of None instances

    • fromOptional

      public static <A> Option<A> fromOptional(Optional<A> optional)
      Factory method for Option instances from Optional instances.
      Type Parameters:
      A - the contained type
      Parameters:
      optional - a Optional object.
      Returns:
      a Some if Optional.isPresent() or a None otherwise.

    • fold

      public abstract <B> B fold(Supplier<? extends B> none, Function<? super A,? extends 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

    • getOrElse

      public final <B extends A> A getOrElse(B other)
      Get the value if defined, otherwise returns other.
      Specified by:
      getOrElse in interface Maybe<A>
      Type Parameters:
      B - default value type
      Parameters:
      other - value to return if this is empty
      Returns:
      wrapped value if this is defined, otherwise returns other

    • getOr

      public final A getOr(Supplier<? extends A> supplier)
      Get the value if defined or call the supplier and return its value if not. Replaces Maybe.getOrElse(Supplier). Get the value if defined or call the supplier and return its value if not.
      Specified by:
      getOr in interface Maybe<A>
      Parameters:
      supplier - called if this is empty
      Returns:
      the wrapped value or the value from the Supplier

    • getOrElse

      @Deprecated public final A getOrElse(Supplier<? extends A> supplier)
      Deprecated.
      Get the value if defined or call the supplier and return its value if not.
      Specified by:
      getOrElse in interface Maybe<A>
      Parameters:
      supplier - called if this is empty
      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 these must often interface with code that expects and returns nulls.

      Specified by:
      getOrNull in interface Maybe<A>
      Returns:
      the value or null if not defined

    • orElse

      public final Option<A> orElse(Option<? extends A> orElse)
      If this is a some, return the same some. Otherwise, return orElse.
      Parameters:
      orElse - option to return if this is none
      Returns:
      this or orElse
      Since:
      1.1

    • orElse

      public final Option<A> orElse(Supplier<? extends Option<? extends A>> orElse)
      If this is a some, return the same some. Otherwise, return value supplied by orElse.
      Parameters:
      orElse - supplier which provides the option to return if this is none
      Returns:
      this or value supplied by orElse
      Since:
      1.1

    • exists

      public final boolean exists(Predicate<? super A> p)
      Whether this is is defined and applying the predicate to the contained value returns true.
      Specified by:
      exists in interface Maybe<A>
      Parameters:
      p - the predicate to test, must not be null
      Returns:
      true if defined and the predicate returns true for the contained value, false otherwise.

    • forall

      public final boolean forall(Predicate<? super A> p)
      Returns true if empty or the result of the application of the given function to the value.
      Specified by:
      forall in interface Maybe<A>
      Parameters:
      p - The predicate function to test on the contained value, must not be null
      Returns:
      true if no value or returns the result of the application of the given function to the value.

    • isEmpty

      public final boolean isEmpty()
      If the type does not contain a value return true.
      Specified by:
      isEmpty in interface Maybe<A>
      Returns:
      true if this does not hold a value, false otherwise.

    • iterator

      public final Iterator<A> iterator()
      Return an iterator for this type. In most cases this takes the form of an iterator returning zero or one values.
      Specified by:
      iterator in interface Iterable<A>
      Specified by:
      iterator in interface Maybe<A>
      Returns:
      an iterator over the contained value if defined, or an empty one otherwise.

    • map

      public final <B> Option<B> map(Function<? super A,? extends B> f)
      Apply f to the value if defined.

      Transforms to an option of the 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(Function<? super A,? extends Option<? extends B>> f)
      Apply f to the value if defined.

      Transforms to an option of the 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(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
      Returns:
      this option, or none

    • filterNot

      public final Option<A> filterNot(Predicate<? super A> p)
      Returns this Option if it is nonempty and applying the predicate to this option's value returns false. Otherwise, return none().
      Parameters:
      p - the predicate to test
      Returns:
      this option, or none
      Since:
      6.1

    • toRight

      public final <X> Either<X,A> toRight(Supplier<X> left)
      Creates an Either from this Option. Puts the contained value in a right if Maybe.isDefined() otherwise puts the supplier's value in a left.
      Type Parameters:
      X - the left type
      Parameters:
      left - the Supplier to evaluate and return if this is empty
      Returns:
      the content of this option if defined as a right, or the supplier's content as a left if not
      See Also:

    • toLeft

      public final <X> Either<A,X> toLeft(Supplier<X> right)
      Creates an Either from this Option. Puts the contained value in a left if Maybe.isDefined() otherwise puts the supplier's value in a right.
      Type Parameters:
      X - the right type
      Parameters:
      right - the Supplier to evaluate and return if this is empty
      Returns:
      the content of this option if defined as a left, or the supplier's content as a right if not defined.
      See Also:

    • toOptional

      public abstract Optional<A> toOptional()
      Create an Optional from this option. Will throw a NullPointerException if this option is defined and contains a null value.
      Returns:
      Optional.of(Object) with the value if defined and not null, Optional.empty() if not defined.

    • toStream

      public abstract Stream<A> toStream()
      Create a Stream from this option.
      Returns:
      Stream.of(Object) with the value if defined, Stream.empty() if not defined.
      Since:
      4.5.0

    • 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

    • valuesEqual

      private Function<Object,Boolean> valuesEqual()