DATAJDBC-309 - Polishing.

Javadoc, static factory methods, typos.

Author: mp911de

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/Column.java

@@ -72,7 +72,7 @@ public static Column aliased(String name, Table table, String alias) {
 	}
 
 	/**
-	 * Create a new aliased {@link Column}.
+	 * Creates a new aliased {@link Column}.
 	 *
 	 * @param alias column alias name, must not {@literal null} or empty.
 	 * @return the aliased {@link Column}.
@@ -85,7 +85,7 @@ public Column as(String alias) {
 	}
 
 	/**
-	 * Create a new {@link Column} associated with a {@link Table}.
+	 * Creates a new {@link Column} associated with a {@link Table}.
 	 *
 	 * @param table the table, must not be {@literal null}.
 	 * @return a new {@link Column} associated with {@link Table}.

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/Condition.java

@@ -19,6 +19,7 @@
  * AST {@link Segment} for a condition.
  *
  * @author Mark Paluch
+ * @author Jens Schauder
  * @see Conditions
  */
 public interface Condition extends Segment {
@@ -43,6 +44,11 @@ default Condition or(Condition other) {
 		return new OrCondition(this, other);
 	}
 
+	/**
+	 * Creates a {@link Condition} that negates this {@link Condition}.
+	 *
+	 * @return the negated  {@link Condition}.
+	 */
 	default Condition not() {
 		return new Not(this);
 	}

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/Conditions.java

@@ -15,23 +15,19 @@
  */
 package org.springframework.data.relational.core.sql;
 
+import org.springframework.util.Assert;
+
 /**
  * Factory for common {@link Condition}s.
  *
  * @author Mark Paluch
+ * @author Jens Schauder
  * @see SQL
  * @see Expressions
  * @see Functions
  */
 public abstract class Conditions {
 
-	/**
-	 * @return a new {@link Equals} condition.
-	 */
-	public static Equals equals(Expression left, Expression right) {
-		return Equals.create(left, right);
-	}
-
 	/**
 	 * Creates a plain {@code sql} {@link Condition}.
 	 *
@@ -42,20 +38,55 @@ public static Condition just(String sql) {
 		return new ConstantCondition(sql);
 	}
 
-	// Utility constructor.
-	private Conditions() {
+	/**
+	 * Creates a {@code IS NULL} condition.
+	 *
+	 * @param expression the expression to check for nullability, must not be {@literal null}.
+	 * @return the {@code IS NULL} condition.
+	 */
+	public static Condition isNull(Expression expression) {
+		return IsNull.create(expression);
 	}
 
-	public static Condition isNull(Expression expression) {
-		return new IsNull(expression);
+	/**
+	 * Creates a {@code =} (equals) {@link Condition}.
+	 *
+	 * @param leftColumnOrExpression left side of the comparison.
+	 * @param rightColumnOrExpression right side of the comparison.
+	 * @return the {@link Equals} condition.
+	 */
+	public static Equals isEqual(Expression leftColumnOrExpression, Expression rightColumnOrExpression) {
+		return Equals.create(leftColumnOrExpression, rightColumnOrExpression);
 	}
 
-	public static Condition isEqual(Column bar, Expression param) {
-		return new Equals(bar, param);
+	/**
+	 * Creates a {@code IN} {@link Condition clause}.
+	 *
+	 * @param columnOrExpression left side of the comparison.
+	 * @param arg IN argument.
+	 * @return the {@link In} condition.
+	 */
+	public static Condition in(Expression columnOrExpression, Expression arg) {
+
+		Assert.notNull(columnOrExpression, "Comparison column or expression must not be null");
+		Assert.notNull(columnOrExpression, "Expression argument must not be null");
+
+		return In.create(columnOrExpression, arg);
 	}
 
-	public static Condition in(Column bar, Expression subselectExpression) {
-		return new In(bar, subselectExpression);
+	/**
+	 * Creates a {@code IN} {@link Condition clause} for a {@link Select subselect}.
+	 *
+	 * @param Column the column to compare.
+	 * @param subselect the subselect.
+	 * @return the {@link In} condition.
+	 */
+	public static Condition in(Column column, Select subselect) {
+
+		Assert.notNull(column, "Column must not be null");
+		Assert.notNull(subselect, "Subselect must not be null");
+
+		return in(column, new SubselectExpression(subselect));
 	}
 
 	static class ConstantCondition extends AbstractSegment implements Condition {
@@ -71,6 +102,10 @@ public String toString() {
 			return condition;
 		}
 	}
+
+	// Utility constructor.
+	private Conditions() {
+	}
 }
 
 

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/Equals.java

@@ -29,7 +29,7 @@ public class Equals extends AbstractSegment implements Condition {
 	private final Expression left;
 	private final Expression right;
 
-	Equals(Expression left, Expression right) {
+	private Equals(Expression left, Expression right) {
 
 		super(left, right);
 
@@ -44,12 +44,12 @@ public class Equals extends AbstractSegment implements Condition {
 	 * @param right the right {@link Expression}.
 	 * @return the {@link Equals} condition.
 	 */
-	public static Equals create(Expression left, Expression right) {
+	public static Equals create(Expression leftColumnOrExpression, Expression rightColumnOrExpression) {
 
-		Assert.notNull(left, "Left expression must not be null!");
-		Assert.notNull(right, "Right expression must not be null!");
+		Assert.notNull(leftColumnOrExpression, "Left expression must not be null!");
+		Assert.notNull(rightColumnOrExpression, "Right expression must not be null!");
 
-		return new Equals(left, right);
+		return new Equals(leftColumnOrExpression, rightColumnOrExpression);
 	}
 
 	/**

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/Functions.java

@@ -42,7 +42,7 @@ public static SimpleFunction count(Column... columns) {
 		Assert.notNull(columns, "Columns must not be null!");
 		Assert.notEmpty(columns, "Columns must contains at least one column");
 
-		return new SimpleFunction("COUNT", Arrays.asList(columns));
+		return SimpleFunction.create("COUNT", Arrays.asList(columns));
 	}
 
 	/**
@@ -55,9 +55,10 @@ public static SimpleFunction count(Collection<? extends Expression> columns) {
 
 		Assert.notNull(columns, "Columns must not be null!");
 
-		return new SimpleFunction("COUNT", new ArrayList<>(columns));
+		return SimpleFunction.create("COUNT", new ArrayList<>(columns));
 	}
 
 	// Utility constructor.
-	private Functions() {}
+	private Functions() {
+	}
 }

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/In.java

@@ -16,21 +16,28 @@
 package org.springframework.data.relational.core.sql;
 
 /**
+ * {@code IN} {@link Condition} clause.
+ *
  * @author Jens Schauder
+ * TODO: Accept multiple Expressions.
  */
 public class In extends AbstractSegment implements Condition {
 
 	private final Expression left;
 	private final Expression right;
 
-	public In(Expression left, Expression right) {
+	private In(Expression left, Expression right) {
 
 		super(left, right);
 
 		this.left = left;
 		this.right = right;
 	}
 
+	public static Condition create(Expression columnOrExpression, Expression arg) {
+		return new In(columnOrExpression, arg);
+	}
+
 	@Override
 	public String toString() {
 		return left + " IN " + right;

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/IsNull.java

@@ -15,7 +15,11 @@
  */
 package org.springframework.data.relational.core.sql;
 
+import org.springframework.util.Assert;
+
 /**
+ * {@code IS NULL} {@link Condition}.
+ *
  * @author Jens Schauder
  */
 public class IsNull extends AbstractSegment implements Condition {
@@ -24,29 +28,36 @@ public class IsNull extends AbstractSegment implements Condition {
 
 	private final boolean negated;
 
-	public IsNull(Expression expression, boolean negated) {
+	private IsNull(Expression expression) {
+		this(expression, false);
+	}
+
+	private IsNull(Expression expression, boolean negated) {
 
 		super(expression);
 
 		this.expression = expression;
 		this.negated = negated;
 	}
 
-	public IsNull(Expression expression) {
-		this(expression, false);
+	public static IsNull create(Expression expression) {
+
+		Assert.notNull(expression, "Expression must not be null");
+
+		return new IsNull(expression);
 	}
 
 	@Override
 	public Condition not() {
 		return new IsNull(expression, !negated);
 	}
 
+	public boolean isNegated() {
+		return negated;
+	}
+
 	@Override
 	public String toString() {
 		return expression + (negated ? " IS NOT NULL" : " IS NULL");
 	}
-
-	public boolean isNegated() {
-		return negated;
-	}
 }

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/MultipleCondition.java

@@ -19,9 +19,9 @@
 import java.util.List;
 import java.util.StringJoiner;
 
-import org.springframework.util.Assert;
-
 /**
+ * Wrapper for multiple {@link Condition}s.
+ *
  * @author Jens Schauder
  */
 public abstract class MultipleCondition extends AbstractSegment implements Condition {

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/OrderByField.java

@@ -22,6 +22,8 @@
 import org.springframework.util.Assert;
 
 /**
+ * Represents a field in the {@code ORDER BY} clause.
+ *
  * @author Mark Paluch
  */
 public class OrderByField extends AbstractSegment {
@@ -30,7 +32,7 @@ public class OrderByField extends AbstractSegment {
 	private final @Nullable Sort.Direction direction;
 	private final Sort.NullHandling nullHandling;
 
-	OrderByField(Expression expression, Direction direction, NullHandling nullHandling) {
+	OrderByField(Expression expression, @Nullable Direction direction, NullHandling nullHandling) {
 
 		super(expression);
 		Assert.notNull(expression, "Order by expression must not be null");
@@ -41,18 +43,42 @@ public class OrderByField extends AbstractSegment {
 		this.nullHandling = nullHandling;
 	}
 
+	/**
+	 * Creates a new {@link OrderByField} from a {@link Column} applying default ordering.
+	 *
+	 * @param column must not be {@literal null}.
+	 * @return the {@link OrderByField}.
+	 */
 	public static OrderByField from(Column column) {
 		return new OrderByField(column, null, NullHandling.NATIVE);
 	}
 
+	/**
+	 * Creates a new {@link OrderByField} from a the current one using ascending sorting.
+	 *
+	 * @return the new {@link OrderByField} with ascending sorting.
+	 * @see #desc()
+	 */
 	public OrderByField asc() {
-		return new OrderByField(expression, Direction.ASC, NullHandling.NATIVE);
+		return new OrderByField(expression, Direction.ASC, nullHandling);
 	}
 
+	/**
+	 * Creates a new {@link OrderByField} from a the current one using descending sorting.
+	 *
+	 * @return the new {@link OrderByField} with descending sorting.
+	 * @see #asc()
+	 */
 	public OrderByField desc() {
-		return new OrderByField(expression, Direction.DESC, NullHandling.NATIVE);
+		return new OrderByField(expression, Direction.DESC, nullHandling);
 	}
 
+	/**
+	 * Creates a new {@link OrderByField} with {@link NullHandling} applied.
+	 *
+	 * @param nullHandling must not be {@literal null}.
+	 * @return the new {@link OrderByField} with {@link NullHandling} applied.
+	 */
 	public OrderByField withNullHandling(NullHandling nullHandling) {
 		return new OrderByField(expression, direction, nullHandling);
 	}

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/SQL.java

@@ -25,6 +25,7 @@
  * <p/>The Query Builder API is intended for framework usage to produce SQL required for framework operations.
  *
  * @author Mark Paluch
+ * @author Jens Schauder
  * @see Expressions
  * @see Conditions
  * @see Functions

spring-data-relational/src/main/java/org/springframework/data/relational/core/sql/SelectValidator.java

@@ -19,6 +19,10 @@
 import java.util.Set;
 
 /**
+ * Validator for {@link Select} statements.
+ * <p/>
+ * Validates that all {@link Column}s using a table qualifier have a table import from either the {@code FROM} or {@code JOIN} clause.
+ *
  * @author Mark Paluch
  */
 class SelectValidator implements Visitor {
@@ -130,5 +134,6 @@ public void enter(Visitable segment) {
 	 * @see org.springframework.data.relational.core.sql.Visitor#leave(org.springframework.data.relational.core.sql.Visitable)
 	 */
 	@Override
-	public void leave(Visitable segment) {}
+	public void leave(Visitable segment) {
+	}
 }