001: /*
002: * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
003: * PROPRIETARY/CONFIDENTIAL. Use of this product is subject to license terms.
004: */
005: package com.sun.portal.ubt.report.data.file.parser;
006:
007: import java.io.IOException;
008:
009: /**
010: * Read files in comma separated value format.
011: */
012: public interface CSVParse {
013:
014: /**
015: * Read the next value from the file. The line number from
016: * which this value was taken can be obtained from getLastLineNumber().
017: *
018: * @return the next value or null if there are no more values.
019: * @throws IOException if an error occurs while reading.
020: *
021: */
022: public String nextValue() throws IOException;
023:
024: /**
025: * Get the line number that the last token came from.
026: *
027: * @return line number or -1 if no tokens have been returned yet.
028: *
029: */
030: public int lastLineNumber();
031:
032: /**
033: * Get all the values from a line.
034: * <p>
035: * If the line has already been partially read, only the
036: * values that have not already been read will be included.
037: *
038: * @return all the values from the line or null if there are no more values.
039: * @throws IOException if an error occurs while reading.
040: *
041: */
042: public String[] getLine() throws IOException;
043:
044: /**
045: * Get the line number that the last token came from.
046: * <p>
047: * New line breaks that occur in the middle of a token are not
048: * counted in the line number count.
049: *
050: * @return line number or -1 if no tokens have been returned yet.
051: *
052: */
053: public int getLastLineNumber();
054:
055: /**
056: * Get all the values from the file.
057: * <p>
058: * If the file has already been partially read, only the
059: * values that have not already been read will be included.
060: * <p>
061: * Each line of the file that has at least one value will be
062: * represented. Comments and empty lines are ignored.
063: * <p>
064: * The resulting double array may be jagged.
065: *
066: * @return all the values from the file or null if there are no more values.
067: * @throws IOException if an error occurs while reading.
068: *
069: */
070: public String[][] getAllValues() throws IOException;
071:
072: /**
073: * Change this parser so that it uses a new delimiter.
074: * <p>
075: * The initial character is a comma, the delimiter cannot be changed
076: * to a quote or other character that has special meaning in CSV.
077: *
078: * @param newDelim delimiter to which to switch.
079: * @throws com.sun.portal.ubt.report.data.file.parser.BadDelimiterException if the character cannot be used as a delimiter.
080: *
081: */
082: public void changeDelimiter(char newDelim)
083: throws BadDelimiterException;
084:
085: /**
086: * Change this parser so that it uses a new character for quoting.
087: * <p>
088: * The initial character is a double quote ("), the delimiter cannot be changed
089: * to a comma or other character that has special meaning in CSV.
090: *
091: * @param newQuote character to use for quoting.
092: * @throws com.sun.portal.ubt.report.data.file.parser.BadQuoteException if the character cannot be used as a quote.
093: *
094: */
095: public void changeQuote(char newQuote) throws BadQuoteException;
096:
097: /**
098: * Close any stream upon which this parser is based.
099: *
100: * @throws IOException if an error occurs while closing the stream.
101: */
102: public void close() throws IOException;
103:
104: }
|