Package uk.ac.starlink.table.formats

Class AbstractTextTableWriter

java.lang.Object
uk.ac.starlink.table.formats.DocumentedStreamStarTableWriter
uk.ac.starlink.table.formats.AbstractTextTableWriter
All Implemented Interfaces:
Documented, DocumentedIOHandler, StarTableWriter
Direct Known Subclasses:
AsciiTableWriter, IpacTableWriter, TextTableWriter
public abstract class AbstractTextTableWriter extends DocumentedStreamStarTableWriter
A StarTableWriter which outputs text to a human-readable text file. Table parameters (per-table metadata) can optionally be output as well as the table data themselves.
Author:
Mark Taylor (Starlink)

  • Constructor Details

    • AbstractTextTableWriter

      protected AbstractTextTableWriter(String[] extensions, boolean writeParams)
      Constructor.
      Parameters:
      extensions - list of lower-cased filename extensions, excluding the '.' character
      writeParams - whether parameters will be written by default

  • Method Details

    • getFormatName

      public String getFormatName()
      Returns "text";
      Returns:
      "text"

    • getMimeType

      public String getMimeType()
      Description copied from interface: StarTableWriter
      Returns a string suitable for use as the value of a MIME Content-Type header. If no suitable MIME type is available or known, one of "application/octet-stream" (for binary formats) or "text/plain" for ASCII ones) is recommended.
      Returns:
      MIME content type

    • writeStarTable

      public void writeStarTable(StarTable startab, OutputStream strm) throws IOException
      Description copied from interface: StarTableWriter
      Writes a StarTable object to a given output stream. The implementation can assume that out is suitable for direct writing (for instance it should not normally wrap it in a BufferedOutputStream), and should not close it at the end of the call.

      Not all table writers are capable of writing to a stream; an implementation may throw a TableFormatException to indicate that it cannot do so.

      Parameters:
      startab - the table to write
      strm - the output stream to which startab should be written
      Throws:
      TableFormatException - if this table cannot be written to a stream
      IOException - if there is some I/O error

    • setMaximumParameterLength

      @ConfigMethod(property="maxParam", doc="<p>Maximum width in characters of an output table parameter. Parameters with values longer than this will be truncated.</p>") public void setMaximumParameterLength(int maxParamLength)
      Sets the maximum length for the value of a parameter that will be output.
      Parameters:
      maxParamLength - maximum printable parameter length

    • getMaximumParameterLength

      public int getMaximumParameterLength()
      Returns the maximum length for the value of a parameter as passed to printParam(java.io.OutputStream, java.lang.String, java.lang.String, java.lang.Class<?>). The default implementation currently returns 160.
      Returns:
      maximum length for output string parameters

    • setWriteParameters

      @ConfigMethod(property="params", doc="<p>Whether to output table parameters as well as row data.</p>") public void setWriteParameters(boolean writeParams)
      Set whether the output should include table parameters. If so they are written as name:value pairs one per line before the start of the table proper.
      Parameters:
      writeParams - true iff you want table parameters to be output as well as the table data

    • getWriteParameters

      public boolean getWriteParameters()
      Finds out whether the output will include table parameters.
      Returns:
      true iff the table parameters will be output as well as the table data

    • setMaxWidth

      @ConfigMethod(property="maxCell", doc="<p>Maximum width in characters of an output table cell. Cells longer than this will be truncated.</p>") public void setMaxWidth(int maxWidth)
      Sets the maximum width in characters for any output column. Values longer than this may be truncated.
      Parameters:
      maxWidth - maximum column value width in characters

    • getMaxWidth

      public int getMaxWidth()
      Returns the maximum width for any output column. Values longer than this may be truncated.
      Returns:
      maximum permitted column width in characters

    • getMinNameWidth

      public int getMinNameWidth(ColumnInfo info)
      Returns the minimum width required to output the actual characters of the name for a given column. Padding applied subsequently by this object's printColumnHeads(java.io.OutputStream, int[], uk.ac.starlink.table.ColumnInfo[]) method does not need to be included.
      Parameters:
      info - column metadata
      Returns:
      minimum number of characters required for column title

    • setSampledRows

      @ConfigMethod(property="sampledRows", doc="<p>The number of rows examined on a first pass of the table to determine the width of each column. Only a representative number of rows needs to be examined, but if a formatted cell value after this limit is wider than the cells up to it, then such later wide cells may get truncated. If the value is &lt;=0, all rows are examined in the first pass; this is the default, but it can be configured to some other value if that takes too long.</p>") public void setSampledRows(int sampledRows)
      Sets the number of rows which will be sampled before output is commenced to work out the column widths.
      Parameters:
      sampledRows - number of rows to be sampled

    • getSampledRows

      public int getSampledRows()
      Returns the number of rows which will be sampled to work out the column width.
      Returns:
      number of rows scanned

    • formatValue

      protected abstract String formatValue(Object val, ValueInfo vinfo, int width)
      Formats a data value for output.
      Parameters:
      val - the value
      vinfo - the metadata object describing val's type
      width - maximum preferred width into which the value should be formatted
      Returns:
      formatted string meaning value, preferably no longer than width characters

    • printSeparator

      protected abstract void printSeparator(OutputStream strm, int[] colwidths) throws IOException
      Outputs a decorative separator line, of the sort you might find between the column headings and the table data.
      Parameters:
      strm - stream to write into
      colwidths - column widths in characters
      Throws:
      IOException

    • printColumnHeads

      protected abstract void printColumnHeads(OutputStream strm, int[] colwidths, ColumnInfo[] cinfos) throws IOException
      Outputs headings for the table columns.
      Parameters:
      strm - stream to write into
      colwidths - column widths in characters
      cinfos - array of column headings
      Throws:
      IOException

    • printLine

      protected abstract void printLine(OutputStream strm, int[] colwidths, String[] data) throws IOException
      Outputs a line of table data.
      Parameters:
      strm - stream to write into
      colwidths - column widths in characters
      data - array of strings to be output, one per column
      Throws:
      IOException

    • printParam

      protected abstract void printParam(OutputStream strm, String name, String value, Class<?> clazz) throws IOException
      Outputs a parameter and its value.
      Parameters:
      strm - stream to write into
      name - parameter name
      value - formatted parameter value
      clazz - type of value
      Throws:
      IOException

    • getBytes

      protected byte[] getBytes(String str)
      Returns a byte array corresponding to a given string.
      Parameters:
      str - string to decode