Package ortus.boxlang.runtime.dynamic

Class Attempt<T>

java.lang.Object
ortus.boxlang.runtime.dynamic.Attempt<T>
public class Attempt<T> extends Object
This class is a fluent class inspired by Java optionals. It allows for a more fluent way to handle truthy and falsey values in BoxLang with functional aspects.

It is useful when you have a value that could be null or not, and you want to handle it in a more functional way.

Attemps are also immutable, so you can chain methods to handle the value in a more functional way, but it never mutates the original value.

You can also seed the value with a Function (closure or lambda) that will be executed when the value is requested. This gives you a delayed attempt.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Attempt<T>
    empty()
    Create an empty attempt
    boolean
    equals(Object obj)
    Equals method
    Attempt<T>
    filter(Predicate<? super T> predicate)
    If a value is present, and the value matches the given predicate, returns an Optional describing the value, otherwise returns an empty Optional.
    <U> Attempt<U>
    flatMap(Function<? super T,? extends Attempt<? extends U>> mapper)
    If a value is present, returns the result of applying the given Attempt-bearing mapping function to the value, otherwise returns an empty Attempt.
    T
    get()
    Get the value of the attempt
    T
    getOrDefault(T other)
    Alias to `orElse` but more fluent
    int
    hashCode()
    Hash code of the value
    Attempt<T>
    ifEmpty(Runnable consumer)
    If the attempt is NOT present, run the consumer
    boolean
    ifFailed()
    Functional alias to isEmpty()
    Attempt<T>
    ifInvalid(Consumer<? super T> action)
    If the attempt is invalid, run the consumer This is useful for side effects If the attempt is empty and invalid, the consumer is not run
    Attempt<T>
    ifPresent(Consumer<? super T> action)
    If a value is present, performs the given action with the value, otherwise does nothing.
    Attempt<T>
    ifPresentOrElse(Consumer<? super T> action, Runnable emptyAction)
    If a value is present, performs the given action with the value, otherwise performs the given empty-based action.
    Attempt<T>
    ifValid(Consumer<? super T> action)
    If the attempt is valid, run the consumer This is useful for side effects If the attempt is empty and invalid, the consumer is not run
    boolean
    isEmpty()
    Verifies if the attempt is empty or not using the following rules: - If the value is a function, execute it and set the value to the result - If the value is null, it is empty - If the value is a truthy/falsey value, evaluate it
    boolean
    isNull()
    Verifies if the value is null or not
    boolean
    isPresent()
    Verifies if the attempt is empty or not using the following rules: - If the value is null, it is empty - If the value is castable to BoxLang Boolean, evaluate it - If the value is an object, it is not empty
    boolean
    isValid()
    Verifies if the attempt is valid or not according to the validation rules registered If the attempt is empty, it is not valid
    <U> Attempt<U>
    map(Function<? super T,? extends U> mapper)
    Map the attempt to a new value with a supplier
    static <T> Attempt<T>
    of(T value)
    Create an attempt from a value.
    Attempt<T>
    or(Supplier<Attempt<T>> supplier)
    If a value is present, returns the Attempt, otherwise returns an Attempt produced by the supplying function.
    T
    orElse(T other)
    If a value is present, returns the value, otherwise returns the other passed value passed
    T
    orElseGet(Supplier<T> supplier)
    If a value is present, returns the value, otherwise returns the result produced by the supplying function.
    T
    orThrow()
    If a value is present, returns the value, otherwise throws a NoElementException
    T
    orThrow(Exception throwable)
    If a value is present, returns the value, otherwise throws a provided
    T
    orThrow(String message)
    If a value is present, returns the value, otherwise throws a NoElementException with a custom message
    Stream<T>
    stream()
    If a value is present, returns a sequential Stream containing only that value, otherwise returns an empty Stream.
    Attempt<T>
    toBe(Object other)
    Stores a value to explicitly match against
    Attempt<T>
    toBeBetween(Double min, Double max)
    Validates the attempt to be between a range of numbers This assumes the value is a number or castable to a number The range is inclusive If the value is null, it is not valid
    Attempt<T>
    toBeType(String type)
    Validates the attempt to be a specific BoxLang type that you can pass to the isValid function.
    Attempt<T>
    toMatchRegex(String pattern)
    Validates the attempt to match a regex pattern with case sensitivity This assumes the value is a string or castable to a string
    Attempt<T>
    toMatchRegex(String pattern, Boolean caseSensitive)
    Validates the attempt to match a regex pattern with case sensitivity or not
    Attempt<T>
    toSatisfy(Predicate<Object> predicate)
    Register a validation function to the attempt This function will be executed when the attempt is evaluated It must return TRUE for the attempt to be valid
    String
    toString()
    Returns the string representation of the value
    boolean
    wasSuccessful()
    Return true if there is a value present, otherwise false.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • of

      public static <T> Attempt<T> of(T value)
      Create an attempt from a value. This can be anything, a truthy or falsey or null
      Parameters:
      value - The value of the attempt, truthy or falsey
      Returns:
      a new attempt with the value

    • empty

      public static <T> Attempt<T> empty()
      Create an empty attempt
      Returns:
      An empty attempt

    • toMatchRegex

      public Attempt<T> toMatchRegex(String pattern)
      Validates the attempt to match a regex pattern with case sensitivity This assumes the value is a string or castable to a string
      Parameters:
      pattern - The pattern to match
      Returns:
      The attempt

    • toMatchRegex

      public Attempt<T> toMatchRegex(String pattern, Boolean caseSensitive)
      Validates the attempt to match a regex pattern with case sensitivity or not
      Parameters:
      pattern - The pattern to match
      caseSensitive - True if the match is case sensitive, false otherwise
      Returns:
      The attempt

    • toBeBetween

      public Attempt<T> toBeBetween(Double min, Double max)
      Validates the attempt to be between a range of numbers This assumes the value is a number or castable to a number The range is inclusive If the value is null, it is not valid
      Parameters:
      min - The minimum value
      max - The maximum value
      Returns:
      The attempt

    • toBeType

      public Attempt<T> toBeType(String type)
      Validates the attempt to be a specific BoxLang type that you can pass to the isValid function.
      Parameters:
      type - The type to validate
      Returns:
      The attempt
      See Also:

    • toSatisfy

      public Attempt<T> toSatisfy(Predicate<Object> predicate)
      Register a validation function to the attempt This function will be executed when the attempt is evaluated It must return TRUE for the attempt to be valid
      Parameters:
      predicate - The predicate to register
      Returns:
      The attempt

    • toBe

      public Attempt<T> toBe(Object other)
      Stores a value to explicitly match against
      Parameters:
      other - The value to match against
      Returns:
      The attempt

    • isValid

      public boolean isValid()
      Verifies if the attempt is valid or not according to the validation rules registered If the attempt is empty, it is not valid
      Returns:
      True if the attempt is valid, false otherwise

    • ifValid

      public Attempt<T> ifValid(Consumer<? super T> action)
      If the attempt is valid, run the consumer This is useful for side effects If the attempt is empty and invalid, the consumer is not run
      Parameters:
      action - The action to run if the attempt is valid
      Returns:
      The attempt

    • ifInvalid

      public Attempt<T> ifInvalid(Consumer<? super T> action)
      If the attempt is invalid, run the consumer This is useful for side effects If the attempt is empty and invalid, the consumer is not run
      Parameters:
      action - The action to run if the attempt is invalid
      Returns:
      The attempt

    • get

      public T get()
      Get the value of the attempt
      Returns:
      The value of the attempt
      Throws:
      NoElementException - If the attempt is empty

    • isEmpty

      public boolean isEmpty()
      Verifies if the attempt is empty or not using the following rules: - If the value is a function, execute it and set the value to the result - If the value is null, it is empty - If the value is a truthy/falsey value, evaluate it

    • isNull

      public boolean isNull()
      Verifies if the value is null or not
      Returns:
      True if the attempt is null

    • ifFailed

      public boolean ifFailed()
      Functional alias to isEmpty()
      Returns:
      True if the attempt is empty

    • wasSuccessful

      public boolean wasSuccessful()
      Return true if there is a value present, otherwise false. This is an alias to isPresent() for functional programming
      Returns:
      true if there is a value present, otherwise false

    • isPresent

      public boolean isPresent()
      Verifies if the attempt is empty or not using the following rules: - If the value is null, it is empty - If the value is castable to BoxLang Boolean, evaluate it - If the value is an object, it is not empty

    • ifPresent

      public Attempt<T> ifPresent(Consumer<? super T> action)
      If a value is present, performs the given action with the value, otherwise does nothing.
      Parameters:
      action - The action to perform

    • ifPresentOrElse

      public Attempt<T> ifPresentOrElse(Consumer<? super T> action, Runnable emptyAction)
      If a value is present, performs the given action with the value, otherwise performs the given empty-based action.

    • ifEmpty

      public Attempt<T> ifEmpty(Runnable consumer)
      If the attempt is NOT present, run the consumer
      Parameters:
      consumer - The consumer to run

    • or

      public Attempt<T> or(Supplier<Attempt<T>> supplier)
      If a value is present, returns the Attempt, otherwise returns an Attempt produced by the supplying function.
      Parameters:
      supplier - The supplier to run if the attempt is empty

    • orElse

      public T orElse(T other)
      If a value is present, returns the value, otherwise returns the other passed value passed
      Parameters:
      other - The value to return if the attempt is empty
      Returns:
      The value of the attempt or the value passed in

    • getOrDefault

      public T getOrDefault(T other)
      Alias to `orElse` but more fluent
      Parameters:
      other - The value to return if the attempt is empty
      Returns:
      The value of the attempt or the value passed in

    • orElseGet

      public T orElseGet(Supplier<T> supplier)
      If a value is present, returns the value, otherwise returns the result produced by the supplying function.
      Parameters:
      supplier - The supplier to run if the attempt is empty
      Returns:
      The value of the attempt or the value of the supplier

    • map

      public <U> Attempt<U> map(Function<? super T,? extends U> mapper)
      Map the attempt to a new value with a supplier
      Parameters:
      mapper - The mapper to map the attempt to
      Returns:
      The new attempt

    • flatMap

      public <U> Attempt<U> flatMap(Function<? super T,? extends Attempt<? extends U>> mapper)
      If a value is present, returns the result of applying the given Attempt-bearing mapping function to the value, otherwise returns an empty Attempt.

      This method is similar to

      invalid reference 
      #map(Function)
      , but the mapping function is one whose result is already an Attempt, and if invoked, flatMap does not wrap it within an additional Attempt.
      Type Parameters:
      U - The type of value of the Attempt returned by the mapping function
      Parameters:
      mapper - the mapping function to apply to a value, if present
      Returns:
      the result of applying an Attempt-bearing mapping function to the value of this Attempt, if a value is present, otherwise an empty Attempt

    • orThrow

      public T orThrow()
      If a value is present, returns the value, otherwise throws a NoElementException
      Returns:
      The value of the attempt if present
      Throws:
      NoElementException - If the attempt is empty

    • orThrow

      public T orThrow(String message)
      If a value is present, returns the value, otherwise throws a NoElementException with a custom message
      Parameters:
      message - The message to display
      Returns:
      The value of the attempt if present
      Throws:
      NoElementException - If the attempt is empty

    • orThrow

      public T orThrow(Exception throwable)
      If a value is present, returns the value, otherwise throws a provided
      Parameters:
      throwable - The exception to throw if the attempt is empty
      message - The message to display
      Returns:
      The value of the attempt if present
      Throws:
      NoElementException - If the attempt is empty

    • stream

      public Stream<T> stream()
      If a value is present, returns a sequential Stream containing only that value, otherwise returns an empty Stream.

    • toString

      public String toString()
      Returns the string representation of the value
      Overrides:
      toString in class Object
      Returns:
      The string representation of the value if any, else empty string

    • hashCode

      public int hashCode()
      Hash code of the value
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Equals method
      Overrides:
      equals in class Object

    • filter

      public Attempt<T> filter(Predicate<? super T> predicate)
      If a value is present, and the value matches the given predicate, returns an Optional describing the value, otherwise returns an empty Optional.
      Parameters:
      predicate - The predicate to test the value
      Returns:
      The attempt if the predicate is true, else an empty attempt