Module org.klojang.check
Package org.klojang.check.aux

Class Result<T>

java.lang.Object
org.klojang.check.aux.Result<T>
Type Parameters:
T - the type of the result value
All Implemented Interfaces:
Emptyable
public final class Result<T> extends Object implements Emptyable
A simple value container that explicitly allows the value to be null. This class is meant to be used as the return value of methods that would otherwise return null both as the legitimate outcome of a computation and as a signal that the computation yielded no result. The HashMap class is a well-known example. If its get method returns null, it is not clear whether the requested key was absent, or whether it was present, but associated with value null.

Another scenario (and one that we can control) would be iterating over an array and returning a particular element, if found. If the element can itself legitimately be null, it is not clear what a return value of null means not present or really null.

Using the Result class, you would return a Result containing null if the element was present but null. If the element was not present, you would return notAvailable().

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object obj)
    Returns true if the specified object is a Result that either is this Result or contains the same value.
    T
    get()
    Returns the result.
    int
    hashCode()
    Returns the hashcode of the value contained in this Result, or 0 if no result was available.
    <X extends Throwable>
    void
    ifAvailable(FallibleConsumer<T,X> consumer)
    If available, passes the result to the specified consumer; else does nothing.
    boolean
    isAvailable()
    Returns true if the operation that produced this Result successfully computed the result.
    boolean
    isAvailableAndNotNull()
    Returns true if the operation that produced this Result successfully computed the result and the result value was not null.
    boolean
    isAvailableAndNull()
    Returns true if the operation that produced this Result successfully computed the result, but the result value was null.
    boolean
    isDeepNotEmpty()
    Returns true a result is available and is recursively non-empty as per the deepNotEmpty() test.
    boolean
    isEmpty()
    Returns true if no result is available or if the result value is empty as per the empty() test.
    boolean
    isUnavailable()
    Returns true if the operation that produced this Result could not compute a proper result.
    static <T> Result<T>
    notAvailable()
    Returns a special Result instance signifying the absence of a result.
    static <T> Result<T>
    of(T value)
    Returns a Result containing the specified value (possibly null).
    Result<T>
    or(Result<T> alternative)
    Returns this Result if it contains a proper result value (possibly null), else the provided Result.
    T
    orElse(T defaultValue)
    Returns the result value, if available, else the provided default value.
    String
    toString()
    Returns a string representation analogous to the one provided by Optional.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • of

      public static <T> Result<T> of(T value)
      Returns a Result containing the specified value (possibly null).
      Type Parameters:
      T - The type of the result value
      Parameters:
      value - The value
      Returns:
      a Result containing the specified value

    • notAvailable

      public static <T> Result<T> notAvailable()
      Returns a special Result instance signifying the absence of a result.
      Type Parameters:
      T - the type of the result value
      Returns:
      a special Result object signifying the absence of a result

    • get

      public T get() throws NoSuchElementException
      Returns the result. You should have established first that a result value is available or a NoSuchElementException will be thrown.
      Returns:
      the value
      Throws:
      NoSuchElementException - if no result is available

    • isAvailable

      public boolean isAvailable()
      Returns true if the operation that produced this Result successfully computed the result. If so, the result value can be retrieved via the get() method. If not, calling get() method will result in a NoSuchElementException.
      Returns:
      true if a result could be computed

    • isAvailableAndNull

      public boolean isAvailableAndNull()
      Returns true if the operation that produced this Result successfully computed the result, but the result value was null.
      Returns:
      true if a result could be computed, but it turned out to be null

    • isAvailableAndNotNull

      public boolean isAvailableAndNotNull()
      Returns true if the operation that produced this Result successfully computed the result and the result value was not null.
      Returns:
      true if a result could be computed and it was a non-null result

    • isUnavailable

      public boolean isUnavailable()
      Returns true if the operation that produced this Result could not compute a proper result.
      Returns:
      true if the operation that produced this Result could not compute a proper result

    • ifAvailable

      public <X extends Throwable> void ifAvailable(FallibleConsumer<T,X> consumer) throws X
      If available, passes the result to the specified consumer; else does nothing.
      Type Parameters:
      X - the type of the exception thrown by the consumer
      Parameters:
      consumer - the consumer of the result
      Throws:
      X - if the consumer experiences an error

    • orElse

      public T orElse(T defaultValue)
      Returns the result value, if available, else the provided default value.
      Parameters:
      defaultValue - the default value
      Returns:
      the result value, if available, else the provided default value

    • or

      public Result<T> or(Result<T> alternative) throws IllegalArgumentException
      Returns this Result if it contains a proper result value (possibly null), else the provided Result.
      Parameters:
      alternative - the Result to return if this Result is Result.notAvailable(). Must not be null, and must not be Result.notAvailable().
      Returns:
      this instance or the provided instance
      Throws:
      IllegalArgumentException - if the specified Result is Result.notAvailable()

    • isEmpty

      public boolean isEmpty()
      Returns true if no result is available or if the result value is empty as per the empty() test.
      Specified by:
      isEmpty in interface Emptyable
      Returns:
      true if no result is available or the result value is empty.

    • isDeepNotEmpty

      public boolean isDeepNotEmpty()
      Returns true a result is available and is recursively non-empty as per the deepNotEmpty() test.
      Specified by:
      isDeepNotEmpty in interface Emptyable
      Returns:
      true if a result is available and is deep-not-empty

    • equals

      public boolean equals(Object obj)
      Returns true if the specified object is a Result that either is this Result or contains the same value.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare this instance with
      Returns:
      whether this instance equals the specified object.

    • hashCode

      public int hashCode()
      Returns the hashcode of the value contained in this Result, or 0 if no result was available.
      Overrides:
      hashCode in class Object
      Returns:
      the hashcode of the value contained in this Result, or 0 if no result was available

    • toString

      public String toString()
      Returns a string representation analogous to the one provided by Optional.
      Overrides:
      toString in class Object
      Returns:
      a string representation analogous to the one provided by Optional