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.