bundles/org.simantics.db/src/org/simantics/db/function/DbPredicate.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 predicate (boolean-valued function) of one argument that can\r
  20  * throw database exceptions.\r
  21  *\r
  22  * @param <T>\r
  23  *            the type of the input to the predicate\r
  24  *\r
  25  * @author Tuukka Lehtonen\r
  26  * @since 1.22.1 & 1.24.0\r
  27  */\r
  28 @FunctionalInterface\r
  29 public interface DbPredicate<T> {\r
  30 \r
  31     /**\r
  32      * Evaluates this predicate on the given argument.\r
  33      *\r
  34      * @param t the input argument\r
  35      * @return {@code true} if the input argument matches the predicate,\r
  36      * otherwise {@code false}\r
  37      */\r
  38     boolean test(T t) throws DatabaseException;\r
  39 \r
  40     /**\r
  41      * Returns a composed predicate that represents a short-circuiting logical\r
  42      * AND of this predicate and another.  When evaluating the composed\r
  43      * predicate, if this predicate is {@code false}, then the {@code other}\r
  44      * predicate is not evaluated.\r
  45      *\r
  46      * <p>Any exceptions thrown during evaluation of either predicate are relayed\r
  47      * to the caller; if evaluation of this predicate throws an exception, the\r
  48      * {@code other} predicate will not be evaluated.\r
  49      *\r
  50      * @param other a predicate that will be logically-ANDed with this\r
  51      *              predicate\r
  52      * @return a composed predicate that represents the short-circuiting logical\r
  53      * AND of this predicate and the {@code other} predicate\r
  54      * @throws NullPointerException if other is null\r
  55      */\r
  56     default DbPredicate<T> and(DbPredicate<? super T> other) {\r
  57         Objects.requireNonNull(other);\r
  58         return (t) -> test(t) && other.test(t);\r
  59     }\r
  60 \r
  61     /**\r
  62      * Returns a predicate that represents the logical negation of this\r
  63      * predicate.\r
  64      *\r
  65      * @return a predicate that represents the logical negation of this\r
  66      * predicate\r
  67      */\r
  68     default DbPredicate<T> negate() {\r
  69         return (t) -> !test(t);\r
  70     }\r
  71 \r
  72     /**\r
  73      * Returns a composed predicate that represents a short-circuiting logical\r
  74      * OR of this predicate and another.  When evaluating the composed\r
  75      * predicate, if this predicate is {@code true}, then the {@code other}\r
  76      * predicate is not evaluated.\r
  77      *\r
  78      * <p>Any exceptions thrown during evaluation of either predicate are relayed\r
  79      * to the caller; if evaluation of this predicate throws an exception, the\r
  80      * {@code other} predicate will not be evaluated.\r
  81      *\r
  82      * @param other a predicate that will be logically-ORed with this\r
  83      *              predicate\r
  84      * @return a composed predicate that represents the short-circuiting logical\r
  85      * OR of this predicate and the {@code other} predicate\r
  86      * @throws NullPointerException if other is null\r
  87      */\r
  88     default DbPredicate<T> or(DbPredicate<? super T> other) {\r
  89         Objects.requireNonNull(other);\r
  90         return (t) -> test(t) || other.test(t);\r
  91     }\r
  92 \r
  93     /**\r
  94      * Returns a predicate that tests if two arguments are equal according\r
  95      * to {@link Objects#equals(Object, Object)}.\r
  96      *\r
  97      * @param <T> the type of arguments to the predicate\r
  98      * @param targetRef the object reference with which to compare for equality,\r
  99      *               which may be {@code null}\r
 100      * @return a predicate that tests if two arguments are equal according\r
 101      * to {@link Objects#equals(Object, Object)}\r
 102      */\r
 103     static <T> DbPredicate<T> isEqual(Object targetRef) {\r
 104         return (null == targetRef)\r
 105                 ? Objects::isNull\r
 106                 : object -> targetRef.equals(object);\r
 107     }\r
 108 \r
 109 }\r