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 from an input data stream.
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.
Additionally, a list of TableScheme
objects is maintained,
each of which can produce a table from an opaque specification string
of the form :<scheme-name>:<spec>
.
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):
FitsPlusTableBuilder
(format name="fits-plus")
ColFitsPlusTableBuilder
(format name="colfits-plus")
ColFitsTableBuilder
(format name="colfits-basic")
FitsTableBuilder
(format name="fits")
VOTableBuilder
(format name="votable")
CdfTableBuilder
(format name="cdf")
EcsvTableBuilder
(format name="ecsv")
Pds4TableBuilder
(format name="pds4")
MrtTableBuilder
(format name="mrt")
ParquetTableBuilder
(format name="parquet")
FeatherTableBuilder
(format name="feather")
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")
GbinTableBuilder
(format name="gbin")
WDCTableBuilder
(format name="wdc")
Additionally, any classes named in the
startable.readers system property (as a colon-separated list)
which implement the TableBuilder
interface and have a no-arg
constructor will be instantiated and added to the known handler list.
Some makeStarTable
methods
take a location String rather than an input stream or DataSource;
these may either give a URL or filename, or a
scheme-based location of the form
:<scheme-name>:<scheme-specification>
,
for instance "jdbc://localhost/db1#SELECT id FROM gsc
".
There is a theoretical risk of a namespace clash between
input-yielding URLs, or even filenames, and scheme-based locations,
but if scheme names avoid obvious values like "http" and "C"
this is not likely to cause problems in practice.
The following TableSchemes are installed by default:
JDBCTableScheme
(scheme name="jdbc")
LoopTableScheme
(scheme name="loop")
ClassTableScheme
(scheme name="class")
Additionally, any classes named in the startable.schemes
system property (as a colon-separated list) which implement the
TableScheme
interface and have a no-arg constructor
will be instantiated and added to the known scheme 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 and 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
classnames for addition to the known (non-automatically detected)
handler list. |
static java.lang.String |
SCHEMES_PROPERTY
System property which can contain a list of
TableScheme
classnames for addition to the default list. |
Constructor and 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 and Description |
---|---|
void |
addScheme(TableScheme scheme)
Safely adds a table scheme for use by this factory.
|
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<TableBuilder> |
getDefaultBuilders()
Gets the list of builders which are used for automatic format detection.
|
java.util.function.Predicate<DataSource> |
getInputRestriction()
Returns the object controlling access to input data.
|
JDBCHandler |
getJDBCHandler()
Returns the JDBC handler object used by this factory.
|
java.util.List<TableBuilder> |
getKnownBuilders()
Gets the list of builders which are available for selection by
format name.
|
java.util.List<java.lang.String> |
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.
|
java.util.Map<java.lang.String,TableScheme> |
getSchemes()
Returns a schemeName->scheme map indicating the TableSchemes
in use by this factory.
|
StoragePolicy |
getStoragePolicy()
Returns the current storage policy.
|
TableBuilder |
getTableBuilder(java.lang.String name)
Returns a table handler with a given name.
|
StarTable |
makeStarTable(DataSource datsrc)
Constructs a StarTable from a DataSource
object using automatic format detection.
|
StarTable |
makeStarTable(DataSource datsrc,
java.lang.String handler)
Constructs a StarTable from a DataSource
using a named table input handler.
|
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 StarTable from a location string
without format specification.
|
StarTable |
makeStarTable(java.lang.String location,
java.lang.String handler)
Constructs a StarTable from a location string
using a named table input handler.
|
StarTable |
makeStarTable(java.awt.datatransfer.Transferable trans)
Constructs a StarTable from a
Transferable object
using automatic format detection. |
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) |
TableSequence |
makeStarTables(DataSource datsrc)
Constructs a sequence of StarTables from a DataSource using automatic
format detection.
|
TableSequence |
makeStarTables(DataSource datsrc,
java.lang.String handler)
Constructs a sequence of StarTables 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.
|
static java.lang.String[] |
parseSchemeLocation(java.lang.String location)
Parses a scheme-format table specification as a scheme name
and a scheme-specific part.
|
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 |
setInputRestriction(java.util.function.Predicate<DataSource> restriction)
Sets an object that can control access to input data.
|
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
classnames for addition to the known (non-automatically detected)
handler list.public static final java.lang.String SCHEMES_PROPERTY
TableScheme
classnames for addition to the default 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<TableBuilder> getDefaultBuilders()
TableBuilder
objects used to
construct StarTablespublic void setDefaultBuilders(TableBuilder[] builders)
builders
- an array of TableBuilder objects used to
construct StarTablespublic java.util.List<TableBuilder> 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<java.lang.String> getKnownFormats()
getKnownBuilders()
.public java.util.Map<java.lang.String,TableScheme> getSchemes()
addScheme(uk.ac.starlink.table.TableScheme)
method for adding entries.public void addScheme(TableScheme scheme)
getSchemes().put(scheme.getSchemeName(),scheme)
.scheme
- new scheme for usepublic 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 void setInputRestriction(java.util.function.Predicate<DataSource> restriction)
test
method returns false,
the table read attempt will fail with an IOException.restriction
- policy for restricting DataSource access,
or null for no restrictionspublic java.util.function.Predicate<DataSource> getInputRestriction()
setInputRestriction(java.util.function.Predicate<uk.ac.starlink.util.DataSource>)
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(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(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
<scheme>:<scheme-spec>
corresponding to one of the installed schemes
.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 table@Deprecated public 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(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(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.
Alternatively, the location string can be a
scheme-based specification, in which case the handler
is ignored.
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.
Alternatively, the location string can be a
scheme-based specification, in which case the handler
is ignored.
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 encountered@Deprecated public 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 handlerpublic static java.lang.String[] parseSchemeLocation(java.lang.String location)
location
- table specification