feat: add OR operator to QuerySpec constraints

Close #61

Author: javier-godoy

backend-core-data-impl/src/main/java/com/flowingcode/backendcore/dao/jpa/ConstraintTransformerJpaImpl.java

@@ -2,7 +2,7 @@
  * #%L
  * Commons Backend - Data Access Layer Implementations
  * %%
- * Copyright (C) 2020 - 2021 Flowing Code
+ * Copyright (C) 2020 - 2026 Flowing Code
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,6 +31,7 @@
 import com.flowingcode.backendcore.model.constraints.AttributeLikeConstraint;
 import com.flowingcode.backendcore.model.constraints.AttributeNullConstraint;
 import com.flowingcode.backendcore.model.constraints.AttributeRelationalConstraint;
+import com.flowingcode.backendcore.model.constraints.DisjunctionConstraint;
 import com.flowingcode.backendcore.model.constraints.NegatedConstraint;
 import com.flowingcode.backendcore.model.constraints.RelationalConstraint;
 
@@ -44,6 +45,11 @@
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
 
+/**
+ * JPA/Criteria implementation of {@link ConstraintTransformer}.
+ *
+ * <p><b>Instances are not thread-safe.</b> A new instance must be created for each query.
+ */
 @RequiredArgsConstructor
 public class ConstraintTransformerJpaImpl extends ConstraintTransformer<Predicate> {
 
@@ -80,10 +86,12 @@ private From<?,?> join(From<?,?> root, String[] path) {
 		return from;
 	}
 
+	private JoinType currentJoinType = JoinType.INNER;
+
 	@SuppressWarnings("rawtypes")
 	private From<?,?> join(From<?,?> source, String attributeName) {
 		Optional<Join> existingJoin = source.getJoins().stream().filter(join->join.getAttribute().getName().equals(attributeName)).map(join->(Join)join).findFirst();
-		return existingJoin.orElseGet(()->source.join(attributeName, JoinType.INNER));
+		return existingJoin.orElseGet(()->source.join(attributeName, currentJoinType));
 	}
 
 	private static Class<?> boxed(Class<?> type) {
@@ -166,4 +174,18 @@ protected Predicate transformNullConstraint(AttributeNullConstraint c) {
     protected Predicate transformILikeConstraint(AttributeILikeConstraint c) {
         return criteriaBuilder.like(criteriaBuilder.lower(getExpression(c, String.class)), c.getPattern().toLowerCase());
     }
+
+	@Override
+	protected Predicate transformDisjunctionConstraint(DisjunctionConstraint c) {
+		JoinType saved = currentJoinType;
+		currentJoinType = JoinType.LEFT;
+		try {
+			Predicate[] predicates = c.getConstraints().stream()
+					.map(this::apply)
+					.toArray(Predicate[]::new);
+			return criteriaBuilder.or(predicates);
+		} finally {
+			currentJoinType = saved;
+		}
+	}
 }

backend-core-data-impl/src/test/java/com/flowingcode/backendcore/dao/jpa/JpaDaoSupportTest.java

@@ -2,7 +2,7 @@
  * #%L
  * Commons Backend - Data Access Layer Implementations
  * %%
- * Copyright (C) 2020 - 2021 Flowing Code
+ * Copyright (C) 2020 - 2026 Flowing Code
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -147,6 +147,27 @@ void testFilterByState() {
 		assertEquals(5, count);
 	}
 
+	@Test
+	void testFilterWithOrConstraint() {
+		// OR of both city ids must match all 10 persons that have a city assigned
+		PersonFilter pf = new PersonFilter();
+		pf.addConstraint(
+			ConstraintBuilder.of("city", "id").equal(cities.get(0).getId())
+				.or(ConstraintBuilder.of("city", "id").equal(cities.get(1).getId())));
+		assertEquals(10, dao.count(pf));
+	}
+
+	@Test
+	void testFilterWithOrConstraintPartialMatch() {
+		// city.id branch matches 5 persons; id branch matches persistedPerson (who has no city).
+		// LEFT JOIN on city must keep persistedPerson in the result set so the OR can match them.
+		PersonFilter pf = new PersonFilter();
+		pf.addConstraint(
+			ConstraintBuilder.of("city", "id").equal(cities.get(0).getId())
+				.or(ConstraintBuilder.of("id").equal(persistedPerson.getId())));
+		assertEquals(6, dao.count(pf));
+	}
+
 	@Test
 	@Disabled
 	void testDelete() {

backend-core-model/src/main/java/com/flowingcode/backendcore/model/Constraint.java

@@ -2,7 +2,7 @@
  * #%L
  * Commons Backend - Model
  * %%
- * Copyright (C) 2020 - 2021 Flowing Code
+ * Copyright (C) 2020 - 2026 Flowing Code
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,12 +19,32 @@
  */
 package com.flowingcode.backendcore.model;
 
+import com.flowingcode.backendcore.model.constraints.DisjunctionConstraint;
 import com.flowingcode.backendcore.model.constraints.NegatedConstraint;
 
 public interface Constraint {
 
   default Constraint not() {
     return new NegatedConstraint(this);
   }
-  
+
+  /**
+   * Returns a constraint that is satisfied when this constraint or any of the given constraints is
+   * satisfied (logical OR).
+   *
+   * @param first the first additional constraint
+   * @param rest  optional additional constraints
+   * @return a {@link DisjunctionConstraint} combining this and the given constraints
+   */
+  default Constraint or(Constraint first, Constraint... rest) {
+    return DisjunctionConstraint.of(this, prepend(first, rest));
+  }
+
+  private static Constraint[] prepend(Constraint first, Constraint[] rest) {
+    Constraint[] result = new Constraint[1 + rest.length];
+    result[0] = first;
+    System.arraycopy(rest, 0, result, 1, rest.length);
+    return result;
+  }
+
 }

backend-core-model/src/main/java/com/flowingcode/backendcore/model/ConstraintTransformer.java

@@ -2,7 +2,7 @@
  * #%L
  * Commons Backend - Model
  * %%
- * Copyright (C) 2020 - 2021 Flowing Code
+ * Copyright (C) 2020 - 2026 Flowing Code
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,6 +28,7 @@
 import com.flowingcode.backendcore.model.constraints.AttributeLikeConstraint;
 import com.flowingcode.backendcore.model.constraints.AttributeNullConstraint;
 import com.flowingcode.backendcore.model.constraints.AttributeRelationalConstraint;
+import com.flowingcode.backendcore.model.constraints.DisjunctionConstraint;
 import com.flowingcode.backendcore.model.constraints.NegatedConstraint;
 
 /**
@@ -80,6 +81,10 @@ protected T transform(Constraint c) {
           return transformILikeConstraint((AttributeILikeConstraint) c);
       }
 
+		if (c instanceof DisjunctionConstraint) {
+			return transformDisjunctionConstraint((DisjunctionConstraint) c);
+		}
+
 		return null;
 	}
 
@@ -125,4 +130,10 @@ protected T transformNullConstraint(AttributeNullConstraint c) {
     protected T transformILikeConstraint(AttributeILikeConstraint c) {
         return null;
     }
+
+	/** Return an implementation-specific representation of a {@code DisjunctionConstraint} constraint.
+	 * @return an implementation-specific representation of the constraint, or {@code null} if it cannot be transformed.*/
+	protected T transformDisjunctionConstraint(DisjunctionConstraint c) {
+		return null;
+	}
 }

backend-core-model/src/main/java/com/flowingcode/backendcore/model/constraints/DisjunctionConstraint.java

@@ -0,0 +1,48 @@
+/*-
+ * #%L
+ * Commons Backend - Model
+ * %%
+ * Copyright (C) 2020 - 2026 Flowing Code
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+package com.flowingcode.backendcore.model.constraints;
+
+import com.flowingcode.backendcore.model.Constraint;
+import java.util.List;
+import java.util.Objects;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NonNull;
+import lombok.RequiredArgsConstructor;
+import lombok.experimental.FieldDefaults;
+
+/** A constraint that is satisfied when any of its member constraints is satisfied (logical OR). */
+@Getter
+@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
+@FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
+public final class DisjunctionConstraint implements Constraint {
+
+  @NonNull List<Constraint> constraints;
+
+  public static DisjunctionConstraint of(Constraint first, Constraint... rest) {
+    List<Constraint> list = new java.util.ArrayList<>();
+    list.add(Objects.requireNonNull(first, "constraint must not be null"));
+    for (Constraint c : rest) {
+      list.add(Objects.requireNonNull(c, "constraint must not be null"));
+    }
+    return new DisjunctionConstraint(List.copyOf(list));
+  }
+
+}