Package uk.ac.starlink.table
Class StarTableOutput
java.lang.Object
uk.ac.starlink.table.StarTableOutput
Outputs StarTable objects.
This object delegates the actual writing to one of a list of
format-specific writer objects whose content can be configured
externally.
By default, if the corresponding classes are present, the following
handlers are installed:
-
invalid reference
uk.ac.starlink.votable.UnifiedFitsTableWriter
-
invalid reference
uk.ac.starlink.votable.VOTableWriter
-
invalid reference
uk.ac.starlink.fits.HealpixFitsTableWriter
-
invalid reference
uk.ac.starlink.ecsv.EcsvTableWriter
-
invalid reference
uk.ac.starlink.parquet.ParquetTableWriter
-
TextTableWriter
-
AsciiTableWriter
-
CsvTableWriter
-
IpacTableWriter
-
HTMLTableWriter
-
LatexTableWriter
-
TstTableWriter
-
invalid reference
uk.ac.starlink.feather.FeatherTableWriter
-
invalid reference
uk.ac.starlink.mirage.MirageTableWriter
startable.writers
system property (as a colon-separated list) which implement the
StarTableWriter
interface and have a no-arg constructor will be
instantiated and added to this list of handlers.
It can additionally write to JDBC tables.
- Author:
- Mark Taylor (Starlink)
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Special output handler name indicating automatic format selection.static final String
System property which can contain a list ofStarTableWriter
classes for addition to the list of known output handlers. -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a StarTableOutput with a default list of handlers. -
Method Summary
Modifier and TypeMethodDescriptioncreateOutputSink
(OutputStream out, StarTableWriter handler) Returns a sink which allows you to write data to an output table.createOutputSink
(String location, String format) Returns a sink which allows you to write data to an output table.getHandler
(String format) Returns a StarTableWriter object given an output format name.getHandler
(String format, String location) Returns a StarTableWriter object given an output format name and/or a location to write to.Gets the list of handlers which can actually do table output.Returns the JDBCHandler object used for writing tables to JDBC connections.Returns a list of the format strings which are defined by the handlers registered with this object.getOutputStream
(String location) Returns an output stream which points to a given location.void
setHandlers
(StarTableWriter[] handlers) Sets the list of handlers which can actually do table output.void
setJDBCHandler
(JDBCHandler handler) Sets the JDBCHandler object used for writing tables to JDBC connections.transferStarTable
(StarTable startab) Returns aTransferable
object associated with a given StarTable, for use at the drag end of a drag and drop operation.void
writeStarTable
(StarTable startab, OutputStream out, StarTableWriter handler) Writes a StarTable to an output stream.void
writeStarTable
(StarTable startab, String location, String format) Writes aStarTable
object out to some external storage.void
writeStarTables
(StarTable[] tables, OutputStream out, MultiStarTableWriter handler) Writes an array of StarTables to an output stream.void
writeStarTables
(StarTable[] tables, String location, String format) Writes an array of StarTable objects to some external storage.
-
Field Details
-
AUTO_HANDLER
Special output handler name indicating automatic format selection.- See Also:
-
EXTRA_WRITERS_PROPERTY
System property which can contain a list ofStarTableWriter
classes for addition to the list of known output handlers.- See Also:
-
-
Constructor Details
-
StarTableOutput
public StarTableOutput()Constructs a StarTableOutput with a default list of handlers.
-
-
Method Details
-
getHandlers
Gets the list of handlers which can actually do table output. Handlers earlier in the list are given a chance to write the table before ones later in the list. The returned list may be modified to change this object's behaviour.- Returns:
- handlers a list of
StarTableWriter
objects
-
setHandlers
Sets the list of handlers which can actually do table output. Handlers earlier in the list are given a chance to write the table before ones later in the list.- Parameters:
handlers
- an array ofStarTableWriter
objects
-
writeStarTable
public void writeStarTable(StarTable startab, String location, String format) throws TableFormatException, IOException Writes aStarTable
object out to some external storage. The format in which it is written is determined by some combination of the given output location and a format indicator.- Parameters:
startab
- the table to outputlocation
- the location at which to write the new table. This may be a filename or URL, including ajdbc:
protocol if suitable JDBC drivers are installedformat
- a string which indicates in some way what format should be used for output. This may be the class name of aStarTableWriter
object (which may or may not be registered with thisStarTableOutput
), or else a string which matches the format name of one of the registeredStarTableWriter
s (first match is used, case-insensitive, starting substrings OK) ornull
orAUTO_HANDLER
to indicate that a handler should be selected based on the value oflocation
. Ignored forjdbc:
-protocol locations- Throws:
TableFormatException
- if no suitable handler is knownIOException
-
writeStarTable
public void writeStarTable(StarTable startab, OutputStream out, StarTableWriter handler) throws IOException Writes a StarTable to an output stream. This convenience method wraps the stream in a BufferedOutputStream for efficiency and uses the submittedhandler
to perform the write, closing the stream afterwards.- Parameters:
startab
- table to writeout
- raw output streamhandler
- output handler- Throws:
IOException
- See Also:
-
writeStarTables
public void writeStarTables(StarTable[] tables, String location, String format) throws TableFormatException, IOException Writes an array of StarTable objects to some external storage. The format in which they are written is determined by some combination of the given output location and a format indicator. Note that not all registered output handlers are capable of writing multiple tables; an exception will be thrown if an attempt is made to write multiple tables with a handler which does not implementMultiStarTableWriter
.- Parameters:
tables
- the tables to outputlocation
- the location at which to write the tables; this may be a filename or URLformat
- a string which indicates in some way what format should be used for output. This may be the class name of aMultiStarTableWriter
object (which may or may not be registered with thisStarTableOutput
), or else a string which matches the format name of one of the registeredMultiStarTableWriter
s (first match is used, case-insensitive, starting substrings OK) ornull
orAUTO_HANDLER
to indicate that a handler should be selected based on the value oflocation
.- Throws:
TableFormatException
IOException
-
writeStarTables
public void writeStarTables(StarTable[] tables, OutputStream out, MultiStarTableWriter handler) throws IOException Writes an array of StarTables to an output stream. This convenience method wraps the stream in a BufferedOutputStream for efficiency and uses the submittedhandler
to perform the write, closing the stream afterwards.- Parameters:
tables
- tables to writeout
- destination streamhandler
- output handler- Throws:
IOException
-
createOutputSink
Returns a sink which allows you to write data to an output table. Note that this will only work if thehandler
can write the table using a single pass of the data. If it requires multiple passes, aUnrepeatableSequenceException
will be thrown.- Parameters:
out
- raw output streamhandler
- output handler- Returns:
- sink whose data will be written to a new table
-
createOutputSink
Returns a sink which allows you to write data to an output table. Note that this will only work if thehandler
can write the table using a single pass of the data. If it requires multiple passes, aUnrepeatableSequenceException
will be thrown.- Parameters:
location
- the location at which to write the new table. This may be a filename or URL, including ajdbc:
protocol if suitable JDBC drivers are installedformat
- a string which indicates in some way what format should be used for output. This may be the class name of aStarTableWriter
object (which may or may not be registered with thisStarTableOutput
), or else a string which matches the format name of one of the registeredStarTableWriter
s (first match is used, case-insensitive, starting substrings OK) ornull
orAUTO_HANDLER
to indicate that a handler should be selected based on the value oflocation
. Ignored forjdbc:
-protocol locations- Returns:
- sink whose data will be written to a new table
-
getOutputStream
Returns an output stream which points to a given location. Typicallylocation
is a filename and a correspondingFileOutputStream
is returned, but there may be other possibilities. The stream returned by this method will not in general be buffered; for high performance writes, wrapping it in aBufferedOutputStream
may be a good idea.- Parameters:
location
- name of destination- Returns:
- output stream which writes to
location
- Throws:
IOException
- if no stream pointing tolocation
can be opened
-
getHandler
Returns a StarTableWriter object given an output format name.- Parameters:
format
- a string which indicates in some way what format should be used for output. This may be the class name of aStarTableWriter
object (which may or may not be registered with thisStarTableOutput
), or else a string which matches the format name of one of the registeredStarTableWriter
s (first match is used, case-insensitive, starting substrings OK).- Returns:
- a suitable output handler
- Throws:
TableFormatException
- if no handler suitable for the arguments can be found
-
getHandler
Returns a StarTableWriter object given an output format name and/or a location to write to. If the format name is blank, the location is used to guess the type of output required.- Parameters:
format
- a string which indicates in some way what format should be used for output. This may be the class name of aStarTableWriter
object (which may or may not be registered with thisStarTableOutput
), or else a string which matches the format name of one of the registeredStarTableWriter
s (first match is used, case-insensitive, starting substrings OK) ornull
to indicate that a handler should be selected based on the value oflocation
.location
- destination of the table to be written. Ifformat
is null, the value of this will be used to try to determine which handler to use, typically on the basis of filename extension- Returns:
- a suitable output handler
- Throws:
TableFormatException
- if no handler suitable for the arguments can be found
-
getKnownFormats
Returns a list of the format strings which are defined by the handlers registered with this object. The elements of the returned list can be passed as theformat
argument to thewriteStarTable(uk.ac.starlink.table.StarTable, java.lang.String, java.lang.String)
method. -
getJDBCHandler
Returns the JDBCHandler object used for writing tables to JDBC connections.- Returns:
- the JDBC handler
-
setJDBCHandler
Sets the JDBCHandler object used for writing tables to JDBC connections.- Parameters:
handler
- the handler to use
-
transferStarTable
Returns aTransferable
object associated with a given StarTable, for use at the drag end of a drag and drop operation.- Parameters:
startab
- the table which is to be dragged- See Also:
-