1 /*
2 * Copyright 2006-2007 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.batch.item;
18
19 /**
20 * Strategy interface for providing the data. <br/>
21 *
22 * Implementations are expected to be stateful and will be called multiple times
23 * for each batch, with each call to {@link #read()} returning a different value
24 * and finally returning <code>null</code> when all input data is exhausted.<br/>
25 *
26 * Implementations need *not* be thread safe and clients of a {@link ItemReader}
27 * need to be aware that this is the case.<br/>
28 *
29 * A richer interface (e.g. with a look ahead or peek) is not feasible because
30 * we need to support transactions in an asynchronous batch.
31 *
32 * @author Rob Harrop
33 * @author Dave Syer
34 * @author Lucas Ward
35 * @since 1.0
36 */
37 public interface ItemReader<T> {
38
39 /**
40 * Reads a piece of input data and advance to the next one. Implementations
41 * <strong>must</strong> return <code>null</code> at the end of the input
42 * data set. In a transactional setting, caller might get the same item
43 * twice from successive calls (or otherwise), if the first call was in a
44 * transaction that rolled back.
45 *
46 * @throws ParseException if there is a problem parsing the current record
47 * (but the next one may still be valid)
48 * @throws NonTransientResourceException if there is a fatal exception in
49 * the underlying resource. After throwing this exception implementations
50 * should endeavour to return null from subsequent calls to read.
51 * @throws UnexpectedInputException if there is an uncategorised problem
52 * with the input data. Assume potentially transient, so subsequent calls to
53 * read might succeed.
54 * @throws Exception if an there is a non-specific error.
55 */
56 T read() throws Exception, UnexpectedInputException, ParseException, NonTransientResourceException;
57
58 }