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
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.
getDownloadURL(String)
.
This is useful as a workaround if a URL is no longer accessible.- Since:
- 1.1
- Version:
- 1.3
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Boolean
true
if the user has accepted the EPSG terms of use,false
if (s)he refused, ornull
if (s)he did not yet answered that question.private static final int
Estimation of the EPSG database size after installation, in megabytes.protected final Path
The target directory where to install the resources, ornull
if none.private static final String
Where to download the EPSG scripts after user has approved the terms of use.private final String
The MIME type to use for fetching license texts.private InstallationResources
The provider to use for fetching the actual licensed data after we got user's agreement. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
OptionalInstallations
(String licenseMimeType) Creates a new installation resources downloader. -
Method Summary
Modifier and TypeMethodDescriptionprotected 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.private InstallationResources
Downloads the provider to use for fetching the actual licensed data after we got user's agreement.Returns the names of the authorities providing data that can be installed.private String
getDownloadURL
(String authority) Returns the URL from where to download data for the specified authority.getLicense
(String authority, Locale locale, String mimeType) Returns the terms of use of the dataset provided by the given authority, ornull
if none.Returns the locale to use for messages shown to the user.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.int
getSpaceRequirement
(String authority) Returns an estimation of the space required on the host computer after download and installation.openScript
(String authority, int resource) Returns a reader for the installation script at the given index.private InstallationResources
Returns the provider to use for fetching the actual licensed data after we got user's agreement.private IllegalArgumentException
unsupported
(String authority) Returns the exception to throw for an unsupported authority.Methods inherited from class org.apache.sis.setup.InstallationResources
getInstructionURL
-
Field Details
-
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_SIZEEstimation of the EPSG database size after installation, in megabytes. This is for information purpose only.- See Also:
-
licenseMimeType
The MIME type to use for fetching license texts. Value can be"text/plain"
or"text/html"
. -
destinationDirectory
The target directory where to install the resources, ornull
if none. This is the directory specified by theSIS_DATA
environment variable. -
provider
The provider to use for fetching the actual licensed data after we got user's agreement. -
accepted
true
if the user has accepted the EPSG terms of use,false
if (s)he refused, ornull
if (s)he did not yet answered that question.
-
-
Constructor Details
-
OptionalInstallations
Creates a new installation resources downloader.- Parameters:
licenseMimeType
- either"text/plain"
or"text/html"
.
-
-
Method Details
-
askUserAgreement
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 sameauthority
argument:- With a null
license
argument for asking if the user agrees to download the data. - 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 bygetAuthorities()
.license
- the license, ornull
for asking if the user wants to download the data.- Returns:
- whether user accepted.
- With a null
-
getLocale
Returns the locale to use for messages shown to the user. The default implementation returns the system default locale. -
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 theSIS_DATA
environment variable is not set).- Specified by:
getAuthorities
in classInstallationResources
- Returns:
- authorities of data that can be installed (may be an empty set).
-
unsupported
Returns the exception to throw for an unsupported authority. -
getSpaceRequirement
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 bygetAuthorities()
.- Returns:
- an estimation of space requirement in megabytes.
- Throws:
IllegalArgumentException
- if the givenauthority
argument is not one of the expected values.
-
getDownloadURL
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
-
download
Downloads the provider to use for fetching the actual licensed data after we got user's agreement.- Parameters:
authority
- one of the authorities returned bygetAuthorities()
.- Returns:
- the actual provider for the given authority.
- Throws:
IllegalArgumentException
- if the givenauthority
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 givenauthority
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
Returns the terms of use of the dataset provided by the given authority, ornull
if none. The terms of use can be returned in either plain text or HTML.- Specified by:
getLicense
in classInstallationResources
- Parameters:
authority
- one of the values returned bygetAuthorities()
.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 givenauthority
argument is not one of the expected values.IOException
- if an error occurred while reading the license file.
-
getResourceNames
Returns the names of installation scripts provided by the given authority. This method is invoked byEPSGFactory.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 classInstallationResources
- Parameters:
authority
- one of the values returned bygetAuthorities()
.- Returns:
- the names of all SQL scripts to execute.
- Throws:
IllegalArgumentException
- if the givenauthority
argument is not one of the expected values.IOException
- if an error occurred while fetching the script names.
-
getResource
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 anAccessDeniedException
will be thrown.- Overrides:
getResource
in classInstallationResources
- Parameters:
authority
- one of the values returned bygetAuthorities()
.index
- index of the resource to get, from 0 inclusive togetResourceNames(authority).length
exclusive.- Returns:
- the resource as an URL or any other type, at implementation choice.
- Throws:
IllegalArgumentException
- if the givenauthority
argument is not one of the expected values.IndexOutOfBoundsException
- if the givenresource
argument is out of bounds.IOException
- if an error occurred while fetching the resource.- See Also:
-
openScript
Returns a reader for the installation script at the given index. This method is invoked byEPSGFactory.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 classInstallationResources
- Parameters:
authority
- one of the values returned bygetAuthorities()
.resource
- index of the script to open, from 0 inclusive togetResourceNames(authority).length
exclusive.- Returns:
- a reader for the installation script content.
- Throws:
IllegalArgumentException
- if the givenauthority
argument is not one of the expected values.IndexOutOfBoundsException
- if the givenresource
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.
-