src/main/java/wtf/metio/reguloj/Rule.java

   1 /*
   2  * This file is part of reguloj. It is subject to the license terms in the LICENSE file found in the top-level
   3  * directory of this distribution and at https://creativecommons.org/publicdomain/zero/1.0/. No part of reguloj,
   4  * including this file, may be copied, modified, propagated, or distributed except according to the terms contained
   5  * in the LICENSE file.
   6  */
   7
   8 package wtf.metio.reguloj;
   9
  10 /**
  11  * <p>
  12  * A {@link Rule} combines {@link java.util.function.Predicate} and {@link java.util.function.Consumer} interfaces and
  13  * can be evaluated with a {@link RuleEngine} using a {@link Context}.
  14  * </p>
  15  * <h2>Examples</h2>
  16  * <ol>
  17  * <li>
  18  * <p>
  19  * Check whether a rule would fire inside a given context:
  20  * </p>
  21  *
  22  * <pre>
  23  * Context&lt;X&gt; context = ...;
  24  * Rule&lt;Context&lt;X&gt;&gt; rule = ...;
  25  *
  26  * boolean canFire = rule.fires(context);
  27  * </pre>
  28  *
  29  * </li>
  30  * <li>
  31  * <p>
  32  * Run a rule inside a given context:
  33  * </p>
  34  * <pre>
  35  * Context&lt;X&gt; context = ...;
  36  * Rule&lt;Context&lt;X&gt;&gt; rule = ...;
  37  *
  38  * rule.run(context);
  39  * </pre>
  40  * </li>
  41  * </ol>
  42  *
  43  * @param <CONTEXT> The context type.
  44  * @see RuleEngine
  45  * @see RuleBuilder
  46  * @see Context
  47  */
  48 public interface Rule<CONTEXT extends Context<?>> {
  49
  50   /**
  51    * @param <CONTEXT> The context type.
  52    * @return A new builder to construct rules.
  53    */
  54   static <CONTEXT extends Context<?>> RuleBuilder<CONTEXT> called(final String name) {
  55     return new FluentRuleBuilder<CONTEXT>().called(name);
  56   }
  57
  58   /**
  59    * @return The human readable name of this rule.
  60    */
  61   String name();
  62
  63   /**
  64    * Checks whether this rule would fire for a given context.
  65    *
  66    * @param context The context to check.
  67    * @return <code>true</code> if this rule would fire, <code>false</code> otherwise.
  68    */
  69   boolean fires(CONTEXT context);
  70
  71   /**
  72    * Runs this rule inside a given context. A rule should only run iff {@link #fires(Context)} returns
  73    * <code>true</code>.
  74    *
  75    * @param context The context to use.
  76    */
  77   void run(CONTEXT context);
  78
  79 }