sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1592709 - in /sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature: DefaultAttribute.java DefaultAttributeType.java DefaultFeature.java DefaultFeatureType.java package-info.java
Date Tue, 06 May 2014 10:56:20 GMT
Author: desruisseaux
Date: Tue May  6 10:56:19 2014
New Revision: 1592709

URL: http://svn.apache.org/r1592709
Log:
More documentation.

Modified:
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttribute.java
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttributeType.java
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeature.java
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeatureType.java
    sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/package-info.java

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttribute.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttribute.java?rev=1592709&r1=1592708&r2=1592709&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttribute.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttribute.java
[UTF-8] Tue May  6 10:56:19 2014
@@ -25,7 +25,7 @@ import java.util.Objects;
 
 
 /**
- * Holds the value of an attribute in a feature.
+ * An instance of an {@linkplain DefaultAttributeType attribute type} containing the value
of an attribute in a feature.
  * {@code Attribute} holds two main information:
  *
  * <ul>
@@ -104,7 +104,8 @@ public class DefaultAttribute<T> impleme
      *
      * @param  value The new value.
      * @throws RuntimeException If this method performs validation and the given value does
not meet the conditions.
-     *         <em>This exception will be changed to {@code IllegalAttributeException}
in a future SIS version.</em>
+     *         <span style="color:firebrick">This exception will be changed to {@code
IllegalAttributeException} in a
+     *         future SIS version.</span>
      *
      * @see DefaultFeature#setAttributeValue(String, Object)
      */
