sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1815667 - in /sis/site/trunk: book/en/overview/ book/fr/overview/ book/fr/utility/ content/book/en/ content/book/fr/
Date Sat, 18 Nov 2017 14:18:12 GMT
Author: desruisseaux
Date: Sat Nov 18 14:18:12 2017
New Revision: 1815667

URL: http://svn.apache.org/viewvc?rev=1815667&view=rev
Log:
Add a section about navigating in metadata.

Added:
    sis/site/trunk/book/en/overview/GetMetadataElement.html
    sis/site/trunk/book/fr/overview/GetMetadataElement.html
Modified:
    sis/site/trunk/book/en/overview/DataAccess.html
    sis/site/trunk/book/fr/overview/DataAccess.html
    sis/site/trunk/book/fr/utility/Internationalization.html
    sis/site/trunk/content/book/en/developer-guide.html
    sis/site/trunk/content/book/fr/developer-guide.html

Modified: sis/site/trunk/book/en/overview/DataAccess.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/overview/DataAccess.html?rev=1815667&r1=1815666&r2=1815667&view=diff
==============================================================================
--- sis/site/trunk/book/en/overview/DataAccess.html (original)
+++ sis/site/trunk/book/en/overview/DataAccess.html Sat Nov 18 14:18:12 2017
@@ -124,7 +124,7 @@ Geographic Bounding Box
         <tr><td>  ├─Reference system info</td>        
     <td>Description of the spatial and temporal reference systems used in the dataset.</td></tr>
         <tr><td>  ├─Identification info</td>          
     <td>Basic information about the resource(s) to which the metadata applies.</td></tr>
         <tr><td>  │   ├─Citation</td>   
                   <td>Name by which the cited resource is known, reference dates, presentation
form, <i>etc.</i></td></tr>
-        <tr><td>  │   │   └─Cited
responsible party</td>    <td>Role, name, contact and position information for
individuals or organisations that are responsible for the resource.</td></tr>
+        <tr><td>  │   │   └─Cited
responsible party</td>    <td>Role, name, contact and position information for
individuals or organizations that are responsible for the resource.</td></tr>
         <tr><td>  │   ├─Topic category</td>
                <td>Main theme(s) of the resource (e.g. farming, climatology, environment,
economy, health, transportation, <i>etc.</i>).</td></tr>
         <tr><td>  │   ├─Descriptive keywords</td>
          <td>Category keywords, their type, and reference source.</td></tr>
         <tr><td>  │   ├─Spatial resolution</td>
            <td>Factor which provides a general understanding of the density of spatial
data in the resource.</td></tr>
@@ -133,7 +133,7 @@ Geographic Bounding Box
         <tr><td>  │   ├─Resource format</td>
               <td>Description of the format of the resource(s).</td></tr>
         <tr><td>  │   ├─Resource maintenance</td>
          <td>Information about the frequency of resource updates, and the scope of
those updates.</td></tr>
         <tr><td>  │   └─Resource constraints</td>
          <td>Information about constraints (legal or security) which apply to the resource(s).</td></tr>
-        <tr><td>  ├─Content info</td>                 
     <td>Information about the feature catalogue and describes the coverage and image
data characteristics.</td></tr>
+        <tr><td>  ├─Content info</td>                 
     <td>Information about the feature catalog and describes the coverage and image
data characteristics.</td></tr>
         <tr><td>  │   ├─Imaging condition</td>
             <td>Conditions which affected the image (e.g. blurred image, fog, semi
darkness, <i>etc.</i>).</td></tr>
         <tr><td>  │   ├─Cloud cover percentage</td>
        <td>Area of the dataset obscured by clouds, expressed as a percentage of the
spatial extent.</td></tr>
         <tr><td>  │   └─Attribute group</td>
               <td>Information on attribute groups of the resource.</td></tr>
@@ -156,6 +156,7 @@ Geographic Bounding Box
         <tr><td>      ├─Source</td>       
                 <td>Information about the source data used in creating the data specified
by the scope.</td></tr>
         <tr><td>      └─Process step</td> 
                 <td>Information about events in the life of a resource specified by
the scope.</td></tr>
       </table>
+      <xi:include href="GetMetadataElement.html"/>
     </section>
   </body>
 </html>

