Package uk.ac.starlink.table.formats
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.TableBuilder
s andStarTableWriter
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
All Methods Static Methods Instance Methods Abstract Methods Default Methods 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.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 theDocumented.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 extensionsfilename
- 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>
-
-