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, TextTableWriter, TstTableBuilder, TstTableWriter, 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.

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

Method Summary

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>