In auto mode (if a handler name or instance is not supplied
to the input/output handler when reading/writing a table)
the I/O framework tries to guess the right handler to use,
based on file content and/or filename. This is often sufficient.
However, for both input and output the framework allows
the caller to supply explicitly a handler instance
(TableBuilder
/StarTableWriter
)
or a string identifying such an instance.
In the case of an instance, it can be constructed and configured
in the usual way using constructor arguments or mutator methods;
see the per-handler javadocs.
In the case of a String defining the handler
(e.g. methods
StarTableFactory.makeStarTable(DataSource,String)
,
StarTableOutput.writeStarTable(StarTable,String,String)
)
the basic content of the string can be
either the registered name of one of the handlers known to
the framework,
or the classname of a class having a no-arg constructor which
implements the relevant handler interface.
So for instance the content of a method to write a table in VOTable format like this:
void writeAsVOTable(StarTableOutput sto, StarTable table) throws IOExceptioncould be written in any of the following ways:
sto.writeStarTable( table, System.out, new VOTableWriter() ); sto.writeStarTable( table, "-", "votable" ); sto.writeStarTable( table, "-", "uk.ac.starlink.votable.VOTableWriter" );
However, since STIL v4, the string form may also specify handler options in parenthesis, if such options are offered by the handler in question. So for instance the following are also possible:
sto.writeStarTable( table, "-", "votable(version=V12)" ); sto.writeStarTable( table, "-", "uk.ac.starlink.votable.VOTableWriter(version=V12" );which will write VOTables conforming to version 1.1 of the VOTable handler specification. These options are comma-separated
name=value
pairs,
and the name
is mapped to bean-like configuration
methods on the handler class by use of the
@ConfigMethod
annotation. See the ConfigMethod
javadocs, and e.g. the
VOTableWriter.setVotableVersion
method for an example.
When using STIL programmatically, these string-based options are
not really required since the mutator methods can be used,
but it can be very useful if the format string has been passed in
from a user.
This configuration capability is much more flexible than the
few hard coded handler variant options that were provided in
STIL versions prior to version 4.
So e.g. "votable(format=BINARY2,inline=true)
" is now preferred to
the older form "votable-binary2-inline
",
though the older forms are retained for backward compatiblity.