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>
*
