Class StarTableFactory
- java.lang.Object
-
- uk.ac.starlink.table.StarTableFactory
-
public class StarTableFactory extends java.lang.Object
ManufacturesStarTable
objects from generic inputs. This factory delegates the actual table creation to externalTableBuilder
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 asURL
andDataSource
. 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:
- The format name - this is a short mnemonic string like "fits" which is returned by the TableBuilder's getFormatName method - it is matched case insensitively. This must be one of the builders known to the factory.
- The classname of a suitable TableBuilder (the class must implement TableBuilder and have no-arg constructor). Such a class must be on the classpath, but need not have been specified previously to the factory.
- The empty string or null or
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.
- Author:
- Mark Taylor (Starlink)
-
-
Field Summary
Fields 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 ofTableBuilder
classes for addition to the known (non-automatically detected) handler list.
-
Constructor Summary
Constructors 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.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
canImport(java.awt.datatransfer.DataFlavor[] flavors)
Indicates whether a particular set of DataFlavor ojects offered by aTransferable
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 bygetKnownBuilders()
.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 aTransferable
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.UsemakeStarTable(new URLDataSource(url))
StarTable
makeStarTable(java.net.URL url, java.lang.String handler)
Deprecated.UsemakeStarTable(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.
-
-
-
Field Detail
-
KNOWN_BUILDERS_PROPERTY
public static final java.lang.String KNOWN_BUILDERS_PROPERTY
System property which can contain a list ofTableBuilder
classes for addition to the known (non-automatically detected) handler list.- See Also:
- Constant Field Values
-
AUTO_HANDLER
public static final java.lang.String AUTO_HANDLER
Special handler identifier which signifies automatic format detection.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
StarTableFactory
public StarTableFactory()
Constructs a StarTableFactory with a default list of builders which is not guaranteed to construct random-access tables.
-
StarTableFactory
public StarTableFactory(boolean requireRandom)
Constructs a StarTableFactory with a default list of builders specifying whether it will return random-access tables.- Parameters:
requireRandom
- whether random-access tables will be constructed
-
StarTableFactory
public StarTableFactory(StarTableFactory fact)
Constructs a StarTableFactory which is a copy of an existing one.- Parameters:
fact
- instance to copy
-
-
Method Detail
-
getDefaultBuilders
public java.util.List getDefaultBuilders()
Gets the list of builders which are used for automatic format detection. Builders earlier in the list are given a chance to make the table before ones later in the list. This list can be modified to change the behaviour of the factory.- Returns:
- a mutable list of
TableBuilder
objects used to construct StarTables
-
setDefaultBuilders
public void setDefaultBuilders(TableBuilder[] builders)
Sets the list of builders which actually do the table construction. Builders earlier in the list are given a chance to make the table before ones later in the list.- Parameters:
builders
- an array of TableBuilder objects used to construct StarTables
-
getKnownBuilders
public java.util.List getKnownBuilders()
Gets the list of builders which are available for selection by format name. This is initially set to the list of default builders plus a few others. This list can be modified to change the behaviour of the factory.- Returns:
- a mutable list of
TableBuilder
objects which may be specified for table building
-
setKnownBuilders
public void setKnownBuilders(TableBuilder[] builders)
Sets the list of builders which are available for selection by format name. This is initially set to the list of default builders plus a few others.- Parameters:
builders
- an array of TableBuilder objects used to construct StarTables
-
getKnownFormats
public java.util.List getKnownFormats()
Returns the list of format names, one for each of the handlers returned bygetKnownBuilders()
.- Returns:
- list of format name strings
-
setRequireRandom
public void setRequireRandom(boolean requireRandom)
Sets whether random-access tables will be constructed by this factory. If this flag is set true then any table returned by the various makeStarTable methods is guaranteed to provide random access (itsStarTable.isRandom()
method will return true). If the flag is false, then returned tables may or may not be random-access.- Parameters:
requireRandom
- whether this factory will create random-access tables
-
requireRandom
public boolean requireRandom()
Returns the requireRandom flag. If this flag is set true then any table returned by the various makeStarTable methods is guaranteed to provide random access (itsStarTable.isRandom()
method will return true). If the flag is false, then returned tables may or may not be random-access.- Returns:
- whether this factory will create random-access tables
-
setStoragePolicy
public void setStoragePolicy(StoragePolicy policy)
Sets the storage policy. This may be used to determine what kind of scratch storage is used when constructing tables.- Parameters:
policy
- the new storage policy object
-
getStoragePolicy
public StoragePolicy getStoragePolicy()
Returns the current storage policy. This may be used to determine what kind of scratch storage is used when constructing tables. If it has not been set explicitly, the default policy is used (StoragePolicy.getDefaultPolicy()
).- Returns:
- storage policy object
-
setPreparation
public void setPreparation(TablePreparation tablePrep)
Sets a table preparation object that is invoked on each table created by this factory. Any previous value is overwritten. Null is allowed.- Parameters:
tablePrep
- new table preparation, or null
-
getPreparation
public TablePreparation getPreparation()
Returns the current table preparation object, if any. By default, null is returned.- Returns:
- table preparation, or null
-
randomTable
public StarTable randomTable(StarTable table) throws java.io.IOException
Returns a table based on a given table and guaranteed to have random access. If the original table table has random access then it is returned, otherwise a new random access table is built using its data.This convenience method is equivalent to getStoragePolicy().randomTable(table).
- Parameters:
table
- original table- Returns:
- a table with the same data as table and with isRandom()==true
- Throws:
java.io.IOException
-
makeStarTable
public StarTable makeStarTable(uk.ac.starlink.util.DataSource datsrc) throws TableFormatException, java.io.IOException
Constructs a readable StarTable from a DataSource object using automatic format detection.- Parameters:
datsrc
- the data source containing the table data- Returns:
- a new StarTable view of the resource datsrc
- Throws:
TableFormatException
- if none of the default handlers could turn datsrc into a tablejava.io.IOException
- if an I/O error is encountered
-
makeStarTables
public TableSequence makeStarTables(uk.ac.starlink.util.DataSource datsrc) throws TableFormatException, java.io.IOException
Constructs a sequence of StarTables from a DataSource using automatic format detection. Only certain formats (those whose handlers implementMultiTableBuilder
will be capable of returning a sequence having more than one element.- Parameters:
datsrc
- the data source containing the table data- Returns:
- a sequence of tables loaded from
datsrc
- Throws:
TableFormatException
- if none of the default handlers could turn datsrc into a tablejava.io.IOException
- if an I/O error is encountered
-
makeStarTable
public StarTable makeStarTable(java.lang.String location) throws TableFormatException, java.io.IOException
Constructs a readable StarTable from a location string using automatic format detection. The location string can represent a filename or URL, including a jdbc: protocol URL if an appropriate JDBC driver is installed.- Parameters:
location
- the name of the table resource- Returns:
- a new StarTable view of the resource at location
- Throws:
TableFormatException
- if no handler capable of turning location into a table is availablejava.io.IOException
- if one of the handlers encounters an error constructing a table
-
makeStarTable
public StarTable makeStarTable(java.net.URL url) throws java.io.IOException
Deprecated.UsemakeStarTable(new URLDataSource(url))
Constructs a readable StarTable from a URL using automatic format detection.- Parameters:
url
- the URL where the table lives- Returns:
- a new StarTable view of the resource at url
- Throws:
TableFormatException
- if no handler capable of turning datsrc into a table is availablejava.io.IOException
- if one of the handlers encounters an error constructing a table
-
makeStarTable
public StarTable makeStarTable(uk.ac.starlink.util.DataSource datsrc, java.lang.String handler) throws TableFormatException, java.io.IOException
Constructs a readable StarTable from a DataSource using a named table input handler. The input handler may be named either using its format name (as returned from theTableBuilder.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 valueAUTO_HANDLER
is supplied for handler, it will fall back on automatic format detection.- Parameters:
datsrc
- the data source containing the table datahandler
- specifier for the handler which can handle tables of the right format- Returns:
- a new StarTable view of the resource datsrc
- Throws:
TableFormatException
- if datsrc does not contain a table in the format named by handlerjava.io.IOException
- if an I/O error is encountered
-
makeStarTables
public TableSequence makeStarTables(uk.ac.starlink.util.DataSource datsrc, java.lang.String handler) throws TableFormatException, java.io.IOException
Constructs a sequence of StarTables from a DataSource using a named table input handler. The input handler may be named either using its format name (as returned from theTableBuilder.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 valueAUTO_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.- Parameters:
datsrc
- the data source containing the table datahandler
- specifier for the handler which can handle tables of the right format- Returns:
- a sequence of StarTables loaded from datsrc
- Throws:
TableFormatException
- if datsrc does not contain a table in the format named by handlerjava.io.IOException
- if an I/O error is encountered
-
makeStarTables
public TableSequence makeStarTables(java.lang.String location, java.lang.String handler) throws TableFormatException, java.io.IOException
Constructs a sequence of StarTables from a location string using a named table input handler. The input handler may be named either using its format name (as returned from theTableBuilder.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 valueAUTO_HANDLER
is supplied for handler, it will fall back on automatic format detection.- Parameters:
location
- the name of the table resourcehandler
- specifier for the handler which can handle tables of the right format- Returns:
- a new StarTable view of the resource at location
- Throws:
TableFormatException
- if location does not point to a table in the format named by handlerjava.io.IOException
- if an I/O error is encountered
-
makeStarTable
public StarTable makeStarTable(java.lang.String location, java.lang.String handler) throws TableFormatException, java.io.IOException
Constructs a readable StarTable from a location string using a named table input handler. The input handler may be named either using its format name (as returned from theTableBuilder.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 valueAUTO_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.- Parameters:
location
- the name of the table resourcehandler
- specifier for the handler which can handle tables of the right format- Returns:
- a new StarTable view of the resource at location
- Throws:
TableFormatException
- if location does not point to a table in the format named by handlerjava.io.IOException
- if an I/O error is encountered
-
makeStarTable
public StarTable makeStarTable(java.net.URL url, java.lang.String handler) throws TableFormatException, java.io.IOException
Deprecated.UsemakeStarTable(new URLDataSource(url),handler)
Constructs a readable StarTable from a URL using a named table input handler. The input handler may be named either using its format name (as returned from theTableBuilder.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 valueAUTO_HANDLER
is supplied for handler, it will fall back on automatic format detection.- Parameters:
url
- the URL where the table liveshandler
- specifier for the handler which can handle tables of the right format- Returns:
- a new StarTable view of the resource at url
- Throws:
TableFormatException
- if the resource at url cannot be turned into a table by handlerjava.io.IOException
- if an I/O error is encountered
-
makeStarTable
public StarTable makeStarTable(java.io.InputStream in, TableBuilder builder) throws TableFormatException, java.io.IOException
Attempts to read and return a StarTable from an input stream. This is not always possible, since certain table handlers may required more than one pass through the input data. The handler must be specified (automatic format detection cannot be used on a stream). The input stream will be decompressed and buffered if necessary.- Parameters:
in
- input streambuilder
- handler which understands the data in in- Returns:
- a table read from the stream if it could be done
- Throws:
TableFormatException
- ifbuilder
needs more than one pass of the data, or the stream is in some way malformedjava.io.IOException
- for other I/O errors- See Also:
TableBuilder.streamStarTable(java.io.InputStream, uk.ac.starlink.table.TableSink, java.lang.String)
-
makeStarTable
public StarTable makeStarTable(java.awt.datatransfer.Transferable trans) throws java.io.IOException
Constructs a StarTable from aTransferable
object using automatic format detection. In conjunction with a suitableTransferHandler
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:
- If it finds a
URL
object, passes that to the URL factory method - If it finds a transferable that will supply an
InputStream
, turns it into aDataSource
and passes that to the DataSource constructor
- Parameters:
trans
- the Transferable object to construct a table from- Returns:
- a new StarTable constructed from the Transferable
- Throws:
TableFormatException
- if no table can be constructedjava.io.IOException
- See Also:
canImport(java.awt.datatransfer.DataFlavor[])
- If it finds a
-
canImport
public boolean canImport(java.awt.datatransfer.DataFlavor[] flavors)
Indicates whether a particular set of DataFlavor ojects offered by aTransferable
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
.- Parameters:
flavors
- the data flavours offered
-
getJDBCHandler
public JDBCHandler getJDBCHandler()
Returns the JDBC handler object used by this factory.- Returns:
- the JDBC handler
-
setJDBCHandler
public void setJDBCHandler(JDBCHandler handler)
Sets the JDBC handler object used by this factory.- Parameters:
handler
- the JDBC handler
-
getTableBuilder
public TableBuilder getTableBuilder(java.lang.String name) throws TableFormatException
Returns a table handler with a given name. This name may be either its format name (as returned from theTableBuilder.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.- Parameters:
name
- specification of the handler required- Returns:
- TableBuilder specified by name
- Throws:
TableFormatException
- if name doesn't name any available handler
-
-