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

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