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
commit 0096500b348c061ed84fdd6eb1a9a358ee0a7cb1
Author: Martin Desruisseaux <martin.desruisse...@geomatys.com>
AuthorDate: Sat May 7 15:06:03 2022 +0200
Add documentation and missing annotations.
Fix some javadoc errors.
---
application/sis-javafx/src/main/artifact/bin/sisfx | 2 +-
.../main/java/org/apache/sis/gui/package-info.java | 8 ++++++
.../org/apache/sis/cloud/aws/s3/package-info.java | 2 +-
.../iso/acquisition/DefaultRequirement.java | 2 ++
.../referencing/operation/projection/Mercator.java | 13 +++++-----
.../java/org/apache/sis/internal/util/URLs.java | 9 +++++--
.../java/org/apache/sis/setup/Configuration.java | 2 +-
.../apache/sis/setup/OptionalInstallations.java | 30 ++++++++++++++--------
pom.xml | 1 +
.../sis/storage/landsat/LandsatStoreProvider.java | 7 +++--
.../sis/storage/geotiff/GeoTiffStoreProvider.java | 11 +++++---
.../storage/image/WorldFileStoreProvider.java | 2 +-
.../sis/storage/AbstractGridCoverageResource.java | 2 +-
.../org/apache/sis/storage/DataStoreProvider.java | 4 +--
14 files changed, 63 insertions(+), 32 deletions(-)
diff --git a/application/sis-javafx/src/main/artifact/bin/sisfx
b/application/sis-javafx/src/main/artifact/bin/sisfx
index daf89b2356..1439fff62f 100755
--- a/application/sis-javafx/src/main/artifact/bin/sisfx
+++ b/application/sis-javafx/src/main/artifact/bin/sisfx
@@ -19,7 +19,7 @@
set -o errexit
BASE_DIR="`dirname $0`/.."
-source "$BASE_DIR/conf/setenv.sh"
+. "$BASE_DIR/conf/setenv.sh"
SIS_DATA="${SIS_DATA:-$BASE_DIR/data}"
export SIS_DATA
diff --git
a/application/sis-javafx/src/main/java/org/apache/sis/gui/package-info.java
b/application/sis-javafx/src/main/java/org/apache/sis/gui/package-info.java
index 30f10ab6eb..8686e46534 100644
--- a/application/sis-javafx/src/main/java/org/apache/sis/gui/package-info.java
+++ b/application/sis-javafx/src/main/java/org/apache/sis/gui/package-info.java
@@ -17,6 +17,14 @@
/**
* JavaFX application for Apache SIS.
+ * See the <a href="https://sis.apache.org/javafx.html";>JavaFX application</a>
page
+ * on the Apache SIS web site for more information.
+ *
+ * <h2>File size limit</h2>
+ * There is usually no size limit when viewing only the metadata, because only
the file headers are read at that time.
+ * When viewing the data, there is no size limit if the data are pyramided and
tiled with tiles of reasonable size,
+ * because the application loads only the tiles needed for the area being
displayed.
+ * An example of file format supporting tiling is GeoTIFF.
*
* @author Smaniotto Enzo (GSoC)
* @author Johann Sorel (Geomatys)
diff --git
a/cloud/sis-cloud-S3/src/main/java/org/apache/sis/cloud/aws/s3/package-info.java
b/cloud/sis-cloud-S3/src/main/java/org/apache/sis/cloud/aws/s3/package-info.java
index 2b21a08471..ba209f9fcb 100644
---
a/cloud/sis-cloud-S3/src/main/java/org/apache/sis/cloud/aws/s3/package-info.java
+++
b/cloud/sis-cloud-S3/src/main/java/org/apache/sis/cloud/aws/s3/package-info.java
@@ -30,7 +30,7 @@
*
* <p>Keys can be paths with components separated by the {@code '/'} separator.
* The password and the region can be specified at
- * {@linkplain java.nio.file.FileSystem#newFileSystem file system
initialization time}.
+ * {@linkplain java.nio.file.FileSystems#newFileSystem file system
initialization time}.
* The endpoint (e.g. {@code "s3.eu-central-1.amazonaws.com"}) shall
<em>not</em> be specified in the URI.
* In particular the region ({@code "eu-central-1"} in above example) can
depend on the server location
* instead of the data to access, and can be a global configuration for the
server.</p>
diff --git
a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/DefaultRequirement.java
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/DefaultRequirement.java
index 1117a8dc43..0624a193aa 100644
---
a/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/DefaultRequirement.java
+++
b/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/DefaultRequirement.java
@@ -333,6 +333,8 @@ public class DefaultRequirement extends ISOMetadata
implements Requirement {
}
/**
+ * Sets the plan that identifies solution to satisfy the requirement.
+ *
* @param newValues the new satisfied plans values.
*/
public void setSatisfiedPlans(final Collection<? extends Plan> newValues) {
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
index c22a8bd162..520c75f4dc 100644
---
a/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
+++
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
@@ -147,12 +147,13 @@ public class Mercator extends ConformalProjection {
/**
* The type of Mercator projection. Possible values are:
* <ul>
- * <li>{@link Variant#DEFAULT} if this projection is a Mercator
variant A or B.</li>
- * <li>{@link Variant#REGIONAL} if this projection is the "Mercator
(variant C)" case.</li>
- * <li>{@link Variant#SPHERICAL} if this projection is the "Mercator
(Spherical)" case.</li>
- * <li>{@link Variant#PSEUDO} if this projection is the "Pseudo
Mercator" case.</li>
- * <li>{@link Variant#MILLER} if this projection is the "Miller
Cylindrical" case.</li>
- * <li>{@link Variant#AUXILIARY} if this projection is the "Mercator
Auxiliary Sphere" case.</li>
+ * <li>{@link Variant#ONE_PARALLEL} if this projection is a Mercator
variant A.</li>
+ * <li>{@link Variant#TWO_PARALLELS} if this projection is a Mercator
variant A.</li>
+ * <li>{@link Variant#REGIONAL} if this projection is the "Mercator
(variant C)" case.</li>
+ * <li>{@link Variant#SPHERICAL} if this projection is the "Mercator
(Spherical)" case.</li>
+ * <li>{@link Variant#PSEUDO} if this projection is the "Pseudo
Mercator" case.</li>
+ * <li>{@link Variant#MILLER} if this projection is the "Miller
Cylindrical" case.</li>
+ * <li>{@link Variant#AUXILIARY} if this projection is the "Mercator
Auxiliary Sphere" case.</li>
* </ul>
*
* Other cases may be added in the future.
diff --git
a/core/sis-utility/src/main/java/org/apache/sis/internal/util/URLs.java
b/core/sis-utility/src/main/java/org/apache/sis/internal/util/URLs.java
index 1f49c4f770..50ea417881 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/internal/util/URLs.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/internal/util/URLs.java
@@ -20,8 +20,13 @@ import org.apache.sis.util.Static;
/**
- * Hard-coded URLs other than XML namespaces.
- * The are mostly for documentation.
+ * Hard-coded URLs other than XML namespaces. Those URLs are mostly for
documentation.
+ * Note: other URLs are listed in the following classes:
+ *
+ * <ul>
+ * <li>{@link org.apache.sis.xml.Namespaces} for XML namespaces.</li>
+ * <li>{@link org.apache.sis.setup.OptionalInstallations} for location of
optional data to download.</li>
+ * </ul>
*
* @author Martin Desruisseaux (Geomatys)
* @version 1.2
diff --git
a/core/sis-utility/src/main/java/org/apache/sis/setup/Configuration.java
b/core/sis-utility/src/main/java/org/apache/sis/setup/Configuration.java
index 21538bf16a..8efdf4d2b5 100644
--- a/core/sis-utility/src/main/java/org/apache/sis/setup/Configuration.java
+++ b/core/sis-utility/src/main/java/org/apache/sis/setup/Configuration.java
@@ -85,7 +85,7 @@ public final class Configuration {
* Apache SIS may create the database since it is located in the
directory managed by Apache SIS.</li>
* <li>Otherwise if the {@code non-free:sis-embedded-data} module is
present on the classpath,
* use the embedded database.</li>
- * <li>Otherwise if the {@code "derby.system.home"} property is defined,
+ * <li>Otherwise if the "{@systemProperty derby.system.home}" property
is defined,
* use the data source for {@code "jdbc:derby:SpatialMetadata"}
database.
* This database will <strong>not</strong> be created if it does not
exist.</li>
* </ol>
diff --git
a/core/sis-utility/src/main/java/org/apache/sis/setup/OptionalInstallations.java
b/core/sis-utility/src/main/java/org/apache/sis/setup/OptionalInstallations.java
index ed564b1205..4b2b11be7e 100644
---
a/core/sis-utility/src/main/java/org/apache/sis/setup/OptionalInstallations.java
+++
b/core/sis-utility/src/main/java/org/apache/sis/setup/OptionalInstallations.java
@@ -45,25 +45,22 @@ import static org.apache.sis.internal.util.Constants.EPSG;
* <li>{@code "EPSG"} for the EPSG 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)}.
+ * This is useful as a workaround if a URL is no longer accessible.
+ *
* @author Martin Desruisseaux (Geomatys)
* @version 1.2
* @since 1.1
* @module
*/
public abstract class OptionalInstallations extends InstallationResources
implements Localized {
- /**
- * The {@systemProperty org.apache.sis.epsg.downloadURL} system property
for overriding
- * the {@link #DOWNLOAD_URL} value. This is useful for testing purpose
before a release,
- * or for providing a work-around for bad URL after release.
- *
- * @since 1.2
- */
- private static final String DOWNLOAD_PROPERTY =
"org.apache.sis.epsg.downloadURL";
-
/**
* Where to download the EPSG scripts after user has approved the terms of
use.
*/
- private static final String DOWNLOAD_URL =
"https://repo1.maven.org/maven2/org/apache/sis/non-free/sis-epsg/1.1/sis-epsg-1.1.jar";;
+ private static final String EPSG_DOWNLOAD_URL =
+
"https://repo1.maven.org/maven2/org/apache/sis/non-free/sis-epsg/1.1/sis-epsg-1.1.jar";;
/**
* Estimation of the EPSG database size after installation, in megabytes.
@@ -173,10 +170,21 @@ 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>
+ *
+ * The use of above-listed system properties is usually not needed,
+ * except as a workaround if a hard-coded URL is no longer accessible.
*/
private String getDownloadURL(final String authority) {
switch (authority) {
- case EPSG: return System.getProperty(DOWNLOAD_PROPERTY,
DOWNLOAD_URL);
+ case EPSG: return
System.getProperty("org.apache.sis.epsg.downloadURL", EPSG_DOWNLOAD_URL);
default: throw unsupported(authority); // More authorities
may be added in the future.
}
}
diff --git a/pom.xml b/pom.xml
index f53f303336..d5858f3982 100644
--- a/pom.xml
+++ b/pom.xml
@@ -859,6 +859,7 @@
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.4.0</version>
<configuration>
+ <release>17</release>
<source>${maven.compiler.source}</source> <!-- Enables
javadoc to handle language constructs present in target JDK. -->
<encoding>${project.build.sourceEncoding}</encoding> <!-- Encoding
of Java source file. -->
<docencoding>${website.encoding}</docencoding> <!-- Encoding
of the generated HTML files. -->
diff --git
a/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/landsat/LandsatStoreProvider.java
b/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/landsat/LandsatStoreProvider.java
index 0e04617154..c309746d33 100644
---
a/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/landsat/LandsatStoreProvider.java
+++
b/storage/sis-earth-observation/src/main/java/org/apache/sis/storage/landsat/LandsatStoreProvider.java
@@ -20,9 +20,11 @@ import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.Files;
import org.opengis.parameter.ParameterDescriptorGroup;
+import org.apache.sis.storage.Aggregate;
import org.apache.sis.storage.DataStore;
import org.apache.sis.storage.DataStoreProvider;
import org.apache.sis.storage.DataStoreException;
+import org.apache.sis.storage.GridCoverageResource;
import org.apache.sis.storage.StorageConnector;
import org.apache.sis.storage.ProbeResult;
import org.apache.sis.internal.storage.Capability;
@@ -44,8 +46,9 @@ import org.apache.sis.internal.storage.wkt.FirstKeywordPeek;
* @since 1.1
* @module
*/
-@StoreMetadata(formatName = LandsatStoreProvider.NAME,
- capabilities = Capability.READ)
+@StoreMetadata(formatName = LandsatStoreProvider.NAME,
+ capabilities = Capability.READ,
+ resourceTypes = {Aggregate.class, GridCoverageResource.class})
public class LandsatStoreProvider extends DataStoreProvider {
/**
* The format name.
diff --git
a/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStoreProvider.java
b/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStoreProvider.java
index 5059e7b55b..563f73bd3d 100644
---
a/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStoreProvider.java
+++
b/storage/sis-geotiff/src/main/java/org/apache/sis/storage/geotiff/GeoTiffStoreProvider.java
@@ -20,9 +20,11 @@ import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import org.opengis.parameter.ParameterDescriptorGroup;
import org.apache.sis.util.Version;
+import org.apache.sis.storage.Aggregate;
import org.apache.sis.storage.DataStore;
import org.apache.sis.storage.DataStoreException;
import org.apache.sis.storage.DataStoreProvider;
+import org.apache.sis.storage.GridCoverageResource;
import org.apache.sis.storage.ProbeResult;
import org.apache.sis.storage.StorageConnector;
import org.apache.sis.internal.storage.StoreMetadata;
@@ -40,16 +42,17 @@ import org.apache.sis.internal.util.Constants;
* the part of the caller. However the {@link GeoTiffStore} instances created
by this factory are not thread-safe.
*
* @author Martin Desruisseaux (Geomatys)
- * @version 1.0
+ * @version 1.2
*
* @see GeoTiffStore
*
* @since 0.8
* @module
*/
-@StoreMetadata(formatName = Constants.GEOTIFF,
- fileSuffixes = {"tiff", "tif"},
- capabilities = Capability.READ)
+@StoreMetadata(formatName = Constants.GEOTIFF,
+ fileSuffixes = {"tiff", "tif"},
+ capabilities = Capability.READ,
+ resourceTypes = {Aggregate.class, GridCoverageResource.class})
public class GeoTiffStoreProvider extends DataStoreProvider {
/**
* The MIME type for GeoTIFF files.
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/image/WorldFileStoreProvider.java
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/image/WorldFileStoreProvider.java
index e9c3959cd8..a91f2b5f1e 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/image/WorldFileStoreProvider.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/image/WorldFileStoreProvider.java
@@ -43,7 +43,7 @@ import org.apache.sis.util.ArraysExt;
@StoreMetadata(formatName = WorldFileStoreProvider.NAME,
fileSuffixes = {"jpeg", "jpg", "png", "gif", "bmp"}, //
Non-exhaustive list, intentionally excluding TIFF.
capabilities = {Capability.READ, Capability.WRITE,
Capability.CREATE},
- resourceTypes = GridCoverageResource.class)
+ resourceTypes = {Aggregate.class, GridCoverageResource.class})
public final class WorldFileStoreProvider extends PRJDataStore.Provider {
/**
* The format name.
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/AbstractGridCoverageResource.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/AbstractGridCoverageResource.java
index f188e9fd4f..35950832a0 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/AbstractGridCoverageResource.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/AbstractGridCoverageResource.java
@@ -185,7 +185,7 @@ public abstract class AbstractGridCoverageResource extends
AbstractResource impl
* The log level will be {@link Level#FINE} if the operation was quick
enough,
* or {@link PerformanceLevel#SLOW} or higher level otherwise.
*
- * @param file the file that was opened, or {@code null} for {@link
#getSourceName()}.
+ * @param file the file that was opened, or {@code null} for {@link
StoreListeners#getSourceName()}.
* @param domain domain of the created grid coverage.
* @param startTime value of {@link System#nanoTime()} when the loading
process started.
*/
diff --git
a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
index 0a6daee728..6204dbdbf1 100644
---
a/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
+++
b/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
@@ -320,13 +320,13 @@ public abstract class DataStoreProvider {
* @param <S> the compile-time type of the {@code type} argument
(the source or storage type).
* @param connector information about the storage (URL, stream, JDBC
connection, <i>etc</i>).
* @param type the desired type as one of {@code ByteBuffer},
{@code DataInput}, {@code Connection}
- * class or other types documented in {@link
#getStorageAs(Class)}.
+ * class or other {@linkplain
StorageConnector#getStorageAs(Class) documented types}.
* @param prober the test to apply on the source of the given type.
* @return the result of executing the probe action with a source of the
given type,
* or {@link ProbeResult#UNSUPPORTED_STORAGE} if the given type is
supported
* but no view can be created for the source given at construction
time.
* @throws IllegalArgumentException if the given {@code type} argument is
not one of the supported types.
- * @throws IllegalStateException if this {@code StorageConnector} has been
{@linkplain #closeAllExcept closed}.
+ * @throws IllegalStateException if this {@code StorageConnector} has been
{@linkplain StorageConnector#closeAllExcept closed}.
* @throws DataStoreException if an error occurred while opening a stream
or database connection,
* or during the execution of the probe action.
*
