Package ratpack.func

Interface Action<T>

  • Type Parameters:
    T - The type of thing.
    All Known Implementing Classes:
    GroovyChainAction
    Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

    @FunctionalInterface
    public interface Action<T>
    A generic type for an object that does some work with a thing.

    This type serves the same purpose as the JDK's Consumer, but allows throwing checked exceptions. It contains methods for bridging to and from the JDK type.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  Action.ConditionalSpec<I>
      A spec for adding conditions to a conditional action.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default <O extends T>
      Action<O>
      append​(Action<? super O> action)
      Returns a new action that executes this action and then the given action.
      static Action<java.lang.Throwable> beforeThrow​(Action<? super java.lang.Throwable> action)
      Creates an exception-taking action that executes the given action before throwing the exception.
      static Action<java.lang.Throwable> beforeThrow​(Block block)
      Creates an exception-taking action that executes the given block before throwing the exception.
      static <I> Action<I> conditional​(Action<? super I> onElse, Action<? super Action.ConditionalSpec<I>> conditions)
      Creates an action that delegates based on the specified conditions.
      static <I> Action<I> conditional​(Action<? super Action.ConditionalSpec<I>> conditions)
      Creates an action that delegates based on the specified conditions.
      default Block curry​(T value)
      Creates a block that executes this action with the given value when called.
      void execute​(T t)
      Executes the action against the given thing.
      static <T> Action<T> from​(java.util.function.Consumer<T> consumer)
      Creates an action from a JDK consumer.
      static <T> Action<T> ignoreArg​(Block block)  
      static <T> Action<T> join​(Action<? super T>... actions)
      Returns a new action that executes the given actions in order.
      static <T> Action<T> noop()
      Returns an action that does precisely nothing.
      static <T> Action<? super T> noopIfNull​(Action<T> action)
      If the given action is null, returns noop(), otherwise returns the given action.
      default <O extends T>
      Action<O>
      prepend​(Action<? super O> action)
      Returns a new action that executes the given action and then this action.
      static Action<java.lang.Throwable> suppressAndThrow​(java.lang.Throwable toSuppress)
      An action that receives a throwable to thrown, suppressing the given value.
      static Action<java.lang.Throwable> throwException()
      Returns an action that receives a throwable and immediately throws it.
      static <T> Action<T> throwException​(java.lang.Throwable throwable)
      Returns an action that immediately throws the given exception.
      default java.util.function.Consumer<T> toConsumer()
      Creates a JDK Consumer from this action.
      default <O extends T>
      O
      uncheckedWith​(O o)
      Like with(Object), but unchecks any exceptions thrown by the action via Exceptions.uncheck(Throwable).
      static <T> T uncheckedWith​(T t, Action<? super T> action)
      Like with(Object, Action), but unchecks any exceptions thrown by the action via Exceptions.uncheck(Throwable).
      static <I> Action<I> when​(Predicate<? super I> predicate, Action<? super I> action)
      Creates an action that delegates to the given action if the given predicate applies, else delegates to noop().
      static <I> Action<I> when​(Predicate<? super I> predicate, Action<? super I> onTrue, Action<? super I> onFalse)
      Creates an action that delegates to the first action if the given predicate applies, else the second action.
      default <O extends T>
      O
      with​(O o)
      Executes with the given argument, then returns the argument.
      static <T> T with​(T t, Action<? super T> action)
      Executes the action with the given argument, then returns the argument.
    • Method Detail

      • execute

        void execute​(T t)
              throws java.lang.Exception
        Executes the action against the given thing.
        Parameters:
        t - the thing to execute the action against
        Throws:
        java.lang.Exception - if anything goes wrong
      • noop

        static <T> Action<T> noop()
        Returns an action that does precisely nothing.
        Returns:
        an action that does precisely nothing
      • noopIfNull

        static <T> Action<? super T> noopIfNull​(@Nullable
                                                Action<T> action)
        If the given action is null, returns noop(), otherwise returns the given action.
        Type Parameters:
        T - the type of parameter received by the action
        Parameters:
        action - an action, maybe null.
        Returns:
        the given action param if it is not null, else a noop().
      • join

        @SafeVarargs
        static <T> Action<T> join​(Action<? super T>... actions)
        Returns a new action that executes the given actions in order.
        Type Parameters:
        T - the type of object the action accepts
        Parameters:
        actions - the actions to join into one action
        Returns:
        the newly created aggregate action
      • append

        default <O extends TAction<O> append​(Action<? super O> action)
        Returns a new action that executes this action and then the given action.
        Type Parameters:
        O - the type of object the action accepts
        Parameters:
        action - the action to execute after this action
        Returns:
        the newly created aggregate action
      • prepend

        default <O extends TAction<O> prepend​(Action<? super O> action)
        Returns a new action that executes the given action and then this action.
        Type Parameters:
        O - the type of object the action accepts
        Parameters:
        action - the action to execute before this action
        Returns:
        the newly created aggregate action
      • throwException

        static Action<java.lang.Throwable> throwException()
        Returns an action that receives a throwable and immediately throws it.
        Returns:
        an action that receives a throwable and immediately throws it
      • suppressAndThrow

        static Action<java.lang.Throwable> suppressAndThrow​(java.lang.Throwable toSuppress)
        An action that receives a throwable to thrown, suppressing the given value.
        Returns:
        an action that receives a throwable to thrown, suppressing the given value
        Since:
        1.5
      • throwException

        static <T> Action<T> throwException​(java.lang.Throwable throwable)
        Returns an action that immediately throws the given exception.

        The exception is thrown via Exceptions.toException(Throwable)

        Type Parameters:
        T - the argument type (anything, as the argument is ignored)
        Parameters:
        throwable - the throwable to immediately throw when the returned action is executed
        Returns:
        an action that immediately throws the given exception.
      • ignoreArg

        static <T> Action<T> ignoreArg​(Block block)
      • with

        static <T> T with​(T t,
                          Action<? super T> action)
                   throws java.lang.Exception
        Executes the action with the given argument, then returns the argument.
        
         import ratpack.func.Action;
         import java.util.ArrayList;
        
         import static org.junit.Assert.assertEquals;
        
         public class Example {
           public static void main(String... args) throws Exception {
             assertEquals("foo", Action.with(new ArrayList<>(), list -> list.add("foo")).get(0));
           }
         }
         
        Type Parameters:
        T - the type of the argument
        Parameters:
        t - the argument to execute the given action with
        action - the action to execute with the given argument
        Returns:
        the given argument (i.e. t)
        Throws:
        java.lang.Exception - any thrown by action
      • with

        default <O extends T> O with​(O o)
                              throws java.lang.Exception
        Executes with the given argument, then returns the argument.
        
         import ratpack.func.Action;
         import java.util.List;
         import java.util.ArrayList;
        
         import static org.junit.Assert.assertEquals;
        
         public class Example {
           public static void main(String... args) throws Exception {
             assertEquals("foo", run(list -> list.add("foo")).get(0));
           }
        
           private static List<String> run(Action<? super List<String>> action) throws Exception {
             return action.with(new ArrayList<>());
           }
         }
         
        Type Parameters:
        O - the type of the argument
        Parameters:
        o - the argument to execute the given action with
        Returns:
        the given argument (i.e. o)
        Throws:
        java.lang.Exception - any thrown by execute(Object)
      • uncheckedWith

        static <T> T uncheckedWith​(T t,
                                   Action<? super T> action)
        Like with(Object, Action), but unchecks any exceptions thrown by the action via Exceptions.uncheck(Throwable).
        Type Parameters:
        T - the type of the argument
        Parameters:
        t - the argument to execute the given action with
        action - the action to execute with the given argument
        Returns:
        the given argument (i.e. t)
      • uncheckedWith

        default <O extends T> O uncheckedWith​(O o)
        Like with(Object), but unchecks any exceptions thrown by the action via Exceptions.uncheck(Throwable).
        Type Parameters:
        O - the type of the argument
        Parameters:
        o - the argument to execute with
        Returns:
        the given argument (i.e. o)
      • toConsumer

        default java.util.function.Consumer<T> toConsumer()
        Creates a JDK Consumer from this action.

        Any exceptions thrown by this action will be unchecked via Exceptions.uncheck(Throwable) and rethrown.

        Returns:
        this function as a JDK style consumer.
      • from

        static <T> Action<T> from​(java.util.function.Consumer<T> consumer)
        Creates an action from a JDK consumer.
        Type Parameters:
        T - the type of object this action accepts
        Parameters:
        consumer - the JDK consumer
        Returns:
        the given consumer as an action
      • curry

        default Block curry​(T value)
        Creates a block that executes this action with the given value when called.
        Parameters:
        value - the value to execute this action with when the block is executed
        Returns:
        a new block
      • beforeThrow

        static Action<java.lang.Throwable> beforeThrow​(Action<? super java.lang.Throwable> action)
        Creates an exception-taking action that executes the given action before throwing the exception.

        This can be used with methods such as Promise.onError(Action) to simulate the Java finally construct.

        Parameters:
        action - the action to perform before throwing the exception
        Returns:
        an action that performs the given action before throwing its argument
        Since:
        1.5
      • beforeThrow

        static Action<java.lang.Throwable> beforeThrow​(Block block)
        Creates an exception-taking action that executes the given block before throwing the exception.

        This can be used with methods such as Promise.onError(Action) to simulate the Java finally construct.

        Parameters:
        block - the block to execute before throwing the exception
        Returns:
        an action that executes the given block before throwing its argument
        Since:
        1.5
      • when

        static <I> Action<I> when​(Predicate<? super I> predicate,
                                  Action<? super I> action)
        Creates an action that delegates to the given action if the given predicate applies, else delegates to noop().

        This is equivalent to when(predicate, action, noop()).

        Type Parameters:
        I - the type of argument
        Parameters:
        predicate - the condition for the argument
        action - the action to execute if the predicate applies
        Returns:
        an action that delegates to the given action if the predicate applies, else noops
        Since:
        1.5
        See Also:
        when(Predicate, Action, Action), conditional(Action, Action)
      • when

        static <I> Action<I> when​(Predicate<? super I> predicate,
                                  Action<? super I> onTrue,
                                  Action<? super I> onFalse)
        Creates an action that delegates to the first action if the given predicate applies, else the second action.
        Type Parameters:
        I - the type of argument
        Parameters:
        predicate - the condition for the argument
        onTrue - the action to execute if the predicate applies
        onFalse - the action to execute if the predicate DOES NOT apply
        Returns:
        an action that delegates to the first action if the predicate applies, else the second argument
        Since:
        1.5
        See Also:
        when(Predicate, Action), conditional(Action, Action)
      • conditional

        static <I> Action<I> conditional​(Action<? super Action.ConditionalSpec<I>> conditions)
                                  throws java.lang.Exception
        Creates an action that delegates based on the specified conditions.

        If no conditions match, an IllegalArgumentException will be thrown. Use conditional(Action, Action) alternatively to specify a different “else” strategy.

        Type Parameters:
        I - the input type
        Parameters:
        conditions - the conditions
        Returns:
        a conditional action
        Throws:
        java.lang.Exception - any thrown by conditions
        Since:
        1.5
        See Also:
        conditional(Action, Action)
      • conditional

        static <I> Action<I> conditional​(Action<? super I> onElse,
                                         Action<? super Action.ConditionalSpec<I>> conditions)
                                  throws java.lang.Exception
        Creates an action that delegates based on the specified conditions.

        If no condition applies, the onElse action will be delegated to.

        Type Parameters:
        I - the input type
        Parameters:
        onElse - the action to delegate to if no condition matches
        conditions - the conditions
        Returns:
        a conditional action
        Throws:
        java.lang.Exception - any thrown by conditions
        Since:
        1.5
        See Also:
        conditional(Action)