bundles/org.simantics.db/src/org/simantics/db/function/DbFunction.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2016 Association for Decentralized Information Management\r
   3  * in Industry THTH ry.\r
   4  * All rights reserved. This program and the accompanying materials\r
   5  * are made available under the terms of the Eclipse Public License v1.0\r
   6  * which accompanies this distribution, and is available at\r
   7  * http://www.eclipse.org/legal/epl-v10.html\r
   8  *\r
   9  * Contributors:\r
  10  *     Semantum Oy - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.db.function;\r
  13 \r
  14 import java.util.Objects;\r
  15 \r
  16 import org.simantics.db.exception.DatabaseException;\r
  17 \r
  18 /**\r
  19  * Represents a function that accepts one argument and produces a result that\r
  20  * can throw database exceptions.\r
  21  *\r
  22  * @param <T> the type of the first argument to the function\r
  23  * @param <U> the type of the second argument to the function\r
  24  * @param <R> the type of the result of the function\r
  25  * \r
  26  * @since 1.22.1 & 1.24.0\r
  27  */\r
  28 @FunctionalInterface\r
  29 public interface DbFunction<T, R> {\r
  30 \r
  31     /**\r
  32      * Applies this function to the given argument.\r
  33      *\r
  34      * @param t the function argument\r
  35      * @return the function result\r
  36      */\r
  37     R apply(T t) throws DatabaseException;\r
  38 \r
  39     /**\r
  40      * Returns a composed function that first applies the {@code before}\r
  41      * function to its input, and then applies this function to the result.\r
  42      * If evaluation of either function throws an exception, it is relayed to\r
  43      * the caller of the composed function.\r
  44      *\r
  45      * @param <V> the type of input to the {@code before} function, and to the\r
  46      *           composed function\r
  47      * @param before the function to apply before this function is applied\r
  48      * @return a composed function that first applies the {@code before}\r
  49      * function and then applies this function\r
  50      * @throws NullPointerException if before is null\r
  51      *\r
  52      * @see #andThen(DbFunction)\r
  53      */\r
  54     default <V> DbFunction<V, R> compose(DbFunction<? super V, ? extends T> before) {\r
  55         Objects.requireNonNull(before);\r
  56         return (V v) -> apply(before.apply(v));\r
  57     }\r
  58 \r
  59     /**\r
  60      * Returns a composed function that first applies this function to\r
  61      * its input, and then applies the {@code after} function to the result.\r
  62      * If evaluation of either function throws an exception, it is relayed to\r
  63      * the caller of the composed function.\r
  64      *\r
  65      * @param <V> the type of output of the {@code after} function, and of the\r
  66      *           composed function\r
  67      * @param after the function to apply after this function is applied\r
  68      * @return a composed function that first applies this function and then\r
  69      * applies the {@code after} function\r
  70      * @throws NullPointerException if after is null\r
  71      *\r
  72      * @see #compose(DbFunction)\r
  73      */\r
  74     default <V> DbFunction<T, V> andThen(DbFunction<? super R, ? extends V> after) {\r
  75         Objects.requireNonNull(after);\r
  76         return (T t) -> after.apply(apply(t));\r
  77     }\r
  78 \r
  79     /**\r
  80      * Returns a function that always returns its input argument.\r
  81      *\r
  82      * @param <T> the type of the input and output objects to the function\r
  83      * @return a function that always returns its input argument\r
  84      */\r
  85     static <T> DbFunction<T, T> identity() {\r
  86         return t -> t;\r
  87     }\r
  88 }\r