DATAJDBC-309 - Polishing.

Add since tags. Improve Javadoc.

Author: mp911de

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

@@ -21,6 +21,7 @@
  * Abstract implementation to support {@link Segment} implementations.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 abstract class AbstractSegment implements Segment {
 

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

@@ -19,6 +19,7 @@
  * Aliased element exposing an {@link #getAlias() alias}.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public interface Aliased {
 

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

@@ -19,6 +19,7 @@
  * An expression with an alias.
  *
  * @author Jens Schauder
+ * @since 1.1
  */
 class AliasedExpression extends AbstractSegment implements Aliased, Expression {
 

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

@@ -19,6 +19,7 @@
  * {@link Condition} representing an {@code AND} relation between two {@link Condition}s.
  *
  * @author Mark Paluch
+ * @since 1.1
  * @see Condition#and(Condition)
  */
 public class AndCondition extends MultipleCondition {

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

@@ -19,12 +19,15 @@
  * {@link Segment} to select all columns from a {@link Table}.
  * <p/>
  * * Renders to: {@code
- * <table>
+ *
+<table>
  * .*} as in {@code SELECT
- * <table>
+ *
+<table>
  * .* FROM …}.
  *
  * @author Mark Paluch
+ * @since 1.1
  * @see Table#asterisk()
  */
 public class AsteriskFromTable extends AbstractSegment implements Expression {

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

@@ -21,6 +21,7 @@
  * Bind marker/parameter placeholder used to construct prepared statements with parameter substitution.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public class BindMarker extends AbstractSegment implements Expression {
 

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

@@ -24,6 +24,7 @@
  * Renders to: {@code <name>} or {@code <table(alias)>.<name>}.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public class Column extends AbstractSegment implements Expression, Named {
 

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

@@ -23,6 +23,7 @@
  * Results in a rendered condition: {@code <left> <comparator> <right>} (e.g. {@code col = 'predicate'}.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public class Comparison extends AbstractSegment implements Condition {
 

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

@@ -20,6 +20,7 @@
  *
  * @author Mark Paluch
  * @author Jens Schauder
+ * @since 1.1
  * @see Conditions
  */
 public interface Condition extends Segment {

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

@@ -26,6 +26,7 @@
  *
  * @author Mark Paluch
  * @author Jens Schauder
+ * @since 1.1
  * @see SQL
  * @see Expressions
  * @see Functions

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

@@ -26,6 +26,7 @@
  * Default {@link Select} implementation.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 class DefaultSelect implements Select {
 
@@ -39,7 +40,7 @@ class DefaultSelect implements Select {
 	private final List<OrderByField> orderBy;
 
 	DefaultSelect(boolean distinct, List<Expression> selectList, List<Table> from, long limit, long offset,
-				  List<Join> joins, @Nullable Condition where, List<OrderByField> orderBy) {
+			List<Join> joins, @Nullable Condition where, List<OrderByField> orderBy) {
 
 		this.distinct = distinct;
 		this.selectList = new SelectList(new ArrayList<>(selectList));

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

@@ -30,6 +30,7 @@
  * Default {@link SelectBuilder} implementation.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 class DefaultSelectBuilder implements SelectBuilder, SelectAndFrom, SelectFromAndJoin, SelectWhereAndOr {
 
@@ -39,7 +40,7 @@ class DefaultSelectBuilder implements SelectBuilder, SelectAndFrom, SelectFromAn
 	private long limit = -1;
 	private long offset = -1;
 	private List<Join> joins = new ArrayList<>();
-	private Condition where;
+	private @Nullable Condition where;
 	private List<OrderByField> orderBy = new ArrayList<>();
 
 	/*

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

@@ -19,9 +19,8 @@
  * Expression that can be used in select lists.
  *
  * @author Mark Paluch
+ * @since 1.1
  * @see SQL
  * @see Expressions
  */
-public interface Expression extends Segment {
-
-}
+public interface Expression extends Segment {}

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

@@ -19,6 +19,7 @@
  * Factory for common {@link Expression}s.
  *
  * @author Mark Paluch
+ * @since 1.1
  * @see SQL
  * @see Conditions
  * @see Functions
@@ -52,8 +53,7 @@ public static Expression asterisk(Table table) {
 	}
 
 	// Utility constructor.
-	private Expressions() {
-	}
+	private Expressions() {}
 
 	static class SimpleExpression extends AbstractSegment implements Expression {
 
@@ -69,7 +69,3 @@ public String toString() {
 		}
 	}
 }
-
-
-
-

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

@@ -16,16 +16,15 @@
 package org.springframework.data.relational.core.sql;
 
 import java.util.Arrays;
-import java.util.Collections;
 import java.util.List;
 
-import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
 /**
  * {@code FROM} clause.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public class From extends AbstractSegment {
 
@@ -37,7 +36,7 @@ public class From extends AbstractSegment {
 
 	From(List<Table> tables) {
 
-		super(tables.toArray(new Table[]{}));
+		super(tables.toArray(new Table[] {}));
 
 		this.tables = tables;
 	}

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

@@ -25,6 +25,7 @@
  * Factory for common {@link Expression function expressions}.
  *
  * @author Mark Paluch
+ * @since 1.1
  * @see SQL
  * @see Expressions
  * @see Functions
@@ -59,6 +60,5 @@ public static SimpleFunction count(Collection<? extends Expression> columns) {
 	}
 
 	// Utility constructor.
-	private Functions() {
-	}
+	private Functions() {}
 }

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

@@ -28,6 +28,7 @@
  *
  * @author Jens Schauder
  * @author Mark Paluch
+ * @since 1.1
  */
 public class In extends AbstractSegment implements Condition {
 

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

@@ -21,11 +21,11 @@
  * {@code IS NULL} {@link Condition}.
  *
  * @author Jens Schauder
+ * @since 1.1
  */
 public class IsNull extends AbstractSegment implements Condition {
 
 	private final Expression expression;
-
 	private final boolean negated;
 
 	private IsNull(Expression expression) {

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

@@ -19,10 +19,12 @@
  * {@link Segment} for a {@code JOIN} declaration.
  * <p/>
  * Renders to: {@code JOIN
- * <table>
+ *
+<table>
  *  ON <condition>}.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public class Join extends AbstractSegment {
 

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

@@ -23,6 +23,7 @@
  * Results in a rendered condition: {@code <left> LIKE <right>}.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public class Like extends AbstractSegment implements Condition {
 

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

@@ -23,6 +23,7 @@
  * Wrapper for multiple {@link Condition}s.
  *
  * @author Jens Schauder
+ * @since 1.1
  */
 public abstract class MultipleCondition extends AbstractSegment implements Condition {
 

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

@@ -19,6 +19,7 @@
  * Named element exposing a {@link #getName() name}.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public interface Named {
 

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

@@ -17,6 +17,7 @@
 
 /**
  * @author Jens Schauder
+ * @since 1.1
  */
 public class Not extends AbstractSegment implements Condition {
 

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

@@ -19,6 +19,7 @@
  * {@link Condition} representing an {@code OR} relation between two {@link Condition}s.
  *
  * @author Mark Paluch
+ * @since 1.1
  * @see Condition#or(Condition)
  */
 public class OrCondition extends MultipleCondition {

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

@@ -25,14 +25,15 @@
  * Represents a field in the {@code ORDER BY} clause.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public class OrderByField extends AbstractSegment {
 
 	private final Expression expression;
 	private final @Nullable Sort.Direction direction;
 	private final Sort.NullHandling nullHandling;
 
-	OrderByField(Expression expression, @Nullable Direction direction, NullHandling nullHandling) {
+	private OrderByField(Expression expression, @Nullable Direction direction, NullHandling nullHandling) {
 
 		super(expression);
 		Assert.notNull(expression, "Order by expression must not be null");

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

@@ -19,12 +19,14 @@
 import org.springframework.util.Assert;
 
 /**
- * Utility to create SQL {@link Segment}s. Typically used as entry point to the Statement Builder.
- * Objects and dependent objects created by the Query AST are immutable except for builders.
- * <p/>The Statement Builder API is intended for framework usage to produce SQL required for framework operations.
+ * Utility to create SQL {@link Segment}s. Typically used as entry point to the Statement Builder. Objects and dependent
+ * objects created by the Query AST are immutable except for builders.
+ * <p/>
+ * The Statement Builder API is intended for framework usage to produce SQL required for framework operations.
  *
  * @author Mark Paluch
  * @author Jens Schauder
+ * @since 1.1
  * @see Expressions
  * @see Conditions
  * @see Functions
@@ -76,6 +78,5 @@ public static BindMarker bindMarker(String name) {
 	}
 
 	// Utility constructor.
-	private SQL() {
-	}
+	private SQL() {}
 }

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

@@ -16,9 +16,11 @@
 package org.springframework.data.relational.core.sql;
 
 /**
- * Supertype of all Abstract Syntax Tree (AST) segments. Segments are typically immutable and mutator methods return new instances instead of changing the called instance.
+ * Supertype of all Abstract Syntax Tree (AST) segments. Segments are typically immutable and mutator methods return new
+ * instances instead of changing the called instance.
  *
  * @author Mark Paluch
+ * @since 1.1
  */
 public interface Segment extends Visitable {
 
@@ -28,16 +30,16 @@ public interface Segment extends Visitable {
 	 * Equality is typically given if the {@link #toString()} representation matches.
 	 *
 	 * @param other the reference object with which to compare.
-	 * @return {@literal true} if this object is the same as the {@code other}
-	 * argument; {@literal false} otherwise.
+	 * @return {@literal true} if this object is the same as the {@code other} argument; {@literal false} otherwise.
 	 */
 	@Override
 	boolean equals(Object other);
 
 	/**
 	 * Generate a hash code from this{@link Segment}.
 	 * <p/>
-	 * Hashcode typically derives from the {@link #toString()} representation so two {@link Segment}s yield the same  {@link #hashCode()}  if their {@link #toString()}  representation matches.
+	 * Hashcode typically derives from the {@link #toString()} representation so two {@link Segment}s yield the same
+	 * {@link #hashCode()} if their {@link #toString()} representation matches.
 	 *
 	 * @return a hash code value for this object.
 	 */
@@ -47,7 +49,9 @@ public interface Segment extends Visitable {
 	/**
 	 * Return a SQL string representation of this {@link Segment}.
 	 * <p/>
-	 * The representation is intended for debugging purposes and an approximation to the generated SQL. While it might work in the context of a specific dialect, you should not that the {@link #toString()} representation works across multiple databases.
+	 * The representation is intended for debugging purposes and an approximation to the generated SQL. While it might
+	 * work in the context of a specific dialect, you should not that the {@link #toString()} representation works across
+	 * multiple databases.
 	 *
 	 * @return a SQL string representation of this {@link Segment}.
 	 */

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

@@ -18,18 +18,18 @@
 import java.util.OptionalLong;
 
 /**
- * AST for a {@code SELECT} statement.
- * Visiting order:
+ * AST for a {@code SELECT} statement. Visiting order:
  * <ol>
  * <li>Self</li>
- * <li>{@link Column SELECT columns} </li>
+ * <li>{@link Column SELECT columns}</li>
  * <li>{@link Table FROM tables} clause</li>
  * <li>{@link Join JOINs}</li>
  * <li>{@link Condition WHERE} condition</li>
  * <li>{@link OrderByField ORDER BY fields}</li>
  * </ol>
  *
  * @author Mark Paluch
+ * @since 1.1
  * @see StatementBuilder
  * @see SelectBuilder
  * @see SQL