uk.ac.starlink.table

## Class StarTableFactory

- java.lang.Object
- - uk.ac.starlink.table.StarTableFactory

-     public class StarTableFactory
      extends java.lang.Object

  Manufactures `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:

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

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

- - ### Field Summary

    Fields
    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 Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    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 `StarTable`s 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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### KNOWN_BUILDERS_PROPERTY

          public static final 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.
      See Also:
        Constant Field Values

    - #### SCHEMES_PROPERTY

          public static final java.lang.String SCHEMES_PROPERTY

      System property which can contain a list of `TableScheme` classnames for addition to the default 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<TableBuilder> 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 `StarTable`s

    - #### 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 `StarTable`s

    - #### getKnownBuilders

          public java.util.List<TableBuilder> 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 `StarTable`s

    - #### getKnownFormats

          public java.util.List<java.lang.String> getKnownFormats()

      Returns the list of format names, one for each of the handlers returned by `getKnownBuilders()`.
      Returns:
        list of format name strings

    - #### getSchemes

          public java.util.Map<java.lang.String,TableScheme> getSchemes()

      Returns a schemeName->scheme map indicating the TableSchemes in use by this factory. This map is mutable, so entries may be added or removed, but NOTE that the map keys are assumed to be equivalent to the getSchemeName return value for their value, so modify it with care. Consider using the `addScheme(uk.ac.starlink.table.TableScheme)` method for adding entries.
      Returns:
        map of scheme names to schemes

    - #### addScheme

          public void addScheme(TableScheme scheme)

      Safely adds a table scheme for use by this factory. It is equivalent to `getSchemes().put(scheme.getSchemeName(),scheme)`.
      Parameters:
        `scheme` - new scheme for use

    - #### 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 (its `StarTable.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 (its `StarTable.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

    - #### setInputRestriction

          public void setInputRestriction(java.util.function.Predicate<DataSource> restriction)

      Sets an object that can control access to input data. If a non-null value is set, then any attempt to read a table from a resource such as a file or URL will first test it using the supplied predicate. If its `test` method returns false, the table read attempt will fail with an IOException.
      Parameters:
        `restriction` - policy for restricting DataSource access, or null for no restrictions

    - #### getInputRestriction

          public java.util.function.Predicate<DataSource> getInputRestriction()

      Returns the object controlling access to input data. By default this returns null, meaning no access controls.
      Returns:
        policy for restricting DataSource access, or null
      See Also:
        `setInputRestriction(java.util.function.Predicate<uk.ac.starlink.util.DataSource>)`

    - #### 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(DataSource datsrc)
                                  throws TableFormatException,
                                         java.io.IOException

      Constructs a `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 table
        `java.io.IOException` - if an I/O error is encountered

    - #### makeStarTables

          public TableSequence makeStarTables(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 implement `MultiTableBuilder`) 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 table
        `java.io.IOException` - if an I/O error is encountered

    - #### makeStarTable

          public StarTable makeStarTable(java.lang.String location)
                                  throws TableFormatException,
                                         java.io.IOException

      Constructs a `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`.
      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 available
        `java.io.IOException` - if one of the handlers encounters an error constructing a table

    - #### makeStarTable

          @Deprecated
          public StarTable makeStarTable(java.net.URL url)
                                              throws java.io.IOException

      Deprecated. Use `makeStarTable(new URLDataSource(url))`
      Constructs a `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 available
        `java.io.IOException` - if one of the handlers encounters an error constructing a table

    - #### makeStarTable

          public StarTable makeStarTable(DataSource datsrc,
                                         java.lang.String handler)
                                  throws TableFormatException,
                                         java.io.IOException

      Constructs a `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.
      Parameters:
        `datsrc` - the data source containing the table data
        `handler` - 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 `handler`
        `java.io.IOException` - if an I/O error is encountered

    - #### makeStarTables

          public TableSequence makeStarTables(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 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.

      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 data
        `handler` - 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 `handler`
        `java.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 `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.

      Parameters:
        `location` - the name of the table resource
        `handler` - 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 `handler`
        `java.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 `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.

      Parameters:
        `location` - the name of the table resource
        `handler` - 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 `handler`
        `java.io.IOException` - if an I/O error is encountered

    - #### makeStarTable

          @Deprecated
          public StarTable makeStarTable(java.net.URL url,
                                                     java.lang.String handler)
                                              throws TableFormatException,
                                                     java.io.IOException

      Deprecated. Use `makeStarTable(new URLDataSource(url),handler)`
      Constructs a `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.
      Parameters:
        `url` - the URL where the table lives
        `handler` - 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 `handler`
        `java.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 stream
        `builder` - handler which understands the data in `in`
      Returns:
        a table read from the stream if it could be done
      Throws:
        `TableFormatException` - if `builder` needs more than one pass of the data, or the stream is in some way malformed
        `java.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 a `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:

      - 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 a `DataSource` 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 constructed
        `java.io.IOException`
      See Also:
        `canImport(java.awt.datatransfer.DataFlavor[])`

    - #### canImport

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

      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 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.
      Parameters:
        `name` - specification of the handler required
      Returns:
        TableBuilder specified by `name`
      Throws:
        `TableFormatException` - if `name` doesn't name any available handler

    - #### parseSchemeLocation

          public static java.lang.String[] parseSchemeLocation(java.lang.String location)

      Parses a scheme-format table specification as a scheme name and a scheme-specific part. Normally schemes are of the form ":<scheme-name>:<scheme-specific-part>", but as a special case the initial colon may be omitted for JDBC (backward compatibility).
      Parameters:
        `location` - table specification
      Returns:
        if the location is syntactically a scheme, a 2-element array giving [scheme-name,scheme-specific-part]; otherwise null