sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1490584 - in /sis/branches/JDK7/core/sis-metadata/src: main/java/org/apache/sis/metadata/ main/java/org/apache/sis/metadata/iso/ site/apt/
Date Fri, 07 Jun 2013 11:01:56 GMT
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).



Mime
View raw message