DATAJDBC-327 - Polishing.

Extend Javadoc. Reorder constructors in the order of their parameter number. Add missing assertions. Introduce utility to create predicates. Remove unused fields. Add since tags. Reformat.

Original pull request: #123.

Author: mp911de

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/core/DefaultDataAccessStrategy.java

@@ -65,26 +65,46 @@ public class DefaultDataAccessStrategy implements DataAccessStrategy {
 	private final @NonNull NamedParameterJdbcOperations operations;
 	private final @NonNull DataAccessStrategy accessStrategy;
 
-	public DefaultDataAccessStrategy(SqlGeneratorSource sqlGeneratorSource, RelationalMappingContext context,
-			JdbcConverter converter, NamedParameterJdbcOperations operations, @Nullable DataAccessStrategy accessStrategy) {
-
-		this.sqlGeneratorSource = sqlGeneratorSource;
-		this.context = context;
-		this.converter = converter;
-		this.operations = operations;
-		this.accessStrategy = accessStrategy == null ? this : accessStrategy;
-	}
-
 	/**
 	 * Creates a {@link DefaultDataAccessStrategy} which references it self for resolution of recursive data accesses.
 	 * Only suitable if this is the only access strategy in use.
+	 *
+	 * @param sqlGeneratorSource must not be {@literal null}.
+	 * @param context must not be {@literal null}.
+	 * @param converter must not be {@literal null}.
+	 * @param operations must not be {@literal null}.
 	 */
 	public DefaultDataAccessStrategy(SqlGeneratorSource sqlGeneratorSource, RelationalMappingContext context,
 			JdbcConverter converter, NamedParameterJdbcOperations operations) {
-
 		this(sqlGeneratorSource, context, converter, operations, null);
 	}
 
+	/**
+	 * Creates a {@link DefaultDataAccessStrategy}
+	 *
+	 * @param sqlGeneratorSource must not be {@literal null}.
+	 * @param context must not be {@literal null}.
+	 * @param converter must not be {@literal null}.
+	 * @param operations must not be {@literal null}.
+	 * @param mappingAccessStrategy can be {@literal null}.
+	 * @since 1.1
+	 */
+	public DefaultDataAccessStrategy(SqlGeneratorSource sqlGeneratorSource, RelationalMappingContext context,
+			JdbcConverter converter, NamedParameterJdbcOperations operations,
+			@Nullable DataAccessStrategy mappingAccessStrategy) {
+
+		Assert.notNull(sqlGeneratorSource, "SqlGeneratorSource must not be null");
+		Assert.notNull(context, "RelationalMappingContext must not be null");
+		Assert.notNull(converter, "JdbcConverter must not be null");
+		Assert.notNull(operations, "NamedParameterJdbcOperations must not be null");
+
+		this.sqlGeneratorSource = sqlGeneratorSource;
+		this.context = context;
+		this.converter = converter;
+		this.operations = operations;
+		this.accessStrategy = mappingAccessStrategy == null ? this : mappingAccessStrategy;
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.data.jdbc.core.DataAccessStrategy#insert(java.lang.Object, java.lang.Class, java.util.Map)
@@ -104,7 +124,8 @@ public <T> Object insert(T instance, Class<T> domainType, Identifier identifier)
 		KeyHolder holder = new GeneratedKeyHolder();
 		RelationalPersistentEntity<T> persistentEntity = getRequiredPersistentEntity(domainType);
 
-		MapSqlParameterSource parameterSource = getParameterSource(instance, persistentEntity, "", PersistentProperty::isIdProperty);
+		MapSqlParameterSource parameterSource = getParameterSource(instance, persistentEntity, "",
+				PersistentProperty::isIdProperty);
 
 		identifier.forEach((name, value, type) -> addConvertedPropertyValue(parameterSource, name, value, type));
 
@@ -134,7 +155,7 @@ public <S> boolean update(S instance, Class<S> domainType) {
 		RelationalPersistentEntity<S> persistentEntity = getRequiredPersistentEntity(domainType);
 
 		return operations.update(sql(domainType).getUpdate(),
-				getParameterSource(instance, persistentEntity, "", property -> false)) != 0;
+				getParameterSource(instance, persistentEntity, "", Predicates.includeAll())) != 0;
 	}
 
 	/*
@@ -289,7 +310,7 @@ public <T> boolean existsById(Object id, Class<T> domainType) {
 	}
 
 	private <S, T> MapSqlParameterSource getParameterSource(S instance, RelationalPersistentEntity<S> persistentEntity,
-															String prefix, Predicate<RelationalPersistentProperty> skipProperty) {
+			String prefix, Predicate<RelationalPersistentProperty> skipProperty) {
 
 		MapSqlParameterSource parameters = new MapSqlParameterSource();
 
@@ -445,4 +466,19 @@ private <S> RelationalPersistentEntity<S> getRequiredPersistentEntity(Class<S> d
 	private SqlGenerator sql(Class<?> domainType) {
 		return sqlGeneratorSource.getSqlGenerator(domainType);
 	}
+
+	/**
+	 * Utility to create {@link Predicate}s.
+	 */
+	static class Predicates {
+
+		/**
+		 * Include all {@link Predicate} returning {@literal false} to never skip a property.
+		 *
+		 * @return the include all {@link Predicate}.
+		 */
+		static Predicate<RelationalPersistentProperty> includeAll() {
+			return it -> false;
+		}
+	}
 }

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/core/convert/ArrayUtil.java

