Module com.jongsoft.lang
Package com.jongsoft.lang.control

Interface Optional<T>

  • Type Parameters:
    T - the type of entity contained in the Optional
    All Superinterfaces:
    java.lang.Iterable<T>, java.io.Serializable, Streamable<T>, Value<T>
    public interface Optional<T>
extends Value<T>
    The Optional provides a functional way to detect null values without null reference checks or complicated logic throughout the code base.

    Usage of this Optional is advices as a return type rather then using null as it moves away the change of potential NullPointerException in the code calling the operation. 

      // Sample usage of the Optional
     API.Option("one")
          .ifPresent(System.out::println)
          .orElse(() -> System.out.println("No value is present");
    Since:
    0.0.1

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  Optional.OrElse
      The OrElse interface is an extension to the Optional interface.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      Optional<T> filter​(java.util.function.Predicate<T> predicate)
      Filter out an element if it does not match the supplied predicate.
      T getOrSupply​(java.util.function.Supplier<T> supplier)
      This method will provide the entity contained within the Optional, in case no entity is present the Supplier is called to create the else situation.
      <X extends java.lang.Throwable>
      T      		 getOrThrow​(java.util.function.Supplier<X> exceptionSupplier)
      This method will return the contained entity within the Optional, in case no entity is present an exception will be thrown using the provided exceptionSupplier.
      default Optional.OrElse ifNotPresent​(java.lang.Runnable runner)
      Execute the runner method if no entity is present in this wrapped object
      default <X extends java.lang.Throwable>
      Optional.OrElse      		 ifNotPresent​(java.util.function.Supplier<X> exceptionSupplier)
      Throws an exception when no value is present in this value
      Optional.OrElse ifPresent​(java.util.function.Consumer<T> consumer)
      Process the present element wrapped within using the provided Consumer.
      <X extends java.lang.Throwable>
      Optional.OrElse      		 ifPresent​(java.util.function.Supplier<X> exceptionSupplier)
      Throw an exception if an element is present within.
      boolean isPresent()
      Indicates if a value is present within the wrapper
      default boolean isSingleValued()
      Is this instance single-valued or not.
      <U> Optional<U> map​(java.util.function.Function<T,​U> mapper)
      Perform a mapping operation on the elements in the stream.

      • Methods inherited from interface java.lang.Iterable

        forEach, iterator, spliterator

    • Method Detail

      • filter

        Optional<T> filter​(java.util.function.Predicate<T> predicate)
        Description copied from interface: Streamable
        Filter out an element if it does not match the supplied predicate. This operation will iterate over all elements and return a new set containing only the elements where the predicate returns true for.
        Specified by:
        filter in interface Streamable<T>
        Parameters:
        predicate - the predicate to apply to the contents of this
        Returns:
        the filtered value

      • getOrSupply

        T getOrSupply​(java.util.function.Supplier<T> supplier)
        This method will provide the entity contained within the Optional, in case no entity is present the Supplier is called to create the else situation.
        Parameters:
        supplier - the supplier to create an entity of none is contained in the Optional
        Returns:
        either the contained entity or the created one using the Supplier

      • getOrThrow

        <X extends java.lang.Throwable> T getOrThrow​(java.util.function.Supplier<X> exceptionSupplier)
                                      throws X extends java.lang.Throwable
        This method will return the contained entity within the Optional, in case no entity is present an exception will be thrown using the provided exceptionSupplier.
        Type Parameters:
        X - the type of the Throwable that will be thrown
        Parameters:
        exceptionSupplier - the Supplier used to create the Throwable
        Returns:
        the entity contained within the Optional
        Throws:
        X - in case of no entity
        java.lang.NullPointerException - in case the exceptionSupplier was null
        X extends java.lang.Throwable

      • ifNotPresent

        default Optional.OrElse ifNotPresent​(java.lang.Runnable runner)
        Execute the runner method if no entity is present in this wrapped object
        Parameters:
        runner - the code to execute if nothing is present
        Returns:
        the Optional.OrElse functionality, which enables processing in case of isPresent() being true.
        Throws:
        java.lang.NullPointerException - in case the runner is null

      • ifNotPresent

        default <X extends java.lang.Throwable> Optional.OrElse ifNotPresent​(java.util.function.Supplier<X> exceptionSupplier)
                                                              throws X extends java.lang.Throwable
        Throws an exception when no value is present in this value
        Type Parameters:
        X - the type of exception expected
        Parameters:
        exceptionSupplier - the supplier to create the exception
        Returns:
        the Optional.OrElse functionality, which enables processing in case of isPresent() being true.
        Throws:
        X - the exception thrown if no present element
        java.lang.NullPointerException - in case the exceptionSupplier is null
        X extends java.lang.Throwable

      • ifPresent

        Optional.OrElse ifPresent​(java.util.function.Consumer<T> consumer)
        Process the present element wrapped within using the provided Consumer.
        Parameters:
        consumer - the method that will consume the element
        Returns:
        the Optional.OrElse functionality, which enables processing in case of isPresent() being false.

      • ifPresent

        <X extends java.lang.Throwable> Optional.OrElse ifPresent​(java.util.function.Supplier<X> exceptionSupplier)
                                                   throws X extends java.lang.Throwable
        Throw an exception if an element is present within. Otherwise it will return the Optional.OrElse.
        Type Parameters:
        X - the type of exception expected
        Parameters:
        exceptionSupplier - the supplier to create the exception
        Returns:
        the Optional.OrElse in case no element is present
        Throws:
        X - the exception thrown if a present element
        X extends java.lang.Throwable

      • isPresent

        boolean isPresent()
        Indicates if a value is present within the wrapper
        Returns:
        true if an element is present, otherwise false

      • isSingleValued

        default boolean isSingleValued()
        Description copied from interface: Value
        Is this instance single-valued or not.
        Specified by:
        isSingleValued in interface Value<T>
        Returns:
        true if single-valued, otherwise false

      • map

        <U> Optional<U> map​(java.util.function.Function<T,​U> mapper)
        Description copied from interface: Streamable
        Perform a mapping operation on the elements in the stream.

        This operation will loop over all elements in the stream and apply the mapper method. The mapped values will be returned in as a new stream of elements.

        Specified by:
        map in interface Streamable<T>
        Type Parameters:
        U - the type of object expected as a result
        Parameters:
        mapper - the mapping functionality
        Returns:
        the mapped object