Package org.apache.sis.setup

Class OptionalInstallations

java.lang.Object
org.apache.sis.setup.InstallationResources
org.apache.sis.setup.OptionalInstallations
All Implemented Interfaces:
Localized
Direct Known Subclasses:
ResourcesDownloader
public abstract class OptionalInstallations extends InstallationResources implements Localized
A predefined set of data important to Apache SIS but not redistributed for space or licensing reasons. 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.
Data are downloaded from URLs hard-coded in this class. Those URLs depend on the Apache SIS versions in use, typically because more recent SIS versions will reference more recent data. The default URLs can be overridden using system properties documented in getDownloadURL(String). This is useful as a workaround if a URL is no longer accessible.
Since:
1.1
Version:
1.3

  • Field Details

    • EPSG_DOWNLOAD_URL

      private static final String EPSG_DOWNLOAD_URL
      Where to download the EPSG scripts after user has approved the terms of use.
      See Also:

    • DATABASE_SIZE

      private static final int DATABASE_SIZE
      Estimation of the EPSG database size after installation, in megabytes. This is for information purpose only.
      See Also:

    • licenseMimeType

      private final String licenseMimeType
      The MIME type to use for fetching license texts. Value can be "text/plain" or "text/html".

    • destinationDirectory

      protected final Path destinationDirectory
      The target directory where to install the resources, or null if none. This is the directory specified by the SIS_DATA environment variable.

    • provider

      private InstallationResources provider
      The provider to use for fetching the actual licensed data after we got user's agreement.

    • accepted

      private Boolean accepted
      true if the user has accepted the EPSG terms of use, false if (s)he refused, or null if (s)he did not yet answered that question.

  • Constructor Details

    • OptionalInstallations

      protected OptionalInstallations(String licenseMimeType)
      Creates a new installation resources downloader.
      Parameters:
      licenseMimeType - either "text/plain" or "text/html".

  • Method Details

    • askUserAgreement

      protected abstract boolean askUserAgreement(String authority, String license)
      Asks to the user if (s)he agree to download and install the resource for the given authority. This method may be invoked twice for the same authority argument:
      1. With a null license argument for asking if the user agrees to download the data.
      2. With a non-null license argument for asking if the user agrees with the license terms.
      Design note: the download action needs to be initiated before to ask for license agreement because the license text is bundled in the resource to download.
      Parameters:
      authority - one of the authorities returned by getAuthorities().
      license - the license, or null for asking if the user wants to download the data.
      Returns:
      whether user accepted.

    • getLocale

      public Locale getLocale()
      Returns the locale to use for messages shown to the user. The default implementation returns the system default locale.
      Specified by:
      getLocale in interface Localized
      Returns:
      the locale of messages shown to the user.

    • getAuthorities

      public Set<String> getAuthorities()
      Returns the names of the authorities providing data that can be installed. The default implementation returns the authorities listed in class javadoc, or a subset of those authorities if some of them cannot be installed (for example because the SIS_DATA environment variable is not set).
      Specified by:
      getAuthorities in class InstallationResources
      Returns:
      authorities of data that can be installed (may be an empty set).

    • unsupported

      private IllegalArgumentException unsupported(String authority)
      Returns the exception to throw for an unsupported authority.

    • getSpaceRequirement

      public int getSpaceRequirement(String authority)
      Returns an estimation of the space required on the host computer after download and installation. This information can be shown to the user before to ask for confirmation.
      Parameters:
      authority - one of the authorities returned by getAuthorities().
      Returns:
      an estimation of space requirement in megabytes.
      Throws:
      IllegalArgumentException - if the given authority argument is not one of the expected values.

    • getDownloadURL

      private String getDownloadURL(String authority)
      Returns the URL from where to download data for the specified authority. The URLs are hard-coded and may change in any Apache SIS version. The default URLs can be overridden using system properties documented below:
      Configuration of download URLs
      Authority System property
      EPSG org.apache.sis.epsg.downloadURL
      The use of above-listed system properties is usually not needed, except as a workaround if a hard-coded URL is no longer accessible.

    • download

      private InstallationResources download(String authority) throws IOException
      Downloads the provider to use for fetching the actual licensed data after we got user's agreement.
      Parameters:
      authority - one of the authorities returned by getAuthorities().
      Returns:
      the actual provider for the given authority.
      Throws:
      IllegalArgumentException - if the given authority argument is not one of the expected values.
      IOException - if an error occurred while downloading the provider.
      IllegalArgumentException - if the specified authority is not recognized.

    • provider

      private InstallationResources provider(String authority, boolean requireAgreement) throws IOException
      Returns the provider to use for fetching the actual licensed data after we got user's agreement. This method asks for user's agreement when first invoked.
      Parameters:
      requireAgreement - true if license agreement is required.
      Throws:
      IllegalArgumentException - if the given authority argument is not one of the expected values.
      AccessDeniedException - if the user does not accept to install the licensed resource.
      IOException - if an error occurred while downloading the resource.

    • 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, then 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, then 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.
      See Also:

    • 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, then 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.