public class StarTableFactory
extends java.lang.Object
StarTable
objects from generic inputs.
This factory delegates the actual table creation to external
TableBuilder
objects, each of which knows how to read a
particular table format. Various makeStarTable methods
are offered, which construct StarTables from different
types of object, such as URL
and
DataSource
. Each of these comes in
two types: automatic format detection and named format.
In the case of a named format, a specifier must be given for the format in which the table to be read is held. This may be one of the following:
AUTO_HANDLER
-
in this case automatic format detection is used.
In the case of automatic format detection (no format specified), the factory hands the table location to each of the handlers in the default handler list in turn, and if any of them can make a table out of it, it is returned.
In either case, failure to make a table will usually result in a TableFormatException, though if an error in actual I/O is encountered an IOException may be thrown instead.
By default, if the corresponding classes are present, the following TableBuilders are installed in the default handler list (used by default in automatic format detection):
uk.ac.starlink.votable.FitsPlusTableBuilder
(format name="fits-plus")
uk.ac.starlink.votable.ColFitsPlusTableBuilder
(format name="colfits-plus")
uk.ac.starlink.fits.ColFitsTableBuilder
(format name="colfits-basic")
uk.ac.starlink.fits.FitsTableBuilder
(format name="fits")
uk.ac.starlink.votable.VOTableBuilder
(format name="votable")
uk.ac.starlink.cdf.CdfTableBuilder
(format name="cdf")
The following additional handlers are installed in the known handler list (not used by default but available by specifying the format name):
AsciiTableBuilder
(format name="ascii")
CsvTableBuilder
(format name="csv")
TstTableBuilder
(format name="tst")
IpacTableBuilder
(format name="ipac")
uk.ac.starlink.gbin.GbinTableBuilder
(format name="gbin")
WDCTableBuilder
(format name="wdc")
TableBuilder
interface and have a no-arg
constructor will be instantiated and added to the known handler list.
The factory has a flag requireRandom which determines whether the makeStarTable methods are guaranteed to return tables which provide random access (StarTable.isRandom()==true). NOTE the meaning (and name) of this flag has changed as of STIL version 2.1. Previously it was only a hint that random tables were preferred. Now setting it true guarantees that all tables returned by the factory are random.
Modifier and Type | Field | Description |
---|---|---|
static java.lang.String |
AUTO_HANDLER |
Special handler identifier which signifies automatic format detection.
|
static java.lang.String |
KNOWN_BUILDERS_PROPERTY |
System property which can contain a list of
TableBuilder classes
for addition to the known (non-automatically detected) handler list. |
Constructor | Description |
---|---|
StarTableFactory() |
Constructs a StarTableFactory with a default list of builders
which is not guaranteed to construct random-access tables.
|
StarTableFactory(boolean requireRandom) |
Constructs a StarTableFactory with a default list of builders
specifying whether it will return random-access tables.
|
StarTableFactory(StarTableFactory fact) |
Constructs a StarTableFactory which is a copy of an existing one.
|
Modifier and Type | Method | Description |
---|---|---|
boolean |
canImport(java.awt.datatransfer.DataFlavor[] flavors) |
Indicates whether a particular set of DataFlavor ojects
offered by a
Transferable
is suitable for attempting to turn the Transferable
into a StarTable. |
java.util.List |
getDefaultBuilders() |
Gets the list of builders which are used for automatic format detection.
|
JDBCHandler |
getJDBCHandler() |
Returns the JDBC handler object used by this factory.
|
java.util.List |
getKnownBuilders() |
Gets the list of builders which are available for selection by
format name.
|
java.util.List |
getKnownFormats() |
Returns the list of format names, one for each of the handlers returned
by
getKnownBuilders() . |
TablePreparation |
getPreparation() |
Returns the current table preparation object, if any.
|
StoragePolicy |
getStoragePolicy() |
Returns the current storage policy.
|
TableBuilder |
getTableBuilder(java.lang.String name) |
Returns a table handler with a given name.
|
StarTable |
makeStarTable(java.awt.datatransfer.Transferable trans) |
Constructs a StarTable from a
Transferable object
using automatic format detection. |
StarTable |
makeStarTable(java.io.InputStream in,
TableBuilder builder) |
Attempts to read and return a StarTable from an input stream.
|
StarTable |
makeStarTable(java.lang.String location) |
Constructs a readable StarTable from a location string
using automatic format detection.
|
StarTable |
makeStarTable(java.lang.String location,
java.lang.String handler) |
Constructs a readable StarTable from a location string
using a named table input handler.
|
StarTable |
makeStarTable(java.net.URL url) |
Deprecated.
Use
makeStarTable(new URLDataSource(url)) |
StarTable |
makeStarTable(java.net.URL url,
java.lang.String handler) |
Deprecated.
Use
makeStarTable(new URLDataSource(url),handler) |
StarTable |
makeStarTable(uk.ac.starlink.util.DataSource datsrc) |
Constructs a readable StarTable from a DataSource
object using automatic format detection.
|
StarTable |
makeStarTable(uk.ac.starlink.util.DataSource datsrc,
java.lang.String handler) |
Constructs a readable StarTable from a DataSource
using a named table input handler.
|
TableSequence |
makeStarTables(java.lang.String location,
java.lang.String handler) |
Constructs a sequence of StarTables from a location string
using a named table input handler.
|
TableSequence |
makeStarTables(uk.ac.starlink.util.DataSource datsrc) |
Constructs a sequence of StarTables from a DataSource using automatic
format detection.
|
TableSequence |
makeStarTables(uk.ac.starlink.util.DataSource datsrc,
java.lang.String handler) |
Constructs a sequence of StarTables from a DataSource using a named
table input handler.
|
StarTable |
randomTable(StarTable table) |
Returns a table based on a given table and guaranteed to have
random access.
|
boolean |
requireRandom() |
Returns the requireRandom flag.
|
void |
setDefaultBuilders(TableBuilder[] builders) |
Sets the list of builders which actually do the table construction.
|
void |
setJDBCHandler(JDBCHandler handler) |
Sets the JDBC handler object used by this factory.
|
void |
setKnownBuilders(TableBuilder[] builders) |
Sets the list of builders which are available for selection by
format name.
|
void |
setPreparation(TablePreparation tablePrep) |
Sets a table preparation object that is invoked on each table
created by this factory.
|
void |
setRequireRandom(boolean requireRandom) |
Sets whether random-access tables will be constructed by this factory.
|
void |
setStoragePolicy(StoragePolicy policy) |
Sets the storage policy.
|
public static final java.lang.String KNOWN_BUILDERS_PROPERTY
TableBuilder
classes
for addition to the known (non-automatically detected) handler list.public static final java.lang.String AUTO_HANDLER
public StarTableFactory()
public StarTableFactory(boolean requireRandom)
requireRandom
- whether random-access tables will be constructedpublic StarTableFactory(StarTableFactory fact)
fact
- instance to copypublic java.util.List getDefaultBuilders()
TableBuilder
objects used to
construct StarTablespublic void setDefaultBuilders(TableBuilder[] builders)
builders
- an array of TableBuilder objects used to
construct StarTablespublic java.util.List getKnownBuilders()
TableBuilder
objects which may be
specified for table buildingpublic void setKnownBuilders(TableBuilder[] builders)
builders
- an array of TableBuilder objects used to
construct StarTablespublic java.util.List getKnownFormats()
getKnownBuilders()
.public void setRequireRandom(boolean requireRandom)
StarTable.isRandom()
method will
return true). If the flag is false, then returned
tables may or may not be random-access.requireRandom
- whether this factory will create
random-access tablespublic boolean requireRandom()
StarTable.isRandom()
method will
return true). If the flag is false, then returned
tables may or may not be random-access.public void setStoragePolicy(StoragePolicy policy)
policy
- the new storage policy objectpublic StoragePolicy getStoragePolicy()
StoragePolicy.getDefaultPolicy()
).public void setPreparation(TablePreparation tablePrep)
tablePrep
- new table preparation, or nullpublic TablePreparation getPreparation()
public StarTable randomTable(StarTable table) throws java.io.IOException
This convenience method is equivalent to getStoragePolicy().randomTable(table).
table
- original tablejava.io.IOException
public StarTable makeStarTable(uk.ac.starlink.util.DataSource datsrc) throws TableFormatException, java.io.IOException
datsrc
- the data source containing the table dataTableFormatException
- if none of the default handlers
could turn datsrc into a tablejava.io.IOException
- if an I/O error is encounteredpublic TableSequence makeStarTables(uk.ac.starlink.util.DataSource datsrc) throws TableFormatException, java.io.IOException
MultiTableBuilder
will be capable of returning
a sequence having more than one element.datsrc
- the data source containing the table datadatsrc
TableFormatException
- if none of the default handlers
could turn datsrc into a tablejava.io.IOException
- if an I/O error is encounteredpublic StarTable makeStarTable(java.lang.String location) throws TableFormatException, java.io.IOException
location
- the name of the table resourceTableFormatException
- if no handler capable of turning
location into a table is availablejava.io.IOException
- if one of the handlers encounters an error
constructing a tablepublic StarTable makeStarTable(java.net.URL url) throws java.io.IOException
makeStarTable(new URLDataSource(url))
url
- the URL where the table livesTableFormatException
- if no handler capable of turning
datsrc into a table is availablejava.io.IOException
- if one of the handlers encounters an error
constructing a tablepublic StarTable makeStarTable(uk.ac.starlink.util.DataSource datsrc, java.lang.String handler) throws TableFormatException, java.io.IOException
TableBuilder.getFormatName()
method)
or by giving the full class name of the handler. In the latter
case this factory does not need to have been informed about the
handler previously. If null or the empty string or
the special value AUTO_HANDLER
is
supplied for handler, it will fall back on automatic
format detection.datsrc
- the data source containing the table datahandler
- specifier for the handler which can handle tables
of the right formatTableFormatException
- if datsrc does not contain
a table in the format named by handlerjava.io.IOException
- if an I/O error is encounteredpublic TableSequence makeStarTables(uk.ac.starlink.util.DataSource datsrc, java.lang.String handler) throws TableFormatException, java.io.IOException
TableBuilder.getFormatName()
method)
or by giving the full class name of the handler. In the latter
case this factory does not need to have been informed about the
handler previously. If null or the empty string or
the special value AUTO_HANDLER
is
supplied for handler, it will fall back on automatic
format detection.
If the handler does not implement the MultiTableBuilder
interface, then the returned sequence will contain a single table.
datsrc
- the data source containing the table datahandler
- specifier for the handler which can handle tables
of the right formatTableFormatException
- if datsrc does not contain
a table in the format named by handlerjava.io.IOException
- if an I/O error is encounteredpublic TableSequence makeStarTables(java.lang.String location, java.lang.String handler) throws TableFormatException, java.io.IOException
TableBuilder.getFormatName()
method)
or by giving the full class name of the handler. In the latter
case this factory does not need to have been informed about the
handler previously. If null or the empty string or
the special value AUTO_HANDLER
is
supplied for handler, it will fall back on automatic
format detection.location
- the name of the table resourcehandler
- specifier for the handler which can handle tables
of the right formatTableFormatException
- if location does not point to
a table in the format named by handlerjava.io.IOException
- if an I/O error is encounteredpublic StarTable makeStarTable(java.lang.String location, java.lang.String handler) throws TableFormatException, java.io.IOException
TableBuilder.getFormatName()
method)
or by giving the full class name of the handler. In the latter
case this factory does not need to have been informed about the
handler previously. If null or the empty string or
the special value AUTO_HANDLER
is
supplied for handler, it will fall back on automatic
format detection. A location of "-" means standard input - in
this case the handler must be specified.location
- the name of the table resourcehandler
- specifier for the handler which can handle tables
of the right formatTableFormatException
- if location does not point to
a table in the format named by handlerjava.io.IOException
- if an I/O error is encounteredpublic StarTable makeStarTable(java.net.URL url, java.lang.String handler) throws TableFormatException, java.io.IOException
makeStarTable(new URLDataSource(url),handler)
TableBuilder.getFormatName()
method)
or by giving the full class name of the handler. In the latter
case this factory does not need to have been informed about the
handler previously. If null or the empty string or
the special value AUTO_HANDLER
is
supplied for handler, it will fall back on automatic
format detection.url
- the URL where the table liveshandler
- specifier for the handler which can handle tables
of the right formatTableFormatException
- if the resource at url cannot
be turned into a table by handlerjava.io.IOException
- if an I/O error is encounteredpublic StarTable makeStarTable(java.io.InputStream in, TableBuilder builder) throws TableFormatException, java.io.IOException
in
- input streambuilder
- handler which understands the data in inTableFormatException
- if builder
needs more
than one pass of the data, or the stream is in some way
malformedjava.io.IOException
- for other I/O errorsTableBuilder.streamStarTable(java.io.InputStream, uk.ac.starlink.table.TableSink, java.lang.String)
public StarTable makeStarTable(java.awt.datatransfer.Transferable trans) throws java.io.IOException
Transferable
object
using automatic format detection.
In conjunction with a suitable TransferHandler
this makes it easy to accept drop of an object representing a table
which has been dragged from another application.
The implementation of this method currently tries the following on a given transferable to turn it into a table:
URL
object, passes that to the
URL factory method
InputStream
, turns it into a
DataSource
and passes that to the
DataSource constructor
trans
- the Transferable object to construct a table fromTableFormatException
- if no table can be constructedjava.io.IOException
canImport(java.awt.datatransfer.DataFlavor[])
public boolean canImport(java.awt.datatransfer.DataFlavor[] flavors)
Transferable
is suitable for attempting to turn the Transferable
into a StarTable.
Each of the builder objects is queried about whether it can
import the given flavour, and if one says it can, a true value
is returned. A true value is also returned if one of the flavours
has a representation class of URL
.
flavors
- the data flavours offeredpublic JDBCHandler getJDBCHandler()
public void setJDBCHandler(JDBCHandler handler)
handler
- the JDBC handlerpublic TableBuilder getTableBuilder(java.lang.String name) throws TableFormatException
TableBuilder.getFormatName()
method)
or by giving the full class name of the handler. In the latter
case this factory does not need to have been informed about the
handler previously.name
- specification of the handler requiredTableFormatException
- if name doesn't name any
available handlerCopyright © 2018 Central Laboratory of the Research Councils. All Rights Reserved.