Interface DocumentedIOHandler

All Superinterfaces:
Documented
All Known Implementing Classes:
AbstractTextTableWriter, AsciiTableBuilder, AsciiTableWriter, CsvTableBuilder, CsvTableWriter, DocumentedStreamStarTableWriter, DocumentedTableBuilder, HTMLTableWriter, IpacTableBuilder, IpacTableWriter, LatexTableWriter, MrtTableBuilder, TextTableWriter, TstTableBuilder, TstTableWriter, WDCTableBuilder

public interface DocumentedIOHandler extends Documented
Marker interface providing some behaviour that should be implemented by table I/O handlers to assist with auto-generating XML user documentation.

Handlers implementing this class should moreover provide the ConfigMethod annotation on all mutator methods that ought to be documented in the user documentation.

TableBuilders and StarTableWriters don't have to implement this class in order to be used for reading/writing tables, but they are expected to if they are going to be one of the handlers installed by default in the I/O controller classes and hence documented in the STIL/STILTS/TOPCAT user documentation.

Since:
21 Sept 2020
Author:
Mark Taylor
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    Indicates whether the serialization of some (short) example table should be added to the user documentation for this handler.
    Returns the list of filename extensions recognised by this handler.
    static boolean
    Utility method that returns true if the supplied filename has one of the extensions associated with a given handler (ends with a "." plus the extension), matched case-insensitively.
    default String
    readText(String resourceName)
    Utility method to read text from a resource file.
    static String
    Utility method that returns the text of an XML <A> element whose href and content are both given by a supplied URL.

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

    getXmlDescription
  • Method Details

    • getExtensions

      String[] getExtensions()
      Returns the list of filename extensions recognised by this handler.
      Returns:
      lower-cased filename extension strings, no "." characters
    • docIncludesExample

      boolean docIncludesExample()
      Indicates whether the serialization of some (short) example table should be added to the user documentation for this handler. Binary formats, or instances for which the Documented.getXmlDescription() method already includes some example output, should return false.
      Returns:
      true if the user documentation would benefit from the addition of an example serialization
    • readText

      default String readText(String resourceName)
      Utility method to read text from a resource file. UTF-8 encoding is assumed. IOExceptions are rethrown for convenience as RuntimeExceptions.
      Parameters:
      resourceName - name of resource relative to the class of this object
      Returns:
      content of resource file as a string
      Throws:
      RuntimeException - if the resource doesn't exist or something else goes wrong
    • matchesExtension

      static boolean matchesExtension(DocumentedIOHandler handler, String filename)
      Utility method that returns true if the supplied filename has one of the extensions associated with a given handler (ends with a "." plus the extension), matched case-insensitively.
      Parameters:
      handler - handler with extensions
      filename - name to test
      Returns:
      true iff filename has a recognised extension
    • toLink

      static String toLink(String url)
      Utility method that returns the text of an XML <A> element whose href and content are both given by a supplied URL.
      Parameters:
      url - URL text
      Returns:
      <a href='url'>url</a>