Author: desruisseaux
Date: Fri Jun 7 11:01:55 2013
New Revision: 1490584
URL: http://svn.apache.org/r1490584
Log:
Documentation update: moved some content from index.apt to package-info.
Modified:
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/package-info.java
sis/branches/JDK7/core/sis-metadata/src/site/apt/index.apt
Modified:
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java?rev=1490584&r1=1490583&r2=1490584&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] Fri Jun 7 11:01:55 2013
@@ -70,6 +70,8 @@ import org.apache.sis.util.logging.Loggi
* @since 0.3 (derived from geotk-2.4)
* @version 0.3
* @module
+ *
+ * @see MetadataStandard
*/
public abstract class AbstractMetadata implements LenientComparable {
/**
Modified:
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java?rev=1490584&r1=1490583&r2=1490584&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] Fri Jun 7 11:01:55 2013
@@ -83,6 +83,8 @@ import static org.apache.sis.util.Argume
* @since 0.3 (derived from geotk-2.4)
* @version 0.3
* @module
+ *
+ * @see AbstractMetadata
*/
@ThreadSafe
public class MetadataStandard implements Serializable {
Modified:
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java?rev=1490584&r1=1490583&r2=1490584&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/package-info.java
[UTF-8] Fri Jun 7 11:01:55 2013
@@ -23,6 +23,9 @@
* {@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>.
+ * For some explanation about how to use various ISO 19115 elements for
scientific dataset, the
+ * <a
href="https://geo-ide.noaa.gov/wiki/index.php?title=Category:ISO_19115";>NOAA
wiki page</a>
+ * is a good source of information.
*
* <table class="sis"><tr>
* <th>Class hierarchy</th>
Modified:
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/package-info.java?rev=1490584&r1=1490583&r2=1490584&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/package-info.java
[UTF-8] Fri Jun 7 11:01:55 2013
@@ -19,22 +19,107 @@
* Root package for various metadata implementations. 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>.
*
- * <p>This root package can work with different {@linkplain
org.apache.sis.metadata.MetadataStandard
- * metadata standards}, not just ISO 19115. In this package, a metadata
standard is defined by a
- * collection of Java interfaces defined in a specific package and its
sub-packages. For example
- * the {@linkplain org.apache.sis.metadata.MetadataStandard#ISO_19115 ISO
19115} standard is
- * defined by the interfaces in the {@link org.opengis.metadata} package and
sub-packages.
- * This {@code org.apache.sis.metadata} package uses Java reflection for
performing basic
- * operations like comparisons and copies.</p>
- *
- * <p>All metadata can be view {@linkplain
org.apache.sis.metadata.AbstractMetadata#asMap() as a map}
- * for use with Java collections, or {@linkplain
org.apache.sis.metadata.AbstractMetadata#asTreeTable()
- * as a tree table} for use in GUI applications.</p>
+ * {@section Foreword}
+ * Many metadata standards exist, including <cite>Dublin core</cite>,
<cite>ISO 19115</cite> and the Image I/O
+ * metadata defined in {@link 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.
*
- * <p>ISO 19115 metadata can be marshalled and unmarshalled in XML using the
- * {@link org.apache.sis.xml.XML} convenience methods.</p>
+ * {@section 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 <a
href="http://www.geoapi.org";>GeoAPI</a> interfaces
+ * defined in the {@link org.opengis.metadata} package and sub-packages. That
standard is identified in SIS by the
+ * {@link org.apache.sis.metadata.MetadataStandard#ISO_19115} constant. Other
standards are defined as well,
+ * for example the {@link org.apache.sis.metadata.MetadataStandard#ISO_19119}
constant stands for the standards
+ * defined by the interfaces in the {@link org.opengis.service} package and
sub-packages.
+ *
+ * <p>For each interface, the collection of declared getter methods defines
its <cite>properties</cite>
+ * (or <cite>attributes</cite>). If a {@link org.opengis.annotation.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 {@code UML} annotation)
+ * the property name is inferred from the method name like what the <cite>Java
Beans</cite> framework does.</p>
+ *
+ * <p>The implementation classes, if they exist, are defined in different
packages than the interfaces.
+ * For example the ISO 19115 interfaces, declared in {@code
org.opengis.metadata}, are implemented by
+ * SIS in {@link 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 {@code Abstract}
+ * or {@code Default}.</p>
+ *
+ * <p><b>Notes:</b></p>
+ * <ul>
+ * <li>The {@code 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.</li>
+ * <li>The properties are determined by the getter methods declared in the
interfaces.
+ * Getter methods declared in the implementation classes are
ignored.</li>
+ * <li>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.</li>
+ * <li>The implementation is not required to exist as source code. They can
be generated on the fly with
+ * {@link java.lang.reflect.Proxy}. This is the approach taken by the
{@link org.apache.sis.metadata.sql}
+ * package for generating metadata implementations backed by the content
of a database.</li>
+ * </ul>
+ *
+ * {@section 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 {@code title} property of a
{@code Citation} object), but provide few logic.
+ * The package {@code org.apache.sis.metadata.iso} and its sub-packages are
the main examples of such containers.
+ *
+ * <p>In addition, the metadata modules provide support methods for handling
the metadata objects through Java Reflection.
+ * This is an approach similar to <cite>Java Beans</cite>, in that users are
encouraged to use directly the API of
+ * <cite>Plain Old Java</cite> objects (actually interfaces) everytime their
type is known at compile time,
+ * and fallback on the reflection technic when the type is known only at
runtime.</p>
+ *
+ * <p>Using Java reflection, a metadata can be viewed in many different
ways:</p>
+ * <ul>
+ * <li><b>As a {@link java.util.Map}</b><br>
+ * The {@link org.apache.sis.metadata.MetadataStandard} class provides
various methods returning a view
+ * of an arbitrary metadata implementation as a {@code Map}, where the
key are the property names and the
+ * values are the return values, types or descriptions of getter
methods. The map is writable if the
+ * underlying metadata implementation has setter methods, otherwise
attempts to set a value throw an
+ * {@code UnmodifiableMetadataException}.</li>
+ *
+ * <li><b>As a {@link org.apache.sis.util.collection.TreeTable}</b><br>
+ * The metadata are organized as a tree. For example the {@code
Citation} metadata contains one or many
+ * {@code ResponsibleParty} elements, each of them containing a {@code
Contact} element, which contains
+ * a {@code Telephone} element, <i>etc</i>. For each node, there is many
information that can be displayed
+ * in columns:
+ * <ul>
+ * <li>A description of the element.</li>
+ * <li>The type of values ({@code String}, {@code double},
<i>etc</i>).</li>
+ * <li>The range of valid values (if the type is numeric),
+ * or an enumeration of valid values (if the type is a code
list).</li>
+ * <li>The value stored in the element, or the default value.</li>
+ * </ul></li>
+ *
+ * <li><b>As a table record in a database (using {@link
org.apache.sis.metadata.sql})</b><br>
+ * It is possible to establish the following mapping between metadata
and a SQL database:
+ * <ul>
+ * <li>Each metadata interface maps to a table of the same name in the
database.</li>
+ * <li>Each property in the above interface maps to a column of the
same name in the above table.</li>
+ * <li>Each instance of the above interface is a record in the above
table.</li>
+ * </ul>
+ * 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.</li>
+ * </ul>
+ *
+ * {@section 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.
+ *
+ * <p>Only the implementation classes defined in the {@link
org.apache.sis.metadata.iso} packages and sub-packages
+ * are annotated for JAXB marshalling. If a metadata is implemented by an
other package (for example
+ * {@code 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.</p>
+ *
+ * <p>The annotated classes can be given to a JAXB {@code Marshaller}. For
best results, it shall be a marshaller
+ * obtained from the {@link org.apache.sis.xml.MarshallerPool}, otherwise some
XML outputs may be incomplete
+ * (missing namespaces for instance). The {@link org.apache.sis.xml.XML} class
provides convenience methods
+ * for this purpose.</p>
*
* @author Martin Desruisseaux (IRD, Geomatys)
+ * @author Adrian Custer (Geomatys)
* @since 0.3 (derived from geotk-2.0)
* @version 0.3
* @module
Modified: sis/branches/JDK7/core/sis-metadata/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/site/apt/index.apt?rev=1490584&r1=1490583&r2=1490584&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-metadata/src/site/apt/index.apt [UTF-8]
(original)
+++ sis/branches/JDK7/core/sis-metadata/src/site/apt/index.apt [UTF-8] Fri Jun
7 11:01:55 2013
@@ -5,128 +5,40 @@
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.
+ Implementations of metadata derived from ISO 19115. This module provides
both an implementation
+ of the metadata interfaces defined in GeoAPI, and a framework for handling
those metadata through
+ Java reflection.
- * {{{./faq.html}Frequently Asked Questions}}
+ * {{{./faq.html}Frequently Asked Questions}}
+ * {{{https://geo-ide.noaa.gov/wiki/index.php?title=Category:ISO_19115}ISO
19115 wiki at NOAA}}
-* Overview of Metadata handling in Apache SIS
-** Foreword
+* Overview of Metadata handling in Apache SIS
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
+ standards.
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
+ In addition, the metadata modules provide support methods 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.
-
+ known at compile time, and fallback on the reflection technic 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>>>)
-*** 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 <<<TreeTable>>> (from <<<org.apache.sis.util.collection>>>)
-*** As a <<<IIOMetadata>>> (from <<<javax.imageio.metadata>>>)
+ * 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.
+ * As a table record in a database (using <<<org.apache.sis.metadata.sql>>>)
** How Metadata are marshalled
@@ -140,7 +52,3 @@ Apache SIS Metadata
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).