Added: sis/site/trunk/book/en/overview/GetMetadataElement.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/overview/GetMetadataElement.html?rev=1815667&view=auto
==============================================================================
--- sis/site/trunk/book/en/overview/GetMetadataElement.html (added)
+++ sis/site/trunk/book/en/overview/GetMetadataElement.html Sat Nov 18 14:18:12 2017
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+  <head>
+    <title>GetMetadataElement</title>
+    <meta charset="UTF-8"/>
+    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+  </head>
+  <body>
+    <!--
+      Content below this point is copied in "../../content/book/en/developer-guide.html"
+      by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+    -->
+    <section>
+      <header>
+        <h2 id="GetMetadataElement">Navigating in metadata elements</h2>
+      </header>
+      <p>
+        Methods like <code class="GeoAPI">getExtents()</code> are efficient when
looking for a particular element known at compile-time.
+        But those elements may be deep in the tree structure and may require traversal of
many optional elements and collection members,
+        which is sometime tedious. For a few frequently-used elements, some convenience methods
are provided.
+        Those conveniences are generally defined as static methods in classes having a name
in plural form.
+        For example the <code>Extents</code> class defines static methods for
fetching more easily some information from <code>Extent</code> metadata elements.
+        For example the following method navigates through different branches where North,
South, East and West data bounds may be found:
+      </p>
+      <pre><code>GeographicBoundingBox bbox = Extents.getGeographicBoundingBox(extent);</code></pre>
+      <p>
+        Those conveniences are defined as static methods in order to allow their use with
different metadata implementations.
+        Even in Apache <abbr>SIS</abbr> library, the <code>DefaultExtent</code>
class is not the only implementation of <code>Extent</code> interface.
+        There is also implementations fetching information on-demand in a database, or implementations
for particular data formats.
+        Some other classes providing static methods for specific interfaces are
+        <code>Citations</code>, <code>Envelopes</code>, <code>Matrices</code>
and <code>MathTransforms</code>.
+      </p><p>
+        Those static methods explore fragments of metadata tree in search for requested information,
+        but the searches are still targeted to elements whose types and at least part of
their paths are known at compile-time.
+        Sometime the element to search is known only at runtime, or sometime there is a need
to iterate over all elements.
+        In such cases, one can view the metadata as a <code>java.util.Map</code>
like below:
+      </p>
+
+<pre><code>Map&lt;String,Object&gt; elements = MetadataStandard.ISO_19115.asValueMap(
+        metadata,                           // Any instance from the org.opengis.metadata
package or a sub-package.
+        null,                               // Used for resolving ambiguities. We can ignore
for this example.
+        KeyNamePolicy.JAVABEANS_PROPERTY,   // Keys in the map will be getter method names
without "get" prefix.
+        ValueExistencePolicy.NON_EMPTY);    // Entries with null or empty values will be
omitted.
+/*
+ * Print the names of all root metadata elements having a value.
+ * This loop does not iterate recursively in children.
+ */
+for (String name : elements.keySet()) {
+    System.out.println(name);
+}</code></pre>
+
+      <p>
+        The <code>Map</code> object returned by <code class="SIS">asValueMap(…)</code>
is live:
+        any change in the <code>metadata</code> instance will be immediately
reflected in the view.
+        Actually, each <code>map.get("foo")</code> call is forwarded to the corresponding
<code>metadata.getFoo()</code> method.
+        Conversely, any <code>map.put("foo", …)</code> or <code>map.remove("foo")</code>
operation applied on the view
+        will be forwarded to the corresponding <code>metadata.setFoo(…)</code>
method, if that method exists.
+        The view is lenient regarding keys given in arguments to <code>Map</code>
methods:
+        keys may be property names (<code>"foo"</code>), method names (<code>"getFoo"</code>),
+        or names used in <abbr>ISO</abbr> 19115 standard <abbr>UML</abbr>
diagrams
+        (similar to property names but not always identical).
+        Differences in upper cases and lower cases are ignored when this tolerance does not
introduce ambiguities.
+      </p><p>
+        Among metadata elements introduced in this chapter,
+        there is one which will be the topic of a dedicated chapter: <code class="OGC">referenceSystemInfo</code>.
+        Its content is essential for accurate data positioning;
+        without this element, even positions given by latitudes and longitudes are ambiguous.
+        Reference systems have many characteristics that make them apart from other metadata:
+        they are immutable, can not be handled by <code class="SIS">MetadataStandard.ISO_19115.asValueMap(…)</code>,
+        have a particular text representation and are associated to an engine
+        performing coordinate transformation from one reference system to an other.
+      </p>
+    </section>
+  </body>
+</html>

