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:
-
uk.ac.starlink.votable.FitsPlusTableWriter
-
uk.ac.starlink.fits.FitsTableWriter
-
uk.ac.starlink.fits.VariableFitsTableWriter
-
uk.ac.starlink.fits.HealpixFitsTableWriter
-
uk.ac.starlink.votable.VOTableWriter
-
uk.ac.starlink.ecsv.EcsvTableWriter
-
uk.ac.starlink.parquet.ParquetTableWriter
-
uk.ac.starlink.feather.FeatherTableWriter
-
TextTableWriter
-
AsciiTableWriter
-
CsvTableWriter
-
IpacTableWriter
-
TstTableWriter
-
uk.ac.starlink.votable.ColFitsPlusTableWriter
-
HTMLTableWriter
-
LatexTableWriter
-
uk.ac.starlink.mirage.MirageTableWriter
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 a Transferable 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 a StarTable 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 of StarTableWriter objects
-
writeStarTable
public void writeStarTable(StarTable startab, String location, String format) throws TableFormatException, IOException Writes a StarTable 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 a jdbc: 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 a StarTableWriter object (which may or may not be registered with this StarTableOutput), or else a string which matches the format name of one of the registered StarTableWriters (first match is used, case-insensitive, starting substrings OK) or null orAUTO_HANDLER
to indicate that a handler should be selected based on the value of location. Ignored for jdbc:-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 submitted handler 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 a MultiStarTableWriter object (which may or may not be registered with this StarTableOutput), or else a string which matches the format name of one of the registered MultiStarTableWriters (first match is used, case-insensitive, starting substrings OK) or null orAUTO_HANDLER
to indicate that a handler should be selected based on the value of location.- 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 submitted handler 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 a jdbc: 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 a StarTableWriter object (which may or may not be registered with this StarTableOutput), or else a string which matches the format name of one of the registered StarTableWriters (first match is used, case-insensitive, starting substrings OK) or null orAUTO_HANDLER
to indicate that a handler should be selected based on the value of location. Ignored for jdbc:-protocol locations- Returns:
- sink whose data will be written to a new table
-
getOutputStream
Returns an output stream which points to a given location. Typically location is a filename and a corresponding FileOutputStream 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 to location 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 a StarTableWriter object (which may or may not be registered with this StarTableOutput), or else a string which matches the format name of one of the registered StarTableWriters (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 a StarTableWriter object (which may or may not be registered with this StarTableOutput), or else a string which matches the format name of one of the registered StarTableWriters (first match is used, case-insensitive, starting substrings OK) or null to indicate that a handler should be selected based on the value of location.location
- destination of the table to be written. If format 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 the format 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 a Transferable 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:
-