All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • ratpack.func.Action Maven / Gradle / Ivy

    There is a newer version: 2.0.0-rc-1
    Show newest version
    /*
 * Copyright 2013 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package ratpack.func;

import ratpack.api.Nullable;
import ratpack.util.ExceptionUtils;

import java.util.function.Consumer;

/**
 * A generic type for an object that does some work with a thing.
 * 
    
 * This type serves the same purpose as the JDK's {@link java.util.function.Consumer}, but allows throwing checked exceptions.
 * It contains methods for bridging to and from the JDK type.
 *
 * @param  The type of thing.
 */
@FunctionalInterface
public interface Action {

  /**
   * Executes the action against the given thing.
   *
   * @param t the thing to execute the action against
   * @throws Exception if anything goes wrong
   */
  void execute(T t) throws Exception;

  /**
   * Returns an action that does precisely nothing.
   *
   * @return an action that does precisely nothing
   */
  static Action noop() {
    return thing -> {
    };
  }

  /**
   * If the given action is {@code null}, returns {@link #noop()}, otherwise returns the given action.
   *
   * @param action an action, maybe {@code null}.
   * @param  the type of parameter received by the action
   * @return the given {@code action} param if it is not {@code null}, else a {@link #noop()}.
   */
  static  Action noopIfNull(@Nullable Action action) {
    if (action == null) {
      return noop();
    } else {
      return action;
    }
  }

  /**
   * Returns a new action that executes the given actions in order.
   *
   * @param actions the actions to join into one action
   * @param  the type of object the action accepts
   * @return the newly created aggregate action
   */
  @SafeVarargs
  static  Action join(final Action... actions) {
    return new Action() {
      @Override
      public void execute(T thing) throws Exception {
        for (Action action : actions) {
          action.execute(thing);
        }
      }
    };
  }

  /**
   * Returns an action that receives a throwable and immediately throws it.
   *
   * @return an action that receives a throwable and immediately throws it
   */
  static Action throwException() {
    return throwable -> {
      throw ExceptionUtils.toException(throwable);
    };
  }

  /**
   * Returns an action that immediately throws the given exception.
   * 
    
   * The exception is thrown via {@link ratpack.util.ExceptionUtils#toException(Throwable)}
   *
   * @param  the argument type (anything, as the argument is ignored)
   * @param throwable the throwable to immediately throw when the returned action is executed
   * @return an action that immediately throws the given exception.
   */
  static  Action throwException(final Throwable throwable) {
    return t -> {
      throw ExceptionUtils.toException(throwable);
    };
  }

  static  Action ignoreArg(final NoArgAction noArgAction) {
    return t -> noArgAction.execute();
  }

  /**
   * Executes the action with the given argument, then returns the argument.
   * 
    {@code
   * 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));
   *   }
   * }
   * }
    
   * @param t the argument to execute the given action with
   * @param action the action to execute with the given argument
   * @param  the type of the argument
   * @return the given argument (i.e. {@code t})
   * @throws Exception any thrown by {@code action}
   */
  static  T with(T t, Action action) throws Exception {
    return action.with(t);
  }

  /**
   * Executes with the given argument, then returns the argument.
   * 
    {@code
   * 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 run(Action> action) throws Exception {
   *     return action.with(new ArrayList<>());
   *   }
   * }
   * }
    
   * @param o the argument to execute the given action with
   * @param  the type of the argument
   * @return the given argument (i.e. {@code o})
   * @throws Exception any thrown by {@link #execute(Object)}
   */
  default  O with(O o) throws Exception {
    execute(o);
    return o;
  }

  /**
   * Like {@link #with(Object, Action)}, but unchecks any exceptions thrown by the action via {@link ExceptionUtils#uncheck(Throwable)}.
   *
   * @param t the argument to execute the given action with
   * @param action the action to execute with the given argument
   * @param  the type of the argument
   * @return the given argument (i.e. {@code t})
   */
  static  T uncheckedWith(T t, Action action) {
    return action.uncheckedWith(t);
  }

  /**
   * Like {@link #with(Object)}, but unchecks any exceptions thrown by the action via {@link ExceptionUtils#uncheck(Throwable)}.
   *
   * @param o the argument to execute  with
   * @param  the type of the argument
   * @return the given argument (i.e. {@code o})
   */
  default  O uncheckedWith(O o) {
    return ExceptionUtils.uncheck(() -> {
      execute(o);
      return o;
    });
  }

  /**
   * Creates a JDK {@link Consumer} from this action.
   * 
    
   * Any exceptions thrown by {@code this} action will be unchecked via {@link ExceptionUtils#uncheck(Throwable)} and rethrown.
   *
   * @return this function as a JDK style consumer.
   */
  default Consumer toConsumer() {
    return t -> {
      try {
        execute(t);
      } catch (Exception e) {
        throw ExceptionUtils.uncheck(e);
      }
    };
  }

  /**
   * Creates an action from a JDK consumer.
   *
   * @param consumer the JDK consumer
   * @param  the type of object this action accepts
   * @return the given consumer as an action
   */
  static  Action from(Consumer consumer) {
    return consumer::accept;
  }

}
    
    
    
    

    




    
    
    © 2015 - 2025 Weber Informatics LLC | Privacy Policy