Module org.apache.sis.util
Package org.apache.sis.setup

Class OptionalInstallations

Object
InstallationResources
OptionalInstallations
All Implemented Interfaces:
Localized
Direct Known Subclasses:
Resources­Downloader
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 get­Download­URL(String). This is useful as a workaround if a URL is no longer accessible.
Since:
1.1

  • Field Details

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

  • Constructor Details

    • OptionalInstallations

      protected OptionalInstallations(String licenseMimeType)
      Creates a new installation resources downloader.
      Parameters:
      license­Mime­Type - 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 get­Authorities().
      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:
      get­Locale 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:
      get­Authorities in class Installation­Resources
      Returns:
      authorities of data that can be installed (may be an empty set).

    • 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 get­Authorities().
      Returns:
      an estimation of space requirement in megabytes.
      Throws:
      Illegal­Argument­Exception - if the given authority argument is not one of the expected values.

    • 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:
      get­License in class Installation­Resources
      Parameters:
      authority - one of the values returned by get­Authorities().
      locale - the preferred locale for the terms of use.
      mime­Type - either "text/plain" or "text/html".
      Returns:
      the terms of use in plain text or HTML, or null if none.
      Throws:
      Illegal­Argument­Exception - 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 Access­Denied­Exception will be thrown.

      Specified by:
      get­Resource­Names in class Installation­Resources
      Parameters:
      authority - one of the values returned by get­Authorities().
      Returns:
      the names of all SQL scripts to execute.
      Throws:
      Illegal­Argument­Exception - 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 Access­Denied­Exception will be thrown.
      Overrides:
      get­Resource in class Installation­Resources
      Parameters:
      authority - one of the values returned by get­Authorities().
      index - index of the resource to get, from 0 inclusive to get­Resource­Names(authority)​.length exclusive.
      Returns:
      the resource as an URL or any other type, at implementation choice.
      Throws:
      Illegal­Argument­Exception - if the given authority argument is not one of the expected values.
      Index­Out­Of­Bounds­Exception - 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 Access­Denied­Exception will be thrown.

      Specified by:
      open­Script in class Installation­Resources
      Parameters:
      authority - one of the values returned by get­Authorities().
      resource - index of the script to open, from 0 inclusive to get­Resource­Names(authority)​.length exclusive.
      Returns:
      a reader for the installation script content.
      Throws:
      Illegal­Argument­Exception - if the given authority argument is not one of the expected values.
      Index­Out­Of­Bounds­Exception - if the given resource argument is out of bounds.
      File­Not­Found­Exception - if the SQL script of the given name has not been found.
      IOException - if an error occurred while creating the reader.