This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
new 4bfbc548af Improve documentations. There is no significant code change
except an adjustment of logging level.
4bfbc548af is described below
commit 4bfbc548af1b08fab05f465daa1ef5e55fe97242
Author: Martin Desruisseaux <[email protected]>
AuthorDate: Wed Jan 21 17:07:53 2026 +0100
Improve documentations.
There is no significant code change except an adjustment of logging level.
---
.../org.apache.sis.console/main/module-info.java | 14 ++++-
.../apache/sis/console/ResourcesDownloader.java | 6 ++-
.../apache/sis/setup/InstallationResources.java | 7 ++-
.../apache/sis/setup/OptionalInstallations.java | 60 +++++++++++++++++-----
.../main/org/apache/sis/setup/package-info.java | 2 +-
.../org/apache/sis/storage/isobmff/Reader.java | 2 +-
.../apache/sis/storage/isobmff/gimi/ModelCRS.java | 2 +-
.../main/module-info.java | 11 +++-
.../apache/sis/storage/gdal/GDALStoreProvider.java | 2 +
.../org/apache/sis/storage/gdal/package-info.java | 4 +-
10 files changed, 89 insertions(+), 21 deletions(-)
diff --git a/endorsed/src/org.apache.sis.console/main/module-info.java
b/endorsed/src/org.apache.sis.console/main/module-info.java
index 04b493293f..3e5b6b1983 100644
--- a/endorsed/src/org.apache.sis.console/main/module-info.java
+++ b/endorsed/src/org.apache.sis.console/main/module-info.java
@@ -16,9 +16,21 @@
*/
/**
- * Command line interface for Apache SIS.
+ * Command line interface for Apache <abbr>SIS</abbr>.
* An introduction is available in the <a
href="https://sis.apache.org/command-line.html";>Apache SIS web site</a>.
*
+ * <h2>Usage</h2>
+ * The main method is launched by the {@code sis} executable (a bash script).
+ * Invoking {@code sis} without argument shows a summary of available commands
and all options.
+ * For executing a command, the syntax is:
+ *
+ * <blockquote><pre>sis <command> [options] [files]</pre></blockquote>
+ *
+ * For example, {@code sis crs EPSG:6676} prints the definition of the
<abbr>CRS</abbr> identified by
+ * the <abbr>EPSG</abbr> code 6676. Other commands allow to verify the
validity of a <abbr>CRS</abbr>,
+ * perform coordinate operations or show <abbr>ISO</abbr> 19115 metadata.
+ * See above-cited web site for more details.
+ *
* @author Martin Desruisseaux (Geomatys)
* @version 1.5
* @since 0.3
diff --git
a/endorsed/src/org.apache.sis.console/main/org/apache/sis/console/ResourcesDownloader.java
b/endorsed/src/org.apache.sis.console/main/org/apache/sis/console/ResourcesDownloader.java
index 585c8b0ca8..de3e80a0cf 100644
---
a/endorsed/src/org.apache.sis.console/main/org/apache/sis/console/ResourcesDownloader.java
+++
b/endorsed/src/org.apache.sis.console/main/org/apache/sis/console/ResourcesDownloader.java
@@ -36,9 +36,13 @@ import org.apache.sis.pending.jdk.JDK22;
* before to install them. Authorities managed by the current implementation
are:
*
* <ul>
- * <li>{@code "EPSG"} for the EPSG geodetic dataset.</li>
+ * <li>{@code "EPSG"} for the <abbr>EPSG</abbr> geodetic dataset.</li>
* </ul>
*
+ * This is an implementation of {@link OptionalInstallations} in which user's
permission
+ * is asked on the {@link Console}. By comparison, the {@code
org.apache.sis.gui} module
+ * (for example) contains a similar implementation but asking for permission
in a JavaFX dialog.
+ *
* @author Martin Desruisseaux (Geomatys)
* @version 1.5
* @since 0.7
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/InstallationResources.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/InstallationResources.java
index 55be5828be..9c942be667 100644
---
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/InstallationResources.java
+++
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/InstallationResources.java
@@ -44,7 +44,7 @@ import org.apache.sis.system.Reflect;
* </ul>
*
* <h2>Recognized authorities</h2>
- * Some authorities implemented in Apache SIS modules are listed below.
+ * Some authorities implemented in Apache <abbr>SIS</abbr> modules are listed
below.
* In this list, {@code "Embedded"} is a pseudo-authority for an embedded
database containing EPSG and other data.
* The embedded database is provided as a convenience for avoiding the need to
define a {@code SIS_DATA} directory
* on the local machine.
@@ -66,6 +66,11 @@ import org.apache.sis.system.Reflect;
* allowing Apache SIS to read the EPSG scripts (however SIS still needs an
installation directory
* for writing the database; see above-cited web page for more
information).</p>
*
+ * <h2>Asking user's permission before installation</h2>
+ * By default, data provided by {@code InstallationResources} subclasses must
be bundled with the application
+ * and are silently installed when first needed. If instead, it is desired to
ask user's permission before to
+ * download and install the data, see the {@link OptionalInstallations}
subclass.
+ *
* @author Martin Desruisseaux (Geomatys)
* @version 1.4
* @since 0.7
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/OptionalInstallations.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/OptionalInstallations.java
index 923886c020..3c230dd9c7 100644
---
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/OptionalInstallations.java
+++
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/OptionalInstallations.java
@@ -38,19 +38,61 @@ import static
org.apache.sis.util.internal.shared.Constants.EPSG;
/**
- * A predefined set of data important to Apache SIS but not redistributed for
space or licensing reasons.
+ * A predefined set of data important to Apache <abbr>SIS</abbr> 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:
*
* <ul>
- * <li>{@code "EPSG"} for the EPSG geodetic dataset.</li>
+ * <li>{@code "EPSG"} for the <abbr>EPSG</abbr> geodetic dataset.</li>
* </ul>
*
- * 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
{@link #getDownloadURL(String)}.
+ * Data are downloaded from <abbr>URL</abbr>s hard-coded in this class.
+ * Those <abbr>URL</abbr>s depend on the Apache <abbr>SIS</abbr> versions in
use,
+ * typically because more recent <abbr>SIS</abbr> versions will reference more
recent data.
+ * The default URLs can be overridden using system properties documented below.
* This is useful as a workaround if a URL is no longer accessible.
*
+ * <table class="sis">
+ * <caption>Properties for configuring download <abbr>URL</abbr>s</caption>
+ * <tr><th>Authority</th> <th>System property</th></tr>
+ * <tr><td>EPSG</td> <td>{@systemProperty
org.apache.sis.epsg.downloadURL}</td></tr>
+ * </table>
+ *
+ * <h2>Asking user's permission to download <abbr>EPSG</abbr> data</h2>
+ * If an application does not want to bundle <abbr>EPSG</abbr> data by default,
+ * either for licensing reasons or for saving space, the application can ask
user's permission the first time
+ * that <abbr>EPSG</abbr> data are needed, then (if agreed) download and
install the data automatically.
+ * It can be done as below:
+ *
+ * {@snippet lang="java" :
+ * public class OptionalInstallDialog extends OptionalInstallations {
+ * public OptionalInstallDialog() {
+ * super("text/plain"); // Desired format for the `license`
argument below.
+ * }
+ *
+ * @Override
+ * protected boolean askUserAgreement(String authority, String license) {
+ * if ("EPSG".equals(authority)) {
+ * return false; // If not interested in data other than EPSG.
+ * } else if (license == null) {
+ * // Ask here to user if she wants to download the EPSG data.
+ * } else {
+ * // Ask here to user if she accepts the EPSG terms of use.
+ * }
+ * }
+ * }
+ * }
+ *
+ * The above class needs to be declared as an implementation of the {@link
InstallationResources} service.
+ * This is done either in {@code module-info.java} or, if the application does
not use Java modules,
+ * in the {@code META-INF/services/org.apache.sis.setup.InstallationResources}
file.
+ * In addition, the {@code SIS_DATA} environment variable (not to be confused
with Java property)
+ * needs to be set to the destination directory where to write data on the
user's machine.
+ * With this configuration, Apache <abbr>SIS</abbr> will automatically asks
for user agreement and,
+ * if agreed, download <abbr>EPSG</abbr> data when first needed. If the user
does not agree,
+ * Apache <abbr>SIS</abbr> will still work but with a small set of hard-coded
<abbr>EPSG</abbr>
+ * codes listed {@linkplain org.apache.sis.referencing.CRS#forCode(String)
here}.
+ *
* @author Martin Desruisseaux (Geomatys)
* @version 1.5
* @since 1.1
@@ -177,13 +219,7 @@ public abstract class OptionalInstallations extends
InstallationResources implem
/**
* 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:
- *
- * <table class="sis">
- * <caption>Configuration of download URLs</caption>
- * <tr><th>Authority</th> <th>System property</th></tr>
- * <tr><td>EPSG</td> <td>{@systemProperty
org.apache.sis.epsg.downloadURL}</td></tr>
- * </table>
+ * See class Javadoc for the list of properties recognized by this method.
*
* The use of above-listed system properties is usually not needed,
* except as a workaround if a hard-coded URL is no longer accessible.
diff --git
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/package-info.java
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/package-info.java
index 37c25bb411..765bdd50e8 100644
---
a/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/package-info.java
+++
b/endorsed/src/org.apache.sis.util/main/org/apache/sis/setup/package-info.java
@@ -16,7 +16,7 @@
*/
/**
- * Provides information and some controls about SIS configuration.
+ * Provides information and some controls about Apache <abbr>SIS</abbr>
configuration.
* System-wide information are provided by the {@link
org.apache.sis.setup.About} class.
* Some controls, for example on the {@linkplain
org.apache.sis.setup.GeometryLibrary geometry library} to use,
* is provided by a set of {@linkplain org.apache.sis.setup.OptionKey options}
which can be used when a data store
diff --git
a/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/isobmff/Reader.java
b/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/isobmff/Reader.java
index cea92bb39c..49102adb12 100644
---
a/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/isobmff/Reader.java
+++
b/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/isobmff/Reader.java
@@ -339,7 +339,7 @@ public final class Reader implements Cloneable {
if (type instanceof Integer fourCC) {
type = Box.formatFourCC(fourCC);
}
- var record = new LogRecord(Level.WARNING, "The \"" + type + "\"
type of box is unrecognized.");
+ var record = new LogRecord(Level.FINE, "The \"" + type + "\" type
of box is unrecognized.");
listeners.warning(record);
}
}
diff --git
a/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/isobmff/gimi/ModelCRS.java
b/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/isobmff/gimi/ModelCRS.java
index 42670c2f58..51331dcf54 100644
---
a/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/isobmff/gimi/ModelCRS.java
+++
b/incubator/src/org.apache.sis.storage.geoheif/main/org/apache/sis/storage/isobmff/gimi/ModelCRS.java
@@ -130,7 +130,7 @@ public final class ModelCRS extends FullBox {
case CURI: // Fall through.
case CRSU: return CRS.forCode(crs);
case WKT2: return CRS.fromWKT(crs);
- default: listeners.warning("Unknown CRS encoding:" +
formatFourCC(crsEncoding));
+ default: listeners.warning("Unknown CRS encoding: " +
formatFourCC(crsEncoding));
}
} catch (FactoryException e) {
listeners.warning(e);
diff --git a/optional/src/org.apache.sis.storage.gdal/main/module-info.java
b/optional/src/org.apache.sis.storage.gdal/main/module-info.java
index e4d87b9584..16e0623100 100644
--- a/optional/src/org.apache.sis.storage.gdal/main/module-info.java
+++ b/optional/src/org.apache.sis.storage.gdal/main/module-info.java
@@ -19,8 +19,15 @@
* Bridge to the <abbr>GDAL</abbr> library for reading rasters.
* This module assumes that <abbr>GDAL</abbr> 3.0 or later is preinstalled.
* The <abbr>GDAL</abbr> C/C++ functions are invoked by using the {@link
java.lang.foreign} package.
- * <em>Accesses to native functions are restricted by default in Java and
requires user's authorization.</em>
- * This authorization can be granted by the following option on the
command-line:
+ *
+ * <h2>Prerequisites</h2>
+ * The {@code libgdal.so} (on <abbr>POSIX</abbr>) or {@code gdal.dll} (on
Windows) file must be reachable
+ * on the library search path. On <abbr>POSIX</abbr> systems, the {@code
libgdal.so} is searched in the
+ * directories specified by the {@code LD_LIBRARY_PATH} environment variable.
If the file is not found
+ * in these directories, then the search continues in {@code /lib/} and {@code
/usr/lib/}.
+ *
+ * <p><em>Accesses to native functions are restricted by default in Java and
require user's authorization.</em>
+ * This authorization can be granted by the following option on the
command-line:</p>
*
* {@snippet lang="java" :
* java --enable-native-access org.apache.sis.storage.gdal <other options>
diff --git
a/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/GDALStoreProvider.java
b/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/GDALStoreProvider.java
index 53336cb275..0974d6f407 100644
---
a/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/GDALStoreProvider.java
+++
b/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/GDALStoreProvider.java
@@ -18,6 +18,7 @@ package org.apache.sis.storage.gdal;
import java.util.List;
import java.util.Optional;
+import java.util.NoSuchElementException;
import java.util.logging.Logger;
import java.util.function.Function;
import java.time.LocalDate;
@@ -125,6 +126,7 @@ public class GDALStoreProvider extends DataStoreProvider {
* Creates a new provider which will load the <abbr>GDAL</abbr> library
from the specified file.
* The library will be unloaded when this provider will be
garbage-collected.
*
+ * @param library path to the library to load.
* @throws IllegalArgumentException if the GDAL library has not been found.
* @throws NoSuchElementException if a <abbr>GDAL</abbr> function has not
been found in the library.
* @throws IllegalCallerException if this Apache SIS module is not
authorized to call native methods.
diff --git
a/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/package-info.java
b/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/package-info.java
index 49980b5d67..b5f6f0df47 100644
---
a/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/package-info.java
+++
b/optional/src/org.apache.sis.storage.gdal/main/org/apache/sis/storage/gdal/package-info.java
@@ -22,7 +22,9 @@
* Running this package requires user's authorization to perform native
accesses.
* See the module Javadoc for more information.
*
- * <p>Having this module on the module-path is sufficient for allowing Apache
<abbr>SIS</abbr> to
+ * <p>If the prerequisites described in the module Javadoc are met
+ * (<abbr>GDAL</abbr> presents in the library search path, native accesses
enabled),
+ * then having this module on the module-path is sufficient for allowing
Apache <abbr>SIS</abbr> to
* try <abbr>GDAL</abbr> when {@link
org.apache.sis.storage.DataStores#open(Object)} is invoked.
* Pure Java implementations are tried first, and <abbr>GDAL</abbr> is tried
as a fallback when
* no Java implementation can decode a file. When first needed, this module
searches on the
