Next Previous Up Contents
Next: Supplied Input Handlers
Up: Table I/O
Previous: Generic Table Output

3.5 Specifying I/O Handlers

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 IOException 
could 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.


Next Previous Up Contents
Next: Supplied Input Handlers
Up: Table I/O
Previous: Generic Table Output

STIL - Starlink Tables Infrastructure Library
Starlink User Note252
STIL web page: http://www.starlink.ac.uk/stil/
Author email: m.b.taylor@bristol.ac.uk