@@ -118,7 +119,8 @@ public class DefaultAttribute<T> impleme
      * {@link DefaultFeature#validate()}.
      *
      * @throws RuntimeException If the current attribute value violates a constraint.
-     *         <em>This exception will be changed to {@code IllegalAttributeException}
in a future SIS version.</em>
+     *         <span style="color:firebrick">This exception will be changed to {@code
IllegalAttributeException}
+     *         in a future SIS version.</span>
      *
      * @see DefaultFeature#validate()
      */

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttributeType.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttributeType.java?rev=1592709&r1=1592708&r2=1592709&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttributeType.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultAttributeType.java
[UTF-8] Tue May  6 10:56:19 2014
@@ -18,6 +18,7 @@ package org.apache.sis.feature;
 
 import java.util.Map;
 import org.opengis.util.GenericName;
+import org.opengis.util.InternationalString;
 import org.apache.sis.util.Debug;
 import org.apache.sis.util.Classes;
 import org.apache.sis.util.resources.Errors;
@@ -45,6 +46,18 @@ import java.util.Objects;
  * When such interface will be available, most references to {@code DefaultAttributeType}
in the API
  * will be replaced by references to the {@code AttributeType} interface.</div>
  *
+ * {@section Value type}
+ * Attributes can be used for both spatial and non-spatial properties.
+ * Some examples are:
+ *
+ * <table class="sis">
+ *   <caption>Attribute value type examples</caption>
+ *   <tr><th>Attribute name</th>      <th>Value type</th></tr>
+ *   <tr><td>Building shape</td>      <td>{@link org.opengis.geometry.Geometry}</td></tr>
+ *   <tr><td>Building owner</td>      <td>{@link org.opengis.metadata.citation.ResponsibleParty}</td></tr>
+ *   <tr><td>Horizontal accuracy</td> <td>{@link org.opengis.metadata.quality.PositionalAccuracy}</td></tr>
+ * </table>
+ *
  * {@section Immutability and thread safety}
  * Instances of this class are immutable if all properties ({@link GenericName} and {@link
InternationalString}
  * instances) and all arguments (default value, cardinality) given to the constructor are
also immutable.

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeature.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeature.java?rev=1592709&r1=1592708&r2=1592709&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeature.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeature.java
[UTF-8] Tue May  6 10:56:19 2014
@@ -32,7 +32,7 @@ import java.util.Objects;
 
 
 /**
- * An instance of {@linkplain DefaultFeatureType feature type} containing values for a real-world
phenomena.
+ * An instance of a {@linkplain DefaultFeatureType feature type} containing values for a
real-world phenomena.
  *
  * {@section Usage in multi-thread environment}
  * {@code DefaultFeature} are <strong>not</strong> thread-safe.
@@ -197,7 +197,8 @@ public class DefaultFeature implements S
      * @param  value The new value for the given attribute (may be {@code null}).
      * @throws IllegalArgumentException If the given argument is not an attribute name of
this feature.
      * @throws RuntimeException If this method performs validation and the given value does
not meet the conditions.
-     *         <em>This exception will be changed to {@code IllegalAttributeException}
in a future SIS version.</em>
+     *         <span style="color:firebrick">This exception will be changed to {@code
IllegalAttributeException} in
+     *         a future SIS version.</span>
      *
      * @see DefaultAttribute#setValue(Object)
      */
@@ -255,7 +256,8 @@ public class DefaultFeature implements S
      * This method will implicitly invokes {@link DefaultAttribute#validate()} for all attribute
values.
      *
      * @throws RuntimeException If the current attribute value violates a constraint.
-     *         <em>This exception will be changed to {@code IllegalAttributeException}
in a future SIS version.</em>
+     *         <span style="color:firebrick">This exception will be changed to {@code
IllegalAttributeException}
+     *         in a future SIS version.</span>
      *
      * @see DefaultAttribute#validate()
      */

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeatureType.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeatureType.java?rev=1592709&r1=1592708&r2=1592709&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeatureType.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/DefaultFeatureType.java
[UTF-8] Tue May  6 10:56:19 2014
@@ -26,6 +26,7 @@ import java.io.IOException;
 import java.io.ObjectInputStream;
 import java.lang.reflect.Field;
 import org.opengis.util.GenericName;
+import org.opengis.util.InternationalString;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.resources.Errors;
 import org.apache.sis.util.collection.Containers;

Modified: sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/package-info.java?rev=1592709&r1=1592708&r2=1592709&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-feature/src/main/java/org/apache/sis/feature/package-info.java
[UTF-8] Tue May  6 10:56:19 2014
@@ -21,21 +21,42 @@
  * The term “feature” may be used in different contexts:
  *
  * <ul>
- *   <li>{@linkplain org.apache.sis.feature.DefaultFeatureType Feature types} define
the <em>structure</em> of a
- *       real-world representation. A feature type lists the attributes, operations, or associations
to other
+ *   <li>{@linkplain org.apache.sis.feature.DefaultFeatureType Feature types} define
the <em>structure</em> of
+ *       real-world representations. A feature type lists the attributes, operations, or
associations to other
  *       features (collectively called “properties”) that a feature can have.
  *
  *       <div class="note"><b>Note:</b> a {@code FeatureType} in a Spatial
Information System is equivalent to a
  *       {@link java.lang.Class} in the Java language. By extension, {@code AttributeType}
and {@code OperationType}
  *       are equivalent to {@link java.lang.reflect.Field} and {@link java.lang.reflect.Method}
respectively.</div></li>
  *
- *   <li>{@linkplain org.apache.sis.feature.DefaultFeature Feature instances} holds
the <em>content</em> (or values)
- *       that describe one specific real-world object. For example the “Eiffel tower”
is a feature <em>instance</em>
- *       belonging to the “Tower” feature <em>type</em>.
+ *   <li>{@linkplain org.apache.sis.feature.DefaultFeature Feature instances} (often
called only {@code Feature}s)
+ *       hold the <em>content</em> (or values) that describe one specific real-world
object.
  *
- *       <div class="note"><b>Note:</b> feature instances are often called
only {@code Feature}s.</div></li>
+ *       <div class="note"><b>Example:</b> the “Eiffel tower” is a
feature <em>instance</em> belonging
+ *       to the “Tower” feature <em>type</em>.</div></li>
  * </ul>
  *
+ * {@section Class hierarchy}
+ * The class hierarchy for features <cite>types</cite> and <cite>instances</cite>
are closely related:
+ *
+ * <table class="sis">
+ * <caption>Class hierarchy</caption>
+ * <tr>
+ *   <th>Types</th>
+ *   <th class="sep">Instances</th>
+ * </tr><tr><td style="width: 50%; white-space: nowrap">
+ *                 {@linkplain org.apache.sis.feature.AbstractIdentifiedType    Identified
type}<br>
+ * {@code  ├─}     {@linkplain org.apache.sis.feature.DefaultFeatureType        Feature
type}<br>
+ * {@code  └─}     {@linkplain org.apache.sis.feature.AbstractPropertyType      Property
type}<br>
+ * {@code      ├─} {@linkplain org.apache.sis.feature.DefaultAttributeType     
Attribute type}<br>
+ * {@code      ├─} {@linkplain org.apache.sis.feature.DefaultOperation         
Operation}<br>
+ * {@code      └─} {@linkplain org.apache.sis.feature.DefaultFeatureAssociation
Feature association role}<br>
+ * </td><td class="sep" style="width: 50%; white-space: nowrap">
+ *             {@linkplain org.apache.sis.feature.DefaultFeature    Feature}<br>
+ *             {@linkplain org.apache.sis.feature.AbstractProperty  Property}<br>
+ * {@code  └─} {@linkplain org.apache.sis.feature.DefaultAttribute  Attribute}<br>
+ * </td></tr></table>
+ *
  * @author  Travis L. Pinney
  * @author  Johann Sorel (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)



Mime
View raw message