uk.ac.starlink.table.formats

## Interface DocumentedIOHandler

- All Superinterfaces:
    Documented
  All Known Implementing Classes:
    AbstractTextTableWriter, AsciiTableBuilder, AsciiTableWriter, CdfTableBuilder, ColFitsPlusTableWriter, ColFitsTableBuilder, CsvTableBuilder, CsvTableWriter, DocumentedStreamStarTableWriter, DocumentedTableBuilder, EcsvTableBuilder, EcsvTableWriter, FeatherTableBuilder, FeatherTableWriter, FitsPlusTableWriter, FitsTableBuilder, GbinTableBuilder, HapiTableBuilder, HTMLTableWriter, IpacTableBuilder, IpacTableWriter, LatexTableWriter, MirageTableWriter, MrtTableBuilder, ParquetTableBuilder, ParquetTableWriter, Pds4TableBuilder, RowEvaluatorTableBuilder, TextTableWriter, TstTableBuilder, TstTableWriter, UnifiedFitsTableWriter, UnifiedFitsTableWriter.Col, VerTableBuilder, VOTableBuilder, VOTableWriter, 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.

  `TableBuilder`s and `StarTableWriter`s 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

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `docIncludesExample()` Indicates whether the serialization of some (short) example table should be added to the user documentation for this handler.
    `java.lang.String[]` | `getExtensions()` Returns the list of filename extensions recognised by this handler.
    `static boolean` | `matchesExtension(DocumentedIOHandler handler, java.lang.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.
    `default java.lang.String` | `readText(java.lang.String resourceName)` Utility method to read text from a resource file.
    `static java.lang.String` | `toLink(java.lang.String url)` 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 Detail

    - #### getExtensions

          java.lang.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 java.lang.String readText(java.lang.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:
        `java.lang.RuntimeException` - if the resource doesn't exist or something else goes wrong

    - #### matchesExtension

          static boolean matchesExtension(DocumentedIOHandler handler,
                                          java.lang.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 java.lang.String toLink(java.lang.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>