Author: desruisseaux
Date: Fri Mar 22 16:10:49 2013
New Revision: 1459878
URL: http://svn.apache.org/r1459878
Log:
Added a few documentation for metadata.
Added:
sis/branches/JDK7/sis-metadata/src/site/apt/
sis/branches/JDK7/sis-metadata/src/site/apt/index.apt (with props)
sis/branches/JDK7/sis-metadata/src/site/fml/
sis/branches/JDK7/sis-metadata/src/site/fml/faq.fml (with props)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/constraint/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/content/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/distribution/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/identification/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/lineage/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/quality/package-info.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/spatial/package-info.java
sis/branches/JDK7/sis-metadata/src/site/site.xml
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/acquisition/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -24,6 +24,24 @@
* For a global overview of metadata in SIS, see the
* <a href="{@docRoot}/../sis-metadata/index.html">Metadata page on the
project web site</a>.
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Cédric Briançon (Geomatys)
* @author Martin Desruisseaux (Geomatys)
* @since 0.3 (derived from geotk-3.03)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/citation/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -31,6 +31,24 @@
* except at XML marshalling time (for ISO 19139 compliance).
* See {@link org.apache.sis.xml.IdentifierMap} for more information.
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/constraint/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/constraint/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/constraint/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/constraint/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -24,12 +24,23 @@
* For a global overview of metadata in SIS, see the
* <a href="{@docRoot}/../sis-metadata/index.html">Metadata page on the
project web site</a>.
*
- * {@section Parameterized types}
- * In GeoAPI interfaces, most collections are typed with wildcards, for
example {@code Collection<? extends Citation>}.
- * The SIS implementation removes the wildcards and declares {@code
Collection<Citation>} instead.
- * This allows collections to be <cite>live</cite>: it is possible to add new
elements directly in
- * an existing collection using code like {@code
getCitations().add(myCitation)} instead than
- * setting the collection as a whole with {@code setCitations(myCitations)}.
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
*
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/content/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/content/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/content/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/content/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -33,6 +33,24 @@
* Both {@code Band} and {@code SampleDimension} interfaces extend the same
parent,
* {@link org.opengis.metadata.content.RangeDimension}.
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/distribution/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/distribution/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/distribution/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/distribution/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -24,6 +24,24 @@
* For a global overview of metadata in SIS, see the
* <a href="{@docRoot}/../sis-metadata/index.html">Metadata page on the
project web site</a>.
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -63,6 +63,24 @@
* for adding extent elements inferred from the given envelope.</li>
* </ul>
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/identification/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/identification/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/identification/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/identification/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -30,6 +30,24 @@
* for computing the denominator from a scale value.</li>
* </ul>
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/lineage/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/lineage/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/lineage/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/lineage/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -24,6 +24,24 @@
* For a global overview of metadata in SIS, see the
* <a href="{@docRoot}/../sis-metadata/index.html">Metadata page on the
project web site</a>.
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/maintenance/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -24,6 +24,24 @@
* For a global overview of metadata in SIS, see the
* <a href="{@docRoot}/../sis-metadata/index.html">Metadata page on the
project web site</a>.
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -33,6 +33,24 @@
* {@link org.apache.sis.metadata.iso.DefaultMetadata#setLanguage
setLanguage(Locale)} method
* will have precedence. The later behavior is compliant with INSPIRE rules.
*
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/quality/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/quality/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/quality/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/quality/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -20,6 +20,28 @@
* An explanation for this package is provided in the {@linkplain
org.opengis.metadata.quality OpenGIS® javadoc}.
* The remaining discussion on this page is specific to the SIS implementation.
*
+ * {@section Overview}
+ * For a global overview of metadata in SIS, see the
+ * <a href="{@docRoot}/../sis-metadata/index.html">Metadata page on the
project web site</a>.
+ *
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/spatial/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/spatial/package-info.java?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/spatial/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/iso/spatial/package-info.java
[UTF-8] Fri Mar 22 16:10:49 2013
@@ -20,6 +20,28 @@
* An explanation for this package is provided in the {@linkplain
org.opengis.metadata.spatial OpenGIS® javadoc}.
* The remaining discussion on this page is specific to the SIS implementation.
*
+ * {@section Overview}
+ * For a global overview of metadata in SIS, see the
+ * <a href="{@docRoot}/../sis-metadata/index.html">Metadata page on the
project web site</a>.
+ *
+ * {@section Collections and null values}
+ * Unless otherwise noted in the Javadoc, all constructors and setter methods
accept {@code null} argument.
+ * A null argument value means that the metadata element can not be provided,
and the reason for that is unspecified.
+ * Alternatively, users can specify why a metadata element is missing by
providing a value created by
+ * {@link org.apache.sis.xml.NilReason#createNilObject
NilReason.createNilObject(Class)}.
+ *
+ * <p>Unless otherwise noted in the Javadoc, all getter methods may return an
empty collection,
+ * an empty array or {@code null} if there is no value. More specifically:</p>
+ * <ul>
+ * <li>If the return type is a collection, the method may return an empty
collection (never {@code null}).</li>
+ * <li>If the return type is an array, the method may return an empty array
(never {@code null}).</li>
+ * <li>Otherwise the method may return {@code null}.</li>
+ * </ul>
+ *
+ * Unless the metadata object has been marked as unmodifiable and unless
otherwise noted in the Javadoc,
+ * all collections returned by getter methods are <cite>live</cite>: adding
new elements in the collection
+ * modify directly the underlying metadata object.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @author Touraïvane (IRD)
* @author Cédric Briançon (Geomatys)
Added: sis/branches/JDK7/sis-metadata/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/site/apt/index.apt?rev=1459878&view=auto
==============================================================================
--- sis/branches/JDK7/sis-metadata/src/site/apt/index.apt (added)
+++ sis/branches/JDK7/sis-metadata/src/site/apt/index.apt [UTF-8] Fri Mar 22
16:10:49 2013
@@ -0,0 +1,146 @@
+ ------------------------------
+ Overview
+ ------------------------------
+
+
+Apache SIS Metadata
+
+ Group of packages related to handling metadata. This group contains the ISO
19115 metadata classes
+ (in <<<org.apache.sis.metadata.iso>>>) and various support classes.
+
+ * {{{./faq.html}Frequently Asked Questions}}
+
+
+* Overview of Metadata handling in Apache SIS
+
+** Foreword
+
+ Many metadata standards exist, including <Dublin core>, <ISO 19115> and the
Image I/O metadata
+ defined in <<<javax.imageio.metadata>>>. The SIS implementation focuses on
ISO 19115 (including
+ its ISO 19115-2 extension), but the classes are designed in a way that allow
the usage of different
+ standards. This genericity goal should be keept in mind in the discussion
below.
+
+
+** How Metadata are defined
+
+ A metadata standard is defined by a set of Java interfaces belonging to a
specific package and its
+ sub-packages. For example the ISO 19115 standard is defined by the
{{{http://www.geoapi.org}GeoAPI}}
+ interfaces defined in the <<<org.opengis.metadata>>> package and
sub-packages. That standard is
+ identified in SIS by the <<<MetadataStandard.ISO_19115>>> constant. Other
standards are defined
+ as well, for example the <<<MetadataStandard.ISO_19119>>> constant stands
for the standards defined
+ by the interfaces in the <<<org.opengis.service>>> package and sub-packages.
+
+ For each interface, the collection of declared getter methods defines its
<properties> (or <attributes>).
+ If a <<<@UML>>> annotation is attached to the getter method, the identifier
declared in that annotation
+ is taken as the property name. This is typically the name defined by the
International Standard from
+ which the interface is derived. Otherwise (if there is no <<<@UML>>>
annotation) the property name is
+ inferred from the method name like what the <Java Beans> framework does.
+
+ The implementation classes, if they exist, are defined in different packages
than the interfaces.
+ For example the ISO 19115 interfaces, declared in
<<<org.opengis.metadata>>>, are implemented by
+ SIS in <<<org.apache.sis.metadata.iso>>>. The subpackages hierarchy is the
same, and the names
+ of implementation classes are the name of the implemented interfaces
prefixed with <<<Abstract>>>
+ or <<<Default>>>.
+
+ <<Notes:>>
+
+ * The <<<Abstract>>> prefix means that the class is abstract in the sense of
the implemented
+ standard. It it not necessarily abstract in the sense of Java. Because
incomplete metadata are
+ common in practice, sometime we wish to instantiate an "abstract" class
despite the lack of
+ knowledge about the exact sub-type.
+
+ * The properties are determined by the getter methods declared in the
interfaces.
+ Getter methods declared in the implementation classes are ignored.
+
+ * Setter methods, if any, can be declared in the implementation classes
without the need for
+ declarations in the interfaces. In other words, interfaces are assumed
read-only unless a
+ specific implementation provide setter methods.
+
+ * The implementation is not required to exist as source code. They can be
generated
+ on the fly with <<<java.lang.reflect.Proxy>>>. This is the approach taken
by the
+ <<<org.apache.sis.metadata.sql>>> package for generating metadata
implementations
+ backed by the content of a database (see also the {{{./faq.html#proxy}FAQ
entry}}).
+
+
+** How Metadata are handled
+
+ Metadata objects in SIS are mostly containers: they provide getter and
setter methods for
+ manipulating the values associated to properties (for example the <title>
properties of an
+ <Citation> object), but provide few logic. The package
<<<org.apache.sis.metadata.iso>>> and
+ its sub-packages are the main examples of such containers.
+
+ In addition, the metadata modules provide support classes for handling the
metadata objects
+ through Java Reflection. This is an approach similar to <Java Beans>, in
that users are encouraged
+ to use directly the API of <Plain Old Java> objects (actually interfaces)
everytime their type is
+ known at compile time, and fallback on the support classes when the type is
known only at runtime.
+
+ Using Java reflection, a metadata can be viewed in many different ways:
+
+
+*** As a <<<Map>>> (from <<<java.util>>>)
+
+ The <<<MetadataStandard>>> class provides various methods returning a view
of an arbitrary
+ metadata implementation as a <<<java.util.Map>>>, where the key are the
property names and
+ the values are the return values of getter methods. The map is writable if
the underlying
+ metadata implementation has setter methods, otherwise attempts to set a
value throw an
+ <<<UnmodifiableMetadataException>>>.
+
+
+*** As a <<<IIOMetadata>>> (from <<<javax.imageio.metadata>>>)
+
+ The ISO 19115-2 standard defines metadata for gridded data, which are good
candidates for
+ Image I/O metadata with spatial data. The
<<<org.apache.sis.image.io.metadata>>> package
+ provides a framework for converting an ISO metadata like
<<<ImageDescription>>> into an
+ <<<IIOMetadata>>> object, and conversely.
+
+
+*** As a <<<TreeTableModel>>> (from <<<org.jdesktop.swingx.treetable>>>)
+
+ The metadata are organized as a tree. For example the <<<Citation>>>
metadata contains one
+ or many <<<ResponsibleParty>>> elements, each of them containing a
<<<Contact>>> element,
+ which contains a <<<Telephone>>> element, <etc>. For each node, there is
many information
+ that can be displayed in columns:
+
+ * A description of the element.
+
+ * The type of values (<<<String>>>, <<<double>>>, <etc>).
+
+ * The range of valid values (if the type is numeric),
+ or an enumeration of valid values (if the type is a code list).
+
+ * The value stored in the element, or the default value.
+
+ The current SIS library provides an indirect way to view metadata in such
tree table:
+ create an <<<IIOMetadata>>> view from the metadata, then create a
<<<TreeTableModel>>>
+ view from the <<<IIOMetadata>>>. A more direct way may be provided in a
future version.
+
+
+*** As a table record in a database (using <<<org.apache.sis.metadata.sql>>>)
+
+ It is possible to establish the following mapping between metadata and a SQL
database:
+
+ * Each metadata interface maps to a table of the same name in the database.
+
+ * Each property in the above interface maps to a column of the same name in
the above table.
+
+ * Each instance of the above interface is a record in the above table.
+
+ Using Java reflection, it is possible to generate implementations of the
metadata interfaces
+ where each call to a getter method is translated into a SQL query for the
above database.
+
+
+** How Metadata are marshalled
+
+ The ISO 19139 standard defines how ISO 19115 metadata shall be represented
in XML.
+ The SIS library supports XML marshalling and unmarshalling with JAXB
annotations.
+
+ Only the implementation classes defined in the
<<<org.apache.sis.metadata.iso>>> packages
+ are annotated for JAXB marshalling. If a metadata is implemented by an other
package (for
+ example <<<org.apache.sis.metadata.sql>>>), then it shall be converted to an
annotated class
+ before to be marshalled. All SIS annotated classes provide a copy
constructor for this
+ purpose. A shallow copy is sufficient; JAXB adapters will convert the
elements on-the-fly
+ when needed.
+
+ The annotated classes can be given to a JAXB <<<Marshaller>>>. For best
results, it shall
+ be a marshaller obtained from the <<<org.apache.sis.xml.MarshallerPool>>>,
otherwise some
+ XML outputs may be incomplete (missing namespaces for instance).
Propchange: sis/branches/JDK7/sis-metadata/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/branches/JDK7/sis-metadata/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Added: sis/branches/JDK7/sis-metadata/src/site/fml/faq.fml
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/site/fml/faq.fml?rev=1459878&view=auto
==============================================================================
--- sis/branches/JDK7/sis-metadata/src/site/fml/faq.fml (added)
+++ sis/branches/JDK7/sis-metadata/src/site/fml/faq.fml Fri Mar 22 16:10:49 2013
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<faqs xmlns="http://maven.apache.org/FML/1.0.1";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/FML/1.0.1
http://maven.apache.org/xsd/fml-1.0.1.xsd";
+ title="Metadata FAQ" toplink="false">
+ <part id="implementation">
+ <title>Custom implementations</title>
+ <faq id="proxy">
+ <question>
+ My metadata are stored in a database-like framework.
+ Implementing every GeoAPI interfaces for accessing them is impratical.
+ </question>
+ <answer>
+ <p>Developers do not need to implement directly the metadata
interfaces.
+ If the underlying storage framework allows access to metadata from
their class and attribute names
+ (either Java names or ISO/OGC names), then it is possible to implement
a single engine accessing
+ any kind of metadata and let the Java Virtual Machine implements the
GeoAPI interfaces on-the-fly, using the
+ <code><a
href="http://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Proxy.html";>java.lang.reflect.Proxy</a></code>
+ class. See the <code>Proxy</code> Javadoc for details, keeping in mind
that the ISO/OGC name
+ of a <code>java.lang.Class</code> or
<code>java.lang.reflect.Method</code> object can be
+ obtained as below:</p>
+
+<blockquote><pre>UML uml = method.getAnnotation(UML.class);
+if (uml != null) {
+ String name = uml.identifier();
+ // Fetch the metadata here.
+}</pre></blockquote>
+
+ <p>This is exactly the approach taken by the
<code>org.apache.sis.metadata.sql</code> package
+ for providing an implementation of all GeoAPI metadata interfaces
reading their values
+ directly from a SQL database.</p>
+ </answer>
+ </faq>
+ <faq id="unknownClass">
+ <question>
+ I can't marshall my custom implementation (<code>JAXBException</code>)
+ </question>
+ <answer>
+ <p>The classes given to the JAXB marshaller must contain JAXB
annotations,
+ otherwise the following exception is thrown:</p>
+
+ <blockquote><code>javax.xml.bind.JAXBException:</code> class
<cite>MyCustomClass</cite>
+ nor any of its super class is known to this context.</blockquote>
+
+ <p>The easiest workaround is to wrap the custom implementation into
one of the implementations
+ provided in the <code>org.apache.metadata.iso</code> package. All
those SIS implementation
+ classes provide shallow copy constructor for making that easy. Note
that you need to wrap
+ only the root class, not the attributes. The attribute values will be
wrapped automatically
+ as needed by JAXB adapters.</p>
+ </answer>
+ </faq>
+ </part>
+</faqs>
Propchange: sis/branches/JDK7/sis-metadata/src/site/fml/faq.fml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/branches/JDK7/sis-metadata/src/site/fml/faq.fml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: sis/branches/JDK7/sis-metadata/src/site/site.xml
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/site/site.xml?rev=1459878&r1=1459877&r2=1459878&view=diff
==============================================================================
--- sis/branches/JDK7/sis-metadata/src/site/site.xml (original)
+++ sis/branches/JDK7/sis-metadata/src/site/site.xml Fri Mar 22 16:10:49 2013
@@ -26,8 +26,8 @@
<body>
<menu name="Quick links">
<item name="Module Javadoc" href="apidocs/index.html"/>
+ <item name="FAQ" href="faq.html"/>
<item name="Apache SIS home" href="../index.html"/>
</menu>
-
</body>
</project>