Modified: sis/site/trunk/book/fr/overview/DataAccess.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/overview/DataAccess.html?rev=1815667&r1=1815666&r2=1815667&view=diff
==============================================================================
--- sis/site/trunk/book/fr/overview/DataAccess.html (original)
+++ sis/site/trunk/book/fr/overview/DataAccess.html Sat Nov 18 14:18:12 2017
@@ -158,6 +158,7 @@ Geographic Bounding Box
         <tr><td>      ├─Source</td>       
                 <td>Information sur les données sources utilisées pour créer
les données décrites par les méta-données.</td></tr>
         <tr><td>      └─Process step</td> 
                 <td>Historique des événements survenues dans la productions des
données.</td></tr>
       </table>
+      <xi:include href="GetMetadataElement.html"/>
     </section>
   </body>
 </html>

Added: sis/site/trunk/book/fr/overview/GetMetadataElement.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/overview/GetMetadataElement.html?rev=1815667&view=auto
==============================================================================
--- sis/site/trunk/book/fr/overview/GetMetadataElement.html (added)
+++ sis/site/trunk/book/fr/overview/GetMetadataElement.html Sat Nov 18 14:18:12 2017
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html>
+
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="fr">
+  <head>
+    <title>GetMetadataElement</title>
+    <meta charset="UTF-8"/>
+    <link rel="stylesheet" type="text/css" href="../../../content/book/book.css"/>
+  </head>
+  <body>
+    <!--
+      Content below this point is copied in "../../content/book/en/developer-guide.html"
+      by the 'org.apache.sis.internal.book.Assembler' class in 'sis-build-helper' module.
+    -->
+    <section>
+      <header>
+        <h2 id="GetMetadataElement">Parcourir les méta-données</h2>
+      </header>
+      <p>
+        L’utilisation de méthodes telles que <code class="GeoAPI">getExtents()</code>
+        est efficace lorsque l’on cherche un élément bien précis, connu au
moment de la compilation.
+        Mais le fait que l’élément recherché peut être assez loin dans l’arborescence
et
+        que beaucoup d’éléments soient optionnels ou membres de collections rend
parfois le parcourt laborieux.
+        Pour quelques éléments fréquemment demandés, des méthodes de commodité
existent.
+        Elles sont généralement définies sous forme de méthodes statiques dans
une classe dont le nom est au pluriel.
+        Par exemple la classe <code>Extents</code> définie des méthodes
statiques pour extraire plus facilement
+        certaines informations à partir de l’élément de méta-donnée <code>Extent</code>.
+        Ainsi la ligne suivante prendra en charge le travail un peu fastidieux de parcourir
les différentes branches possible
+        pouvant aboutir aux limites nord, sud, est et ouest de la donnée:
+      </p>
+      <pre><code>GeographicBoundingBox bbox = Extents.getGeographicBoundingBox(extent);</code></pre>
+      <p>
+        Ces méthodes de commodité sont définies sous forme de méthodes statiques
+        afin de permettre leur utilisation avec différentes implémentations des éléments
de méta-données.
+        Même dans Apache <abbr>SIS</abbr>, la classe <code>DefaultExtent</code>
n’est pas la seule implémentation de l’interface <code>Extent</code>.
+        Il y a aussi d’autres implémentations qui puiseront leur information à
la demande dans une base de données,
+        ou des implémentations conçues spécifiquement pour des formats de données
particuliers.
+        D’autres exemples de classes fournissant des méthodes statiques dédiées
à une interface sont
+        <code>Citations</code>, <code>Envelopes</code>, <code>Matrices</code>
et <code>MathTransforms</code>.
+      </p><p>
+        Ces méthodes statiques parcourent une plus grande portion de l’arbre de méta-données
afin de trouver ou dériver l’élément demandé,
+        mais ce dernier reste un élément dont le type et au moins une partie du chemin
sont connus au moment de la compilation.
+        Il arrive que l’on veuille plutôt accéder à des éléments qui
ne sont connus qu’au moment de l’exécution, ou encore parcourir tous les éléments.
+        Dans ces cas, on peut utiliser une vue sous forme de <code>java.util.Map</code>
comme dans l’exemple suivant:
+      </p>
+
+<pre><code>Map&lt;String,Object&gt; elements = MetadataStandard.ISO_19115.asValueMap(
+        metadata,                           // N’importe quelle instance du paquet org.opengis.metadata
ou d’un sous-paquet.
+        null,                               // Utilisé pour résoudre des ambiguïtés.
Peut être ignoré pour cet exemple.
+        KeyNamePolicy.JAVABEANS_PROPERTY,   // Les clés seront les noms des méthodes
mais sans le prefix « get ».
+        ValueExistencePolicy.NON_EMPTY);    // Les entrés dont la valeur est nulle ou
vide seront omises.
+/*
+ * Affiche les noms de tous les éléments à la racine de la méta-données qui
ont une valeur.
+ * Cette bouche ne va pas descendre dans les enfants (pas de récursivité).
+ */
+for (String name : elements.keySet()) {
+    System.out.println(name);
+}</code></pre>
+
+      <p>
+        Le <code>Map</code> retourné par <code class="SIS">asValueMap(…)</code>
est une vue « vivante »:
+        tout changement dans l’instance <code>metadata</code> se reflétera
immédiatement dans la vue.
+        En fait, chaque appel à <code>map.get("foo")</code> se traduit par
un appel à la méthode <code>metadata.getFoo()</code> correspondante.
+        Réciproquement, toute opération <code>map.put("foo", …)</code>
ou <code>map.remove("foo")</code> effectuée sur la vue
+        sera traduite en appel à la méthode <code>metadata.setFoo(…)</code>
correspondante si cette dernière existe.
+        Cette vue est assez souple sur les clés données en argument aux méthodes
de <code>Map</code>:
+        elles peuvent être le nom de la propriété (<code>"foo"</code>),
le nom de la méthode (<code>"getFoo"</code>),
+        ou le nom utilisé dans les diagrammes <abbr>UML</abbr> de la norme
<abbr>ISO</abbr> 19115
+        (assez proche du nom de la propriété mais pas toujours identique).
+        Les différences entre majuscules et minuscules sont ignorées si elles ne causent
pas d’ambiguïtés.
+      </p><p>
+        Parmi les éléments de méta-données présentés dans ce chapitre,
+        il en est un qui fera l’objet d’un chapitre dédié: <code class="OGC">referenceSystemInfo</code>.
+        Son contenu est essentiel pour positionner précisément les données.
+        Sans lui, même les positions exprimées sous forme de latitudes et longitudes
sont ambigües.
+        Les systèmes de références ont plusieurs caractéristiques qui les différencient
des autres méta-données:
+        ils sont immuables, ne peuvent pas être parcourus par <code class="SIS">MetadataStandard.ISO_19115.asValueMap(…)</code>,
+        ont une représentation sous forme de texte particulière,
+        et sont associés à un mécanisme permettant de transformer des coordonnées
d’un référentiel vers un autre.
+      </p>
+    </section>
+  </body>
+</html>

