DATAJDBC-1953 Introduced DialectCriteriaCondition

Signed-off-by: mipo256 <[email protected]>

Author: mipo256

spring-data-r2dbc/src/test/java/org/springframework/data/r2dbc/query/CriteriaUnitTests.java

@@ -23,6 +23,7 @@
 import org.assertj.core.api.SoftAssertions;
 import org.junit.jupiter.api.Test;
 
+import org.springframework.data.relational.core.dialect.condition.Postgres;
 import org.springframework.data.relational.core.query.Criteria;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
 

spring-data-relational/src/main/java/org/springframework/data/relational/core/dialect/OracleDialect.java

@@ -28,7 +28,7 @@
  * An SQL dialect for Oracle.
  *
  * @author Jens Schauder
- * @author Mikahil Polivakha
+ * @author Mikhail Polivakha
  * @since 2.1
  */
 public class OracleDialect extends AnsiDialect {

spring-data-relational/src/main/java/org/springframework/data/relational/core/dialect/condition/DialectCriteriaCondition.java

@@ -0,0 +1,18 @@
+package org.springframework.data.relational.core.dialect.condition;
+
+import org.springframework.data.relational.core.query.Criteria;
+
+/**
+ * This interface represents dialect specific conditions used in WHERE causes built by {@link Criteria}.
+ *
+ * @author Mikhail Polivakha
+ */
+public interface DialectCriteriaCondition {
+
+    /**
+     * Render a vendor-specific part of the SQL condition.
+     *
+     * @return the rendered part of the SQL statement
+     */
+    String render();
+}

spring-data-relational/src/main/java/org/springframework/data/relational/core/dialect/condition/Postgres.java

@@ -0,0 +1,67 @@
+package org.springframework.data.relational.core.dialect.condition;
+
+import org.springframework.data.relational.core.dialect.PostgresDialect;
+
+/**
+ * {@link DialectCriteriaCondition DialectCriteriaConditions} that are specific to {@link PostgresDialect PostgreSQL Dialect}
+ *
+ * @author Mikhail Polivakha
+ */
+public class Postgres {
+
+    /**
+     * Creates a condition that checks that the assumed column of an {@link java.sql.Array} type
+     * contains an array of any values
+     *
+     * @param values array that assumed column should contain
+     * @return crafted {@link DialectCriteriaCondition}
+     */
+    public static DialectCriteriaCondition arrayContains(Object... values) {
+        return () -> "@> ARRAY[%s]".formatted(toLiterals(false, values));
+    }
+
+    /**
+     * Creates a condition that checks that the assumed column of an {@link java.sql.Array} type
+     * contains an array of {@link String} values.
+     *
+     * @param values array of {@link String String} that assumed column should contain
+     * @return crafted {@link DialectCriteriaCondition}
+     */
+    public static DialectCriteriaCondition arrayContains(String... values) {
+        return () -> "@> ARRAY[%s]::text[]".formatted(toLiterals(true, values));
+    }
+
+    /**
+     * Creates a condition that checks that the assumed column of an {@link java.sql.Array} type
+     * contains an array of a single {@link String} value.
+     *
+     * @param value array of {@link String String} that assumed value should contain
+     * @return crafted {@link DialectCriteriaCondition}
+     */
+    public static DialectCriteriaCondition arrayContains(String value) {
+        return arrayContains(new String[]{value});
+    }
+
+    @SafeVarargs
+    private static  <T> String toLiterals(boolean quoted, T... values) {
+        StringBuilder result = new StringBuilder();
+        for (int i = 0; i < values.length; i++) {
+            T value = values[i];
+
+            if (value != null) {
+                if (quoted) {
+                    result.append('\'').append(value).append('\'');
+                } else {
+                    result.append(value);
+                }
+            } else {
+                result.append("NULL");
+            }
+
+            if (i != values.length - 1) {
+                result.append(",");
+            }
+        }
+        return result.toString();
+    }
+}

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Criteria.java

@@ -25,6 +25,7 @@
 import java.util.StringJoiner;
 
 import org.springframework.dao.InvalidDataAccessApiUsageException;
+import org.springframework.data.relational.core.dialect.condition.DialectCriteriaCondition;
 import org.springframework.data.relational.core.sql.IdentifierProcessing;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
 import org.springframework.data.util.Pair;
@@ -53,11 +54,12 @@
  * @author Oliver Drotbohm
  * @author Roman Chigvintsev
  * @author Jens Schauder
+ * @author Mikhail Polivakha
  * @since 2.0
  */
 public class Criteria implements CriteriaDefinition {
 
-	static final Criteria EMPTY = new Criteria(SqlIdentifier.EMPTY, Comparator.INITIAL, null);
+	static final Criteria EMPTY = new Criteria(SqlIdentifier.EMPTY, Comparator.INITIAL, null, null);
 
 	private final @Nullable Criteria previous;
 	private final Combinator combinator;
@@ -68,17 +70,25 @@ public class Criteria implements CriteriaDefinition {
 	private final @Nullable Object value;
 	private final boolean ignoreCase;
 
-	private Criteria(SqlIdentifier column, Comparator comparator, @Nullable Object value) {
-		this(null, Combinator.INITIAL, Collections.emptyList(), column, comparator, value, false);
+    private final DialectCriteriaCondition dialectCriteriaCondition;
+
+	private Criteria(SqlIdentifier column, @Nullable Comparator comparator, @Nullable Object value, DialectCriteriaCondition dialectCriteriaCondition) {
+		this(null, Combinator.INITIAL, Collections.emptyList(), column, comparator, value, false, dialectCriteriaCondition);
 	}
 
 	private Criteria(@Nullable Criteria previous, Combinator combinator, List<CriteriaDefinition> group,
-			@Nullable SqlIdentifier column, @Nullable Comparator comparator, @Nullable Object value) {
-		this(previous, combinator, group, column, comparator, value, false);
+			@Nullable SqlIdentifier column, @Nullable Comparator comparator, @Nullable Object value, DialectCriteriaCondition dialectCriteriaCondition) {
+		this(previous, combinator, group, column, comparator, value, false, dialectCriteriaCondition);
 	}
 
 	private Criteria(@Nullable Criteria previous, Combinator combinator, List<CriteriaDefinition> group,
-			@Nullable SqlIdentifier column, @Nullable Comparator comparator, @Nullable Object value, boolean ignoreCase) {
+			@Nullable SqlIdentifier column, @Nullable Comparator comparator, @Nullable Object value, boolean ignoreCase,
+            @Nullable DialectCriteriaCondition dialectCriteriaCondition) {
+
+        Assert.state(
+          (dialectCriteriaCondition != null && comparator == null) || (dialectCriteriaCondition == null && comparator != null),
+          "Either DialectCriteriaCondition or Comparator should be specified for this criteria, but not both"
+        );
 
 		this.previous = previous;
 		this.combinator = previous != null && previous.isEmpty() ? Combinator.INITIAL : combinator;
@@ -87,6 +97,7 @@ private Criteria(@Nullable Criteria previous, Combinator combinator, List<Criter
 		this.comparator = comparator;
 		this.value = value;
 		this.ignoreCase = ignoreCase;
+        this.dialectCriteriaCondition = dialectCriteriaCondition;
 	}
 
 	private Criteria(@Nullable Criteria previous, Combinator combinator, List<CriteriaDefinition> group) {
@@ -98,6 +109,7 @@ private Criteria(@Nullable Criteria previous, Combinator combinator, List<Criter
 		this.comparator = null;
 		this.value = null;
 		this.ignoreCase = false;
+        this.dialectCriteriaCondition = null;
 	}
 
 	/**
@@ -169,8 +181,8 @@ public CriteriaStep and(String column) {
 		SqlIdentifier identifier = SqlIdentifier.unquoted(column);
 		return new DefaultCriteriaStep(identifier) {
 			@Override
-			protected Criteria createCriteria(Comparator comparator, @Nullable Object value) {
-				return new Criteria(Criteria.this, Combinator.AND, Collections.emptyList(), identifier, comparator, value);
+			protected Criteria createCriteria(Comparator comparator, @Nullable Object value, DialectCriteriaCondition dialectCriteriaCondition) {
+				return new Criteria(Criteria.this, Combinator.AND, Collections.emptyList(), identifier, comparator, value, dialectCriteriaCondition);
 			}
 		};
 	}
@@ -216,8 +228,8 @@ public CriteriaStep or(String column) {
 		SqlIdentifier identifier = SqlIdentifier.unquoted(column);
 		return new DefaultCriteriaStep(identifier) {
 			@Override
-			protected Criteria createCriteria(Comparator comparator, @Nullable Object value) {
-				return new Criteria(Criteria.this, Combinator.OR, Collections.emptyList(), identifier, comparator, value);
+			protected Criteria createCriteria(Comparator comparator, @Nullable Object value, DialectCriteriaCondition dialectCriteriaCondition) {
+				return new Criteria(Criteria.this, Combinator.OR, Collections.emptyList(), identifier, comparator, value, dialectCriteriaCondition);
 			}
 		};
 	}
@@ -259,7 +271,7 @@ public Criteria or(List<? extends CriteriaDefinition> criteria) {
 	 */
 	public Criteria ignoreCase(boolean ignoreCase) {
 		if (this.ignoreCase != ignoreCase) {
-			return new Criteria(previous, combinator, group, column, comparator, value, ignoreCase);
+			return new Criteria(previous, combinator, group, column, comparator, value, ignoreCase, dialectCriteriaCondition);
 		}
 		return this;
 	}
@@ -328,18 +340,25 @@ private boolean doIsEmpty() {
 	/**
 	 * @return {@literal true} if this {@link Criteria} is empty.
 	 */
+    @Override
 	public boolean isGroup() {
 		return !this.group.isEmpty();
 	}
 
 	/**
 	 * @return {@link Combinator} to combine this criteria with a previous one.
 	 */
+    @Override
 	public Combinator getCombinator() {
 		return combinator;
 	}
 
-	@Override
+    @Override
+    public DialectCriteriaCondition getDialectCriteriaCondition() {
+        return dialectCriteriaCondition;
+    }
+
+    @Override
 	public List<CriteriaDefinition> getGroup() {
 		return group;
 	}
@@ -476,8 +495,16 @@ private void render(CriteriaDefinition criteria, StringBuilder stringBuilder) {
 			return;
 		}
 
-		stringBuilder.append(criteria.getColumn().toSql(IdentifierProcessing.NONE)).append(' ')
-				.append(criteria.getComparator().getComparator());
+        stringBuilder.append(criteria.getColumn().toSql(IdentifierProcessing.NONE)).append(' ');
+
+        DialectCriteriaCondition dialectCriteriaCondition = criteria.getDialectCriteriaCondition();
+
+        if (dialectCriteriaCondition != null) {
+            stringBuilder.append(dialectCriteriaCondition.render());
+            return;
+        }
+
+        stringBuilder.append(criteria.getComparator().getComparator());
 
 		switch (criteria.getComparator()) {
 			case BETWEEN:
@@ -653,6 +680,39 @@ public interface CriteriaStep {
 		 * @return a new {@link Criteria} object
 		 */
 		Criteria isFalse();
+
+        /**
+         * Creates a {@link Criteria} using custom {@link DialectCriteriaCondition}. This API primarily exists
+         * to handle conditions in WHERE clause that are specific to particular RDBMS vendor.
+         * <p>
+         * There are some predefined vendor-specific conditions in the {@link org.springframework.data.relational.core.dialect.condition}
+         * package. For instance, an example of usage is:
+         * <p>
+         * <pre class="code">
+         *    Criteria criteria = Criteria
+         *        .where("tags")
+         *        .satisfies(Postgres.arrayContains("computers", "electronics"))
+         * </pre>
+         *
+         * This will yield the following SQL:
+         * <p>
+         * <pre class="code">
+         *     tags @> ARRAY['computers','electronics']::text[]
+         * </pre>
+         *
+         * In the sample above, the assumption is that the 'tags' column is of an 'ARRAY TEXT' or 'ARRAY VARCHAR' PostgreSQL type.
+         * <p>
+         * If there is no appropriate {@link DialectCriteriaCondition} built-in, please, consider to file an issue, and in the meantime,
+         * consider to write your own {@link DialectCriteriaCondition}, like this (case insensitive regexp-match in PostgreSQL):
+         * <p>
+         * <pre class="code">
+         *
+         * </pre>
+         *
+         * @see org.springframework.data.relational.core.dialect.condition.Postgres
+         * @return a new {@link Criteria} object
+         */
+        Criteria satisfies(DialectCriteriaCondition condition);
 	}
 
 	/**
@@ -671,15 +731,15 @@ public Criteria is(Object value) {
 
 			Assert.notNull(value, "Value must not be null");
 
-			return createCriteria(Comparator.EQ, value);
+			return createCriteria(Comparator.EQ, value, null);
 		}
 
 		@Override
 		public Criteria not(Object value) {
 
 			Assert.notNull(value, "Value must not be null");
 
-			return createCriteria(Comparator.NEQ, value);
+			return createCriteria(Comparator.NEQ, value, null);
 		}
 
 		@Override
@@ -693,7 +753,7 @@ public Criteria in(Object... values) {
 						"You can only pass in one argument of type " + values[1].getClass().getName());
 			}
 
-			return createCriteria(Comparator.IN, Arrays.asList(values));
+			return createCriteria(Comparator.IN, Arrays.asList(values), null);
 		}
 
 		@Override
@@ -702,7 +762,7 @@ public Criteria in(Collection<?> values) {
 			Assert.notNull(values, "Values must not be null");
 			Assert.noNullElements(values.toArray(), "Values must not contain a null value");
 
-			return createCriteria(Comparator.IN, values);
+			return createCriteria(Comparator.IN, values, null);
 		}
 
 		@Override
@@ -716,7 +776,7 @@ public Criteria notIn(Object... values) {
 						"You can only pass in one argument of type " + values[1].getClass().getName());
 			}
 
-			return createCriteria(Comparator.NOT_IN, Arrays.asList(values));
+			return createCriteria(Comparator.NOT_IN, Arrays.asList(values), null);
 		}
 
 		@Override
@@ -725,7 +785,7 @@ public Criteria notIn(Collection<?> values) {
 			Assert.notNull(values, "Values must not be null");
 			Assert.noNullElements(values.toArray(), "Values must not contain a null value");
 
-			return createCriteria(Comparator.NOT_IN, values);
+			return createCriteria(Comparator.NOT_IN, values, null);
 		}
 
 		@Override
@@ -734,7 +794,7 @@ public Criteria between(Object begin, Object end) {
 			Assert.notNull(begin, "Begin value must not be null");
 			Assert.notNull(end, "End value must not be null");
 
-			return createCriteria(Comparator.BETWEEN, Pair.of(begin, end));
+			return createCriteria(Comparator.BETWEEN, Pair.of(begin, end), null);
 		}
 
 		@Override
@@ -743,77 +803,82 @@ public Criteria notBetween(Object begin, Object end) {
 			Assert.notNull(begin, "Begin value must not be null");
 			Assert.notNull(end, "End value must not be null");
 
-			return createCriteria(Comparator.NOT_BETWEEN, Pair.of(begin, end));
+			return createCriteria(Comparator.NOT_BETWEEN, Pair.of(begin, end), null);
 		}
 
 		@Override
 		public Criteria lessThan(Object value) {
 
 			Assert.notNull(value, "Value must not be null");
 
-			return createCriteria(Comparator.LT, value);
+			return createCriteria(Comparator.LT, value, null);
 		}
 
 		@Override
 		public Criteria lessThanOrEquals(Object value) {
 
 			Assert.notNull(value, "Value must not be null");
 
-			return createCriteria(Comparator.LTE, value);
+			return createCriteria(Comparator.LTE, value, null);
 		}
 
 		@Override
 		public Criteria greaterThan(Object value) {
 
 			Assert.notNull(value, "Value must not be null");
 
-			return createCriteria(Comparator.GT, value);
+			return createCriteria(Comparator.GT, value, null);
 		}
 
 		@Override
 		public Criteria greaterThanOrEquals(Object value) {
 
 			Assert.notNull(value, "Value must not be null");
 
-			return createCriteria(Comparator.GTE, value);
+			return createCriteria(Comparator.GTE, value, null);
 		}
 
 		@Override
 		public Criteria like(Object value) {
 
 			Assert.notNull(value, "Value must not be null");
 
-			return createCriteria(Comparator.LIKE, value);
+			return createCriteria(Comparator.LIKE, value, null);
 		}
 
 		@Override
 		public Criteria notLike(Object value) {
 			Assert.notNull(value, "Value must not be null");
-			return createCriteria(Comparator.NOT_LIKE, value);
+			return createCriteria(Comparator.NOT_LIKE, value, null);
 		}
 
 		@Override
 		public Criteria isNull() {
-			return createCriteria(Comparator.IS_NULL, null);
+			return createCriteria(Comparator.IS_NULL, null, null);
 		}
 
 		@Override
 		public Criteria isNotNull() {
-			return createCriteria(Comparator.IS_NOT_NULL, null);
+			return createCriteria(Comparator.IS_NOT_NULL, null, null);
 		}
 
 		@Override
 		public Criteria isTrue() {
-			return createCriteria(Comparator.IS_TRUE, true);
+			return createCriteria(Comparator.IS_TRUE, true, null);
 		}
 
 		@Override
 		public Criteria isFalse() {
-			return createCriteria(Comparator.IS_FALSE, false);
+			return createCriteria(Comparator.IS_FALSE, false, null);
 		}
 
-		protected Criteria createCriteria(Comparator comparator, @Nullable Object value) {
-			return new Criteria(this.property, comparator, value);
+        @Override
+        public Criteria satisfies(DialectCriteriaCondition condition) {
+            return createCriteria(null, null, condition);
+        }
+
+        protected Criteria createCriteria(@Nullable Comparator comparator, @Nullable Object value, DialectCriteriaCondition dialectCriteriaCondition) {
+			return new Criteria(this.property, comparator, value, dialectCriteriaCondition);
 		}
 	}
 }

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/CriteriaDefinition.java

@@ -18,6 +18,7 @@
 import java.util.Arrays;
 import java.util.List;
 
+import org.springframework.data.relational.core.dialect.condition.DialectCriteriaCondition;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
@@ -28,6 +29,7 @@
  *
  * @author Mark Paluch
  * @author Jens Schauder
+ * @author Mikhail Polivakha
  * @since 2.0
  */
 public interface CriteriaDefinition {
@@ -133,6 +135,12 @@ static CriteriaDefinition from(List<? extends CriteriaDefinition> criteria) {
 	 */
 	Combinator getCombinator();
 
+    /**
+     * @return {@link DialectCriteriaCondition} used in this criteria
+     */
+    @Nullable
+    DialectCriteriaCondition getDialectCriteriaCondition();
+
 	enum Combinator {
 		INITIAL, AND, OR;
 	}

spring-data-relational/src/test/java/org/springframework/data/relational/core/query/CriteriaUnitTests.java

@@ -22,6 +22,7 @@
 import java.util.Arrays;
 
 import org.junit.jupiter.api.Test;
+import org.springframework.data.relational.core.dialect.condition.Postgres;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
 
 /**
@@ -30,6 +31,7 @@
  * @author Mark Paluch
  * @author Jens Schauder
  * @author Roman Chigvintsev
+ * @author Mikhail Polivakha
  */
 class CriteriaUnitTests {
 
@@ -95,6 +97,27 @@ void andChainedCriteria() {
 		assertThat(criteria.getValue()).isEqualTo("bar");
 	}
 
+	@Test // DATAJDBC-513
+	void andChainedCriteriaWithDialectCriteriaCondition() {
+
+		Criteria criteria = where("foo").is("bar").and("baz").satisfies(Postgres.arrayContains("first", "second"));
+
+		assertThat(criteria.getColumn()).isEqualTo(SqlIdentifier.unquoted("baz"));
+		assertThat(criteria.getComparator()).isNull();
+		assertThat(criteria.getValue()).isNull();
+		assertThat(criteria.getPrevious()).isNotNull();
+		assertThat(criteria.getDialectCriteriaCondition()).isNotNull();
+		assertThat(criteria.getCombinator()).isEqualTo(Criteria.Combinator.AND);
+
+		criteria = criteria.getPrevious();
+
+		assertThat(criteria.getColumn()).isEqualTo(SqlIdentifier.unquoted("foo"));
+		assertThat(criteria.getComparator()).isEqualTo(CriteriaDefinition.Comparator.EQ);
+		assertThat(criteria.getValue()).isEqualTo("bar");
+
+        criteria.toString().equals("foo = 'bar' AND baz @> ARRAY['first','second']::text[]");
+	}
+
 	@Test // DATAJDBC-513
 	void andGroupedCriteria() {
 
@@ -116,6 +139,27 @@ void andGroupedCriteria() {
 		assertThat(grouped).hasToString("foo = 'bar' AND (foo = 'baz' OR bar IS NOT NULL)");
 	}
 
+	@Test // DATAJDBC-1953
+	void andGroupedCriteriaWithDialectCriteriaCondition() {
+
+		Criteria grouped = where("foo").is("bar").and(where("foo").is("baz").or("bar").satisfies(Postgres.arrayContains("electronics")));
+		Criteria criteria = grouped;
+
+		assertThat(criteria.isGroup()).isTrue();
+		assertThat(criteria.getGroup()).hasSize(1);
+		assertThat(criteria.getGroup().get(0).getColumn()).isEqualTo(SqlIdentifier.unquoted("bar"));
+		assertThat(criteria.getCombinator()).isEqualTo(Criteria.Combinator.AND);
+
+		criteria = criteria.getPrevious();
+
+		assertThat(criteria).isNotNull();
+		assertThat(criteria.getColumn()).isEqualTo(SqlIdentifier.unquoted("foo"));
+		assertThat(criteria.getComparator()).isEqualTo(CriteriaDefinition.Comparator.EQ);
+		assertThat(criteria.getValue()).isEqualTo("bar");
+
+		assertThat(grouped).hasToString("foo = 'bar' AND (foo = 'baz' OR bar @> ARRAY['electronics']::text[])");
+	}
+
 	@Test // DATAJDBC-513
 	void orChainedCriteria() {
 
@@ -179,6 +223,32 @@ void shouldBuildNotEqualsCriteria() {
 		assertThat(criteria.getValue()).isEqualTo("bar");
 	}
 
+	@Test // DATAJDBC-1953
+	void shouldBuildSimplePredefinedDialectCriteriaCondition() {
+
+		Criteria criteria = where("foo").satisfies(Postgres.arrayContains(1, 2, 3));
+
+		assertThat(criteria.getColumn()).isEqualTo(SqlIdentifier.unquoted("foo"));
+		assertThat(criteria.getComparator()).isNull();
+		assertThat(criteria.getDialectCriteriaCondition()).isNotNull();
+		assertThat(criteria.getValue()).isNull();
+
+        assertThat(criteria.toString()).isEqualTo("foo @> ARRAY[1,2,3]");
+	}
+
+	@Test // DATAJDBC-1953
+	void shouldBuildSimpleCustomDialectCriteriaCondition() {
+
+		Criteria criteria = where("foo").satisfies(() -> "~* '*.example.*'");
+
+		assertThat(criteria.getColumn()).isEqualTo(SqlIdentifier.unquoted("foo"));
+		assertThat(criteria.getComparator()).isNull();
+		assertThat(criteria.getDialectCriteriaCondition()).isNotNull();
+		assertThat(criteria.getValue()).isNull();
+
+        assertThat(criteria.toString()).isEqualTo("foo ~* '*.example.*'");
+	}
+
 	@Test // DATAJDBC-513
 	void shouldBuildInCriteria() {