sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1420668 [3/3] - in /sis/trunk: ./ ide-project/NetBeans/ ide-project/NetBeans/nbproject/ sis-metadata/src/main/java/org/apache/sis/internal/ sis-utility/src/main/java/org/apache/sis/internal/jaxb/ sis-utility/src/main/java/org/apache/sis/in...
Date Wed, 12 Dec 2012 13:38:24 GMT
Modified: sis/trunk/src/main/docbook/fr/XML.xml
URL: http://svn.apache.org/viewvc/sis/trunk/src/main/docbook/fr/XML.xml?rev=1420668&r1=1420667&r2=1420668&view=diff
==============================================================================
--- sis/trunk/src/main/docbook/fr/XML.xml (original)
+++ sis/trunk/src/main/docbook/fr/XML.xml Wed Dec 12 13:38:18 2012
@@ -120,42 +120,88 @@
     </para>
     <para>
       Le standard <acronym>ISO</acronym> 19139 dispose le contenu de ces objets
d’une manière inhabituelle:
-      pour chaque attribut dont le type est lui-même une autre classe du standard <acronym>ISO</acronym>
19139,
-      l’attribut est enveloppé dans un élément qui représente son type plutôt
que d’être écrit directement.
-      Par exemple dans un objet de type <classname role="OGC">gmd:CI_Citation</classname>,
-      l’attribut <function role="OGC">gmd:citedResponsibleParty</function>
-      est enveloppé dans un élément <classname role="OGC">gmd:CI_ResponsibleParty</classname>.
+      pour chaque propriété dont le type de la valeur est lui-même une autre classe
du standard <acronym>ISO</acronym> 19139,
+      la valeur est enveloppée dans un élément qui représente son type plutôt
que d’être écrite directement.
+      Par exemple dans un objet de type <classname role="OGC">CI_Citation</classname>,
+      la valeur de la propriété <function role="OGC">citedResponsibleParty</function>
+      est enveloppée dans un élément <classname role="OGC">CI_ResponsibleParty</classname>.
       Cette pratique double la profondeur de l’arborescence, en introduisant une duplication
-      à tous les niveaux pour chaque attribut, comme dans l’exemple suivant:
+      à tous les niveaux pour chaque valeur, comme dans l’exemple suivant:
     </para>
     <example>
       <title>Redondance dans la représentation <acronym>XML</acronym>
d’une méta-donnée</title>
-      <programlisting language="xml">&lt;gmd:MD_Metadata&gt;
-  &lt;gmd:identificationInfo&gt;
-    &lt;gmd:MD_DataIdentification&gt;
-      &lt;gmd:citation&gt;
-        &lt;gmd:CI_Citation&gt;
-          &lt;gmd:citedResponsibleParty&gt;
-            &lt;gmd:CI_ResponsibleParty&gt;
-              &lt;gmd:contactInfo&gt;
-                &lt;gmd:CI_Contact&gt;
-                  &lt;gmd:onlineResource&gt;
-                    &lt;gmd:CI_OnlineResource&gt;
-                      &lt;gmd:linkage&gt;
-                        &lt;gmd:URL&gt;http://www.opengeospatial.org&lt;/gmd:URL&gt;
-                      &lt;/gmd:linkage&gt;
-                    &lt;/gmd:CI_OnlineResource&gt;
-                  &lt;/gmd:onlineResource&gt;
-                &lt;/gmd:CI_Contact&gt;
-              &lt;/gmd:contactInfo&gt;
-            &lt;/gmd:CI_ResponsibleParty&gt;
-          &lt;/gmd:citedResponsibleParty&gt;
-        &lt;/gmd:CI_Citation&gt;
-      &lt;/gmd:citation&gt;
-    &lt;/gmd:MD_DataIdentification&gt;
-  &lt;/gmd:identificationInfo&gt;
-&lt;/gmd:MD_Metadata&gt;</programlisting>
+      <programlisting language="xml">&lt;MD_Metadata&gt;
+  &lt;identificationInfo&gt;
+    &lt;MD_DataIdentification&gt;
+      &lt;citation&gt;
+        &lt;CI_Citation&gt;
+          &lt;citedResponsibleParty&gt;
+            &lt;CI_ResponsibleParty&gt;
+              &lt;contactInfo&gt;
+                &lt;CI_Contact&gt;
+                  &lt;onlineResource&gt;
+                    &lt;CI_OnlineResource&gt;
+                      &lt;linkage&gt;
+                        &lt;URL&gt;http://www.opengeospatial.org&lt;/URL&gt;
+                      &lt;/linkage&gt;
+                    &lt;/CI_OnlineResource&gt;
+                  &lt;/onlineResource&gt;
+                &lt;/CI_Contact&gt;
+              &lt;/contactInfo&gt;
+            &lt;/CI_ResponsibleParty&gt;
+          &lt;/citedResponsibleParty&gt;
+        &lt;/CI_Citation&gt;
+      &lt;/citation&gt;
+    &lt;/MD_DataIdentification&gt;
+  &lt;/identificationInfo&gt;
+&lt;/MD_Metadata&gt;</programlisting>
     </example>