Modified: sis/site/trunk/book/fr/utility/Internationalization.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/utility/Internationalization.html?rev=1815667&r1=1815666&r2=1815667&view=diff
==============================================================================
--- sis/site/trunk/book/fr/utility/Internationalization.html [UTF-8] (original)
+++ sis/site/trunk/book/fr/utility/Internationalization.html [UTF-8] Sat Nov 18 14:18:12 2017
@@ -97,7 +97,7 @@
         <code>InternationalString</code> là où une valeur de type <code>String</code>
serait susceptible d’être localisée.
         Cette approche permet de différer le processus d’internationalisation au moment
d’obtenir
         une chaîne de caractères plutôt qu’au moment de construire l’objet qui les
contient.
-        C’est particulièrement utile pour les classes immutables qui serviront à créer
des instances uniques
+        C’est particulièrement utile pour les classes immuables qui serviront à créer
des instances uniques
         indépendamment des conventions locales.
       </p>
       <div class="example"><p><b>Exemple:</b>

Modified: sis/site/trunk/content/book/en/developer-guide.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/en/developer-guide.html?rev=1815667&r1=1815666&r2=1815667&view=diff
==============================================================================
--- sis/site/trunk/content/book/en/developer-guide.html [UTF-8] (original)
+++ sis/site/trunk/content/book/en/developer-guide.html [UTF-8] Sat Nov 18 14:18:12 2017
@@ -32,7 +32,8 @@ Partially translated by <i>Christina Hou
 <li><a href="#GeoAPI-implementation">Implementations provided by Apache SIS</a></li></ul></li>
 <li><a href="#AboutBook">Conventions used in this guide</a><ul>
 <li><a href="#ChosenTerms">Chosen terms</a></li></ul></li></ul></li>
-<li><a href="#DataAccess">Geospatial data access</a></li>
+<li><a href="#DataAccess">Geospatial data access</a><ul>
+<li><a href="#GetMetadataElement">Navigating in metadata elements</a></li></ul></li>
 <li><a href="#Coverage">Data coverages</a></li>
 <li><a href="#Geometry">Geometries</a><ul>
 <li><a href="#GeometryBase">Base classes</a><ul>
