uk.ac.starlink.table

## Class StarTableOutput

- java.lang.Object
- - uk.ac.starlink.table.StarTableOutput

-     public class StarTableOutput
      extends java.lang.Object

  Outputs StarTable objects. This object delegates the actual writing to one of a list of format-specific writer objects whose content can be configured externally. By default, if the corresponding classes are present, the following handlers are installed:
  - `FitsPlusTableWriter`
  - `FitsTableWriter`
  - `VariableFitsTableWriter`
  - `HealpixFitsTableWriter`
  - `VOTableWriter`
  - `EcsvTableWriter`
  - `ParquetTableWriter`
  - `FeatherTableWriter`
  - `TextTableWriter`
  - `AsciiTableWriter`
  - `CsvTableWriter`
  - `IpacTableWriter`
  - `TstTableWriter`
  - `ColFitsPlusTableWriter`
  - `HTMLTableWriter`
  - `LatexTableWriter`
  - `MirageTableWriter`
  Additionally, any classes named in the `startable.writers` system property (as a colon-separated list) which implement the `StarTableWriter` interface and have a no-arg constructor will be instantiated and added to this list of handlers.

  It can additionally write to JDBC tables.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `AUTO_HANDLER` Special output handler name indicating automatic format selection.
    `static java.lang.String` | `EXTRA_WRITERS_PROPERTY` System property which can contain a list of `StarTableWriter` classes for addition to the list of known output handlers.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StarTableOutput()` Constructs a StarTableOutput with a default list of handlers.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `TableSink` | `createOutputSink(java.io.OutputStream out, StarTableWriter handler)` Returns a sink which allows you to write data to an output table.
    `TableSink` | `createOutputSink(java.lang.String location, java.lang.String format)` Returns a sink which allows you to write data to an output table.
    `StarTableWriter` | `getHandler(java.lang.String format)` Returns a StarTableWriter object given an output format name.
    `StarTableWriter` | `getHandler(java.lang.String format, java.lang.String location)` Returns a StarTableWriter object given an output format name and/or a location to write to.
    `java.util.List<StarTableWriter>` | `getHandlers()` Gets the list of handlers which can actually do table output.
    `JDBCHandler` | `getJDBCHandler()` Returns the JDBCHandler object used for writing tables to JDBC connections.
    `java.util.List<java.lang.String>` | `getKnownFormats()` Returns a list of the format strings which are defined by the handlers registered with this object.
    `java.io.OutputStream` | `getOutputStream(java.lang.String location)` Returns an output stream which points to a given location.
    `void` | `setHandlers(StarTableWriter[] handlers)` Sets the list of handlers which can actually do table output.
    `void` | `setJDBCHandler(JDBCHandler handler)` Sets the JDBCHandler object used for writing tables to JDBC connections.
    `java.awt.datatransfer.Transferable` | `transferStarTable(StarTable startab)` Returns a `Transferable` object associated with a given StarTable, for use at the drag end of a drag and drop operation.
    `void` | `writeStarTable(StarTable startab, java.io.OutputStream out, StarTableWriter handler)` Writes a StarTable to an output stream.
    `void` | `writeStarTable(StarTable startab, java.lang.String location, java.lang.String format)` Writes a `StarTable` object out to some external storage.
    `void` | `writeStarTables(StarTable[] tables, java.io.OutputStream out, MultiStarTableWriter handler)` Writes an array of StarTables to an output stream.
    `void` | `writeStarTables(StarTable[] tables, java.lang.String location, java.lang.String format)` Writes an array of StarTable objects to some external storage.

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

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

- - ### Field Detail

    - #### AUTO_HANDLER

          public static final java.lang.String AUTO_HANDLER

      Special output handler name indicating automatic format selection.
      See Also:
        Constant Field Values

    - #### EXTRA_WRITERS_PROPERTY

          public static final java.lang.String EXTRA_WRITERS_PROPERTY

      System property which can contain a list of `StarTableWriter` classes for addition to the list of known output handlers.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### StarTableOutput

          public StarTableOutput()

      Constructs a StarTableOutput with a default list of handlers.

  - ### Method Detail

    - #### getHandlers

          public java.util.List<StarTableWriter> getHandlers()

      Gets the list of handlers which can actually do table output. Handlers earlier in the list are given a chance to write the table before ones later in the list. The returned list may be modified to change this object's behaviour.
      Returns:
        handlers a list of `StarTableWriter` objects

    - #### setHandlers

          public void setHandlers(StarTableWriter[] handlers)

      Sets the list of handlers which can actually do table output. Handlers earlier in the list are given a chance to write the table before ones later in the list.
      Parameters:
        `handlers` - an array of `StarTableWriter` objects

    - #### writeStarTable

          public void writeStarTable(StarTable startab,
                                     java.lang.String location,
                                     java.lang.String format)
                              throws TableFormatException,
                                     java.io.IOException

      Writes a `StarTable` object out to some external storage. The format in which it is written is determined by some combination of the given output location and a format indicator.
      Parameters:
        `startab` - the table to output
        `location` - the location at which to write the new table. This may be a filename or URL, including a `jdbc:` protocol if suitable JDBC drivers are installed
        `format` - a string which indicates in some way what format should be used for output. This may be the class name of a `StarTableWriter` object (which may or may not be registered with this `StarTableOutput`), or else a string which matches the format name of one of the registered `StarTableWriter`s (first match is used, case-insensitive, starting substrings OK) or `null` or `AUTO_HANDLER` to indicate that a handler should be selected based on the value of `location`. Ignored for `jdbc:`-protocol locations
      Throws:
        `TableFormatException` - if no suitable handler is known
        `java.io.IOException`

    - #### writeStarTable

          public void writeStarTable(StarTable startab,
                                     java.io.OutputStream out,
                                     StarTableWriter handler)
                              throws java.io.IOException

      Writes a StarTable to an output stream. This convenience method wraps the stream in a BufferedOutputStream for efficiency and uses the submitted `handler` to perform the write, closing the stream afterwards.
      Parameters:
        `startab` - table to write
        `out` - raw output stream
        `handler` - output handler
      Throws:
        `java.io.IOException`
      See Also:
        `getHandler(java.lang.String)`

    - #### writeStarTables

          public void writeStarTables(StarTable[] tables,
                                      java.lang.String location,
                                      java.lang.String format)
                               throws TableFormatException,
                                      java.io.IOException

      Writes an array of StarTable objects to some external storage. The format in which they are written is determined by some combination of the given output location and a format indicator. Note that not all registered output handlers are capable of writing multiple tables; an exception will be thrown if an attempt is made to write multiple tables with a handler which does not implement `MultiStarTableWriter`.
      Parameters:
        `tables` - the tables to output
        `location` - the location at which to write the tables; this may be a filename or URL
        `format` - a string which indicates in some way what format should be used for output. This may be the class name of a `MultiStarTableWriter` object (which may or may not be registered with this `StarTableOutput`), or else a string which matches the format name of one of the registered `MultiStarTableWriter`s (first match is used, case-insensitive, starting substrings OK) or `null` or `AUTO_HANDLER` to indicate that a handler should be selected based on the value of `location`.
      Throws:
        `TableFormatException`
        `java.io.IOException`

    - #### writeStarTables

          public void writeStarTables(StarTable[] tables,
                                      java.io.OutputStream out,
                                      MultiStarTableWriter handler)
                               throws java.io.IOException

      Writes an array of StarTables to an output stream. This convenience method wraps the stream in a BufferedOutputStream for efficiency and uses the submitted `handler` to perform the write, closing the stream afterwards.
      Parameters:
        `tables` - tables to write
        `out` - destination stream
        `handler` - output handler
      Throws:
        `java.io.IOException`

    - #### createOutputSink

          public TableSink createOutputSink(java.io.OutputStream out,
                                            StarTableWriter handler)

      Returns a sink which allows you to write data to an output table. Note that this will only work if the `handler` can write the table using a single pass of the data. If it requires multiple passes, a `UnrepeatableSequenceException` will be thrown.
      Parameters:
        `out` - raw output stream
        `handler` - output handler
      Returns:
        sink whose data will be written to a new table

    - #### createOutputSink

          public TableSink createOutputSink(java.lang.String location,
                                            java.lang.String format)

      Returns a sink which allows you to write data to an output table. Note that this will only work if the `handler` can write the table using a single pass of the data. If it requires multiple passes, a `UnrepeatableSequenceException` will be thrown.
      Parameters:
        `location` - the location at which to write the new table. This may be a filename or URL, including a `jdbc:` protocol if suitable JDBC drivers are installed
        `format` - a string which indicates in some way what format should be used for output. This may be the class name of a `StarTableWriter` object (which may or may not be registered with this `StarTableOutput`), or else a string which matches the format name of one of the registered `StarTableWriter`s (first match is used, case-insensitive, starting substrings OK) or `null` or `AUTO_HANDLER` to indicate that a handler should be selected based on the value of `location`. Ignored for `jdbc:`-protocol locations
      Returns:
        sink whose data will be written to a new table

    - #### getOutputStream

          public java.io.OutputStream getOutputStream(java.lang.String location)
                                               throws java.io.IOException

      Returns an output stream which points to a given location. Typically `location` is a filename and a corresponding `FileOutputStream` is returned, but there may be other possibilities. The stream returned by this method will not in general be buffered; for high performance writes, wrapping it in a `BufferedOutputStream` may be a good idea.
      Parameters:
        `location` - name of destination
      Returns:
        output stream which writes to `location`
      Throws:
        `java.io.IOException` - if no stream pointing to `location` can be opened

    - #### getHandler

          public StarTableWriter getHandler(java.lang.String format)
                                     throws TableFormatException

      Returns a StarTableWriter object given an output format name.
      Parameters:
        `format` - a string which indicates in some way what format should be used for output. This may be the class name of a `StarTableWriter` object (which may or may not be registered with this `StarTableOutput`), or else a string which matches the format name of one of the registered `StarTableWriter`s (first match is used, case-insensitive, starting substrings OK).
      Returns:
        a suitable output handler
      Throws:
        `TableFormatException` - if no handler suitable for the arguments can be found

    - #### getHandler

          public StarTableWriter getHandler(java.lang.String format,
                                            java.lang.String location)
                                     throws TableFormatException

      Returns a StarTableWriter object given an output format name and/or a location to write to. If the format name is blank, the location is used to guess the type of output required.
      Parameters:
        `format` - a string which indicates in some way what format should be used for output. This may be the class name of a `StarTableWriter` object (which may or may not be registered with this `StarTableOutput`), or else a string which matches the format name of one of the registered `StarTableWriter`s (first match is used, case-insensitive, starting substrings OK) or `null` to indicate that a handler should be selected based on the value of `location`.
        `location` - destination of the table to be written. If `format` is null, the value of this will be used to try to determine which handler to use, typically on the basis of filename extension
      Returns:
        a suitable output handler
      Throws:
        `TableFormatException` - if no handler suitable for the arguments can be found

    - #### getKnownFormats

          public java.util.List<java.lang.String> getKnownFormats()

      Returns a list of the format strings which are defined by the handlers registered with this object. The elements of the returned list can be passed as the `format` argument to the `writeStarTable(uk.ac.starlink.table.StarTable, java.lang.String, java.lang.String)` method.

    - #### getJDBCHandler

          public JDBCHandler getJDBCHandler()

      Returns the JDBCHandler object used for writing tables to JDBC connections.
      Returns:
        the JDBC handler

    - #### setJDBCHandler

          public void setJDBCHandler(JDBCHandler handler)

      Sets the JDBCHandler object used for writing tables to JDBC connections.
      Parameters:
        `handler` - the handler to use

    - #### transferStarTable

          public java.awt.datatransfer.Transferable transferStarTable(StarTable startab)

      Returns a `Transferable` object associated with a given StarTable, for use at the drag end of a drag and drop operation.
      Parameters:
        `startab` - the table which is to be dragged
      See Also:
        `StarTableFactory.makeStarTable(java.awt.datatransfer.Transferable)`