+    <para>
+      L’exemple précédent, comme tous les documents conformes à <acronym>ISO</acronym>
19139,
+      est constitué d’une alternance systématique de deux types d’éléments
<acronym>XML</acronym>.
+      Il y a d’abord le nom de la propriété, qui commence toujours par une lettre
minuscule (en ignorant les préfixes).
+      Dans les <acronym>API</acronym> Java, chaque propriété correspond
à une méthode de la classe englobante.
+      Par exemple dans l’exemple ci-haut, <classname role="OGC">gmd:identificationInfo</classname>
+      correspond à la méthode <function role="GeoAPI">Metadata.getIdentificationInfo()</function>.
+      Contrairement aux <acronym>API</acronym> Java toutefois, les documents
<acronym>XML</acronym>
+      ne placent pas les propriétés filles directement en dessous.
+      À la place, ces éléments n’acceptent que les informations suivantes:
+    </para>
+    <itemizedlist>
+      <listitem>
+        Un élément, décrit dans le paragraphe suivant, qui englobera les propriétés
filles.
+      </listitem>
+      <listitem>
+        Un groupe d’attributs (notamment <literal role="OGC">gmd:idref</literal>,
<literal role="OGC">gco:uuidref</literal> et <literal>xlink:href</literal>)
+        que les schémas <acronym>XSD</acronym> de l’<acronym>OGC</acronym>
nomment collectivement <classname role="OGC">gco:ObjectReference</classname>.
+      </listitem>
+    </itemizedlist>
+    <para>
+      Sous chaque propriété se trouve le type de la valeur, sauf si elle a été
remplacée par une référence (la sous-section suivante approfondira ce sujet).
+      Le type de la valeur est un élément <acronym>XML</acronym> dont le
nom commence toujours par une lettre majuscule, en ignorant les préfixes.
+      Dans l’exemple ci-haut nous avions <classname role="OGC">MD_DataIdentification</classname>,
qui correspond à l’interface Java <classname role="GeoAPI">DataIdentification</classname>.
+      C’est cet élément <acronym>XML</acronym> qui contient les propriétés
filles. Cet élément accepte aussi un groupe d’attributs
+      (notamment <literal role="OGC">gmd:id</literal> et <literal role="OGC">gco:uuid</literal>)
+      que les schémas <acronym>XSD</acronym> de l’<acronym>OGC</acronym>
nomment collectivement <classname role="OGC">gco:ObjectIdentification</classname>.
+      Ces attributs n’ont pas de méthodes Java dédiées, mais sont accessibles
indirectement via l’interface <classname role="SIS">IdentifiedObject</classname>
+      décrite dans la sous-section suivante.
+    </para>
+    <sidebar>
+      <title>Convention de nommage dans les schémas <acronym>XSD</acronym></title>
+      <para>
+        Les schémas <acronym>XSD</acronym> de l’<acronym>OGC</acronym>
définissent pour chaque élément du premier groupe
+        un type dont le nom se termine par “<classname role="OGC">_PropertyType</classname>”.
+        Pour le second groupe, chaque élément a un type dont le nom se termine par
“<classname role="OGC">_Type</classname>”.
+      </para>
+    </sidebar>
+    <para>
+      Afin de réduire la complexité des bibliothèques, GeoAPI et Apache <acronym>SIS</acronym>
n’exposent publiquement
+      qu’une vision unifiée de ces deux types d’éléments. L’<acronym>API</acronym>
public correspond essentiellement au
+      deuxième groupe. Toutefois, lors de l’écriture d’un document <acronym>XML</acronym>,
des éléments du premier groupe
+      doivent être temporairement recréés. Les classes qui y correspondent sont
définies dans des paquets internes de
+      <acronym>SIS</acronym>. Ces classes peuvent être ignorées, sauf si
le développeur souhaite implémenter ses propres
+      classes dont les instances devront être lus et écrits par <acronym>JAXB</acronym>.
+    </para>
     <sidebar>
       <title>Stratégie d’implémentation dans Apache <acronym>SIS</acronym></title>
       <para>
