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
This commit is contained in:
Mahmoud Ben Hassine
@@ -13,10 +13,14 @@ include::attributes.adoc[]
|
||||
.Available Item Readers
|
||||
[options="header"]
|
||||
|===============
|
||||
|Item Reader|Description
|
||||
|Item Reader|Description|Thread-safe
|
||||
|`AbstractItemStreamItemReader`|Abstract base class that combines the `ItemStream` and `ItemReader` interfaces.|Yes
|
||||
|`AbstractItemCountingItemStreamItemReader`|Abstract base class that provides basic
|
||||
restart capabilities by counting the number of items returned from
|
||||
an `ItemReader`.
|
||||
an `ItemReader`.|No
|
||||
|`AbstractPagingItemReader`|Abstract base class that provides basic paging features|No
|
||||
|`AbstractPaginatedDataItemReader`|Abstract base class that provides basic paging features based on Spring Data's
|
||||
paginated facilities|No
|
||||
|`AggregateItemReader`|An `ItemReader` that delivers a list as its
|
||||
item, storing up objects from the injected `ItemReader` until they
|
||||
are ready to be packed out as a collection. This class must be used
|
||||
@@ -25,46 +29,49 @@ include::attributes.adoc[]
|
||||
records by returning an `AggregateItem` which responds `true` to its
|
||||
query methods (`isHeader()` and `isFooter()`). Note that this reader
|
||||
is not part of the library of readers provided by Spring Batch
|
||||
but given as a sample in `spring-batch-samples`.
|
||||
but given as a sample in `spring-batch-samples`.|Yes
|
||||
|`AmqpItemReader`|Given a Spring `AmqpTemplate`, it provides
|
||||
synchronous receive methods. The `receiveAndConvert()` method
|
||||
lets you receive POJO objects.
|
||||
lets you receive POJO objects.|Yes
|
||||
|`KafkaItemReader`|An `ItemReader` that reads messages from an Apache Kafka topic.
|
||||
It can be configured to read messages from multiple partitions of the same topic.
|
||||
This reader stores message offsets in the execution context to support restart capabilities.
|
||||
This reader stores message offsets in the execution context to support restart capabilities.|No
|
||||
|`FlatFileItemReader`|Reads from a flat file. Includes `ItemStream`
|
||||
and `Skippable` functionality. See link:readersAndWriters.html#flatFileItemReader["`FlatFileItemReader`"].
|
||||
and `Skippable` functionality. See link:readersAndWriters.html#flatFileItemReader["`FlatFileItemReader`"].|No
|
||||
|`HibernateCursorItemReader`|Reads from a cursor based on an HQL query. See
|
||||
link:readersAndWriters.html#cursorBasedItemReaders[`Cursor-based ItemReaders`].
|
||||
|`HibernatePagingItemReader`|Reads from a paginated HQL query.
|
||||
link:readersAndWriters.html#cursorBasedItemReaders[`Cursor-based ItemReaders`].|No
|
||||
|`HibernatePagingItemReader`|Reads from a paginated HQL query.|Yes
|
||||
|`ItemReaderAdapter`|Adapts any class to the
|
||||
`ItemReader` interface.
|
||||
`ItemReader` interface.|Yes
|
||||
|`JdbcCursorItemReader`|Reads from a database cursor over JDBC. See
|
||||
link:readersAndWriters.html#cursorBasedItemReaders["`Cursor-based ItemReaders`"].
|
||||
link:readersAndWriters.html#cursorBasedItemReaders["`Cursor-based ItemReaders`"].|No
|
||||
|`JdbcPagingItemReader`|Given an SQL statement, pages through the rows,
|
||||
such that large datasets can be read without running out of
|
||||
memory.
|
||||
memory.|Yes
|
||||
|`JmsItemReader`|Given a Spring `JmsOperations` object and a JMS
|
||||
destination or destination name to which to send errors, provides items
|
||||
received through the injected `JmsOperations#receive()`
|
||||
method.
|
||||
|`JpaPagingItemReader`|Given a JPQL statement, pages through the
|
||||
method.|Yes
|
||||
|`JpaCursorItemReader`|Executes a JPQL query and iterates over the returned result set|No
|
||||
|`JpaPagingItemReader`|Given a JPQL query, pages through the
|
||||
rows, such that large datasets can be read without running out of
|
||||
memory.
|
||||
|`ListItemReader`|Provides the items from a list, one at a
|
||||
time.
|
||||
memory.|Yes
|
||||
|`ListItemReader`|Provides the items from a list, one at a time.|No
|
||||
|`MongoItemReader`|Given a `MongoOperations` object and a JSON-based MongoDB
|
||||
query, provides items received from the `MongoOperations#find()` method.
|
||||
query, provides items received from the `MongoOperations#find()` method.|Yes
|
||||
|`Neo4jItemReader`|Given a `Neo4jOperations` object and the components of a
|
||||
Cyhper query, items are returned as the result of the Neo4jOperations.query
|
||||
method.
|
||||
method.|Yes
|
||||
|`RepositoryItemReader`|Given a Spring Data `PagingAndSortingRepository` object,
|
||||
a `Sort`, and the name of method to execute, returns items provided by the
|
||||
Spring Data repository implementation.
|
||||
Spring Data repository implementation.|Yes
|
||||
|`StoredProcedureItemReader`|Reads from a database cursor resulting from the
|
||||
execution of a database stored procedure. See link:readersAndWriters.html#StoredProcedureItemReader[`StoredProcedureItemReader`]
|
||||
|`StaxEventItemReader`|Reads over StAX. see link:readersAndWriters.html#StaxEventItemReader[`StaxEventItemReader`].
|
||||
|`JsonItemReader`|Reads items from a Json document. see link:readersAndWriters.html#JsonItemReader[`JsonItemReader`].
|
||||
execution of a database stored procedure. See link:readersAndWriters.html#StoredProcedureItemReader[`StoredProcedureItemReader`]|No
|
||||
|`StaxEventItemReader`|Reads over StAX. see link:readersAndWriters.html#StaxEventItemReader[`StaxEventItemReader`].|No
|
||||
|`JsonItemReader`|Reads items from a Json document. see link:readersAndWriters.html#JsonItemReader[`JsonItemReader`].|No
|
||||
|`AvroItemReader`|Reads items from a resource containing serialized Avro objects.|No
|
||||
|`LdifReader`|Reads items from a LDIF resource and returns them as `LdapAttributes`|No
|
||||
|`MappingLdifReader`|Reads items from a LDIF resource and uses a `RecordMapper` to map them to domain objects|No
|
||||
|
||||
|===============
|
||||
|
||||
@@ -75,55 +82,55 @@ This reader stores message offsets in the execution context to support restart c
|
||||
.Available Item Writers
|
||||
[options="header"]
|
||||
|===============
|
||||
|Item Writer|Description
|
||||
|`AbstractItemStreamItemWriter`|Abstract base class that combines the
|
||||
`ItemStream` and
|
||||
`ItemWriter` interfaces.
|
||||
|Item Writer|Description|Thread-safe
|
||||
|`AbstractItemStreamItemWriter`|Abstract base class that combines the`ItemStream` and`ItemWriter` interfaces.|Yes
|
||||
|`AmqpItemWriter`|Given a Spring `AmqpTemplate`, provides
|
||||
for a synchronous `send` method. The `convertAndSend(Object)`
|
||||
method lets you send POJO objects.
|
||||
method lets you send POJO objects.|Yes
|
||||
|`CompositeItemWriter`|Passes an item to the `write` method of each item
|
||||
in an injected `List` of `ItemWriter` objects.
|
||||
in an injected `List` of `ItemWriter` objects.|Yes
|
||||
|`FlatFileItemWriter`|Writes to a flat file. Includes `ItemStream` and
|
||||
Skippable functionality. See link:readersAndWriters.html#flatFileItemWriter["`FlatFileItemWriter`"].
|
||||
Skippable functionality. See link:readersAndWriters.html#flatFileItemWriter["`FlatFileItemWriter`"].|No
|
||||
|`HibernateItemWriter`|This item writer is Hibernate-session aware
|
||||
and handles some transaction-related work that a non-"`hibernate-aware`"
|
||||
item writer would not need to know about and then delegates
|
||||
to another item writer to do the actual writing.
|
||||
to another item writer to do the actual writing.|Yes
|
||||
|`ItemWriterAdapter`|Adapts any class to the
|
||||
`ItemWriter` interface.
|
||||
`ItemWriter` interface.|Yes
|
||||
|`JdbcBatchItemWriter`|Uses batching features from a
|
||||
`PreparedStatement`, if available, and can
|
||||
take rudimentary steps to locate a failure during a
|
||||
`flush`.
|
||||
`flush`.|Yes
|
||||
|`JmsItemWriter`|Using a `JmsOperations` object, items are written
|
||||
to the default queue through the `JmsOperations#convertAndSend()` method.
|
||||
to the default queue through the `JmsOperations#convertAndSend()` method.|Yes
|
||||
|`JpaItemWriter`|This item writer is JPA `EntityManager`-aware
|
||||
and handles some transaction-related work that a non-"`JPA-aware`"
|
||||
`ItemWriter` would not need to know about and
|
||||
then delegates to another writer to do the actual writing.
|
||||
then delegates to another writer to do the actual writing.|Yes
|
||||
|`KafkaItemWriter`|Using a `KafkaTemplate` object, items are written to the default topic through the
|
||||
`KafkaTemplate#sendDefault(Object, Object)` method by using a `Converter` to map the key from the item.
|
||||
A delete flag can also be configured to send delete events to the topic.
|
||||
A delete flag can also be configured to send delete events to the topic.|No
|
||||
|`MimeMessageItemWriter`|Using Spring's `JavaMailSender`, items of type `MimeMessage`
|
||||
are sent as mail messages.
|
||||
are sent as mail messages.|Yes
|
||||
|`MongoItemWriter`|Given a `MongoOperations` object, items are written
|
||||
through the `MongoOperations.save(Object)` method. The actual write is delayed
|
||||
until the last possible moment before the transaction commits.
|
||||
until the last possible moment before the transaction commits.|Yes
|
||||
|`Neo4jItemWriter`|Given a `Neo4jOperations` object, items are persisted through the
|
||||
`save(Object)` method or deleted through the `delete(Object)`, as dictated by the
|
||||
`ItemWriter's` configuration
|
||||
`ItemWriter's` configuration|Yes
|
||||
|`PropertyExtractingDelegatingItemWriter`|Extends `AbstractMethodInvokingDelegator`
|
||||
creating arguments on the fly. Arguments are created by retrieving
|
||||
the values from the fields in the item to be processed (through a
|
||||
`SpringBeanWrapper`), based on an injected array of field
|
||||
names.
|
||||
names.|Yes
|
||||
|`RepositoryItemWriter`|Given a Spring Data `CrudRepository` implementation,
|
||||
items are saved through the method specified in the configuration.
|
||||
items are saved through the method specified in the configuration.|Yes
|
||||
|`StaxEventItemWriter`|Uses a `Marshaller` implementation to
|
||||
convert each item to XML and then writes it to an XML file by using
|
||||
StAX.
|
||||
StAX.|No
|
||||
|`JsonFileItemWriter`|Uses a `JsonObjectMarshaller` implementation to
|
||||
convert each item to Json and then writes it to a Json file.
|
||||
convert each item to Json and then writes it to a Json file.|No
|
||||
|`AvroItemWriter`|Serializes data to an `WritableResource` using Avro|No
|
||||
|`ListItemWriter`|Item writer that writes items to a `List`.|No
|
||||
|
||||
|===============
|
||||
|
||||
@@ -2787,6 +2787,25 @@ When using an `ItemReader` that is not thread safe, Spring Batch offers the
|
||||
thread safe. Spring Batch provides a `SynchronizedItemStreamReaderBuilder` to construct
|
||||
an instance of the `SynchronizedItemStreamReader`.
|
||||
|
||||
For example, the `FlatFileItemReader` is *not* thread-safe and cannot be used in
|
||||
a multi-threaded step. This reader can be decorated with a `SynchronizedItemStreamReader`
|
||||
in order to use it safely in a multi-threaded step. Here is an example of how to decorate
|
||||
such a reader:
|
||||
|
||||
[source, java]
|
||||
----
|
||||
@Bean
|
||||
public SynchronizedItemStreamReader<Person> itemReader() {
|
||||
FlatFileItemReader<Person> flatFileItemReader = new FlatFileItemReaderBuilder<Person>()
|
||||
// set reader properties
|
||||
.build();
|
||||
|
||||
return new SynchronizedItemStreamReaderBuilder<Person>()
|
||||
.delegate(flatFileItemReader)
|
||||
.build();
|
||||
}
|
||||
----
|
||||
|
||||
[[singleItemPeekableItemReader]]
|
||||
===== `SingleItemPeekableItemReader`
|
||||
Spring Batch includes a decorator that adds a peek method to an `ItemReader`. This peek
|
||||
@@ -2806,6 +2825,25 @@ When using an `ItemWriter` that is not thread safe, Spring Batch offers the
|
||||
thread safe. Spring Batch provides a `SynchronizedItemStreamWriterBuilder` to construct
|
||||
an instance of the `SynchronizedItemStreamWriter`.
|
||||
|
||||
For example, the `FlatFileItemWriter` is *not* thread-safe and cannot be used in
|
||||
a multi-threaded step. This writer can be decorated with a `SynchronizedItemStreamWriter`
|
||||
in order to use it safely in a multi-threaded step. Here is an example of how to decorate
|
||||
such a writer:
|
||||
|
||||
[source, java]
|
||||
----
|
||||
@Bean
|
||||
public SynchronizedItemStreamWriter<Person> itemWriter() {
|
||||
FlatFileItemWriter<Person> flatFileItemWriter = new FlatFileItemWriterBuilder<Person>()
|
||||
// set writer properties
|
||||
.build();
|
||||
|
||||
return new SynchronizedItemStreamWriterBuilder<Person>()
|
||||
.delegate(flatFileItemWriter)
|
||||
.build();
|
||||
}
|
||||
----
|
||||
|
||||
[[multiResourceItemWriter]]
|
||||
===== `MultiResourceItemWriter`
|
||||
The `MultiResourceItemWriter` wraps a `ResourceAwareItemWriterItemStream` and creates a new
|
||||
|
||||
Reference in New Issue
Block a user