net.sf.staccatocommons.defs.predicate.Predicate Maven / Gradle / Ivy

Go to download
/**
 *  Copyright (c) 2010-2012, The StaccatoCommons Team
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation; version 3 of the License.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 */


package net.sf.staccatocommons.defs.predicate;

import net.sf.staccatocommons.defs.Applicable;
import net.sf.staccatocommons.defs.Applicative;
import net.sf.staccatocommons.defs.Evaluable;
import net.sf.staccatocommons.defs.Executable;
import net.sf.staccatocommons.defs.NullSafe;
import net.sf.staccatocommons.restrictions.check.NonNull;

/**
 * A rich {@link Evaluable}
 * 
 * @author flbulgarelli
 */
@Applicative
public interface Predicate extends Evaluable, Applicable {

  /**
   * Negates this {@link Predicate}
   * 
   * @return a {@link Predicate} that negates this {@link Predicate}'s result.
   */
  Predicate not();

  /**
   * Returns a predicate that, performs a short-circuit logical-or between this
   * {@link Predicate}'s {@link #eval(Object)} and other
   * 
   * @param other
   *          another {@link Evaluable}. Non null.
   * @return A new predicate that performs the short circuited or between this
   *         and other when evaluated.
   */
  Predicate or(@NonNull final Evaluable other);

  /**
   * Returns a predicate that performs a short-circuit logical-and between this
   * {@link Predicate}'s {@link #eval(Object)} and other
   * 
   * @param other
   *          another {@link Evaluable}. Non null.
   * @return A new predicate that performs the short circuited logical-and
   *         between this and other when evaluated. Non Null
   */
  Predicate and(@NonNull final Evaluable other);

  /**
   * Returns a null-safe predicate that, when evaluated, answers
   * false if its argument is null, or evaluates this predicate,
   * otherwise.
   * 
   * @return a predicate that returns arg != null && this.eval(arg)
   */
  @NullSafe
  Predicate andNotNull();

  /**
   * Returns a null-safe predicate that, when evaluated, answers
   * true if its argument is null, or evaluates this predicate,
   * otherwise.
   * 
   * @return a predicate that returns arg == null || this.eval(arg)
   */
  @NullSafe
  Predicate orNull();

  // /**
  // * Adds a side effect to this predicate, that will be evaluated whenever the
  // * predicate is evaluated.
  // *
  // * @param executable
  // * @return a new Predicate that adds an {@link Executable} effect to this
  // */
  // Predicate withEffect(Executable executable);

  /**
   * Adds a side effect to this predicate, that will be evaluated whenever the
   * predicate evaluation is true
   * 
   * @param executable
   * @return a new Predicate that adds an {@link Executable} effect to this
   */
  Predicate withEffectOnTrue(Executable executable);

  /**
   * Adds a a side effect to this predicate, that will be evaluated whenever the
   * predicate evaluation is false
   * 
   * @param executable
   * @return a new Predicate that adds an {@link Executable} effect to this
   */
  Predicate withEffectOnFalse(Executable executable);

  /**
   * Composes
   * this predicate with another {@link Applicable}, resulting in a new
   * {@link Predicate} that when applied returns
   * this.eval(other.apply(arg)
   * 
   * @param 
   * @param other
   * @return a new predicate, this composed with other
   */
   Predicate of(@NonNull final Applicable other);
}