Document thread-safety of item readers and writers

This commit also adds a sample of how to use the synchronized decorators of item readers and writers. Resolves #3646
2023-05-09 11:45:57 +02:00
parent 118be5e002
commit 2374a5ac11
22 changed files with 187 additions and 61 deletions
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/adapter/ItemReaderAdapter.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/adapter/ItemReaderAdapter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2019 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -23,6 +23,11 @@ import org.springframework.lang.Nullable;
 * Invokes a custom method on a delegate plain old Java object which itself provides an
 * item.
 *
+ * <p>
+ * This adapter is thread-safe as long as the delegate <code>ItemReader</code> is
+ * thread-safe.
+ * </p>
+ *
 * @author Robert Kasanicky
 */
 public class ItemReaderAdapter<T> extends AbstractMethodInvokingDelegator<T> implements ItemReader<T> {
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/adapter/ItemWriterAdapter.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/adapter/ItemWriterAdapter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2022 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -23,6 +23,11 @@ import org.springframework.batch.item.ItemWriter;
 * Delegates item processing to a custom method - passes the item as an argument for the
 * delegate method.
 *
+ * <p>
+ * This adapter is thread-safe as long as the delegate <code>ItemWriter</code> is
+ * thread-safe.
+ * </p>
+ *
 * @see PropertyExtractingDelegatingItemWriter
 * @author Robert Kasanicky
 * @author Mahmoud Ben Hassine
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/adapter/PropertyExtractingDelegatingItemWriter.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/adapter/PropertyExtractingDelegatingItemWriter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2022 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -29,6 +29,11 @@ import org.springframework.util.ObjectUtils;
 * Delegates processing to a custom method - extracts property values from item object and
 * uses them as arguments for the delegate method.
 *
+ * <p>
+ * This writer is thread-safe as long as the delegate <code>ItemWriter</code> is
+ * thread-safe.
+ * </p>
+ *
 * @see ItemWriterAdapter
 * @author Robert Kasanicky
 * @author Mahmoud Ben Hassine
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/amqp/AmqpItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/amqp/AmqpItemReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2019 the original author or authors.
+ * Copyright 2012-2023 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,11 @@ import org.springframework.util.Assert;
 * convert messages.
 * </p>
 *
+ * <p>
+ * This reader is thread-safe as long as the delegate <code>AmqpTemplate</code>
+ * implementation is thread-safe.
+ * </p>
+ *
 * @author Chris Schaefer
 * @author Mahmoud Ben Hassine
 */
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/amqp/AmqpItemWriter.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/amqp/AmqpItemWriter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2023 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.
@@ -31,6 +31,11 @@ import org.springframework.util.Assert;
 * {@link AmqpTemplate}.
 * </p>
 *
+ * <p>
+ * This writer is thread-safe as long as the delegate <code>AmqpTemplate</code>
+ * implementation is thread-safe.
+ * </p>
+ *
 * @author Chris Schaefer
 * @author Mahmoud Ben Hassine
 */
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/avro/AvroItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/avro/AvroItemReader.java
@@ -41,6 +41,10 @@ import org.springframework.util.ClassUtils;
 * An {@link ItemReader} that deserializes data from a {@link Resource} containing
 * serialized Avro objects.
 *
+ * <p>
+ * This reader is <b>not</b> thread-safe.
+ * </p>
+ *
 * @author David Turanski
 * @author Mahmoud Ben Hassine
 * @author Song JaeGeun
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/avro/AvroItemWriter.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/avro/AvroItemWriter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2022 the original author or authors.
+ * Copyright 2019-2023 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.
@@ -44,6 +44,10 @@ import org.springframework.util.Assert;
 *
 * This does not support restart on failure.
 *
+ * <p>
+ * This writer is <b>not</b> thread-safe.
+ * </p>
+ *
 * @since 4.2
 * @author David Turanski
 * @author Mahmoud Ben Hassine
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/data/AbstractPaginatedDataItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/data/AbstractPaginatedDataItemReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2013-2019 the original author or authors.
+ * Copyright 2013-2023 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,8 +28,11 @@ import java.util.Iterator;
 * Spring Data's paginated facilities. It also handles the semantics required for
 * restartability based on those facilities.
 *
+ * This reader is <b>not</b> thread-safe.
+ *
 * @author Michael Minella
 * @author Glenn Renfro
+ * @author Mahmoud Ben Hassine
 * @since 2.2
 * @param <T> Type of item to be read
 */
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/AbstractCursorItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/AbstractCursorItemReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2022 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -101,6 +101,10 @@ import org.springframework.util.Assert;
 * position verification is not available for 'TYPE_FORWARD_ONLY' result sets.
 * </p>
 *
+ * <p>
+ * Subclasses are inherently <b>not</b> thread-safe.
+ * </p>
+ *
 * @author Lucas Ward
 * @author Peter Zozom
 * @author Robert Kasanicky
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/AbstractPagingItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/AbstractPagingItemReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2022 the original author or authors.
+ * Copyright 2006-2023 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,8 +36,11 @@ import org.springframework.util.ClassUtils;
 * position.
 * </p>
 *
+ * This reader is <b>not</b> thread-safe.
+ *
 * @author Thomas Risberg
 * @author Dave Syer
+ * @author Mahmoud Ben Hassine
 * @since 2.0
 */
 public abstract class AbstractPagingItemReader<T> extends AbstractItemCountingItemStreamItemReader<T>
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/JdbcCursorItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/JdbcCursorItemReader.java
@@ -47,6 +47,10 @@ import org.springframework.util.ClassUtils;
 * ResultSet.
 * </p>
 *
+ * <p>
+ * This reader is <b>not</b> thread-safe.
+ * </p>
+ *
 * @author Lucas Ward
 * @author Peter Zozom
 * @author Robert Kasanicky
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/StoredProcedureItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/StoredProcedureItemReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2022 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -55,6 +55,10 @@ import org.springframework.util.ClassUtils;
 * This class is modeled after the similar <code>JdbcCursorItemReader</code> class.
 * </p>
 *
+ * <p>
+ * This reader is <b>not</b> thread-safe.
+ * </p>
+ *
 * @author Thomas Risberg
 * @author Mahmoud Ben Hassine
 */
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/file/FlatFileItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/file/FlatFileItemReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2022 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -43,6 +43,10 @@ import org.springframework.util.StringUtils;
 * rethrown as {@link FlatFileParseException} adding information about the problematic
 * line and its line number.
 *
+ * <p>
+ * This reader is <b>not</b> thread-safe.
+ * </p>
+ *
 * @author Robert Kasanicky
 * @author Mahmoud Ben Hassine
 */
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/ldif/LdifReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/ldif/LdifReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2005-2022 the original author or authors.
+ * Copyright 2005-2023 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.
@@ -55,7 +55,12 @@ import org.springframework.util.ClassUtils;
 * or not to require the resource to exist before processing. In the case of a value set
 * to false, a warning is logged instead of an exception being thrown.
 *
+ * <p>
+ * This reader is <b>not</b> thread-safe.
+ * </p>
+ *
 * @author Keith Barlow
+ * @author Mahmoud Ben Hassine
 *
 */
 public class LdifReader extends AbstractItemCountingItemStreamItemReader<LdapAttributes>
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/ldif/MappingLdifReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/ldif/MappingLdifReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2005-2022 the original author or authors.
+ * Copyright 2005-2023 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.
@@ -46,7 +46,12 @@ import org.springframework.util.ClassUtils;
 * or not to require the resource to exist before processing. In the case of a value set
 * to false, a warning is logged instead of an exception being thrown.
 *
+ * <p>
+ * This reader is <b>not</b> thread-safe.
+ * </p>
+ *
 * @author Keith Barlow
+ * @author Mahmoud Ben Hassine
 *
 */
 public class MappingLdifReader<T> extends AbstractItemCountingItemStreamItemReader<T>
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/mail/javamail/MimeMessageItemWriter.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/mail/javamail/MimeMessageItemWriter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2022 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -50,7 +50,7 @@ import org.springframework.util.Assert;
 * </p>
 *
 * <p>
- * Stateless, so automatically restartable.
+ * This writer is stateless, therefore it is thread-safe and automatically restartable.
 * </p>
 *
 * @author Dave Syer
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/support/AbstractItemStreamItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/support/AbstractItemStreamItemReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2007 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -23,7 +23,10 @@ import org.springframework.batch.item.ItemStreamSupport;
 /**
 * Base class for {@link ItemReader} implementations.
 *
+ * This abstract reader is thread-safe.
+ *
 * @author Dave Syer
+ * @author Mahmoud Ben Hassine
 *
 */
 public abstract class AbstractItemStreamItemReader<T> extends ItemStreamSupport implements ItemStreamReader<T> {
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/support/AbstractItemStreamItemWriter.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/support/AbstractItemStreamItemWriter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2007 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -23,7 +23,10 @@ import org.springframework.batch.item.ItemWriter;
 /**
 * Base class for {@link ItemWriter} implementations.
 *
+ * This abstract writer is thread-safe.
+ *
 * @author Dave Syer
+ * @author Mahmoud Ben Hassine
 *
 */
 public abstract class AbstractItemStreamItemWriter<T> extends ItemStreamSupport implements ItemStreamWriter<T> {
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/support/ListItemReader.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/support/ListItemReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2021 the original author or authors.
+ * Copyright 2006-2023 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.
@@ -26,6 +26,10 @@ import org.springframework.lang.Nullable;
 /**
 * An {@link ItemReader} that pulls data from a list. Useful for testing.
 *
+ * <p>
+ * This reader is <b>not</b> thread-safe.
+ * </p>
+ *
 * @author Dave Syer
 * @author jojoldu
 *
--- a/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/support/ListItemWriter.java
+++ b/spring-batch-infrastructure/src/main/java/org/springframework/batch/item/support/ListItemWriter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2022 the original author or authors.
+ * Copyright 2014-2023 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.
@@ -22,6 +22,12 @@ import java.util.ArrayList;
 import java.util.List;

 /**
+ * Item writer that writes items to a <code>List</code>.
+ *
+ * <p>
+ * This writer is <b>not</b> thread-safe.
+ * </p>
+ *
 * @author mminella
 * @author Mahmoud Ben Hassine
 */