uk.ac.starlink.table.formats

## Class RowEvaluatorTableBuilder

- java.lang.Object
- - uk.ac.starlink.table.formats.DocumentedTableBuilder
  - - uk.ac.starlink.table.formats.RowEvaluatorTableBuilder

- All Implemented Interfaces:
    Documented, DocumentedIOHandler, TableBuilder
  Direct Known Subclasses:
    AsciiTableBuilder, CsvTableBuilder

      public abstract class RowEvaluatorTableBuilder
      extends DocumentedTableBuilder

  Partial TableBuilder implementation for TableBuilders based on a RowEvaluator. This manages a couple of the configuration options.
  Since:
    24 Jun 2025

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `RowEvaluatorTableBuilder(java.lang.String[] extensions, java.nio.charset.Charset dfltEncoding)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `canImport(java.awt.datatransfer.DataFlavor flavor)` Indicates whether this builder is able to turn a resource of media type indicated by `flavor` into a table.
    `boolean` | `canStream()` Indicates whether this handler can read tables from a stream.
    `RowEvaluator.Decoder<?>[]` | `getDecoders()` Returns the list of permitted decoders.
    `java.nio.charset.Charset` | `getEncoding()` Returns the character encoding for the input stream.
    `int` | `getMaxSample()` Returns the maximum number of rows that will be sampled to determine column data types.
    `void` | `setDecoderExcludeList(java.lang.String excludeSemicolonList)` Sets the list of decoders from a user-supplied string naming decoders not to use.
    `void` | `setDecoders(RowEvaluator.Decoder<?>[] decoders)` Sets the list of permitted decoders.
    `void` | `setEncoding(java.nio.charset.Charset encoding)` Sets the character encoding for the input stream.
    `void` | `setMaxSample(int maxSample)` Sets the maximum number of rows that will be sampled to determine column data types.
    `void` | `streamStarTable(java.io.InputStream in, TableSink sink, java.lang.String pos)` Reads a table from an input stream and writes it a row at a time to a sink.

    - ### Methods inherited from class uk.ac.starlink.table.formats.DocumentedTableBuilder

      `getExtensions, looksLikeFile`

    - ### 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.TableBuilder

      `getFormatName, makeStarTable`

    - ### Methods inherited from interface uk.ac.starlink.table.formats.DocumentedIOHandler

      `docIncludesExample, matchesExtension, readText, toLink`

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

      `getXmlDescription`

- - ### Constructor Detail

    - #### RowEvaluatorTableBuilder

          protected RowEvaluatorTableBuilder(java.lang.String[] extensions,
                                             java.nio.charset.Charset dfltEncoding)

      Constructor.
      Parameters:
        `extensions` - list of lower-cased filename extensions, excluding the '.' character
        `dfltEncoding` - default character encoding for this format

  - ### Method Detail

    - #### canImport

          public boolean canImport(java.awt.datatransfer.DataFlavor flavor)

      Description copied from interface: `TableBuilder`
      Indicates whether this builder is able to turn a resource of media type indicated by `flavor` into a table. It should return `true` if it thinks that its `TableBuilder.streamStarTable(java.io.InputStream, uk.ac.starlink.table.TableSink, java.lang.String)` method stands a reasonable chance of successfully constructing a `StarTable` from a `DataSource` whose input stream is described by the `DataFlavor` `flavor`. It will typically make this determination based on the flavor's MIME type.

      This method should only return `true` if the flavor looks like it is targeted at this builder; for instance a builder which uses a text-based format should return false for a flavor which indicates a MIME type of `text/plain`.

      This method is used in supporting drag and drop functionality (see `StarTableFactory.canImport(java.awt.datatransfer.DataFlavor[])`).

      Parameters:
        `flavor` - the DataFlavor whose suitability as stream input is to be assessed
      Returns:
        `true` iff this builder reckons it stands a good chance of turning a stream of type `flavor` into a `StarTable`

    - #### streamStarTable

          public void streamStarTable(java.io.InputStream in,
                                      TableSink sink,
                                      java.lang.String pos)
                               throws TableFormatException

      Description copied from interface: `TableBuilder`
      Reads a table from an input stream and writes it a row at a time to a sink. Not all implementations will be able to do this; for instance, extracting the table from the data may be a two-pass process. Implementations which are unable to perform this function should throw a `TableFormatException`.

      The input stream should be prepared for use prior to calling this method, so implementations should not in general attempt to decompress or buffer `istrm`.

      Parameters:
        `in` - input stream containing table data
        `sink` - destination of the table
        `pos` - position identifier describing the location of the table within the stream; see `DataSource.getPosition()` (may be null)
      Throws:
        `TableFormatException` - if the table can't be streamed or the data is malformed

    - #### canStream

          public boolean canStream()

      Description copied from class: `DocumentedTableBuilder`
      Indicates whether this handler can read tables from a stream.
      Specified by:
        `canStream` in class `DocumentedTableBuilder`
      Returns:
        true iff this handler can read from streams

    - #### setMaxSample

          @ConfigMethod(property="maxSample",
                        doc="<p>Controls how many rows of the input file are sampled\nto determine column datatypes.\nThis file format provides no header information about\ncolumn type, so the handler has to look at the column data\nto see what type of value appears to be present\nin each column, before even starting to read the data in.\nBy default it goes through the whole table when doing this,\nwhich can be time-consuming for large tables.\nIf this value is set, it limits the number of rows\nthat are sampled in this data characterisation pass,\nwhich can reduce read time substantially.\nHowever, if values near the end of the table differ\nin apparent type from those near the start,\nit can also result in getting the datatypes wrong.\n</p>",
                        usage="<int>",
                        example="100000",
                        sequence=10)
          public void setMaxSample(int maxSample)

      Sets the maximum number of rows that will be sampled to determine column data types.
      Parameters:
        `maxSample` - maximum number of rows sampled; if <=0, all rows are sampled

    - #### getMaxSample

          public int getMaxSample()

      Returns the maximum number of rows that will be sampled to determine column data types.
      Returns:
        maximum number of rows sampled; if <=0, all rows are sampled

    - #### setEncoding

          @ConfigMethod(property="encoding",
                        usage="ASCII|UTF-8|UTF-16|...",
                        example="ASCII",
                        doc="<p>Specifies the character encoding used to interpret the input file.\n</p>")
          public void setEncoding(java.nio.charset.Charset encoding)

      Sets the character encoding for the input stream.
      Parameters:
        `encoding` - character encoding

    - #### getEncoding

          public java.nio.charset.Charset getEncoding()

      Returns the character encoding for the input stream.
      Returns:
        character encoding

    - #### setDecoders

          public void setDecoders(RowEvaluator.Decoder<?>[] decoders)

      Sets the list of permitted decoders.

      Note the order of the supplied decoder list is significant; a type earlier in the list will be preferred over one later in the list where the data is consistent with both.

      In case of no match, a string decoder will be used, even if it does not appear in the supplied list.

      Parameters:
        `decoders` - decoders that may be used to interpret CSV columns

    - #### getDecoders

          public RowEvaluator.Decoder<?>[] getDecoders()

      Returns the list of permitted decoders.
      Returns:
        decoders that may be used to interpret text columns

    - #### setDecoderExcludeList

          @ConfigMethod(property="notypes",
                        doc="<p>Specifies a semicolon-separated list of names for datatypes that will <em>not</em> appear in the columns of the table as read. Type names that can be excluded are <code>blank</code>, <code>boolean</code>, <code>short</code>, <code>int</code>, <code>long</code>, <code>float</code>, <code>double</code>, <code>date</code>, <code>hms</code> and <code>dms</code>. So if you want to make sure that all integer and floating-point columns are 64-bit (i.e. <code>long</code> and <code>double</code> respectively) you can set this value to \"<code>short;int;float</code>\".</p>",
                        usage="<type>[;<type>...]",
                        example="short;float",
                        sequence=11)
          public void setDecoderExcludeList(java.lang.String excludeSemicolonList)

      Sets the list of decoders from a user-supplied string naming decoders not to use.
      Parameters:
        `excludeSemicolonList` - semicolon-separated list of decoder names not to use