Allow rules to have optional facts annotated with i.e. @Nullable/etc (#…

…16)

Allow rules to have optional facts annotated with i.e. @Nullable/etc (#16)

Co-authored-by: Nicolas Vervelle <nicolas.vervelle@quicksign.com>

README.md

@@ -20,7 +20,7 @@
 ## Project status
 
 This project is forked from [j-easy/easy-rules](https://github.com/j-easy/easy-rules) because it is
-in maintaince mode. Current plan is to support community with minor enhacements and bug fixes.
+in maintenance mode. Current plan is to support community with minor enhancements and bug fixes.
 
 ## Latest news
 

easy-rules-archetype/pom.xml

@@ -4,7 +4,7 @@
   <parent>
     <groupId>io.github.dvgaba</groupId>
     <artifactId>easy-rules</artifactId>
-    <version>1.0.4</version>
+    <version>1.0.5-SNAPSHOT</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
 

easy-rules-core/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.github.dvgaba</groupId>
     <artifactId>easy-rules</artifactId>
-    <version>1.0.4</version>
+    <version>1.0.5-SNAPSHOT</version>
   </parent>
 
   <artifactId>easy-rules-core</artifactId>
@@ -92,6 +92,11 @@
       <version>4.2.0</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>com.google.code.findbugs</groupId>
+      <artifactId>jsr305</artifactId>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
 
   <build>

easy-rules-core/src/main/java/org/jeasy/rules/api/RulesEngineParameters.java

@@ -40,6 +40,9 @@
  */
 public class RulesEngineParameters {
 
+  /** Parameter to define annotation used to mark facts optional, for example javax.annotation.Nullable */
+  private static Class<?> OPTIONAL_PARAMETER_ANNOTATION = null;
+
   /** Default rule priority threshold. */
   public static final int DEFAULT_RULE_PRIORITY_THRESHOLD = Integer.MAX_VALUE;
 
@@ -151,6 +154,14 @@ public RulesEngineParameters failsOnException(final boolean failsOnException) {
     return this;
   }
 
+  public static boolean hasOptionalParameterAnnotation(Class<?> methodAnnotation) {
+    return OPTIONAL_PARAMETER_ANNOTATION != null && OPTIONAL_PARAMETER_ANNOTATION.equals(methodAnnotation);
+  }
+
+  public static void setOptionalParameterAnnotation(Class<?> optionalParameterAnnotation) {
+    OPTIONAL_PARAMETER_ANNOTATION = optionalParameterAnnotation;
+  }
+
   @Override
   public String toString() {
     return "Engine parameters { "

easy-rules-core/src/main/java/org/jeasy/rules/core/RuleDefinitionValidator.java

@@ -30,13 +30,17 @@
 import java.lang.reflect.Modifier;
 import java.lang.reflect.Parameter;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
+import java.util.Set;
+
 import org.jeasy.rules.annotation.Action;
 import org.jeasy.rules.annotation.Condition;
 import org.jeasy.rules.annotation.Fact;
 import org.jeasy.rules.annotation.Priority;
 import org.jeasy.rules.annotation.Rule;
 import org.jeasy.rules.api.Facts;
+import org.jeasy.rules.api.RulesEngineParameters;
 
 /**
  * This component validates that an annotated rule object is well defined.
@@ -145,16 +149,16 @@ private boolean validParameters(final Method method) {
     int notAnnotatedParameterCount = 0;
     Annotation[][] parameterAnnotations = method.getParameterAnnotations();
     for (Annotation[] annotations : parameterAnnotations) {
-      if (annotations.length == 0) {
-        notAnnotatedParameterCount += 1;
-      } else {
-        // Annotation types has to be Fact
-        for (Annotation annotation : annotations) {
-          if (!annotation.annotationType().equals(Fact.class)) {
-            return false;
-          }
+      boolean annotatedAsFact = false;
+      for (Annotation annotation : annotations) {
+        //Annotation types has to be Fact or another accepted annotation
+        if (annotation.annotationType().equals(Fact.class)) {
+          annotatedAsFact = true;
         }
       }
+      if (!annotatedAsFact) {
+        notAnnotatedParameterCount += 1;
+      }
     }
     if (notAnnotatedParameterCount > 1) {
       return false;
@@ -171,7 +175,13 @@ private boolean validParameters(final Method method) {
   private Parameter getNotAnnotatedParameter(Method method) {
     Parameter[] parameters = method.getParameters();
     for (Parameter parameter : parameters) {
-      if (parameter.getAnnotations().length == 0) {
+      boolean hasAnnotation = false;
+      for (Annotation annotation : parameter.getAnnotations()) {
+        if (annotation.annotationType().equals(Fact.class)) {
+          hasAnnotation = true;
+        }
+      }
+      if (!hasAnnotation) {
         return parameter;
       }
     }

easy-rules-core/src/main/java/org/jeasy/rules/core/RuleProxy.java

@@ -42,6 +42,7 @@
 import org.jeasy.rules.annotation.Priority;
 import org.jeasy.rules.api.Facts;
 import org.jeasy.rules.api.Rule;
+import org.jeasy.rules.api.RulesEngineParameters;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -176,17 +177,25 @@ private List<Object> getActualParameters(Method method, Facts facts) {
     List<Object> actualParameters = new ArrayList<>();
     Annotation[][] parameterAnnotations = method.getParameterAnnotations();
     for (Annotation[] annotations : parameterAnnotations) {
-      if (annotations.length == 1) {
-        String factName = ((Fact) (annotations[0])).value(); // validated upfront.
-        Object fact = facts.get(factName);
-        if (fact == null && !facts.asMap().containsKey(factName)) {
+      String factName = null;
+      boolean annotatedAsNullable = false;
+      for (Annotation annotation : annotations) {
+        if (annotation.annotationType().equals(Fact.class)) {
+          factName = ((Fact) annotation).value();
+        } else if (RulesEngineParameters.hasOptionalParameterAnnotation(annotation.annotationType())) {
+          annotatedAsNullable = true;
+        }
+      }
+      if (factName != null) {
+        Object fact = facts.get(factName); //validated upfront.
+        if (fact == null && !facts.asMap().containsKey(factName) && !annotatedAsNullable) {
           throw new NoSuchFactException(
               format("No fact named '%s' found in known facts: %n%s", factName, facts), factName);
         }
         actualParameters.add(fact);
       } else {
         actualParameters.add(
-            facts); // validated upfront, there may be only one parameter not annotated and which is
+            facts); // validated upfront, there may be only one parameter not annotated as Fact and which is
         // of type Facts.class
       }
     }

easy-rules-core/src/test/java/org/jeasy/rules/core/OptionalFactAnnotationParameterTest.java

@@ -0,0 +1,126 @@
+/*
+ * The MIT License
+ *
+ *  Copyright (c) 2022, Mahmoud Ben Hassine (mahmoud.benhassine@icloud.com)
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in
+ *  all copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ *  THE SOFTWARE.
+ */
+package org.jeasy.rules.core;
+
+import java.util.Map;
+import javax.annotation.Nullable;
+import org.jeasy.rules.annotation.Action;
+import org.jeasy.rules.annotation.Condition;
+import org.jeasy.rules.annotation.Fact;
+import org.jeasy.rules.annotation.Rule;
+import org.jeasy.rules.api.Facts;
+import org.jeasy.rules.api.Rules;
+import org.jeasy.rules.api.RulesEngineParameters;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/** Null facts are not accepted by design, a declared fact can be missing though. */
+public class OptionalFactAnnotationParameterTest extends AbstractTest {
+
+  @BeforeEach
+  public void setup() throws Exception {
+    facts = new Facts();
+    facts.put("fact1", fact1);
+    facts.put("fact2", fact2);
+    rules = new Rules();
+
+    RulesEngineParameters rulesEngineParameters = new RulesEngineParameters();
+    rulesEngineParameters.setFailsOnException(true);
+    rulesEngine = new DefaultRulesEngine(rulesEngineParameters);
+  }
+
+  @AfterEach
+  void cleanup() {
+    RulesEngineParameters.setOptionalParameterAnnotation(null);
+  }
+
+  @Test
+  public void testMissingFact() {
+    RulesEngineParameters.setOptionalParameterAnnotation(Nullable.class);
+    Rules rules = new Rules();
+    rules.register(new AnnotatedParametersRule());
+
+    Facts facts = new Facts();
+    facts.put("fact1", new Object());
+
+    Map<org.jeasy.rules.api.Rule, Boolean> results = rulesEngine.check(rules, facts);
+
+    for (boolean b : results.values()) {
+      Assertions.assertTrue(b);
+    }
+  }
+
+  @Test
+  public void testMissingFactNotAnnotated() {
+
+    Rules rules = new Rules();
+
+    new AnnotatedParametersRule();
+    rules.register(new AnnotatedParametersRule());
+
+    Facts facts = new Facts();
+    facts.put("fact1", new Object());
+
+    Map<org.jeasy.rules.api.Rule, Boolean> results = rulesEngine.check(rules, facts);
+
+    for (boolean b : results.values()) {
+      Assertions.assertFalse(b);
+    }
+  }
+
+  @Test
+  public void testNoMissingFact() {
+    Rules rules = new Rules();
+    rules.register(
+        new AnnotatedParametersRule() {
+          @Condition
+          public boolean when(@Fact("fact1") Object fact1, @Nullable @Fact("fact2") Object fact2) {
+            return fact1 != null && fact2 != null;
+          }
+        });
+    Facts facts = new Facts();
+    facts.put("fact1", new Object());
+    facts.put("fact2", new Object());
+
+    Map<org.jeasy.rules.api.Rule, Boolean> results = rulesEngine.check(rules, facts);
+
+    for (boolean b : results.values()) {
+      Assertions.assertTrue(b);
+    }
+  }
+
+  @Rule
+  public static class AnnotatedParametersRule {
+
+    @Condition
+    public boolean when(@Fact("fact1") Object fact1, @Nullable @Fact("fact2") Object fact2) {
+      return fact1 != null && fact2 == null;
+    }
+
+    @Action
+    public void then(@Fact("fact1") Object fact1, @Nullable @Fact("fact2") Object fact2) {}
+  }
+}

easy-rules-jexl/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.github.dvgaba</groupId>
     <artifactId>easy-rules</artifactId>
-    <version>1.0.4</version>
+    <version>1.0.5-SNAPSHOT</version>
   </parent>
 
   <artifactId>easy-rules-jexl</artifactId>

easy-rules-mvel/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.github.dvgaba</groupId>
     <artifactId>easy-rules</artifactId>
-    <version>1.0.4</version>
+    <version>1.0.5-SNAPSHOT</version>
   </parent>
 
   <artifactId>easy-rules-mvel</artifactId>

easy-rules-spel/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.github.dvgaba</groupId>
     <artifactId>easy-rules</artifactId>
-    <version>1.0.4</version>
+    <version>1.0.5-SNAPSHOT</version>
   </parent>
 
   <artifactId>easy-rules-spel</artifactId>

easy-rules-support/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.github.dvgaba</groupId>
     <artifactId>easy-rules</artifactId>
-    <version>1.0.4</version>
+    <version>1.0.5-SNAPSHOT</version>
   </parent>
 
   <artifactId>easy-rules-support</artifactId>

easy-rules-tutorials/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <groupId>io.github.dvgaba</groupId>
     <artifactId>easy-rules</artifactId>
-    <version>1.0.4</version>
+    <version>1.0.5-SNAPSHOT</version>
   </parent>
 
   <artifactId>easy-rules-tutorials</artifactId>

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>io.github.dvgaba</groupId>
   <artifactId>easy-rules</artifactId>
-  <version>1.0.4</version>
+  <version>1.0.5-SNAPSHOT</version>
 
   <modules>
     <module>easy-rules-archetype</module>
@@ -33,6 +33,7 @@
     <system-lambda.version>1.2.1</system-lambda.version>
     <slf4j.version>1.7.36</slf4j.version>
     <jackson.version>2.13.3</jackson.version>
+    <jsr305.version>3.0.2</jsr305.version>
     <maven-release-plugin.version>2.5.3</maven-release-plugin.version>
     <maven-compiler-plugin.version>3.8.1</maven-compiler-plugin.version>
     <maven-surefire-plugin.version>2.22.2</maven-surefire-plugin.version>
@@ -116,6 +117,12 @@
         <version>${mockito.version}</version>
         <scope>test</scope>
       </dependency>
+      <dependency>
+        <groupId>com.google.code.findbugs</groupId>
+        <artifactId>jsr305</artifactId>
+        <version>${jsr305.version}</version>
+        <scope>test</scope>
+      </dependency>
     </dependencies>
   </dependencyManagement>