@@ -164,7 +210,7 @@
         Ces adaptateurs sont de toute façon nécessaires pour permettre à <acronym>JAXB</acronym>
         d’obtenir les classes <acronym>SIS</acronym> implémentant les
interfaces de GeoAPI.
         De manière opportuniste, <acronym>SIS</acronym> en fait à la fois
des adaptateurs <acronym>JAXB</acronym>
-        et des objets englobants le “vrai” objet à lire ou écrire.
+        et des objets enveloppants le “vrai” objet à lire ou écrire.
         Cette utilisation double permet d’éviter d’avoir à doubler le nombre
de classes
         (déjà très élevé) présents dans les paquets internes.
       </para>
@@ -177,6 +223,37 @@
         <literal role="OGC">gco:uuid</literal> ou <literal>xlink:href</literal>.
         Si un de ces attributs est présent, l’élément englobé peut être
complètement omis;
         il sera remplacé au moment de la lecture par l’élément référencé
par l’attribut.
+        Dans l’exemple suivant, la partie gauche définie un élément associé
à l’identifiant “<literal>mon_id</literal>”,
+        alors que la partie droite référence cet élément:
+      </para>
+      <example>
+        <title>Association d’un identifiant à un élément <acronym>XML</acronym></title>
+        <informaltable frame="none">
+          <tgroup cols="2">
+            <colspec colwidth="50%"/>
+            <colspec colwidth="50%"/>
+            <tbody>
+              <row>
+                <entry>
+                  <programlisting language="xml">&lt;MD_MetaData&gt;
+  &lt;identificationInfo&gt;
+    &lt;MD_DataIdentification id="mon_id"&gt;
+      &lt;!-- insérer ici des propriétés filles --&gt;
+    &lt;/MD_DataIdentification&gt;
+  &lt;/identificationInfo&gt;
+&lt;/MD_MetaData&gt;</programlisting>
+                </entry>
+                <entry>
+                  <programlisting language="xml">&lt;MD_MetaData&gt;
+  &lt;identificationInfo idref="mon_id"/&gt;
+&lt;/MD_MetaData&gt;</programlisting>
+                </entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+      </example>
+      <para>
         Le choix de l’attribut à utiliser dépend de la portée de l’élément
référencé:
       </para>
       <itemizedlist>
@@ -218,7 +295,8 @@ public class MyClass {
 }</programlisting>
       </example>
       <para>
-        Bien que ce mécanisme aie été définit dans le but de mieux supporter
les représentations de méta-données en <acronym>XML</acronym>,
+        Bien que ce mécanisme aie été définit dans le but de mieux supporter
les représentations des
+        attributs <acronym>XML</acronym> du groupe <classname role="OGC">gco:ObjectIdentification</classname>,
         il permet aussi de manière opportuniste de manipuler d’autres types d’identifiants.
         Par exemple les attributs <function role="GeoAPI">ISBN</function> et
<function role="GeoAPI">ISSN</function>
         de <classname role="GeoAPI">Citation</classname> peuvent être manipulés
