# Interface DocumentedIOHandler

All Superinterfaces:
  `Documented`

All Known Implementing Classes:
  `AbstractTextTableWriter, AsciiTableBuilder, AsciiTableWriter, CsvTableBuilder, CsvTableWriter, DocumentedStreamStarTableWriter, DocumentedTableBuilder, HTMLTableWriter, IpacTableBuilder, IpacTableWriter, LatexTableWriter, MrtTableBuilder, RowEvaluatorTableBuilder, 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.

`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
Author:
  Mark Taylor

## Method Summary

Modifier and Type
Method
Description
`boolean`
`docIncludesExample()`
Indicates whether the serialization of some (short) example table should be added to the user documentation for this handler.
`String[]`
`getExtensions()`
Returns the list of filename extensions recognised by this handler.
`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.
`default String`
`readText(String resourceName)`
Utility method to read text from a resource file.
`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.

### Methods inherited from interface 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>