Next Previous Up Contents
Next: Generic Table Output
Up: Table I/O
Previous: Extensible I/O framework

3.2 Generic Table Input

Obtaining a table from a generic-format external source is done using a StarTableFactory. The job of this class is to keep track of which input handlers are registered and to use one of them to read data from an input stream and turn it into a StarTable. The basic rule is that you use one of the StarTableFactory's makeStarTable methods to turn what you've got (e.g. String, URL, DataSource) into a StarTable, and away you go. If no StarTable can be created (for instance because the file named doesn't exist, or because it is not in any of the supported formats) then some sort of IOException/TableFormatException will be thrown. Note that if the target stream is compressed in one of the supported formats (gzip, bzip2, Unix compress) it will be uncompressed automatically (the work for this is done by the DataSource class).

There are two distinct modes in which StarTableFactory can work: automatic format detection and named format.

In automatic format detection mode, the type of data contained in an input stream is determined by looking at it. What actually happens is that the factory hands the stream to each of the handlers in its default handler list in turn, and the first one that recognises the format (usually based on looking at the first few bytes) attempts to make a table from it. The filename is not used in any way to guess the format. This works well for formats such as FITS and VOTable that can be easily recognised, but less well for text-based formats such as comma-separated values. You can access and modify the default handler list using the getDefaultBuilders method. In this mode, you only need to specify the table location, like this:

    public StarTable loadTable( File file ) throws IOException {
        return new StarTableFactory().makeStarTable( file.toString() );
    }
Currently, only FITS and VOTable formats are auto-detected.

In named format mode, you have to specify the name of the format as well as the table location. This can be solicited from the user if it's not known at build time; the known format names can be got from the getKnownFormats method. The list of format handlers that can be used in this way can be accessed or modified using the getKnownBuilders method; it usually contains all the ones in the default handler list, but doesn't have to. Table construction in named format mode might look like this:

    public StarTable loadFitsTable( File file ) throws IOException {
        return new StarTableFactory().makeStarTable( file.toString(), "fits" );
    }

The javadocs detail variations on these calls. If you need to influence how bulk data might be cached, you can set the factory's StoragePolicy (see Section 2.3.3). If you want to ensure that the table you get provides random access (see Section 2.3), you should do something like this:

    public StarTable loadRandomTable( File file ) throws IOException {
        StarTableFactory factory = new StarTableFactory();
        factory.setRequireRandom( true );
        StarTable table = factory.makeStarTable( file.toString() );
        return table;
    }
Setting the requireRandom flag on the factory ensures that any table returned from its makeStarTable methods returns true from its isRandom method. (Note prior to STIL version 2.1 this flag only provided a hint to the factory that random tables were wanted - now it is enforced.)


Next Previous Up Contents
Next: Generic Table Output
Up: Table I/O
Previous: Extensible I/O framework

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