@@ -734,7 +735,8 @@ in order to reduce the risk of confusion
 <h1 id="DataAccess"><span class="section-number">2.</span> Geospatial data
access</h1>
 <nav><div class="chapter-links"><div class="previous-chapter">⬅ <a
href="#Standards">Previous chapter</a></div><div class="next-chapter"><a
href="#Coverage">Next chapter</a> ➡</div></div></nav>
 </header>
-<nav>In this chapter:<ul class="toc"/></nav>
+<nav>In this chapter:<ul class="toc">
+<li><a href="#GetMetadataElement">Navigating in metadata elements</a></li></ul></nav>
 <p>
 It is possible to instantiate data structures programmatically in memory.
 But more often, data are read from files or other kinds of data stores.
@@ -824,7 +826,7 @@ For example the <code class="OGC">extent
 <tr><td>  ├─Reference system info</td>              <td>Description
of the spatial and temporal reference systems used in the dataset.</td></tr>
 <tr><td>  ├─Identification info</td>                <td>Basic
information about the resource(s) to which the metadata applies.</td></tr>
 <tr><td>  │   ├─Citation</td>                       <td>Name
by which the cited resource is known, reference dates, presentation form, <i>etc.</i></td></tr>
-<tr><td>  │   │   └─Cited responsible party</td>    <td>Role,
name, contact and position information for individuals or organisations that are responsible
for the resource.</td></tr>
+<tr><td>  │   │   └─Cited responsible party</td>    <td>Role,
name, contact and position information for individuals or organizations that are responsible
for the resource.</td></tr>
 <tr><td>  │   ├─Topic category</td>                 <td>Main
theme(s) of the resource (e.g. farming, climatology, environment, economy, health, transportation,
<i>etc.</i>).</td></tr>
 <tr><td>  │   ├─Descriptive keywords</td>           <td>Category
keywords, their type, and reference source.</td></tr>
 <tr><td>  │   ├─Spatial resolution</td>             <td>Factor
which provides a general understanding of the density of spatial data in the resource.</td></tr>
@@ -833,7 +835,7 @@ For example the <code class="OGC">extent
 <tr><td>  │   ├─Resource format</td>                <td>Description
of the format of the resource(s).</td></tr>
 <tr><td>  │   ├─Resource maintenance</td>           <td>Information
about the frequency of resource updates, and the scope of those updates.</td></tr>
 <tr><td>  │   └─Resource constraints</td>           <td>Information
about constraints (legal or security) which apply to the resource(s).</td></tr>
-<tr><td>  ├─Content info</td>                       <td>Information
about the feature catalogue and describes the coverage and image data characteristics.</td></tr>
+<tr><td>  ├─Content info</td>                       <td>Information
about the feature catalog and describes the coverage and image data characteristics.</td></tr>
 <tr><td>  │   ├─Imaging condition</td>              <td>Conditions
which affected the image (e.g. blurred image, fog, semi darkness, <i>etc.</i>).</td></tr>
 <tr><td>  │   ├─Cloud cover percentage</td>         <td>Area
of the dataset obscured by clouds, expressed as a percentage of the spatial extent.</td></tr>
 <tr><td>  │   └─Attribute group</td>                <td>Information
on attribute groups of the resource.</td></tr>
@@ -856,6 +858,70 @@ For example the <code class="OGC">extent
 <tr><td>      ├─Source</td>                         <td>Information
about the source data used in creating the data specified by the scope.</td></tr>
 <tr><td>      └─Process step</td>                   <td>Information
about events in the life of a resource specified by the scope.</td></tr>
 </table>
