View Javadoc
1   /*
2    * Copyright 2007 Kasper B. Graversen
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  package org.supercsv.io;
17  
18  import java.io.Closeable;
19  import java.io.IOException;
20  import java.util.List;
21  
22  import org.supercsv.exception.SuperCsvException;
23  
24  /**
25   * The interface for tokenizers, which are responsible for reading the CSV file, line by line.
26   * 
27   * @author Kasper B. Graversen
28   * @author James Bassett
29   */
30  public interface ITokenizer extends Closeable {
31  	
32  	/**
33  	 * Gets the line number currently being tokenized (the first line is line 1). This number increments at every line
34  	 * terminator as the data is read, i.e. it will be
35  	 * <ul>
36  	 * <li>0, if {@link #readColumns(List)} hasn't been called yet</li>
37  	 * <li>1, when the first line is being read/tokenized</li>
38  	 * <li>2, when the second line is being read/tokenized</li>
39  	 * </ul>
40  	 * 
41  	 * @return the line number currently being tokenized
42  	 */
43  	int getLineNumber();
44  	
45  	/**
46  	 * Returns the raw (untokenized) CSV row that was just read (which can potentially span multiple lines in the file).
47  	 * 
48  	 * @return the raw (untokenized) CSV row that was just read
49  	 * @since 2.0.0
50  	 */
51  	String getUntokenizedRow();
52  	
53  	/**
54  	 * Reads a CSV row into the supplied List of columns (which can potentially span multiple lines in the file). The
55  	 * columns list is cleared as the first operation in the method. Any empty columns ("") will be added to the list as
56  	 * <tt>null</tt>.
57  	 * 
58  	 * @param columns
59  	 *            the List of columns to read into
60  	 * @return true if something was read, or false if EOF
61  	 * @throws IOException
62  	 *             when an IOException occurs
63  	 * @throws NullPointerException
64  	 *             if columns is null
65  	 * @throws SuperCsvException
66  	 *             on errors in parsing the input
67  	 * @since 2.0.0 (was previously called readStringList)
68  	 */
69  	boolean readColumns(List<String> columns) throws IOException;
70  }