sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1479132 - in /sis/branches/JDK7: sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java sis-utility/src/main/java/org/apache/sis/util/Static.java
Date Sat, 04 May 2013 15:51:12 GMT
Author: desruisseaux
Date: Sat May  4 15:51:03 2013
New Revision: 1479132

URL: http://svn.apache.org/r1479132
Log:
Added Javadoc about the TreeTable.

Modified:
    sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
    sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Static.java

Modified: sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java?rev=1479132&r1=1479131&r2=1479132&view=diff
==============================================================================
--- sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] (original)
+++ sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] Sat May  4 15:51:03 2013
@@ -41,19 +41,25 @@ import org.apache.sis.util.logging.Loggi
  * The methods that modify the metadata may throw {@link UnmodifiableMetadataException} if
the
  * metadata does not support the operation. Those methods are:
  *
- * <ul>
- *   <li>{@link #prune()}</li>
- *   <li>{@link #asMap()} with {@code put} operations</li>
- * </ul>
- *
- * Read-only operations operating on metadata values are:
- *
- * <ul>
- *   <li>{@link #isEmpty()}</li>
- *   <li>{@link #asMap()} with {@code get} operations</li>
- *   <li>{@link #asTreeTable()}</li>
- *   <li>{@link #equals(Object, ComparisonMode)}</li>
- * </ul>
+ * <table class="sis">
+ * <tr>
+ *   <th>Read-only operations</th>
+ *   <th class="sep">Read/write operations</th>
+ * </tr>
+ * <tr>
+ *   <td><ul>
+ *     <li>{@link #isEmpty()}</li>
+ *     <li>{@link #asMap()} with {@code get} operations</li>
+ *     <li>{@link #asTreeTable()} with {@code getValue} operations</li>
+ *     <li>{@link #equals(Object, ComparisonMode)}</li>
+ *   </ul></td>
+ *   <td class="sep"><ul>
+ *     <li>{@link #prune()}</li>
+ *     <li>{@link #asMap()} with {@code put} operations</li>
+ *     <li>{@link #asTreeTable()} with {@code setValue} operations</li>
+ *   </ul></td>
+ * </tr>
+ * </table>
  *
  * Instances of this class are <strong>not</strong> synchronized for multi-threading.
  * Synchronization, if needed, is caller's responsibility. Note that synchronization locks
@@ -155,25 +161,29 @@ public abstract class AbstractMetadata i
      * object, so changes in the underlying metadata object are immediately reflected in
the map
      * and conversely.
      *
-     * <p>The map supports the {@link Map#put(Object, Object) put(…)} and {@link
Map#remove(Object)
+     * {@section Supported operations}
+     * The map supports the {@link Map#put(Object, Object) put(…)} and {@link Map#remove(Object)
      * remove(…)} operations if the underlying metadata object contains setter methods.
-     * The {@code remove(…)} method is implemented by a call to {@code put(…, null)}.</p>
+     * The {@code remove(…)} method is implemented by a call to {@code put(…, null)}.
      *
-     * <p>The keys are case-insensitive and can be either the JavaBeans property name,
the getter method name
+     * {@section Keys and values}
+     * The keys are case-insensitive and can be either the JavaBeans property name, the getter
method name
      * or the {@linkplain org.opengis.annotation.UML#identifier() UML identifier}. The value
given to a call
      * to the {@code put(…)} method shall be an instance of the type expected by the corresponding
setter method,
      * or an instance of a type {@linkplain org.apache.sis.util.ObjectConverters#find(Class,
Class) convertible}
-     * to the expected type.</p>
+     * to the expected type.
      *
-     * <p>Calls to {@code put(…)} replace the previous value, with one noticeable
exception: if the metadata
+     * {@section Multi-values entries}
+     * Calls to {@code put(…)} replace the previous value, with one noticeable exception:
if the metadata
      * property associated to the given key is a {@link java.util.Collection} but the given
value is a single
      * element (not a collection), then the given value is {@linkplain java.util.Collection#add(Object)
added}
      * to the existing collection. In other words, the returned map behaves as a <cite>multi-values
map</cite>
      * for the properties that allow multiple values. If the intend is to unconditionally
discard all previous
      * values, then make sure that the given value is a collection when the associated metadata
property expects
-     * such collection.</p>
+     * such collection.
      *
-     * <p>The default implementation is equivalent to the following method call:</p>
+     * {@section Default implementation}
+     * The default implementation is equivalent to the following method call:
      *
      * {@preformat java
      *   return getStandard().asValueMap(this, KeyNamePolicy.JAVABEANS_PROPERTY, ValueExistencePolicy.NON_EMPTY);
@@ -195,7 +205,55 @@ public abstract class AbstractMetadata i
      * The tree table is backed by the metadata object using Java reflection, so changes
in the
      * underlying metadata object are immediately reflected in the tree table and conversely.
      *
-     * <p>The default implementation is equivalent to the following method call:</p>
+     * <p>The returned {@code TreeTable} instance contains the following columns:</p>
+     * <ul>
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#IDENTIFIER}<br>
+     *       The {@linkplain org.opengis.annotation.UML#identifier() UML identifier} if any,
+     *       or the Java Beans property name otherwise, of a metadata property. For example
+     *       in a tree table view of {@link org.apache.sis.metadata.iso.citation.DefaultCitation},
+     *       there is a node having the {@code "title"} identifier.</p></li>
+     *
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#INDEX}<br>
+     *       If the metadata property is a collection, then the zero-based index of the element
in that collection.
+     *       Otherwise {@code null}. For example in a tree table view of {@code DefaultCitation},
if the
+     *       {@code "alternateTitle"} collection contains two elements, then there is a node
with index 0
+     *       for the first element and an other node with index 1 for the second element.</p>
+     *
+     *       <p>The {@code (IDENTIFIER, INDEX)} pair can be used as a primary key for
uniquely identifying
+     *       a node in a list of children. Note that the uniqueness is guaranteed only for
the children of
+     *       a given node; the same keys may appear in the children of any other nodes.</p></li>
+     *
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#NAME}<br>
+     *       A human-readable name for the node, derived from the identifier and the index.
+     *       This is the column shown in the default {@link #toString()} implementation and
+     *       may be localizable.</p></li>
+     *
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#TYPE}<br>
+     *       The base type of the value (usually an interface).</p></li>
+     *
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#VALUE}<br>
+     *       The metadata value for the node. Values in this column are writable if the underlying
+     *       metadata class have a setter method for the property represented by the node.</p></li>
+     * </ul>
+     *
+     * {@section Write operations}
+     * Only the {@code VALUE} column may be writable, with one exception: newly created children
need
+     * to have their {@code IDENTIFIER} set before any other operation. For example the following
code
+     * adds a title to a citation:
+     *
+     * {@preformat java
+     *     TreeTable.Node node = ...; // The node for a DefaultCitation.
+     *     TreeTable.Node child = node.newChild();
+     *     child.setValue(TableColumn.IDENTIFIER, "title");
+     *     child.setValue(TableColumn.VALUE, "Le petit prince");
+     *     // Nothing else to do - the child node has been added.
+     * }
+     *
+     * Nodes can be removed by invoking the {@link java.util.Iterator#remove()} method on
the
+     * {@linkplain org.apache.sis.util.collection.TreeTable.Node#getChildren() children}
iterator.
+     *
+     * {@section Default implementation}
+     * The default implementation is equivalent to the following method call:
      *
      * {@preformat java
      *   return getStandard().asTreeTable(this, ValueExistencePolicy.NON_EMPTY);

Modified: sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java?rev=1479132&r1=1479131&r2=1479132&view=diff
==============================================================================
--- sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] (original)
+++ sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] Sat May  4 15:51:03 2013
@@ -580,25 +580,28 @@ public class MetadataStandard implements
      * {@code valuePolicy} determines whether entries having a null value or an empty collection
      * shall be included in the map.</p>
      *
-     * <p>The map supports the {@link Map#put(Object, Object) put(…)} and {@link
Map#remove(Object)
+     * {@section Supported operations}
+     * The map supports the {@link Map#put(Object, Object) put(…)} and {@link Map#remove(Object)
      * remove(…)} operations if the underlying metadata object contains setter methods.
      * The {@code remove(…)} method is implemented by a call to {@code put(…, null)}.
      * Note that whether the entry appears as effectively removed from the map or just cleared
-     * (i.e. associated to a null value) depends on the {@code valuePolicy} argument.</p>
+     * (i.e. associated to a null value) depends on the {@code valuePolicy} argument.
      *
-     * <p>The keys are case-insensitive and can be either the JavaBeans property name,
the getter method name
+     * {@section Keys and values}
+     * The keys are case-insensitive and can be either the JavaBeans property name, the getter
method name
      * or the {@linkplain org.opengis.annotation.UML#identifier() UML identifier}. The value
given to a call
      * to the {@code put(…)} method shall be an instance of the type expected by the corresponding
setter method,
      * or an instance of a type {@linkplain org.apache.sis.util.ObjectConverters#find(Class,
Class) convertible}
-     * to the expected type.</p>
+     * to the expected type.
      *
-     * <p>Calls to {@code put(…)} replace the previous value, with one noticeable
exception: if the metadata
+     * {@section Multi-values entries}
+     * Calls to {@code put(…)} replace the previous value, with one noticeable exception:
if the metadata
      * property associated to the given key is a {@link java.util.Collection} but the given
value is a single
      * element (not a collection), then the given value is {@linkplain java.util.Collection#add(Object)
added}
      * to the existing collection. In other words, the returned map behaves as a <cite>multi-values
map</cite>
      * for the properties that allow multiple values. If the intend is to unconditionally
discard all previous
      * values, then make sure that the given value is a collection when the associated metadata
property expects
-     * such collection.</p>
+     * such collection.
      *
      * @param  metadata The metadata object to view as a map.
      * @param  keyPolicy Determines the string representation of map keys.
@@ -624,6 +627,55 @@ public class MetadataStandard implements
      * The tree table is backed by the metadata object using Java reflection, so changes
in the
      * underlying metadata object are immediately reflected in the tree table and conversely.
      *
+     * <p>The returned {@code TreeTable} instance contains the following columns:</p>
+     * <ul>
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#IDENTIFIER}<br>
+     *       The {@linkplain org.opengis.annotation.UML#identifier() UML identifier} if any,
+     *       or the Java Beans property name otherwise, of a metadata property. For example
+     *       in a tree table view of {@link org.apache.sis.metadata.iso.citation.DefaultCitation},
+     *       there is a node having the {@code "title"} identifier.</p></li>
+     *
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#INDEX}<br>
+     *       If the metadata property is a collection, then the zero-based index of the element
in that collection.
+     *       Otherwise {@code null}. For example in a tree table view of {@code DefaultCitation},
if the
+     *       {@code "alternateTitle"} collection contains two elements, then there is a node
with index 0
+     *       for the first element and an other node with index 1 for the second element.</p>
+     *
+     *       <p>The {@code (IDENTIFIER, INDEX)} pair can be used as a primary key for
uniquely identifying
+     *       a node in a list of children. Note that the uniqueness is guaranteed only for
the children of
+     *       a given node; the same keys may appear in the children of any other nodes.</p></li>
+     *
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#NAME}<br>
+     *       A human-readable name for the node, derived from the identifier and the index.
+     *       This is the column shown in the default {@link #toString()} implementation and
+     *       may be localizable.</p></li>
+     *
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#TYPE}<br>
+     *       The base type of the value (usually an interface).</p></li>
+     *
+     *   <li><p>{@link org.apache.sis.util.collection.TableColumn#VALUE}<br>
+     *       The metadata value for the node. Values in this column are writable if the underlying
+     *       metadata class have a setter method for the property represented by the node.</p></li>
+     * </ul>
+     *
+     * {@section Write operations}
+     * Only the {@code VALUE} column may be writable, with one exception: newly created children
need
+     * to have their {@code IDENTIFIER} set before any other operation. For example the following
code
+     * adds a title to a citation:
+     *
+     * {@preformat java
+     *     TreeTable.Node node = ...; // The node for a DefaultCitation.
+     *     TreeTable.Node child = node.newChild();
+     *     child.setValue(TableColumn.IDENTIFIER, "title");
+     *     child.setValue(TableColumn.VALUE, "Le petit prince");
+     *     // Nothing else to do - the child node has been added.
+     * }
+     *
+     * Nodes can be removed by invoking the {@link java.util.Iterator#remove()} method on
the
+     * {@linkplain org.apache.sis.util.collection.TreeTable.Node#getChildren() children}
iterator.
+     * Note that whether the child appears as effectively removed from the node or just cleared
+     * (i.e. associated to a null value) depends on the {@code valuePolicy} argument.
+     *
      * @param  metadata The metadata object to view as a tree table.
      * @param  valuePolicy Whether the property having null value or empty collection shall
be
      *         included in the tree.

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Static.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Static.java?rev=1479132&r1=1479131&r2=1479132&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Static.java [UTF-8] (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Static.java [UTF-8] Sat
May  4 15:51:03 2013
@@ -22,7 +22,7 @@ package org.apache.sis.util;
  * purpose only. The list below summarizes some of the utility classes:
  *
  * <table class="sis">
- * <tr><th colspan="2">Basic classes of the Java language</th></tr>
+ * <tr><th colspan="2">Classes of the Java language</th></tr>
  * <tr><td>{@link Characters}</td>
  *     <td>Find subscript and superscript digit characters.</td></tr>
  * <tr><td>{@link CharSequences}</td>
@@ -30,9 +30,15 @@ package org.apache.sis.util;
  * <tr><td>{@link StringBuilders}</td>
  *     <td>Methods modifying {@link StringBuilder} content in-place.</td></tr>
  * <tr><td>{@link Numbers}</td>
- *     <td>Conversions between different kind of {@link Number}.</td></tr>
+ *     <td>Methods working with {@link Number} instances (include conversions between
different types).</td></tr>
  * <tr><td>{@link Classes}</td>
- *     <td>Methods working on {@link Class} instances.</td></tr>
+ *     <td>Methods working with {@link Class} instances.</td></tr>
+ * <tr><td>{@link org.apache.sis.util.collection.Containers}</td>
+ *     <td>Additions to the JDK {@link java.util.Collections} methods, also related
to the
+ *         {@link org.apache.sis.util.collection.CheckedContainer} interface.</td></tr>
+ * <tr><td>{@link ArraysExt}</td>
+ *     <td>Additions to the JDK {@link java.util.Arrays} methods
+ *         (include insert or remove of elements in the middle of arrays).</td></tr>
  *
  * <tr><th colspan="2" class="hsep">Mathematics and units of measurement</th></tr>
  * <tr><td>{@link org.apache.sis.math.MathFunctions}</td>
@@ -41,13 +47,6 @@ package org.apache.sis.util;
  *     <td>Get a {@linkplain javax.measure.unit.Unit unit} from a symbol or EPSG code,
  *         and test if a unit is angular, linear or temporal.</td></tr>
  *
- * <tr><th colspan="2" class="hsep">Structures (trees, collections, arrays, parameters)</th></tr>
- * <tr><td>{@link org.apache.sis.util.collection.Containers}</td>
- *     <td>Additions to the JDK {@link java.util.Collections} methods, also related
to the
- *         {@link org.apache.sis.util.collection.CheckedContainer} interface.</td></tr>
- * <tr><td>{@link ArraysExt}</td>
- *     <td>Insert or remove elements in the middle of arrays.</td></tr>
- *
  * <tr><th colspan="2" class="hsep">OGC/ISO objects (metadata, referencing, geometries)</th></tr>
  * <tr><td>{@link org.apache.sis.metadata.iso.extent.Extents}</td>
  *     <td>Extract information from {@link org.opengis.metadata.extent.Extent} objects.</td></tr>



Mime
View raw message