+
+
+
+<section>
+<header>
+<h2 id="GetMetadataElement"><span class="section-number">2.1.</span> Navigating
in metadata elements</h2>
+</header>
+<p>
+Methods like <code class="GeoAPI">getExtents()</code> are efficient when looking
for a particular element known at compile-time.
+But those elements may be deep in the tree structure and may require traversal of many optional
elements and collection members,
+which is sometime tedious. For a few frequently-used elements, some convenience methods are
provided.
+Those conveniences are generally defined as static methods in classes having a name in plural
form.
+For example the <code class="SIS">Extents</code> class defines static methods
for fetching more easily some information from <code class="GeoAPI">Extent</code>
metadata elements.
+For example the following method navigates through different branches where North, South,
East and West data bounds may be found:
+</p>
+<pre><code><code class="GeoAPI">GeographicBoundingBox</code> bbox
= <code class="SIS">Extents</code>.getGeographicBoundingBox(extent);</code></pre>
+<p>
+Those conveniences are defined as static methods in order to allow their use with different
metadata implementations.
+Even in Apache <abbr title="Spatial Information System">SIS</abbr> library, the
<code class="SIS">DefaultExtent</code> class is not the only implementation of
<code class="GeoAPI">Extent</code> interface.
+There is also implementations fetching information on-demand in a database, or implementations
for particular data formats.
+Some other classes providing static methods for specific interfaces are
+<code class="SIS">Citations</code>, <code class="SIS">Envelopes</code>,
<code class="SIS">Matrices</code> and <code class="SIS">MathTransforms</code>.
+</p><p>
+Those static methods explore fragments of metadata tree in search for requested information,
+but the searches are still targeted to elements whose types and at least part of their paths
are known at compile-time.
+Sometime the element to search is known only at runtime, or sometime there is a need to iterate
over all elements.
+In such cases, one can view the metadata as a <code>java.util.Map</code> like
below:
+</p>
+
+<pre><code>Map&lt;String,Object&gt; elements = MetadataStandard.ISO_19115.asValueMap(
+        metadata,                           <code class="comment">// Any instance from
the org.opengis.metadata package or a sub-package.
+</code>        <b>null</b>,                               <code class="comment">//
Used for resolving ambiguities. We can ignore for this example.
+</code>        KeyNamePolicy.JAVABEANS_PROPERTY,   <code class="comment">// Keys
in the map will be getter method names without "get" prefix.
+</code>        ValueExistencePolicy.NON_EMPTY);    <code class="comment">// Entries
with null or empty values will be omitted.
+</code><code class="comment">/*
+ * Print the names of all root metadata elements having a value.
+ * This loop does not iterate recursively in children.
+ */</code>
+<b>for</b> (String name : elements.keySet()) {
+    System.out.println(name);
+}</code></pre>
+
+<p>
+The <code>Map</code> object returned by <code class="SIS">asValueMap(…)</code>
is live:
+any change in the <code>metadata</code> instance will be immediately reflected
in the view.
+Actually, each <code>map.get("foo")</code> call is forwarded to the corresponding
<code>metadata​.getFoo()</code> method.
+Conversely, any <code>map.put("foo", …)</code> or <code>map.remove("foo")</code>
operation applied on the view
+will be forwarded to the corresponding <code>metadata​.setFoo(…)</code> method,
if that method exists.
+The view is lenient regarding keys given in arguments to <code>Map</code> methods:
+keys may be property names (<code>"foo"</code>), method names (<code>"getFoo"</code>),
+or names used in <abbr title="International Organization for Standardization">ISO</abbr>
19115 standard <abbr title="Unified Modeling Language">UML</abbr> diagrams
+(similar to property names but not always identical).
+Differences in upper cases and lower cases are ignored when this tolerance does not introduce
ambiguities.
+</p><p>
+Among metadata elements introduced in this chapter,
+there is one which will be the topic of a dedicated chapter: <code class="OGC">referenceSystemInfo</code>.
+Its content is essential for accurate data positioning;
+without this element, even positions given by latitudes and longitudes are ambiguous.
+Reference systems have many characteristics that make them apart from other metadata:
+they are immutable, can not be handled by <code class="SIS">MetadataStandard.ISO_19115​.asValueMap(…)</code>,
+have a particular text representation and are associated to an engine
+performing coordinate transformation from one reference system to an other.
+</p>
+</section>
 </section>
 
 
@@ -1789,7 +1855,7 @@ Example:</p>
 <pre><code>@Override
 <b>public</b> <code class="GeoAPI">Matrix</code> derivative(<code
class="GeoAPI">DirectPosition</code> p) <b>throws</b> <code class="GeoAPI">TransformException</code>
{
     <code class="GeoAPI">Matrix</code> jac = inverse().derivative(transform(p));
-    <b>return</b> Matrices.inverse(jac);
+    <b>return</b> <code class="SIS">Matrices</code>.inverse(jac);
 }</code></pre>
 
 

Modified: sis/site/trunk/content/book/fr/developer-guide.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/fr/developer-guide.html?rev=1815667&r1=1815666&r2=1815667&view=diff
==============================================================================
--- sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] (original)
+++ sis/site/trunk/content/book/fr/developer-guide.html [UTF-8] Sat Nov 18 14:18:12 2017
@@ -32,7 +32,8 @@
 <li><a href="#GeoAPI-implementation">Implémentations fournies par Apache SIS</a></li></ul></li>
 <li><a href="#AboutBook">Conventions utilisées dans ce guide</a><ul>
 <li><a href="#ChosenTerms">Choix des termes</a></li></ul></li></ul></li>
