Package cms.util.maybe

Class Maybe<T>

java.lang.Object
cms.util.maybe.Maybe<T>
All Implemented Interfaces:
Iterable<T>
public abstract class Maybe<T> extends Object implements Iterable<T>
An object that may contain a value of type T. Similar to Java's Optional class but uses a fast checked exception instead of a slow unchecked exception.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Maybe()
    Do nothing.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T, U extends T>
    Maybe<T>
    cast(Maybe<U> in)
    Convert a Maybe<U> to a Maybe<T>, when T is a supertype of U.
    static <T> Maybe<T>
    from(T v)
    Create a Maybe from a possibly null value v.
    static <T> Maybe<T>
    fromOptional(Optional<T> optional)
    Create a Maybe from an Optional value.
    abstract T
    get()
    Returns the contained value, if present.
    static <T> T
    getOptional(Optional<T> optional)
    Get the value in an Optional, if present; otherwise throw the checked exception NoMaybeValue.
    abstract boolean
    isPresent()
    Returns whether a value is contained in this Maybe.
    abstract Iterator<T>
    iterator()
    Provide an iterator that yields either one T or none, depending.
    static <T> Maybe<T>
    none()
    Returns an empty Maybe.
    abstract T
    orElse(T other)
    Returns the contained value, if any; otherwise, returns other.
    abstract T
    orElseGet(Supplier<T> other)
    Returns the contained value, if any; otherwise, returns other.get().
    abstract Maybe<T>
    orElseMaybe(Supplier<Maybe<T>> other)
    Returns this if a value is contained; otherwise, returns other.get().
    abstract <E extends Throwable>
    T
    orElseThrow(E throwable)
    Returns the contained value, if any; otherwise, throws the specified exception.
    static <T> Maybe<T>
    some(T v)
    Creates a Maybe from a non-null argument.
    abstract <U> Maybe<U>
    then(Function<T,U> f)
    If a value v is present, returns a Maybe containing f(v), which must be non-null.
    abstract void
    thenDo(Consumer<T> cons)
    Call cons on the contained value, if any.
    abstract void
    thenElse(Consumer<T> consThen, Runnable procElse)
    If a value is contained, run consThen on the value; otherwise run procElse
    abstract <U> Maybe<U>
    thenMaybe(Function<T,Maybe<U>> f)
    If a value v is present, returns f(v).
    Optional<T>
    toOptional()
    Create an Optional from a Maybe

    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

    forEach, spliterator

  • Constructor Details

    • Maybe

      protected Maybe()
      Do nothing.

  • Method Details

    • isPresent

      public abstract boolean isPresent()
      Returns whether a value is contained in this Maybe.
      Returns:
      whether a value is contained.

    • get

      public abstract T get() throws NoMaybeValue
      Returns the contained value, if present. Otherwise, throws the exception.
      Returns:
      the contained value
      Throws:
      NoMaybeValue - if no value is contained in this Maybe. This method is primarily useful for writing code that is supposed to perform side effects, e.g.: 
       Maybe<T> m = ...
 try {
    ... m.get() ...
 } catch (NoMaybeValue e) {
    ...
 }

    • thenMaybe

      public abstract <U> Maybe<U> thenMaybe(Function<T,Maybe<U>> f)
      If a value v is present, returns f(v). Otherwise, returns an empty Maybe. (This is a monadic bind.) This method is useful for chaining together a series of Maybe accesses. For example, supposing T.foo() returns a Maybe: 
       
 Maybe<T> mt = ...
 mt.thenMaybe(t -> t.foo().then(f -> ...))
   .orElse(...)
      Type Parameters:
      U - The type of the value that may be returned by the function f.
      Parameters:
      f - The function to be applied to the contained value, if any.
      Returns:
      the Maybe returned by f, if a value is contained in this Maybe. Otherwise, an empty Maybe.

    • then

      public abstract <U> Maybe<U> then(Function<T,U> f)
      If a value v is present, returns a Maybe containing f(v), which must be non-null. Otherwise, returns an empty Maybe. (This is a monadic bind composed with a monadic unit.) This method can be used conveniently along with orElse to handle both maybe cases, e.g.: 
       
 Maybe<T> mt = ...
 mt.then(t -> ...)
   .orElse(...)
      Type Parameters:
      U - The type of the value that may be returned by the function f.
      Parameters:
      f - The function to be applied to the contained value, if any.
      Returns:
      a Maybe containing the value f, if a value is contained in this Maybe. Otherwise, an empty Maybe.

    • orElse

      public abstract T orElse(T other)
      Returns the contained value, if any; otherwise, returns other. Note: since orElse is an ordinary method call, its argument is always computed, unlike a Java else statement. If the argument is expensive to compute or has side effects, orElseGet() should be used instead.
      Parameters:
      other - The value to be returned if no value is in this Maybe.
      Returns:
      The contained value, or an empty Maybe.

    • orElseGet

      public abstract T orElseGet(Supplier<T> other)
      Returns the contained value, if any; otherwise, returns other.get().
      Parameters:
      other - The function to use when this Maybe is empty.
      Returns:
      the contained value or other.get().

    • orElseThrow

      public abstract <E extends Throwable> T orElseThrow(E throwable) throws E
      Returns the contained value, if any; otherwise, throws the specified exception.
      Throws:
      E extends Throwable

    • orElseMaybe

      public abstract Maybe<T> orElseMaybe(Supplier<Maybe<T>> other)
      Returns this if a value is contained; otherwise, returns other.get().
      Parameters:
      other - The function to use when this Maybe is empty.
      Returns:
      this or other.get().

    • thenDo

      public abstract void thenDo(Consumer<T> cons)
      Call cons on the contained value, if any.
      Parameters:
      cons - The function to send the contained value to.

    • thenElse

      public abstract void thenElse(Consumer<T> consThen, Runnable procElse)
      If a value is contained, run consThen on the value; otherwise run procElse

    • iterator

      public abstract Iterator<T> iterator()
      Provide an iterator that yields either one T or none, depending.
      Specified by:
      iterator in interface Iterable<T>

    • from

      public static <T> Maybe<T> from(T v)
      Create a Maybe from a possibly null value v. The Maybe will contain a value if v is non-null.
      Type Parameters:
      T - The type of Maybe to be created.
      Parameters:
      v - The value to put into a Maybe, or null.

    • fromOptional

      public static <T> Maybe<T> fromOptional(Optional<T> optional)
      Create a Maybe from an Optional value.
      Type Parameters:
      T - The type of the value inside the Optional.
      Parameters:
      optional - The Optional value.
      Returns:
      If the Optional contains a value, then Some of that value, otherwise None.

    • toOptional

      public Optional<T> toOptional()
      Create an Optional from a Maybe

    • getOptional

      public static <T> T getOptional(Optional<T> optional) throws NoMaybeValue
      Get the value in an Optional, if present; otherwise throw the checked exception NoMaybeValue. This method allows Optionals to be used as if they were Maybes.
      Returns:
      The value in the optional, if any
      Throws:
      NoMaybeValue - if no value is present.

    • none

      public static <T> Maybe<T> none()
      Returns an empty Maybe.

    • some

      public static <T> Maybe<T> some(T v)
      Creates a Maybe from a non-null argument.
      Parameters:
      v - must be non-null
      Throws:
      IllegalArgumentException - if a null value is passed to it.

    • cast

      public static <T, U extends T> Maybe<T> cast(Maybe<U> in)
      Convert a Maybe<U> to a Maybe<T>, when T is a supertype of U. This covariant subtyping is safe because Maybes are immutable.