@@ -21,17 +21,19 @@
  * A collection of utility methods for dealing with arrays.
  *
  * @author Jens Schauder
+ * @since 1.1
  */
 @UtilityClass
 class ArrayUtil {
 
 	/**
-	 * Convertes an {@code Byte[]} into a {@code byte[]}
-	 * @param byteArray the array to be converted. Must not be {@literal null}.
+	 * Converts an {@code Byte[]} into a {@code byte[]}.
 	 *
-	 * @return a {@code byte[]} of same size with the unboxed values of the input array. Guaranteed to be not {@literal null}.
+	 * @param byteArray the array to be converted. Must not be {@literal null}.
+	 * @return a {@code byte[]} of same size with the unboxed values of the input array. Guaranteed to be not
+	 *         {@literal null}.
 	 */
-	static Object toPrimitiveByteArray(Byte[] byteArray) {
+	static byte[] toPrimitiveByteArray(Byte[] byteArray) {
 
 		byte[] bytes = new byte[byteArray.length];
 		for (int i = 0; i < byteArray.length; i++) {

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/core/convert/BasicJdbcConverter.java

@@ -22,6 +22,7 @@
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+
 import org.springframework.core.convert.ConverterNotFoundException;
 import org.springframework.data.convert.CustomConversions;
 import org.springframework.data.jdbc.core.mapping.AggregateReference;
@@ -35,6 +36,7 @@
 import org.springframework.data.util.ClassTypeInformation;
 import org.springframework.data.util.TypeInformation;
 import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
 
 /**
  * {@link RelationalConverter} that uses a {@link MappingContext} to apply basic conversion of relational values to
@@ -54,43 +56,54 @@ public class BasicJdbcConverter extends BasicRelationalConverter implements Jdbc
 
 	private final JdbcTypeFactory typeFactory;
 
+	/**
+	 * Creates a new {@link BasicRelationalConverter} given {@link MappingContext} and a
+	 * {@link JdbcTypeFactory#unsupported() no-op type factory} throwing {@link UnsupportedOperationException} on type
+	 * creation. Use {@link #BasicJdbcConverter(MappingContext, JdbcTypeFactory)} to convert arrays and large objects into
+	 * JDBC-specific types.
+	 *
+	 * @param context must not be {@literal null}.
+	 */
+	public BasicJdbcConverter(
+			MappingContext<? extends RelationalPersistentEntity<?>, ? extends RelationalPersistentProperty> context) {
+		this(context, JdbcTypeFactory.unsupported());
+	}
+
 	/**
 	 * Creates a new {@link BasicRelationalConverter} given {@link MappingContext}.
 	 *
-	 * @param context must not be {@literal null}. org.springframework.data.jdbc.core.DefaultDataAccessStrategyUnitTests
-	 * @param typeFactory
+	 * @param context must not be {@literal null}.
+	 * @param typeFactory must not be {@literal null}
+	 * @since 1.1
 	 */
 	public BasicJdbcConverter(
 			MappingContext<? extends RelationalPersistentEntity<?>, ? extends RelationalPersistentProperty> context,
 			JdbcTypeFactory typeFactory) {
+
 		super(context);
+
+		Assert.notNull(typeFactory, "JdbcTypeFactory must not be null");
+
 		this.typeFactory = typeFactory;
 	}
 
 	/**
-	 * Creates a new {@link BasicRelationalConverter} given {@link MappingContext} and {@link CustomConversions}.
-	 * 
+	 * Creates a new {@link BasicRelationalConverter} given {@link MappingContext}, {@link CustomConversions}, and
+	 * {@link JdbcTypeFactory}.
+	 *
 	 * @param context must not be {@literal null}.
 	 * @param conversions must not be {@literal null}.
-	 * @param typeFactory
+	 * @param typeFactory must not be {@literal null}
+	 * @since 1.1
 	 */
 	public BasicJdbcConverter(
 			MappingContext<? extends RelationalPersistentEntity<?>, ? extends RelationalPersistentProperty> context,
 			CustomConversions conversions, JdbcTypeFactory typeFactory) {
+
 		super(context, conversions);
-		this.typeFactory = typeFactory;
-	}
 
-	/**
-	 * Creates a new {@link BasicRelationalConverter} given {@link MappingContext}.
-	 *
-	 * @param context must not be {@literal null}. org.springframework.data.jdbc.core.DefaultDataAccessStrategyUnitTests
-	 * @deprecated use one of the constructors with {@link JdbcTypeFactory} parameter.
-	 */
-	@Deprecated
-	public BasicJdbcConverter(
-			MappingContext<? extends RelationalPersistentEntity<?>, ? extends RelationalPersistentProperty> context) {
-		this(context, JdbcTypeFactory.unsupported());
+		Assert.notNull(typeFactory, "JdbcTypeFactory must not be null");
+		this.typeFactory = typeFactory;
 	}
 
 	/**
@@ -186,6 +199,11 @@ private boolean canWriteAsJdbcValue(@Nullable Object value) {
 		return customWriteTarget.isPresent() && customWriteTarget.get().isAssignableFrom(JdbcValue.class);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.jdbc.core.convert.JdbcConverter#writeValue(java.lang.Object, java.lang.Class, int)
+	 */
+	@Override
 	public JdbcValue writeJdbcValue(@Nullable Object value, Class<?> columnType, int sqlType) {
 
 		JdbcValue jdbcValue = tryToConvertToJdbcValue(value);
@@ -209,16 +227,15 @@ public JdbcValue writeJdbcValue(@Nullable Object value, Class<?> columnType, int
 		}
 
 		return JdbcValue.of(convertedValue, JDBCType.BINARY);
-
 	}
 
+	@Nullable
 	private JdbcValue tryToConvertToJdbcValue(@Nullable Object value) {
 
-		JdbcValue jdbcValue = null;
 		if (canWriteAsJdbcValue(value)) {
-			jdbcValue = (JdbcValue) writeValue(value, ClassTypeInformation.from(JdbcValue.class));
+			return (JdbcValue) writeValue(value, ClassTypeInformation.from(JdbcValue.class));
 		}
 
-		return jdbcValue;
+		return null;
 	}
 }

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/core/convert/DefaultJdbcTypeFactory.java

@@ -15,16 +15,17 @@
  */
 package org.springframework.data.jdbc.core.convert;
 
+import java.sql.Array;
+import java.sql.JDBCType;
+
 import org.springframework.data.jdbc.support.JdbcUtil;
 import org.springframework.jdbc.core.ConnectionCallback;
 import org.springframework.jdbc.core.JdbcOperations;
 import org.springframework.util.Assert;
 
-import java.sql.Array;
-import java.sql.JDBCType;
-
 /**
- * A {@link JdbcTypeFactory} that performs the conversion by utilizing {@link JdbcOperations#execute(ConnectionCallback)}.
+ * A {@link JdbcTypeFactory} that performs the conversion by utilizing
+ * {@link JdbcOperations#execute(ConnectionCallback)}.
  *
  * @author Jens Schauder
  * @since 1.1
@@ -33,7 +34,15 @@ public class DefaultJdbcTypeFactory implements JdbcTypeFactory {
 
 	private final JdbcOperations operations;
 
+	/**
+	 * Creates a new {@link DefaultJdbcTypeFactory}.
+	 *
+	 * @param operations must not be {@literal null}.
+	 */
 	public DefaultJdbcTypeFactory(JdbcOperations operations) {
+
+		Assert.notNull(operations, "JdbcOperations must not be null");
+
 		this.operations = operations;
 	}
 

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/core/convert/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * JDBC-specific conversion classes.
+ */
+@NonNullApi
+package org.springframework.data.jdbc.core.convert;
+
+import org.springframework.lang.NonNullApi;

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/core/package-info.java

@@ -1,3 +1,6 @@
+/**
+ * Core JDBC implementation.
+ */
 @NonNullApi
 package org.springframework.data.jdbc.core;
 

spring-data-jdbc/src/main/java/org/springframework/data/jdbc/support/JdbcUtil.java

@@ -87,7 +87,7 @@ public static int sqlTypeFor(Class<?> type) {
 
 	/**
 	 * Converts a {@link JDBCType} to an {@code int} value as defined in {@link Types}.
-	 * 
+	 *
 	 * @param jdbcType value to be converted. May be {@literal null}.
 	 * @return One of the values defined in {@link Types} or {@link JdbcUtils#TYPE_UNKNOWN}.
 	 */
@@ -98,7 +98,7 @@ public static int sqlTypeFor(@Nullable JDBCType jdbcType) {
 	/**
 	 * Converts a value defined in {@link Types} into a {@link JDBCType} instance or {@literal null} if the value is
 	 * {@link JdbcUtils#TYPE_UNKNOWN}
-	 * 
+	 *
 	 * @param sqlType One of the values defined in {@link Types} or {@link JdbcUtils#TYPE_UNKNOWN}.
 	 * @return a matching {@link JDBCType} instance or {@literal null}.
 	 */
@@ -121,7 +121,6 @@ public static JDBCType jdbcTypeFor(int sqlType) {
 	 */
 	@Nullable
 	public static JDBCType jdbcTypeFor(Class<?> type) {
-
 		return jdbcTypeFor(sqlTypeFor(type));
 	}
 }