-<li><a href="#DataAccess">Accès aux données géospatiales</a></li>
+<li><a href="#DataAccess">Accès aux données géospatiales</a><ul>
+<li><a href="#GetMetadataElement">Parcourir les méta-données</a></li></ul></li>
 <li><a href="#Coverage">Couvertures de données (Coverages)</a></li>
 <li><a href="#Geometry">Géométries</a><ul>
 <li><a href="#GeometryBase">Classes de base</a><ul>
@@ -771,7 +772,8 @@ Mais un soin particulier doit être appo
 <h1 id="DataAccess"><span class="section-number">2.</span> Accès aux données
géospatiales</h1>
 <nav><div class="chapter-links"><div class="previous-chapter">⬅ <a
href="#Standards">Chapitre précédent</a></div><div class="next-chapter"><a
href="#Coverage">Chapitre suivant</a> ➡</div></div></nav>
 </header>
-<nav>Dans ce chapitre:<ul class="toc"/></nav>
+<nav>Dans ce chapitre:<ul class="toc">
+<li><a href="#GetMetadataElement">Parcourir les méta-données</a></li></ul></nav>
 <p>
 Bien qu’il soit possible de créer des structures de données programmatiquement en mémoire,
 le plus souvent les données sont lues à partir de fichiers ou autres types d’entrepôts.
@@ -895,6 +897,76 @@ Par exemple il peut y avoir plusieurs zo
 <tr><td>      ├─Source</td>                         <td>Information
sur les données sources utilisées pour créer les données décrites par les méta-données.</td></tr>
 <tr><td>      └─Process step</td>                   <td>Historique
des événements survenues dans la productions des données.</td></tr>
 </table>
