uk.ac.starlink.table.formats

## Class StreamStarTable

- java.lang.Object
- - uk.ac.starlink.table.AbstractStarTable
  - - uk.ac.starlink.table.formats.StreamStarTable

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, StarTable
  Direct Known Subclasses:
    AsciiStarTable, CsvStarTable

      public abstract class StreamStarTable
      extends AbstractStarTable

  Abstract superclass for tables which reads a stream of characters to obtain the row data and metadata. Since metadata is typically scarce in such tables, the strategy is to make one pass through the data attempting to work out column types etc at table initialisation time, and to make a further pass through for each required RowSequence, using the metadata obtained earlier.
  Since:
    21 Sep 2004
  See Also:
    `RowEvaluator`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static char` | `END` Char representation of -1 (as returned end-of-stream read)

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `StreamStarTable(java.nio.charset.Charset encoding)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getColumnCount()` Returns the number of columns in this table.
    `ColumnInfo` | `getColumnInfo(int icol)` Returns the object describing the data in a given column.
    `protected java.io.BufferedReader` | `getReader()` Convenience method which returns a buffered reader based on this table's data source.
    `long` | `getRowCount()` Returns the number of rows in this table, if known.
    `RowSequence` | `getRowSequence()` Returns an object which can iterate over all the rows in the table sequentially.
    `protected void` | `init(DataSource datsrc)` Initialises the table from the input stream.
    `protected abstract RowEvaluator.Metadata` | `obtainMetadata()` Obtains column metadata for this table, probably by reading through the rows once and using a RowEvaluator.
    `protected abstract java.util.List<java.lang.String>` | `readRow(java.io.BufferedReader in)` Reads the next row of data from a given stream.

    - ### Methods inherited from class uk.ac.starlink.table.AbstractStarTable

      `checkedLongToInt, close, getCell, getColumnAuxDataInfos, getName, getParameters, getRow, getRowAccess, getRowSplittable, getURL, isRandom, setName, setParameters, setURL`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface uk.ac.starlink.table.StarTable

      `getParameterByName, setParameter`

- - ### Field Detail

    - #### END

          protected static final char END

      Char representation of -1 (as returned end-of-stream read)
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### StreamStarTable

          protected StreamStarTable(java.nio.charset.Charset encoding)

      Constructor. This doesn't perform any processing; you must call `init(uk.ac.starlink.util.DataSource)` before doing anything with the constructed table. It is arranged this way so that the initialisation is able to call overridden methods in subclasses, which is a Bad thing to do from a constructor.
      Parameters:
        `encoding` - character encoding for reading the input stream

  - ### Method Detail

    - #### init

          protected void init(DataSource datsrc)
                       throws TableFormatException,
                              java.io.IOException

      Initialises the table from the input stream. This method calls `obtainMetadata()`, which probably reads through some or all of the stream.
      Parameters:
        `datsrc` - data source from which the stream can be obtained
      Throws:
        `TableFormatException`
        `java.io.IOException`

    - #### getColumnCount

          public int getColumnCount()

      Description copied from interface: `StarTable`
      Returns the number of columns in this table.
      Specified by:
        `getColumnCount` in interface `StarTable`
      Specified by:
        `getColumnCount` in class `AbstractStarTable`
      Returns:
        the number of columns

    - #### getRowCount

          public long getRowCount()

      Description copied from interface: `StarTable`
      Returns the number of rows in this table, if known. If the number of rows cannot be (easily) determined, a value of -1 will be returned.
      Specified by:
        `getRowCount` in interface `StarTable`
      Specified by:
        `getRowCount` in class `AbstractStarTable`
      Returns:
        the number of rows, or -1

    - #### getColumnInfo

          public ColumnInfo getColumnInfo(int icol)

      Description copied from interface: `StarTable`
      Returns the object describing the data in a given column.
      Specified by:
        `getColumnInfo` in interface `StarTable`
      Specified by:
        `getColumnInfo` in class `AbstractStarTable`
      Parameters:
        `icol` - the column for which header information is required
      Returns:
        a ValueInfo object for column `icol`

    - #### getRowSequence

          public RowSequence getRowSequence()
                                     throws java.io.IOException

      Description copied from interface: `StarTable`
      Returns an object which can iterate over all the rows in the table sequentially. Each such returned object is safe for use within a single thread, but not in general from multiple threads concurrently.
      Specified by:
        `getRowSequence` in interface `StarTable`
      Specified by:
        `getRowSequence` in class `AbstractStarTable`
      Returns:
        new RowSequence
      Throws:
        `java.io.IOException` - if there is an error providing access

    - #### getReader

          protected java.io.BufferedReader getReader()
                                              throws java.io.IOException

      Convenience method which returns a buffered reader based on this table's data source.
      Returns:
        input stream containing source data
      Throws:
        `java.io.IOException`

    - #### obtainMetadata

          protected abstract RowEvaluator.Metadata obtainMetadata()
                                                           throws TableFormatException,
                                                                  java.io.IOException

      Obtains column metadata for this table, probably by reading through the rows once and using a RowEvaluator.
      Returns:
        information about the table represented by the character stream
      Throws:
        `TableFormatException` - if the data doesn't represent this kind of table
        `java.io.IOException` - if I/O error is encountered

    - #### readRow

          protected abstract java.util.List<java.lang.String> readRow(java.io.BufferedReader in)
                                                               throws TableFormatException,
                                                                      java.io.IOException

      Reads the next row of data from a given stream. Ignorable rows are skipped; comments may be stashed away.
      Parameters:
        `in` - input stream
      Returns:
        list of Strings one for each cell in the row, or `null` for end of stream
      Throws:
        `TableFormatException` - if the data doesn't represent this kind of table
        `java.io.IOException` - if I/O error is encountered