public class StarTableFactory extends 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 StarTable
s 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:
getFormatName
method - it is matched case insensitively. This must be one of the
builders known to the factory.
TableBuilder
and have no-arg constructor).
Such a class must be on the classpath, but need not have been
specified previously to the factory.
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):
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")
HapiTableBuilder
(format name="hapi")
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")
TestTableScheme
(scheme name="test")
ClassTableScheme
(scheme name="class")
HapiTableScheme
(scheme name="hapi")
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 String |
AUTO_HANDLER
Special handler identifier which signifies automatic format detection.
|
static 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 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(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. |
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.
|
List<TableBuilder> |
getKnownBuilders()
Gets the list of builders which are available for selection by
format name.
|
List<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.
|
Map<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(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,
String handler)
Constructs a
StarTable from a DataSource
using a named table input handler. |
StarTable |
makeStarTable(InputStream in,
TableBuilder builder)
Attempts to read and return a StarTable from an input stream.
|
StarTable |
makeStarTable(String location)
Constructs a
StarTable from a location string
without format specification. |
StarTable |
makeStarTable(String location,
String handler)
Constructs a
StarTable from a location string
using a named table input handler. |
StarTable |
makeStarTable(Transferable trans)
Constructs a StarTable from a
Transferable object
using automatic format detection. |
StarTable |
makeStarTable(URL url)
Deprecated.
Use
makeStarTable(new URLDataSource(url)) |
StarTable |
makeStarTable(URL url,
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,
String handler)
Constructs a sequence of StarTables from a DataSource using a named
table input handler.
|
TableSequence |
makeStarTables(String location,
String handler)
Constructs a sequence of
StarTable s from a location string
using a named table input handler. |
static String[] |
parseSchemeLocation(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 String KNOWN_BUILDERS_PROPERTY
TableBuilder
classnames for addition to the known (non-automatically detected)
handler list.public static final String SCHEMES_PROPERTY
TableScheme
classnames for addition to the default list.public static final String AUTO_HANDLER
public StarTableFactory()
public StarTableFactory(boolean requireRandom)
requireRandom
- whether random-access tables will be constructedpublic StarTableFactory(StarTableFactory fact)
fact
- instance to copypublic List<TableBuilder> getDefaultBuilders()
TableBuilder
objects used to
construct StarTable
spublic void setDefaultBuilders(TableBuilder[] builders)
builders
- an array of TableBuilder objects used to
construct StarTable
spublic 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 StarTable
spublic List<String> getKnownFormats()
getKnownBuilders()
.public Map<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)
true
then any table returned by
the various makeStarTable
methods is guaranteed to
provide random access (its 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()
requireRandom
flag.
If this flag is set true
then any table returned by
the various makeStarTable
methods is guaranteed to
provide random access (its 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 IOException
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)
.
table
- original tabletable
and with
isRandom()==true
IOException
public StarTable makeStarTable(DataSource datsrc) throws TableFormatException, IOException
StarTable
from a DataSource
object using automatic format detection.datsrc
- the data source containing the table datadatsrc
TableFormatException
- if none of the default handlers
could turn datsrc
into a tableIOException
- if an I/O error is encounteredpublic TableSequence makeStarTables(DataSource datsrc) throws TableFormatException, 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 tableIOException
- if an I/O error is encounteredpublic StarTable makeStarTable(String location) throws TableFormatException, IOException
StarTable
from a location string
without format specification.
The location string can represent a filename or URL,
or a scheme-based specification of the form
<scheme>:<scheme-spec>
corresponding to one of the installed schemes
.location
- the name of the table resourcelocation
TableFormatException
- if no handler capable of turning
location
into a table is availableIOException
- if one of the handlers encounters an error
constructing a table@Deprecated public StarTable makeStarTable(URL url) throws IOException
makeStarTable(new URLDataSource(url))
StarTable
from a URL using
automatic format detection.url
- the URL where the table livesurl
TableFormatException
- if no handler capable of turning
datsrc
into a table is availableIOException
- if one of the handlers encounters an error
constructing a tablepublic StarTable makeStarTable(DataSource datsrc, String handler) throws TableFormatException, IOException
StarTable
from a DataSource
using a named table input handler.
The input handler may be named either using its format name
(as returned from the 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 formatdatsrc
TableFormatException
- if datsrc
does not contain
a table in the format named by handler
IOException
- if an I/O error is encounteredpublic TableSequence makeStarTables(DataSource datsrc, String handler) throws TableFormatException, 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 formatdatsrc
TableFormatException
- if datsrc
does not contain
a table in the format named by handler
IOException
- if an I/O error is encounteredpublic TableSequence makeStarTables(String location, String handler) throws TableFormatException, IOException
StarTable
s from a location string
using a named table input handler.
The input handler may be named either using its format name
(as returned from the 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 formatlocation
TableFormatException
- if location
does not point to
a table in the format named by handler
IOException
- if an I/O error is encounteredpublic StarTable makeStarTable(String location, String handler) throws TableFormatException, IOException
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 the 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 formatlocation
TableFormatException
- if location
does not point to
a table in the format named by handler
IOException
- if an I/O error is encountered@Deprecated public StarTable makeStarTable(URL url, String handler) throws TableFormatException, IOException
makeStarTable(new URLDataSource(url),handler)
StarTable
from a URL
using a named table input handler.
The input handler may be named either using its format name
(as returned from the 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 formaturl
TableFormatException
- if the resource at url
cannot
be turned into a table by handler
IOException
- if an I/O error is encounteredpublic StarTable makeStarTable(InputStream in, TableBuilder builder) throws TableFormatException, IOException
in
- input streambuilder
- handler which understands the data in in
TableFormatException
- if builder
needs more
than one pass of the data, or the stream is in some way
malformedIOException
- for other I/O errorsTableBuilder.streamStarTable(java.io.InputStream, uk.ac.starlink.table.TableSink, java.lang.String)
public StarTable makeStarTable(Transferable trans) throws 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 constructedIOException
canImport(java.awt.datatransfer.DataFlavor[])
public boolean canImport(DataFlavor[] flavors)
DataFlavor
ojects
offered by a 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(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 requiredname
TableFormatException
- if name
doesn't name any
available handlerpublic static String[] parseSchemeLocation(String location)
location
- table specificationCopyright © 2024 Central Laboratory of the Research Councils. All Rights Reserved.