Add documentation, update license headers, and update class headers.

Author: ctailor2

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2021 the original author or authors.
+ * Copyright 2020-2022 the original author or authors.
  *
  * 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 @@
  *
  * @author Jens Schauder
  * @author Myeonghyeon Lee
+ * @author Chirag Tailor
  * @since 2.0
  */
 class AggregateChangeExecutor {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2021 the original author or authors.
+ * Copyright 2019-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -53,6 +53,7 @@
  * @author Jens Schauder
  * @author Umut Erturk
  * @author Myeonghyeon Lee
+ * @author Chirag Tailor
  */
 class JdbcAggregateChangeExecutionContext {
 

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

@@ -1,7 +1,34 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.
+ */
 package org.springframework.data.jdbc.core.convert;
 
 import org.springframework.jdbc.core.namedparam.SqlParameterSource;
 
+/**
+ * Strategy for executing a batch insert.
+ *
+ * @author Chirag Tailor
+ */
 interface BatchInsertStrategy {
+
+	/**
+	 * @param sql the insert sql. Must not be {@code null}.
+	 * @param sqlParameterSources the sql parameters for each record to be inserted. Must not be {@code null}.
+	 * @return the ids corresponding to each record that was inserted, if ids were generated. If ids were not generated,
+	 *         elements will be {@code null}.
+	 */
 	Object[] execute(String sql, SqlParameterSource[] sqlParameterSources);
 }

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

@@ -1,3 +1,18 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.
+ */
 package org.springframework.data.jdbc.core.convert;
 
 import org.springframework.jdbc.core.BatchPreparedStatementSetter;
@@ -14,6 +29,7 @@
 import org.springframework.jdbc.support.JdbcUtils;
 import org.springframework.jdbc.support.KeyHolder;
 import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
 
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
@@ -22,21 +38,53 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Counterpart to {@link org.springframework.jdbc.core.namedparam.NamedParameterJdbcOperations} containing
+ * methods for performing batch updates with generated keys.
+ *
+ * @author Chirag Tailor
+ */
 public class BatchJdbcOperations {
 	private final JdbcOperations jdbcOperations;
 
 	public BatchJdbcOperations(JdbcOperations jdbcOperations) {
 		this.jdbcOperations = jdbcOperations;
 	}
 
-	@Nullable
+	/**
+	 * Execute a batch using the supplied SQL statement with the batch of supplied arguments,
+	 * returning generated keys.
+	 * @param sql the SQL statement to execute
+	 * @param batchArgs the array of {@link SqlParameterSource} containing the batch of
+	 * arguments for the query
+	 * @param generatedKeyHolder a {@link KeyHolder} that will hold the generated keys
+	 * @return an array containing the numbers of rows affected by each update in the batch
+	 * (may also contain special JDBC-defined negative values for affected rows such as
+	 * {@link java.sql.Statement#SUCCESS_NO_INFO}/{@link java.sql.Statement#EXECUTE_FAILED})
+	 * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
+	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
+	 */
 	int[] batchUpdate(String sql, SqlParameterSource[] batchArgs, KeyHolder generatedKeyHolder) {
 		return batchUpdate(sql, batchArgs, generatedKeyHolder, null);
 	}
 
-	@Nullable
+	/**
+	 * Execute a batch using the supplied SQL statement with the batch of supplied arguments,
+	 * returning generated keys.
+	 * @param sql the SQL statement to execute
+	 * @param batchArgs the array of {@link SqlParameterSource} containing the batch of
+	 * arguments for the query
+	 * @param generatedKeyHolder a {@link KeyHolder} that will hold the generated keys
+	 * @param keyColumnNames names of the columns that will have keys generated for them
+	 * @return an array containing the numbers of rows affected by each update in the batch
+	 * (may also contain special JDBC-defined negative values for affected rows such as
+	 * {@link java.sql.Statement#SUCCESS_NO_INFO}/{@link java.sql.Statement#EXECUTE_FAILED})
+	 * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
+	 * @see org.springframework.jdbc.support.GeneratedKeyHolder
+	 */
 	public int[] batchUpdate(String sql, SqlParameterSource[] batchArgs, KeyHolder generatedKeyHolder,
-			String[] keyColumnNames) {
+			@Nullable String[] keyColumnNames) {
+
 		if (batchArgs.length == 0) {
 			return new int[0];
 		}
@@ -89,10 +137,13 @@ public int getBatchSize() {
 				return rowsAffectedArray;
 			}
 		};
-		return jdbcOperations.execute(psc, preparedStatementCallback);
+		int[] result = jdbcOperations.execute(psc, preparedStatementCallback);
+		Assert.state(result != null, "No result array");
+		return result;
 	}
 
 	private PreparedStatementCallback<Void> storeGeneratedKeys(KeyHolder generatedKeyHolder) {
+
 		return ps -> {
 			List<Map<String, Object>> generatedKeys = generatedKeyHolder.getKeyList();
 			generatedKeys.clear();

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2021 the original author or authors.
+ * Copyright 2017-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -35,6 +35,7 @@
  * @author Tyler Van Gorder
  * @author Milan Milanov
  * @author Myeonghyeon Lee
+ * @author Chirag Tailor
  * @since 1.1
  */
 public class CascadingDataAccessStrategy implements DataAccessStrategy {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2021 the original author or authors.
+ * Copyright 2019-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -36,25 +36,37 @@
  * @author Tyler Van Gorder
  * @author Milan Milanov
  * @author Myeonghyeon Lee
+ * @author Chirag Tailor
  */
 public interface DataAccessStrategy extends RelationResolver {
 
 	/**
-	 * Inserts a the data of a single entity. Referenced entities don't get handled.
+	 * Inserts the data of a single entity. Referenced entities don't get handled.
 	 *
 	 * @param <T> the type of the instance.
 	 * @param instance the instance to be stored. Must not be {@code null}.
 	 * @param domainType the type of the instance. Must not be {@code null}.
 	 * @param identifier information about data that needs to be considered for the insert but which is not part of the
 	 *          entity. Namely references back to a parent entity and key/index columns for entities that are stored in a
 	 *          {@link Map} or {@link List}.
-	 * @param includeId
+	 * @param includeId an indicator of whether the insert includes the id.
 	 * @return the id generated by the database if any.
 	 * @since 1.1
 	 */
 	@Nullable
 	<T> Object insert(T instance, Class<T> domainType, Identifier identifier, boolean includeId);
 
+	/**
+	 * Inserts the data of a multiple entities.
+	 *
+	 * @param <T> the type of the instance.
+	 * @param insertSubjects the subjects to be inserted, where each subject contains the instance and its identifier.
+	 *          Must not be {@code null}.
+	 * @param domainType the type of the instance. Must not be {@code null}.
+	 * @param includeId an indicator of whether the insert includes the id.
+	 * @return the ids corresponding to each record that was inserted, if ids were generated. If ids were not generated,
+	 *         elements will be {@code null}.
+	 */
 	<T> Object[] insert(List<InsertSubject<T>> insertSubjects, Class<T> domainType, boolean includeId);
 
 	/**

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2021 the original author or authors.
+ * Copyright 2017-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -54,6 +54,7 @@
  * @author Myeonghyeon Lee
  * @author Yunyoung LEE
  * @author Radim Tlusty
+ * @author Chirag Tailor
  * @since 1.1
  */
 public class DefaultDataAccessStrategy implements DataAccessStrategy {
@@ -75,8 +76,8 @@ public class DefaultDataAccessStrategy implements DataAccessStrategy {
 	 * @since 1.1
 	 */
 	public DefaultDataAccessStrategy(SqlGeneratorSource sqlGeneratorSource, RelationalMappingContext context,
-			JdbcConverter converter, NamedParameterJdbcOperations operations, SqlParametersFactory sqlParametersFactory, 
-									 InsertStrategyFactory insertStrategyFactory) {
+			JdbcConverter converter, NamedParameterJdbcOperations operations, SqlParametersFactory sqlParametersFactory,
+			InsertStrategyFactory insertStrategyFactory) {
 		Assert.notNull(sqlGeneratorSource, "SqlGeneratorSource must not be null");
 		Assert.notNull(context, "RelationalMappingContext must not be null");
 		Assert.notNull(converter, "JdbcConverter must not be null");

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2017-2021 the original author or authors.
+ * Copyright 2017-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -32,6 +32,7 @@
  * @author Tyler Van Gorder
  * @author Milan Milanov
  * @author Myeonghyeon Lee
+ * @author Chirag Tailor
  * @since 1.1
  */
 public class DelegatingDataAccessStrategy implements DataAccessStrategy {
@@ -44,7 +45,7 @@ public class DelegatingDataAccessStrategy implements DataAccessStrategy {
 	 */
 	@Override
 	public <T> Object insert(T instance, Class<T> domainType, Identifier identifier, boolean includeId) {
-		return delegate.insert(instance, domainType, identifier, false);
+		return delegate.insert(instance, domainType, identifier, includeId);
 	}
 
 	@Override

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

@@ -1,3 +1,18 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.
+ */
 package org.springframework.data.jdbc.core.convert;
 
 import java.util.Arrays;
@@ -12,6 +27,12 @@
 import org.springframework.jdbc.support.GeneratedKeyHolder;
 import org.springframework.lang.Nullable;
 
+/**
+ * A {@link BatchInsertStrategy} that expects ids to be generated from the batch insert. When the {@link Dialect} does
+ * not support id generation for batch operations, this implementation falls back to performing the inserts serially.
+ *
+ * @author Chirag Tailor
+ */
 class IdGeneratingBatchInsertStrategy implements BatchInsertStrategy {
 
 	private final InsertStrategy insertStrategy;
@@ -68,6 +89,7 @@ public Object[] execute(String sql, SqlParameterSource[] sqlParameterSources) {
 	}
 
 	private String[] getKeyColumnNames() {
+
 		return Optional.ofNullable(idColumn)
 				.map(idColumn -> new String[]{idColumn.getReference(dialect.getIdentifierProcessing())})
 				.orElse(new String[0]);

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

@@ -1,3 +1,18 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.
+ */
 package org.springframework.data.jdbc.core.convert;
 
 import org.springframework.dao.DataRetrievalFailureException;
@@ -14,6 +29,11 @@
 import java.util.Map;
 import java.util.Optional;
 
+/**
+ * An {@link InsertStrategy} that expects an id to be generated from the insert.
+ *
+ * @author Chirag Tailor
+ */
 class IdGeneratingInsertStrategy implements InsertStrategy {
 
 	private final Dialect dialect;

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

@@ -1,9 +1,36 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.
+ */
 package org.springframework.data.jdbc.core.convert;
 
 import org.springframework.jdbc.core.namedparam.SqlParameterSource;
 import org.springframework.lang.Nullable;
 
+/**
+ * Strategy for executing an insert.
+ *
+ * @author Chirag Tailor
+ */
 interface InsertStrategy {
+
+	/**
+	 * @param sql the insert sql. Must not be {@code null}.
+	 * @param sqlParameterSource the sql parameters for the record to be inserted. Must not be {@code null}.
+	 * @return the id corresponding to the record that was inserted, if one was generated. If an id was not generated,
+	 *         this will be {@code null}.
+	 */
 	@Nullable
 	Object execute(String sql, SqlParameterSource sqlParameterSource);
 }