You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2022/03/26 17:24:16 UTC
[sis] 04/05: Review of abstract class documentation before move to public API.
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 1f56b0d96a73fe4696ee2f43182e181fc4b7d16c
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Sat Mar 26 16:41:02 2022 +0100
Review of abstract class documentation before move to public API.
---
.../sis/internal/storage/AbstractFeatureSet.java | 10 +++----
.../sis/internal/storage/AbstractGridResource.java | 30 ++++++++++++---------
.../sis/internal/storage/AbstractResource.java | 31 ++++++++++++++--------
3 files changed, 43 insertions(+), 28 deletions(-)
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
index 8c1d3d8..ebc73a9 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractFeatureSet.java
@@ -30,15 +30,15 @@ import org.opengis.feature.FeatureType;
/**
- * Base implementation of feature sets contained in data stores. This class provides a {@link #getMetadata()}
- * which extracts information from other methods. Subclasses shall or should override the following methods:
+ * Default implementations of several methods for classes that want to implement the {@link FeatureSet} interface.
+ * Subclasses should override the following methods:
*
* <ul>
* <li>{@link #getType()} (mandatory)</li>
+ * <li>{@link #features(boolean parallel)} (mandatory)</li>
* <li>{@link #getFeatureCount()} (recommended)</li>
* <li>{@link #getEnvelope()} (recommended)</li>
- * <li>{@link #createMetadata(MetadataBuilder)} (optional)</li>
- * <li>{@link #features(boolean parallel)} (mandatory)</li>
+ * <li>{@link #createMetadata()} (optional)</li>
* </ul>
*
* <h2>Thread safety</h2>
@@ -55,7 +55,7 @@ public abstract class AbstractFeatureSet extends AbstractResource implements Fea
/**
* Creates a new resource.
*
- * @param parent listeners of the parent resource, or {@code null} if none.
+ * @param parent listeners of the parent resource or data store, or {@code null} if none.
* This is usually the listeners of the {@link DataStore} that created this resource.
*/
protected AbstractFeatureSet(final StoreListeners parent) {
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractGridResource.java b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractGridResource.java
index 162902b..bf415d0 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractGridResource.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractGridResource.java
@@ -47,13 +47,12 @@ import org.apache.sis.internal.jdk9.JDK9;
/**
- * Base class for implementations of {@link GridCoverageResource}.
- * This class provides default implementations of {@code Resource} methods.
- * Those default implementations get data from the following abstract methods:
+ * Default implementations of several methods for classes that want to implement the {@link GridCoverageResource} interface.
+ * Subclasses should override the following methods:
*
* <ul>
- * <li>{@link #getGridGeometry()}</li>
- * <li>{@link #getSampleDimensions()}</li>
+ * <li>{@link #getGridGeometry()} (mandatory)</li>
+ * <li>{@link #getSampleDimensions()} (mandatory)</li>
* </ul>
*
* This class also provides the following helper methods for implementation
@@ -73,7 +72,7 @@ public abstract class AbstractGridResource extends AbstractResource implements G
/**
* Creates a new resource.
*
- * @param parent listeners of the parent resource, or {@code null} if none.
+ * @param parent listeners of the parent resource or data store, or {@code null} if none.
* This is usually the listeners of the {@link DataStore} that created this resource.
*/
protected AbstractGridResource(final StoreListeners parent) {
@@ -81,12 +80,13 @@ public abstract class AbstractGridResource extends AbstractResource implements G
}
/**
- * Returns the grid geometry envelope if known.
- * This implementation fetches the envelope from the grid geometry.
+ * Returns the envelope of the grid geometry if known.
* The envelope is absent if the grid geometry does not provide this information.
*
* @return the grid geometry envelope.
* @throws DataStoreException if an error occurred while computing the grid geometry.
+ *
+ * @see GridGeometry#getEnvelope()
*/
@Override
public Optional<Envelope> getEnvelope() throws DataStoreException {
@@ -118,15 +118,21 @@ public abstract class AbstractGridResource extends AbstractResource implements G
}
/**
- * Creates an exception for a failure to load data. If the failure may be caused by an envelope
- * outside the resource domain, that envelope will be inferred from the {@code request} argument.
+ * Creates an exception for a failure to load data.
+ * The exception sub-type is inferred from the arguments.
+ * If the failure is caused by an envelope outside the resource domain,
+ * then that envelope will be inferred from the {@code request} argument.
*
* @param filename some identification (typically a file name) of the data that can not be read.
* @param request the requested domain, or {@code null} if unspecified.
* @param cause the cause of the failure, or {@code null} if none.
* @return the exception to throw.
+ *
+ * @see NoSuchDataException
+ * @see DataStoreReferencingException
+ * @see DataStoreContentException
*/
- protected final DataStoreException canNotRead(final String filename, final GridGeometry request, Throwable cause) {
+ protected DataStoreException canNotRead(final String filename, final GridGeometry request, Throwable cause) {
final int DOMAIN = 1, REFERENCING = 2, CONTENT = 3;
int type = 0; // One of above constants, with 0 for "none of above".
Envelope bounds = null;
@@ -175,7 +181,7 @@ public abstract class AbstractGridResource extends AbstractResource implements G
* @param domain domain of the created grid coverage.
* @param startTime value of {@link System#nanoTime()} when the loading process started.
*/
- protected final void logReadOperation(final Object file, final GridGeometry domain, final long startTime) {
+ protected void logReadOperation(final Object file, final GridGeometry domain, final long startTime) {
final Logger logger = listeners.getLogger();
final long nanos = System.nanoTime() - startTime;
final Level level = PerformanceLevel.forDuration(nanos, TimeUnit.NANOSECONDS);
diff --git a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
index f40704e..24f9e4d 100644
--- a/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
+++ b/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/AbstractResource.java
@@ -30,6 +30,7 @@ import org.apache.sis.referencing.CRS;
import org.apache.sis.storage.Resource;
import org.apache.sis.storage.DataStore;
import org.apache.sis.storage.DataStoreException;
+import org.apache.sis.storage.FeatureSet;
import org.apache.sis.storage.event.StoreEvent;
import org.apache.sis.storage.event.StoreListener;
import org.apache.sis.storage.event.StoreListeners;
@@ -39,8 +40,9 @@ import org.apache.sis.xml.NilReason;
/**
- * Base implementation of resources contained in data stores. This class provides a {@link #getMetadata()}
- * method which extracts information from other methods. Subclasses should override the following methods:
+ * Default implementations of several methods for classes that want to implement the {@link Resource} interface.
+ * This class provides a {@link #getMetadata()} method which extracts information from other methods.
+ * Subclasses should override the following methods:
*
* <ul>
* <li>{@link #getIdentifier()} (strongly recommended)</li>
@@ -61,14 +63,16 @@ import org.apache.sis.xml.NilReason;
public abstract class AbstractResource implements Resource {
/**
* The set of registered {@link StoreListener}s for this resources.
- * This {@code StoreListeners} while typically have {@link DataStore#listeners} has a parent.
+ * This {@code StoreListeners} has {@link DataStore#listeners} has a parent.
*/
protected final StoreListeners listeners;
/**
* A description of this resource as an unmodifiable metadata, or {@code null} if not yet computed.
* If non-null, this metadata should contain at least the resource {@linkplain #getIdentifier() identifier}.
- * Those metadata are created by {@link #getMetadata()} when first needed.
+ * Those metadata are created by {@link #createMetadata()} when first needed.
+ *
+ * @see #getMetadata()
*/
private volatile Metadata metadata;
@@ -76,7 +80,7 @@ public abstract class AbstractResource implements Resource {
* Creates a new resource. This resource will have its own set of listeners,
* but the listeners of the data store that created this resource will be notified as well.
*
- * @param parent listeners of the parent resource, or {@code null} if none.
+ * @param parent listeners of the parent resource or data store, or {@code null} if none.
* This is usually the listeners of the {@link DataStore} that created this resource.
*/
protected AbstractResource(final StoreListeners parent) {
@@ -90,8 +94,7 @@ public abstract class AbstractResource implements Resource {
*
* <div class="note"><b>Implementation note:</b>
* the default implementation of {@link #createMetadata()} uses this identifier for initializing
- * the {@code metadata/identificationInfo/citation/title} property. So it is generally not useful
- * to fallback on metadata if the identifier is empty.</div>
+ * the {@code metadata/identificationInfo/citation/title} property.</div>
*/
@Override
public Optional<GenericName> getIdentifier() throws DataStoreException {
@@ -99,9 +102,13 @@ public abstract class AbstractResource implements Resource {
}
/**
- * Returns the spatiotemporal envelope of this resource. This information is part of API only in some kinds of resource
- * like {@link org.apache.sis.storage.FeatureSet}. But the method is provided in this base class for convenience and for
- * allowing {@link #createMetadata()} to use this information if available. The default implementation gives an empty value.
+ * Returns the spatiotemporal envelope of this resource. This information is part of API only in some kinds
+ * of resource such as {@link FeatureSet}. But the method is provided in this base class for convenience.
+ * The default implementation gives an empty value.
+ *
+ * <div class="note"><b>Implementation note:</b>
+ * the default implementation of {@link #createMetadata()} uses this identifier for initializing
+ * the {@code metadata/identificationInfo/extent/geographicElement} property.</div>
*
* @return the spatiotemporal resource extent.
* @throws DataStoreException if an error occurred while reading or computing the envelope.
@@ -114,7 +121,7 @@ public abstract class AbstractResource implements Resource {
* Returns a description of this resource. This method invokes {@link #createMetadata()}
* in a synchronized block when first needed, then caches the result.
*
- * @return information about this resource (never {@code null} in this implementation).
+ * @return information about this resource (never {@code null}).
* @throws DataStoreException if an error occurred while reading or computing the metadata.
*/
@Override
@@ -159,12 +166,14 @@ public abstract class AbstractResource implements Resource {
* {@link #createMetadata()} to be invoked again when first needed.
*/
protected void clearCache() {
+ // No need for synchronization because `metadata` is volatile.
metadata = null;
}
/**
* Returns the object on which to perform synchronizations for thread-safety.
* The default implementation returns {@code this}.
+ * Subclasses can override for example for synchronizing everything on an enclosing {@link DataStore}.
*
* @return the synchronization lock.
*/