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

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<Throwable>	beforeThrow(Action<? super Throwable> action)	Creates an exception-taking action that executes the given action before throwing the exception.
static Action<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(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<Throwable>	suppressAndThrow(Throwable toSuppress)	An action that receives a throwable to thrown, suppressing the given value.
static Action<Throwable>	throwException()	Returns an action that receives a throwable and immediately throws it.
static <T> Action<T>	throwException(Throwable throwable)	Returns an action that immediately throws the given exception.
default 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 Exception

Executes the action against the given thing.

Parameters:

t - the thing to execute the action against

Throws:

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 T> Action<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 T> Action<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<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<Throwable> suppressAndThrow(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(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 Exception

Executes the action with the given argument, then returns the argument.

 import ratpack.func.Action;
 import java.util.ArrayList;

 import static org.junit.jupiter.api.Assertions.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:

Exception - any thrown by action

with

default <O extends T> O with(O o)
                      throws 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.jupiter.api.Assertions.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:

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 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(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<Throwable> beforeThrow(Action<? super Throwable> action)

Creates an exception-taking action that executes the given action before throwing the exception.

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<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 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:

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 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:

Exception - any thrown by conditions

Since:

1.5

See Also:

conditional(Action)