# Package uk.ac.starlink.votable

Classes for VOTable input and output.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  TableHandler | SAX-like handler which defines callbacks that can be made when a VOTable data is encountered during a SAX stream.
  TabularData | Contains the actual cell contents of a VOTable TABLE element.

- Class Summary
  Class | Description
  --- | ---
  ColFitsPlusTableBuilder | Implementation of the `TableBuilder` interface which reads tables stored in column-oriented FITS binary table format.
  ColFitsPlusTableWriter | Handles writing of a `StarTable` in a column-oriented FITS binary table format.
  DataFormat | Class of objects representing the different serialization formats into which VOTable cell data can be written.
  FieldElement | Table column characteristics represented by a FIELD element in a VOTable.
  FieldRefElement | Object representing a FIELDref element.
  FitsPlusTableBuilder | Table builder which can read files in 'fits-plus' format (as written by `FitsPlusTableWriter`).
  FitsPlusTableWriter | TableWriter which writes table data into the first extension of a FITS file, Unlike `FitsTableWriter` however, the primary extension is not left contentless, instead it gets the text of a DATA-less VOTable written into it.
  GroupElement | Object representing a GROUP element in a VOTable.
  LinkElement | Object representing a LINK element in a VOTable.
  Namespacing | Determines how namespaces are handled in VOTable documents.
  ParamElement | Object representing a PARAM element in a VOTable.
  ParamRefElement | Object representing a PARAMref element.
  TableContentHandler | Content handler which translates SAX events into table events.
  TableElement | An object representing the TABLE element of a VOTable.
  TimesysElement | Element subclass for a TIMESYS element in a VOTable.
  ValuesElement | Field or Param value restriction set represented by a VALUES element in a VOTable.
  VODocument | Document implementation which holds a VOTable-specific DOM.
  VOElement | Element implementation for use within VOTable documents.
  VOElementFactory | Provides methods for constructing VOElements from a variety of sources.
  VOSerializer | Class which knows how to serialize a table's fields and data to VOTable elements.
  VOStarTable | A `StarTable` implementation based on a VOTable.
  VOTableBuilder | Implementation of the `TableBuilder` interface which gets `StarTable`s from VOTable documents.
  VOTableDOMBuilder | Custom DOM builder for parsing VOTable documents or fragments.
  VOTableFitsTableWriter | TableWriter which writes table data into the first extension of a FITS file, Unlike `FitsTableWriter` however, the primary extension is not left contentless, instead it gets the text of a DATA-less VOTable written into it.
  VOTableVersion | Provides characteristics for a given version of the VOTable standard.
  VOTableWriter | Implementation of the `StarTableWriter` interface for VOTables.

## Package uk.ac.starlink.votable Description

Classes for VOTable input and output.

Elements in the VOTable DTD are represented by instances of `VOElement` or one of its subclasses. Not every VOTable element has a corresponding class, but the generic facilities of `VOElement` can still be used for navigation if required. In general a subclass of `VOElement` is provided in those cases for which functionality beyond that given by the `DelegatingElement.getAttribute(java.lang.String)` and `VOElement.getChildren()` is required.

The usual way of using these classes to read a VOTable document would be to use one of the static `makeVOElement` methods in `VOElementFactory` to construct a top-level VOElement from a file, URL, input stream, DOM or whatever and then to interrogate this element for its children to find the elements of interest (e.g. TABLE elements).

A hybrid SAX/DOM parsing scheme is used, so that if a parse is done by this library (when using one of the non-DOM constructors of VOElement or one of its subclasses) bulk data is not represented in the resulting DOM. In the case of TABLEDATA encoding, this means that the (potentially large) number of TR and TD nodes are parsed directly using SAX and never introduced into the DOM. In the case of FITS or BINARY encoding in which the data is base64-encoded inline in the STREAM element, this element is read and converted into table data during the parse, and the screed of base64 text is not included in the DOM. The user doesn't have to worry about all this of course, but it has the effect that the parsing is fast and as memory-efficient as possible. If the parsing has already been done (a DOMSource constructor is used to construct the VOElement instances) the library will use the text data in DOM nodes which exist in the presented DOM (it will not excise them from the given DOM).

## Implementation Status

These classes support (with a very few exceptions) to the VOTable DTD version 1.0. All three defined data implementations (TABLEDATA, FITS and BINARY) are fully supported for input and output.

See Also:
  STIL