+
+
+
+<section>
+<header>
+<h2 id="GetMetadataElement"><span class="section-number">2.1.</span> Parcourir
les méta-données</h2>
+</header>
+<p>
+L’utilisation de méthodes telles que <code class="GeoAPI">getExtents()</code>
+est efficace lorsque l’on cherche un élément bien précis, connu au moment de la compilation.
+Mais le fait que l’élément recherché peut être assez loin dans l’arborescence et
+que beaucoup d’éléments soient optionnels ou membres de collections rend parfois le parcourt
laborieux.
+Pour quelques éléments fréquemment demandés, des méthodes de commodité existent.
+Elles sont généralement définies sous forme de méthodes statiques dans une classe dont
le nom est au pluriel.
+Par exemple la classe <code class="SIS">Extents</code> définie des méthodes
statiques pour extraire plus facilement
+certaines informations à partir de l’élément de méta-donnée <code class="GeoAPI">Extent</code>.
+Ainsi la ligne suivante prendra en charge le travail un peu fastidieux de parcourir les différentes
branches possible
+pouvant aboutir aux limites nord, sud, est et ouest de la donnée:
+</p>
+<pre><code><code class="GeoAPI">GeographicBoundingBox</code> bbox
= <code class="SIS">Extents</code>.getGeographicBoundingBox(extent);</code></pre>
+<p>
+Ces méthodes de commodité sont définies sous forme de méthodes statiques
+afin de permettre leur utilisation avec différentes implémentations des éléments de méta-données.
+Même dans Apache <abbr title="Spatial Information System">SIS</abbr>, la classe
<code class="SIS">DefaultExtent</code> n’est pas la seule implémentation de
l’interface <code class="GeoAPI">Extent</code>.
+Il y a aussi d’autres implémentations qui puiseront leur information à la demande dans
une base de données,
+ou des implémentations conçues spécifiquement pour des formats de données particuliers.
+D’autres exemples de classes fournissant des méthodes statiques dédiées à une interface
sont
+<code class="SIS">Citations</code>, <code class="SIS">Envelopes</code>,
<code class="SIS">Matrices</code> et <code class="SIS">MathTransforms</code>.
+</p><p>
+Ces méthodes statiques parcourent une plus grande portion de l’arbre de méta-données
afin de trouver ou dériver l’élément demandé,
+mais ce dernier reste un élément dont le type et au moins une partie du chemin sont connus
au moment de la compilation.
+Il arrive que l’on veuille plutôt accéder à des éléments qui ne sont connus qu’au
moment de l’exécution, ou encore parcourir tous les éléments.
+Dans ces cas, on peut utiliser une vue sous forme de <code>java.util.Map</code>
comme dans l’exemple suivant:
+</p>
+
+<pre><code>Map&lt;String,Object&gt; elements = MetadataStandard.ISO_19115.asValueMap(
+        metadata,                           <code class="comment">// N’importe quelle
instance du paquet org.opengis.metadata ou d’un sous-paquet.
+</code>        <b>null</b>,                               <code class="comment">//
Utilisé pour résoudre des ambiguïtés. Peut être ignoré pour cet exemple.
+</code>        KeyNamePolicy.JAVABEANS_PROPERTY,   <code class="comment">// Les
clés seront les noms des méthodes mais sans le prefix « get ».
+</code>        ValueExistencePolicy.NON_EMPTY);    <code class="comment">// Les
entrés dont la valeur est nulle ou vide seront omises.
+</code><code class="comment">/*
+ * Affiche les noms de tous les éléments à la racine de la méta-données qui ont une
valeur.
+ * Cette bouche ne va pas descendre dans les enfants (pas de récursivité).
+ */</code>
+<b>for</b> (String name : elements.keySet()) {
+    System.out.println(name);
+}</code></pre>
+
+<p>
+Le <code>Map</code> retourné par <code class="SIS">asValueMap(…)</code>
est une vue « vivante »:
+tout changement dans l’instance <code>metadata</code> se reflétera immédiatement
dans la vue.
+En fait, chaque appel à <code>map.get("foo")</code> se traduit par un appel
à la méthode <code>metadata​.getFoo()</code> correspondante.
+Réciproquement, toute opération <code>map.put("foo", …)</code> ou <code>map.remove("foo")</code>
effectuée sur la vue
+sera traduite en appel à la méthode <code>metadata​.setFoo(…)</code> correspondante
si cette dernière existe.
+Cette vue est assez souple sur les clés données en argument aux méthodes de <code>Map</code>:
+elles peuvent être le nom de la propriété (<code>"foo"</code>), le nom de
la méthode (<code>"getFoo"</code>),
+ou le nom utilisé dans les diagrammes <abbr title="Unified Modeling Language">UML</abbr>
de la norme <abbr title="International Organization for Standardization">ISO</abbr>
19115
+(assez proche du nom de la propriété mais pas toujours identique).
+Les différences entre majuscules et minuscules sont ignorées si elles ne causent pas d’ambiguïtés.
+</p><p>
+Parmi les éléments de méta-données présentés dans ce chapitre,
+il en est un qui fera l’objet d’un chapitre dédié: <code class="OGC">referenceSystemInfo</code>.
+Son contenu est essentiel pour positionner précisément les données.
+Sans lui, même les positions exprimées sous forme de latitudes et longitudes sont ambigües.
+Les systèmes de références ont plusieurs caractéristiques qui les différencient des
autres méta-données:
+ils sont immuables, ne peuvent pas être parcourus par <code class="SIS">MetadataStandard.ISO_19115​.asValueMap(…)</code>,
+ont une représentation sous forme de texte particulière,
+et sont associés à un mécanisme permettant de transformer des coordonnées d’un référentiel
vers un autre.
+</p>
+</section>
 </section>
 
 
@@ -1939,7 +2011,7 @@ Une fonction inverse peut donc implémen
 <pre><code>@Override
 <b>public</b> <code class="GeoAPI">Matrix</code> derivative(<code
class="GeoAPI">DirectPosition</code> p) <b>throws</b> <code class="GeoAPI">TransformException</code>
{
     <code class="GeoAPI">Matrix</code> jac = inverse().derivative(transform(p));
-    <b>return</b> Matrices.inverse(jac);
+    <b>return</b> <code class="SIS">Matrices</code>.inverse(jac);
 }</code></pre>
 
 </section>
@@ -2547,7 +2619,7 @@ Les <abbr title="Application Programming
 <code class="GeoAPI">InternationalString</code> là où une valeur de type <code>String</code>
serait susceptible d’être localisée.
 Cette approche permet de différer le processus d’internationalisation au moment d’obtenir
 une chaîne de caractères plutôt qu’au moment de construire l’objet qui les contient.
-C’est particulièrement utile pour les classes immutables qui serviront à créer des instances
uniques
+C’est particulièrement utile pour les classes immuables qui serviront à créer des instances
uniques
 indépendamment des conventions locales.
 </p>
 <div class="example"><p><b>Exemple:</b>



Mime
View raw message