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.)