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 offer an input stream to each of them in turn, inviting them to 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 will be thrown. Note that if the target stream is compressed in one of the supported formats (gzip, bzip2, Unix compress) it should get uncompressed automatically. (the work for this is done by the DataSource class).

When acquiring a table, you should decide whether you will need to do random access on it or only sequential access (see section 2.3). A preference for one or other of these can be indicated to the StarTableFactory using its wantRandom attribute (or at construction time). This gives handlers an opportunity to return different StarTable implementations which are efficient for different patterns of access, but note it is only a hint and does not guarantee that tables generated by the factory will be random-access; see section 2.3.3 for that.

Here is a trivial example showing how to read a table file:

    public StarTable loadTable( File file ) throws IOException {
        return new StarTableFactory().makeStarTable( file.toString() );
    }
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.setWantRandom( true );
        StarTable table = factory.makeStarTable( file.toString() );
        return Tables.randomTable( table );
    }

If you want detailed control over which kinds of tables can be loaded, you can use the relevant methods of StarTableFactory to set the exact list of handlers that it uses for table resolution. Alternatively, you can always bypass StarTableFactory and use a particular TableBuilder directly.


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/