Author: desruisseaux Date: Tue Feb 20 15:24:12 2018 New Revision: 1824890 URL: http://svn.apache.org/viewvc?rev=1824890&view=rev Log: Javadoc on org.apache.sis.storage.Resource and subtypes.
Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/FileSystemResource.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/ResourceTransaction.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TransactionalResource.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Capability.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/FileSystemResource.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/FileSystemResource.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/FileSystemResource.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/FileSystemResource.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -20,24 +20,28 @@ import java.nio.file.Path; import org.apache.sis.storage.DataStoreException; import org.apache.sis.storage.Resource; + /** - * Files-related {@linkplain org.apache.sis.storage.Resource resource}. - * This interface allows a resource to indicate it's used files, it - * can then be used to improve data management. + * A resource which is loaded from one or many files on an arbitrary file system. This interface + * allows a resource (typically a {@linkplain org.apache.sis.storage.DataStore data store}) to + * list the files that it uses. This information can be used for improving data management, + * for example copy operations. * - * @author Johann Sorel (Geomatys) - * @since 1.0 + * @author Johann Sorel (Geomatys) + * @version 1.0 + * @since 1.0 * @module + * + * @todo Current name suggests resources provided by the file system (i.e. files and directories). + * Rename as {@code FileBackedResource}, {@code ResourceBackedByFiles} or {@code ResourceOnFileSystem}? */ public interface FileSystemResource extends Resource { - /** - * Get all files used by this {@linkplain org.apache.sis.storage.DataStore data store}. + * Gets the paths to all files used by this resource. This is typically the + * files opened by a {@linkplain org.apache.sis.storage.DataStore data store}. * - * @return Files used by this store. Should never be {@code null}. - * @throws org.apache.sis.storage.DataStoreException if an error on the file system prevent - * the creation of the list. + * @return files used by this resource. Should never be {@code null}. + * @throws DataStoreException if an error on the file system prevent the creation of the list. */ Path[] getResourcePaths() throws DataStoreException; - } Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/ResourceTransaction.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/ResourceTransaction.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/ResourceTransaction.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/ResourceTransaction.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -20,29 +20,36 @@ import org.apache.sis.storage.Aggregate; import org.apache.sis.storage.DataStoreException; import org.apache.sis.storage.Resource; + /** - * A transaction resource. - * This transaction include both this resource and all children resources - * if it is an {@linkplain Aggregate}. + * A writable resource containing data (features or coverages) that can be changed in a all-or-nothing way. + * Resource transaction shall also implement at least one of the {@code Writable*} interfaces. + * If the resource is an {@link Aggregate}, then this transaction includes both this resource + * and all children resources. * - * @author Johann Sorel (Geomatys) - * @since 1.0 + * @author Johann Sorel (Geomatys) + * @version 1.0 + * @since 1.0 * @module */ public interface ResourceTransaction extends Resource { - /** - * Apply all the changes made in this transaction. + * Makes permanent all changes that have been in current transaction. + * The current transaction contains the changes performed since the {@code ResourceTransaction} + * creation, or since the last call to either the {@code commit()} or {@link #rollback()} methods. * - * @throws DataStoreException + * @throws DataStoreException if an error occurred while committing the transaction. + * In such case, the system shall be in state before the commit attempt. */ void commit() throws DataStoreException; /** - * Revert all changes made in this session. + * Undoes all changes made in the current transaction. + * The current transaction contains the changes performed since the {@code ResourceTransaction} + * creation, or since the last call to either the {@link #commit()} or {@code rollback()} methods. * - * @throws DataStoreException + * @throws DataStoreException if an error occurred while rolling back the transaction. + * In such case, the system shall be in state before the rollback attempt. */ void rollback() throws DataStoreException; - } Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TransactionalResource.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TransactionalResource.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TransactionalResource.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/TransactionalResource.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -16,27 +16,32 @@ */ package org.apache.sis.internal.storage; +import org.apache.sis.storage.DataStore; import org.apache.sis.storage.DataStoreException; import org.apache.sis.storage.Resource; + /** - * This interface identify resources which support a transactional procedure. - * Example : Databases, WFS + * Identifies resources capable to create transactions. A {@code TransactionalResource} is not directly writable, + * but the transactions created by {@link #newTransaction()} are writable. Each transaction is a unit of work + * independent of other transactions until a commit or rollback operation is performed. + * + * <p>Common cases of transactional resources are {@link DataStore} backed by databases or by + * transactional Web Feature Services (WFS-T).</p> * - * @author Johann Sorel (Geomatys) - * @since 1.0 + * @author Johann Sorel (Geomatys) + * @version 1.0 + * @since 1.0 * @module */ public interface TransactionalResource extends Resource { - /** - * Start a new transaction on this resource. - * The returned resource should have the same capabilities of this - * resource and writing capabilities. + * Starts a new transaction on this resource. + * The returned resource should have the same capabilities than this resource + * with the addition of write capabilities. * - * @return new TransactionResource - * @throws org.apache.sis.storage.DataStoreException + * @return a new writable resource that can be changed in a all-or-nothing way. + * @throws DataStoreException if an error occurred while creating the transaction. */ ResourceTransaction newTransaction() throws DataStoreException; - } Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Aggregate.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -54,7 +54,7 @@ import java.util.Collection; * associated resources} with an {@link org.opengis.metadata.identification.AssociationType#IS_COMPOSED_OF} relation. * * @author Johann Sorel (Geomatys) - * @version 0.8 + * @version 1.0 * @since 0.8 * @module */ @@ -86,5 +86,4 @@ public interface Aggregate extends Resou * @throws DataStoreException if an error occurred while fetching the components. */ Collection<Resource> components() throws DataStoreException; - } Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Capability.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Capability.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Capability.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Capability.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -17,18 +17,21 @@ package org.apache.sis.storage; import java.util.ArrayList; +import java.util.Iterator; import java.util.List; import org.opengis.util.CodeList; + import static org.opengis.util.CodeList.valueOf; + /** - * A capability indicate a special behavior or information for a {@link Resource}. - * Capabilities are used as flags returned by the {@link Resource#getCapabilities() } method. + * Indicates which optional behavior or information can be provided by a {@link Resource}. + * Capabilities are used as flags returned by the {@link Resource#getCapabilities()} method. * - * A common {@link Capability} is {@link Capability#WRITABLE} which should be declared - * accordingly by {@link Resource}s. + * A commonly used value is {@link Capability#WRITABLE}, which should be declared by all + * {@link Resource}s implementing {@code add(…)} and {@code update(…)} methods. * - * @author Johann Sorel (Geomatys) + * @author Johann Sorel (Geomatys) * @version 1.0 * @since 1.0 * @module @@ -43,12 +46,12 @@ public final class Capability extends Co * List of all enumerations of this type. * Must be declared before any enum declaration. */ - private static final List<Capability> VALUES = new ArrayList<>(); + private static final List<Capability> VALUES = new ArrayList<>(1); /** - * The resource support writing operations. - * The methods related to writing such as {@link org.apache.sis.storage.WritableFeatureSet#add(java.util.Iterator) } - * should not throw any unsupported exception if this capability is set. + * The resource supports write operations. + * The methods related to writing such as {@link org.apache.sis.storage.WritableFeatureSet#add(Iterator)} + * should not throw any {@link UnsupportedOperationException} if this capability is set. */ public static final Capability WRITABLE = new Capability("WRITABLE"); @@ -100,4 +103,3 @@ public final class Capability extends Co return valueOf(Capability.class, code); } } - Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/FeatureSet.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -16,8 +16,9 @@ */ package org.apache.sis.storage; -// Branch-dependent imports import java.util.stream.Stream; + +// Branch-dependent imports import org.opengis.feature.Feature; import org.opengis.feature.FeatureType; @@ -30,7 +31,7 @@ import org.opengis.feature.FeatureType; * are also allowed. * * @author Johann Sorel (Geomatys) - * @version 0.8 + * @version 1.0 * @since 0.8 * @module */ @@ -135,5 +136,4 @@ public interface FeatureSet extends Data * @throws DataStoreException if an error occurred while creating the stream. */ Stream<Feature> features(boolean parallel) throws DataStoreException; - } Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -107,17 +107,18 @@ public interface Resource { Metadata getMetadata() throws DataStoreException; /** - * Returns the capabilities of this resource. - * Resources may have different capabilites based on the type and context.<br> - * Example : {@link Capability#WRITABLE} can be found on {@link Aggregate} or - * {@link FeatureSet} to indicate the resource support writing operations. + * Indicates which optional behavior or information can be provided by this resource. + * Resources may have different capabilites based on the type and context. + * + * <div class="note"><b>Example:</b> + * {@link Capability#WRITABLE} can be found on {@link WritableAggregate} or {@link WritableFeatureSet} + * to indicate that the resource supports write operations.</div> * * <p>The default implementation returns an empty Set.</p> * - * @return Set of {@link Capability}, never null, unmodifiable, can be empty. + * @return supported capabilities (never null). May be empty. */ default Set<Capability> getCapabilities() { - return Collections.EMPTY_SET; + return Collections.emptySet(); } - } Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableAggregate.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -18,16 +18,16 @@ package org.apache.sis.storage; import org.apache.sis.internal.storage.Resources; + /** - * Subtype of {@linkplain Aggregate} with writing capabilities. + * An {@linkplain Aggregate} with writing capabilities. * - * @author Johann Sorel (Geomatys) + * @author Johann Sorel (Geomatys) * @version 1.0 * @since 1.0 * @module */ public interface WritableAggregate extends Aggregate { - /** * Adds a new {@code Resource} in this {@code Aggregate}. * The given {@link Resource} will be copied, and the <cite>effectively added</cite> resource returned. @@ -46,8 +46,8 @@ public interface WritableAggregate exten * then this {@code Aggregate} may throw an exception. * </div> * - * <p>The {@link Capability#WRITABLE} flag if present in the {@link Resource#getCapabilities() } set - * indicate this method should be implemented</p> + * <p>The {@link Capability#WRITABLE} flag if presents in the {@link #getCapabilities()} set + * indicates that this method should be implemented.</p> * * <p>The default implementation throws {@link ReadOnlyStorageException}.</p> * @@ -64,8 +64,8 @@ public interface WritableAggregate exten * Removes a {@code Resource} from this {@code Aggregate}. * This operation is destructive: the {@link Resource} and it's related data will be removed. * - * <p>The {@link Capability#WRITABLE} flag if present in the {@link Resource#getCapabilities() } set - * indicate this method should be implemented</p> + * <p>The {@link Capability#WRITABLE} flag if presents in the {@link #getCapabilities()} set + * indicates that this method should be implemented.</p> * * <p>The default implementation throws {@link ReadOnlyStorageException}.</p> * @@ -76,5 +76,4 @@ public interface WritableAggregate exten default void remove(Resource resource) throws ReadOnlyStorageException, DataStoreException { throw new ReadOnlyStorageException(this, Resources.Keys.StoreIsReadOnly); } - } Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java?rev=1824890&r1=1824889&r2=1824890&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/WritableFeatureSet.java [UTF-8] Tue Feb 20 15:24:12 2018 @@ -20,41 +20,37 @@ import java.util.Iterator; import java.util.function.Predicate; import java.util.function.UnaryOperator; import org.apache.sis.internal.storage.Resources; + +// Branch-dependent imports import org.opengis.feature.Feature; import org.opengis.feature.FeatureType; + /** * Subtype of {@linkplain FeatureSet} with writing capabilities. * - * @author Johann Sorel (Geomatys) + * @author Johann Sorel (Geomatys) * @version 1.0 * @since 1.0 * @module */ public interface WritableFeatureSet extends FeatureSet { - /** - * Redefine the feature type of this feature set, including all features. - * This operation may take an undefined time since all features in the set must be transformed. - * - * <p> - * An {@linkplain org.apache.sis.storage.IllegalFeatureTypeException} will be throw - * when the provided type contains incompatible attribute changes. - * </p> - * - * <p> - * In the case of a newly created feature set, this method can be used to define - * stored feature type. - * </p> - * - * <p> - * Default implementation throw a {@linkplain org.apache.sis.storage.ReadOnlyStorageException}. - * </p> - * - * @param newType new feature type definition, (not {@code null}). - * @throws ReadOnlyStorageException if this instance does not support schema update - * @throws IllegalFeatureTypeException if the given type is not compatible - * @throws DataStoreException if another error occurred while changing feature type. + * Declares or redefines the type of all feature instances in this feature set. + * In the case of a newly created feature set, this method can be used for defining the type of features + * to be stored (this is not a required step however). In the case of a feature set which already contains + * feature instances, this operation may take an undefined amount of time to execute since all features in + * the set may need to be transformed. + * + * <p>Feature sets may restrict the kind of changes that are allowed. An {@link IllegalFeatureTypeException} + * will be thrown if the given type contains incompatible property changes.</p> + * + * <p>The default implementation throws a {@linkplain ReadOnlyStorageException}.</p> + * + * @param newType new feature type definition (not {@code null}). + * @throws ReadOnlyStorageException if this instance does not support schema update. + * @throws IllegalFeatureTypeException if the given type is not compatible with the types supported by the store. + * @throws DataStoreException if another error occurred while changing the feature type. */ default void updateType(FeatureType newType) throws ReadOnlyStorageException, IllegalFeatureTypeException, DataStoreException { throw new ReadOnlyStorageException(this, Resources.Keys.StoreIsReadOnly); @@ -70,8 +66,8 @@ public interface WritableFeatureSet exte * than implementing a {@link java.util.stream.Stream}. On the other side if the user has a {@link java.util.stream.Stream}, * obtaining an {@link java.util.Iterator} can be done by a call to {@link java.util.stream.Stream#iterator()}.</div> * - * <p>The {@link Capability#WRITABLE} flag if present in the {@link Resource#getCapabilities() } set - * indicate this method should be implemented</p> + * <p>The {@link Capability#WRITABLE} flag if presents in the {@link #getCapabilities()} set + * indicates that this method should be implemented.</p> * * <p>The default implementation throws {@link ReadOnlyStorageException}.</p> * @@ -86,8 +82,8 @@ public interface WritableFeatureSet exte /** * Removes all features from this {@code FeatureSet} which matches the given predicate. * - * <p>The {@link Capability#WRITABLE} flag if present in the {@link Resource#getCapabilities() } set - * indicate this method should be implemented</p> + * <p>The {@link Capability#WRITABLE} flag if presents in the {@link #getCapabilities()} set + * indicates that this method should be implemented.</p> * * <p>The default implementation throws {@link ReadOnlyStorageException}.</p> * @@ -112,8 +108,8 @@ public interface WritableFeatureSet exte * <li>If the operator returns {@code null}, then the feature will be removed from the {@code FeatureSet}.</li> * </ul> * - * <p>The {@link Capability#WRITABLE} flag if present in the {@link Resource#getCapabilities() } set - * indicate this method should be implemented</p> + * <p>The {@link Capability#WRITABLE} flag if presents in the {@link #getCapabilities()} set + * indicates that this method should be implemented.</p> * * <p>The default implementation throws {@link ReadOnlyStorageException}.</p> *