# Class InstallationScriptProvider

Object
InstallationResources
InstallationScriptProvider

public abstract class InstallationScriptProvider extends InstallationResources
Provides the SQL scripts needed for creating a local copy of a geodetic dataset. This is used mostly for automatic installation of the EPSG dataset, but could also be used for other registries. Implementations of this class are discovered automatically by `EPSGFactory` if they are declared in the `module-info​.class` file as providers of the `org​.apache​.sis​.setup​.InstallationResources` service.

## How this class is used

The first time that an `EPSGDataAccess` needs to be instantiated, `EPSGFactory` verifies if the EPSG database exists. If it does not, then:

1. `EPSGFactory​.install(Connection)` searches for the first instance of `InstallationResources` for which the set of authorities contains `"EPSG"`.
2. The license will be shown to the user if the application allows that (for example, when running as a console application).
3. If the user accepts the EPSG terms of use, then this class iterates over all readers provided by `openScript(String, int)` and executes the SQL statements (not necessarily verbatim, as the installation process may adapt some SQL statements to the target database).

Since:
  0.7

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final String`
  `FINISH`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Ignored since the upgrade to version 10+ of EPSG because too dependent of the database schema.
  `protected static final String`
  `PREPARE`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Ignored since the upgrade to version 10+ of EPSG because too dependent of the database schema.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `InstallationScriptProvider(String authority, String... resources)`
  Creates a new provider which will read script files of the given names in the given order.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Set<String>`
  `getAuthorities()`
  Returns the identifiers of the dataset installed by the SQL scripts.
  `String[]`
  `getResourceNames(String authority)`
  Returns the names of all SQL scripts to execute.
  `BufferedReader`
  `openScript(String authority, int resource)`
  Returns a reader for the SQL script at the given index.
  `protected abstract InputStream`
  `openStream(String name)`
  Opens the input stream for the SQL script of the given name.

  ### Methods inherited from class InstallationResources

  `getInstructionURL, getLicense, getResource, load`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### PREPARE

    @Deprecated(since="1.5", forRemoval=true) protected static final String PREPARE
    Deprecated, for removal: This API element is subject to removal in a future version.
    Ignored since the upgrade to version 10+ of EPSG because too dependent of the database schema.
    A sentinel value for the content of the script to execute before the SQL scripts provided by the authority. This is an Apache SIS build-in script for replacing the `VARCHAR` type of some columns by enumeration types, in order to constraint the values to the codes recognized by `EPSGDataAccess`. Those enumerations are not mandatory for allowing `EPSGFactory` to work, but improve data integrity.
    See Also:
      - Constant Field Values

  - ### FINISH

    @Deprecated(since="1.5", forRemoval=true) protected static final String FINISH
    Deprecated, for removal: This API element is subject to removal in a future version.
    Ignored since the upgrade to version 10+ of EPSG because too dependent of the database schema.
    A sentinel value for the content of the script to execute after the SQL scripts provided by the authority. This is an Apache SIS build-in script for creating indexes or performing other manipulations that help SIS to use the dataset. Those indexes are not mandatory for allowing `EPSGFactory` to work, but improve performances.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### InstallationScriptProvider

    protected InstallationScriptProvider(String authority, String... resources)
    Creates a new provider which will read script files of the given names in the given order. The given names are often filenames, but not necessarily (it is okay to use those names only as labels).

    Example of argument values
    Authority | Resources
    --- | ---
    `EPSG` | `{"Tables.sql", "Data.sql", "FKeys.sql", "Indexes.sql"}`

    Parameters:
      `authority` - the authority (typically `"EPSG"`), or `null` if not available.
      `resources` - names of the SQL scripts to read (typically filenames).
    See Also:
      - `getResourceNames(String)`
      - `openStream(String)`

- ## Method Details

  - ### getAuthorities

    public Set<String> getAuthorities()
    Returns the identifiers of the dataset installed by the SQL scripts. The values currently recognized by SIS are:
    - `"EPSG"` for the EPSG geodetic dataset.
    The default implementation returns the authority given at construction time, or an empty set if that authority was `null`. An empty set means that the provider does not have all needed resources or does not have permission to distribute the installation scripts.
    Specified by:
      `getAuthorities` in class `InstallationResources`
    Returns:
      identifiers of SQL scripts that this instance can distribute.

  - ### getResourceNames

    public String[] getResourceNames(String authority) throws IOException
    Returns the names of all SQL scripts to execute. This is a copy of the array of names given to the constructor. Those names are often filenames, but not necessarily (they may be just labels).
    Specified by:
      `getResourceNames` in class `InstallationResources`
    Parameters:
      `authority` - the value given at construction time (e.g. `"EPSG"`).
    Returns:
      the names of all SQL scripts to execute.
    Throws:
      `IllegalArgumentException` - if the given `authority` argument is not the expected value.
      `IOException` - if fetching the script names required an I/O operation and that operation failed.

  - ### openScript

    public BufferedReader openScript(String authority, int resource) throws IOException
    Returns a reader for the SQL script at the given index. The script may be read, for example, from a local file or from a resource in a JAR file. The returned `BufferedReader` instance shall be closed by the caller.

    #### Default implementation

    The default implementation delegates to `openStream(String)`. The input stream returned by `openStream(…)` is assumed encoded in UTF-8 and is wrapped in a `LineNumberReader`.
    Specified by:
      `openScript` in class `InstallationResources`
    Parameters:
      `authority` - the value given at construction time (e.g. `"EPSG"`).
      `resource` - index of the SQL script to read, from 0 inclusive to `getResourceNames(authority)​.length` exclusive.
    Returns:
      a reader for the content of SQL script to execute.
    Throws:
      `IllegalArgumentException` - if the given `authority` argument is not the expected value.
      `IndexOutOfBoundsException` - if the given `resource` argument is out of bounds.
      `FileNotFoundException` - if the SQL script of the given name has not been found.
      `IOException` - if an error occurred while creating the reader.

  - ### openStream

    protected abstract InputStream openStream(String name) throws IOException
    Opens the input stream for the SQL script of the given name. This method is invoked by the default implementation of `openScript(String, int)`. The returned input stream does not need to be buffered.

    #### Example 1

    If this `InstallationScriptProvider` instance gets the SQL scripts from files in a well-known directory and if the names given at construction time are filenames in that directory, then this method can be implemented as below:

             protected InputStream openStream(String name) throws IOException {
                 return Files.newInputStream(directory.resolve(name));
             }

    #### Example 2

    If this `InstallationScriptProvider` instance gets the SQL scripts from resources bundled in the same JAR file and in the same package as the subclass, this method can be implemented as below:

             protected InputStream openStream(String name) {
                 return MyClass.getResourceAsStream(name);
             }

    Parameters:
      `name` - name of the script file to open. Can be `null` if the resource is not found.
    Returns:
      an input stream opened of the given script file.
    Throws:
      `IOException` - if an error occurred while opening the file.