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