de cette manière.
@@ -265,18 +343,18 @@ public class MyClass {
             <tbody>
               <row>
                 <entry>
-                  <programlisting language="xml">&lt;gmd:CI_Citation&gt;
-  &lt;gmd:series&gt;
-    &lt;gmd:CI_Series&gt;
-      &lt;!-- Some content here --&gt;
-    &lt;/gmd:CI_Series&gt;
-  &lt;/gmd:series&gt;
-&lt;/gmd:CI_Citation&gt;</programlisting>
+                  <programlisting language="xml">&lt;CI_Citation&gt;
+  &lt;series&gt;
+    &lt;CI_Series&gt;
+      &lt;!-- insérer ici des propriétés filles --&gt;
+    &lt;/CI_Series&gt;
+  &lt;/series&gt;
+&lt;/CI_Citation&gt;</programlisting>
                 </entry>
                 <entry>
-                  <programlisting language="xml">&lt;gmd:CI_Citation&gt;
-  &lt;gmd:series nilReason="unknown"/&gt;
-&lt;/gmd:CI_Citation&gt;</programlisting>
+                  <programlisting language="xml">&lt;CI_Citation&gt;
+  &lt;series nilReason="unknown"/&gt;
+&lt;/CI_Citation&gt;</programlisting>
                 </entry>
               </row>
             </tbody>

Modified: sis/trunk/src/main/docbook/fr/geoapi.xml
URL: http://svn.apache.org/viewvc/sis/trunk/src/main/docbook/fr/geoapi.xml?rev=1420668&r1=1420667&r2=1420668&view=diff
==============================================================================
--- sis/trunk/src/main/docbook/fr/geoapi.xml (original)
+++ sis/trunk/src/main/docbook/fr/geoapi.xml Wed Dec 12 13:38:18 2012
@@ -260,7 +260,7 @@ System.out.println("Le nom standard de l
       </example>
 
       <para>
-        La classe <classname role="SIS">org.apache.sis.util.type.Types</classname>
fournit la méthode de commodité
+        La classe <classname role="SIS">org.apache.sis.util.iso.Types</classname>
fournit la méthode de commodité
         <function role="SIS">getStandardName(Class)</function> pour effectuer
cette opération.
       </para>
 
@@ -288,7 +288,7 @@ System.out.println("L’interface Geo
       </example>
 
       <para>
-        La classe <classname role="SIS">org.apache.sis.util.type.Types</classname>
fournit la méthode de commodité
+        La classe <classname role="SIS">org.apache.sis.util.iso.Types</classname>
fournit la méthode de commodité
         <function role="SIS">forStandardName(String)</function> pour effectuer
cette opération.
       </para>
     </section>

Modified: sis/trunk/src/main/docbook/fr/utility.xml
URL: http://svn.apache.org/viewvc/sis/trunk/src/main/docbook/fr/utility.xml?rev=1420668&r1=1420667&r2=1420668&view=diff
==============================================================================
--- sis/trunk/src/main/docbook/fr/utility.xml (original)
+++ sis/trunk/src/main/docbook/fr/utility.xml Wed Dec 12 13:38:18 2012
@@ -20,7 +20,9 @@
       Mais cette politique nécessite que chaque interface ou classe de base définisse
entièrement dans sa Javadoc les critères ou calculs
       que doivent employer les méthodes <function>equals(Object)</function>
et <function>hashCode()</function> dans toutes les implémentations.
       Cette approche est choisie notamment par <classname>java.util.Collection</classname>
et ses interfaces filles.
-      Elle se fait toutefois au détriment de la possibilité de prendre en compte des
attributs supplémentaires dans les interfaces filles,
+      La transposition de cette approche aux centaines d’interfaces de GeoAPI serait
toutefois une entreprise ardue,
+      qui risquerait d’être assez peu suivie par les diverses implémentations.
+      En outre, elle se fait au détriment de la possibilité de prendre en compte des
attributs supplémentaires dans les interfaces filles
       si cette possibilité n’a pas été spécifiée dans l’interface
parente.
       Cette contrainte découle des points suivants du contrat des méthodes <function>equals(Object)</function>
et <function>hashCode()</function>:
     </para>
@@ -35,7 +37,7 @@
       Pour contourner cette difficulté, une approche alternative consiste à exiger
que les objets comparés par la méthode
       <function>Object.equals(Object)</function> soient exactement de la même
classe, c’est-à-dire que <literal>A.getClass() == B.getClass()</literal>.
       Cette approche est parfois considérée contraire aux principes de la programmation
orientée objets.
-      Dans la pratique, pour des applications relativement complexes, ça dépend du
contexte dans lequel les objets sont comparés:
+      Dans la pratique, pour des applications relativement complexes, l’importance accordée
à ces principes dépend du contexte dans lequel les objets sont comparés:
       si les objets sont ajoutés à un <classname>HashSet</classname> ou
utilisés comme clés dans un <classname>HashMap</classname>,
       alors nous avons besoin d’un strict respect du contrat de <function>equals(Object)</function>
et <function>hashCode()</function>.
       Mais si le développeur compare les objets lui-même, par exemple pour vérifier
si des informations qui l’intéresse ont changées,
@@ -70,9 +72,13 @@
     </itemizedlist>
     <para>
       Le mode par défaut, utilisé par les toutes les méthodes <function>equals(Object)</function>
de <acronym>SIS</acronym>,
-      est <constant role="SIS">STRICT</constant>. Ce mode est choisi à la
fois pour une utilisation plus sécuritaire avec <classname>HashMap</classname>,
-      et aussi parce que définir rigoureusement le contrat des méthodes <function>equals(Object)</function>
et <function>hashCode()</function>
-      dans les centaines d’interfaces de GeoAPI semble une entreprise peu réaliste,
qui risque d’être assez peu suivit par les diverses implémentations.
+      est <constant role="SIS">STRICT</constant>. Ce mode est choisi pour une
utilisation sécuritaire — notamment avec <classname>HashMap</classname> —
+      sans nécessiter de définitions rigoureuses des méthodes <function>equals(Object)</function>
et <function>hashCode()</function> dans toutes les interfaces.
+      Avec ce mode, l’ordre des objets (<literal>A.equals(B)</literal> ou
<literal>B.equals(A)</literal>) n’a pas d’importance.
+      C’est toutefois le seul mode à offrir cette garantie. Dans l’expression
<literal>A.equals(B)</literal>,
+      le mode <constant role="SIS">BY_CONTRACT</constant> (et donc par extension
tous les autres modes qui en dépendent)
+      ne comparera que les propriétés connues de <literal>A</literal>,
sans se soucier de savoir si <literal>B</literal>
+      en connaît davantage.
     </para>
   </section>
 
@@ -167,6 +173,31 @@
     </section>
 
     <section>
+      <title>Convention locale nulle</title>
+      <para>
+        La plupart des méthodes <acronym>SIS</acronym> recevant ou retournant
une valeur de type <classname>Locale</classname>
+        acceptent la valeur <constant>null</constant>. Cette valeur est interprétée
comme signifiant de ne pas localiser le texte.
+        La notion de <quote>texte non-localisé</quote> est un peu fausse,
puisqu’il faut bien choisir une convention de format.
+        Mais cette convention, bien que très proche de l’anglais, sera généralement
légèrement différente.
+        Par exemple:
+      </para>
+      <itemizedlist>
+        <listitem>
+          Les identifiants sont écrits tels qu’ils apparaissent dans les diagrammes
<acronym>UML</acronym>,
+          par exemple <quote>blurredImage</quote> au lieu de <quote>Blurred
image</quote>.
+        </listitem>
+        <listitem>
+          Les dates sont écrites selon le format <acronym>ISO</acronym> 8601,
+          qui ne correspond pas aux conventions anglaises.
+        </listitem>
+        <listitem>
+          Les nombres sont écrits à l’aide de leurs méthodes <function>toString()</function>
plutôt qu’à l’aide d’un <classname>java.text.NumberFormat</classname>.
+          Il en résulte des différences dans le nombre de chiffres significatifs, l’utilisation
de la notation exponentielle et l’absence de séparateur des milliers.
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section>
       <title>Traitement des caractères</title>
       <para>
         Les chaînes de caractères en Java utilisent l’encodage UTF-16. Il existe
une correspondance directe

Modified: sis/trunk/src/main/javadoc/stylesheet.css
URL: http://svn.apache.org/viewvc/sis/trunk/src/main/javadoc/stylesheet.css?rev=1420668&r1=1420667&r2=1420668&view=diff
==============================================================================
--- sis/trunk/src/main/javadoc/stylesheet.css (original)
+++ sis/trunk/src/main/javadoc/stylesheet.css Wed Dec 12 13:38:18 2012
@@ -104,6 +104,12 @@ div.block ol {
   margin-bottom: 9pt;
 }
 
+div.block li > ul,
+div.block li > ol {
+  margin-top:    0pt;
+  margin-bottom: 6pt;
+}
+
 div.block ul {
   list-style-type: square;
 }



Mime
View raw message