Package org.apache.sis.console

## Class ResourcesDownloader

- Object
- - InstallationResources
  - - ResourcesDownloader

-     public class ResourcesDownloader
      extends InstallationResources

  A provider for data licensed under different terms of use than the Apache license. This class is in charge of downloading the data if necessary and asking user's agreement before to install them. Authorities managed by the current implementation are:
  - `"EPSG"` for the EPSG geodetic dataset.
  Since:
    0.7

  Defined in the `sis-console` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ResourcesDownloader()` | Creates a new installation scripts provider.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Set<String>` | `getAuthorities()` | Returns the name of the authority who provides data under non-Apache terms of use.
    `String` | `getLicense​(String authority, Locale locale, String mimeType)` | Returns the terms of use of the dataset provided by the given authority, or `null` if none.
    `Object` | `getResource​(String authority, int index)` | Returns an installation resource for the given authority.
    `String[]` | `getResourceNames​(String authority)` | Returns the names of installation scripts provided by the given authority.
    `BufferedReader` | `openScript​(String authority, int resource)` | Returns a reader for the installation script at the given index.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### ResourcesDownloader

          public ResourcesDownloader()

      Creates a new installation scripts provider.

  - ### Method Detail

    - #### getAuthorities

          public Set<String> getAuthorities()

      Returns the name of the authority who provides data under non-Apache terms of use. If this `ResourcesDownloader` can not ask user's agreement because there is no `Console` attached to the current Java virtual machine, then this method returns an empty set.
      Specified by:
        `getAuthorities` in class `InstallationResources`
      Returns:
        `"EPSG"` or an empty set.

    - #### getLicense

          public String getLicense​(String authority,
                                   Locale locale,
                                   String mimeType)
                            throws IOException

      Returns the terms of use of the dataset provided by the given authority, or `null` if none. The terms of use can be returned in either plain text or HTML.
      Specified by:
        `getLicense` in class `InstallationResources`
      Parameters:
        `authority` - one of the values returned by `getAuthorities()`.
        `mimeType` - either `"text/plain"` or `"text/html"`.
        `locale` - the preferred locale for the terms of use.
      Returns:
        the terms of use in plain text or HTML, or `null` if none.
      Throws:
        `IllegalArgumentException` - if the given `authority` argument is not one of the expected values.
        `IOException` - if an error occurred while reading the license file.

    - #### getResourceNames

          public String[] getResourceNames​(String authority)
                                    throws IOException

      Returns the names of installation scripts provided by the given authority. This method is invoked by `EPSGFactory​.install(Connection)` for listing the SQL scripts to execute during EPSG dataset installation.

      If that question has not already been asked, this method asks to the user if (s)he accepts EPSG terms of use. If (s)he refuses, an `AccessDeniedException` will be thrown.

      Specified by:
        `getResourceNames` in class `InstallationResources`
      Parameters:
        `authority` - one of the values returned by `getAuthorities()`.
      Returns:
        the names of all SQL scripts to execute.
      Throws:
        `IllegalArgumentException` - if the given `authority` argument is not one of the expected values.
        `IOException` - if an error occurred while fetching the script names.

    - #### getResource

          public Object getResource​(String authority,
                                    int index)
                             throws IOException

      Returns an installation resource for the given authority. If that question has not already been asked, this method asks to the user if (s)he accepts EPSG terms of use. If (s)he refuses, an `AccessDeniedException` will be thrown.
      Overrides:
        `getResource` in class `InstallationResources`
      Parameters:
        `authority` - one of the values returned by `getAuthorities()`.
        `index` - index of the resource to get, from 0 inclusive to `getResourceNames(authority)​.length` exclusive.
      Returns:
        the resource as an URL or any other type, at implementation choice.
      Throws:
        `IllegalArgumentException` - if the given `authority` argument is not one of the expected values.
        `IndexOutOfBoundsException` - if the given `resource` argument is out of bounds.
        `IOException` - if an error occurred while fetching the resource.
      Since:
        0.8
      See Also:
        `ClassLoader​.getResource(String)`

    - #### openScript

          public BufferedReader openScript​(String authority,
                                           int resource)
                                    throws IOException

      Returns a reader for the installation script at the given index. This method is invoked by `EPSGFactory​.install(Connection)` for getting the SQL scripts to execute during EPSG dataset installation.

      If that question has not already been asked, this method asks to the user if (s)he accepts EPSG terms of use. If (s)he refuses, an `AccessDeniedException` will be thrown.

      Specified by:
        `openScript` in class `InstallationResources`
      Parameters:
        `authority` - one of the values returned by `getAuthorities()`.
        `resource` - index of the script to open, from 0 inclusive to `getResourceNames(authority)​.length` exclusive.
      Returns:
        a reader for the installation script content.
      Throws:
        `IllegalArgumentException` - if the given `authority` argument is not one of the expected values.
        `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.