001/*
002 * Copyright 2006-2018 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.batch.item;
018
019import org.springframework.lang.Nullable;
020
021/**
022 * Strategy interface for providing the data. <br>
023 * 
024 * Implementations are expected to be stateful and will be called multiple times
025 * for each batch, with each call to {@link #read()} returning a different value
026 * and finally returning <code>null</code> when all input data is exhausted.<br>
027 * 
028 * Implementations need <b>not</b> be thread-safe and clients of a {@link ItemReader}
029 * need to be aware that this is the case.<br>
030 * 
031 * A richer interface (e.g. with a look ahead or peek) is not feasible because
032 * we need to support transactions in an asynchronous batch.
033 * 
034 * @author Rob Harrop
035 * @author Dave Syer
036 * @author Lucas Ward
037 * @author Mahmoud Ben Hassine
038 * @since 1.0
039 */
040public interface ItemReader<T> {
041
042        /**
043         * Reads a piece of input data and advance to the next one. Implementations
044         * <strong>must</strong> return <code>null</code> at the end of the input
045         * data set. In a transactional setting, caller might get the same item
046         * twice from successive calls (or otherwise), if the first call was in a
047         * transaction that rolled back.
048         * 
049         * @throws ParseException if there is a problem parsing the current record
050         * (but the next one may still be valid)
051         * @throws NonTransientResourceException if there is a fatal exception in
052         * the underlying resource. After throwing this exception implementations
053         * should endeavour to return null from subsequent calls to read.
054         * @throws UnexpectedInputException if there is an uncategorised problem
055         * with the input data. Assume potentially transient, so subsequent calls to
056         * read might succeed.
057         * @throws Exception if an there is a non-specific error.
058         * @return T the item to be processed or {@code null} if the data source is
059         * exhausted
060         */
061        @Nullable
062        T read() throws Exception, UnexpectedInputException, ParseException, NonTransientResourceException;
063
064}