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"><gmd:MD_Metadata> - <gmd:identificationInfo> - <gmd:MD_DataIdentification> - <gmd:citation> - <gmd:CI_Citation> - <gmd:citedResponsibleParty> - <gmd:CI_ResponsibleParty> - <gmd:contactInfo> - <gmd:CI_Contact> - <gmd:onlineResource> - <gmd:CI_OnlineResource> - <gmd:linkage> - <gmd:URL>http://www.opengeospatial.org</gmd:URL> - </gmd:linkage> - </gmd:CI_OnlineResource> - </gmd:onlineResource> - </gmd:CI_Contact> - </gmd:contactInfo> - </gmd:CI_ResponsibleParty> - </gmd:citedResponsibleParty> - </gmd:CI_Citation> - </gmd:citation> - </gmd:MD_DataIdentification> - </gmd:identificationInfo> -</gmd:MD_Metadata></programlisting> + <programlisting language="xml"><MD_Metadata> + <identificationInfo> + <MD_DataIdentification> + <citation> + <CI_Citation> + <citedResponsibleParty> + <CI_ResponsibleParty> + <contactInfo> + <CI_Contact> + <onlineResource> + <CI_OnlineResource> + <linkage> + <URL>http://www.opengeospatial.org</URL> + </linkage> + </CI_OnlineResource> + </onlineResource> + </CI_Contact> + </contactInfo> + </CI_ResponsibleParty> + </citedResponsibleParty> + </CI_Citation> + </citation> + </MD_DataIdentification> + </identificationInfo> +</MD_Metadata></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"><MD_MetaData> + <identificationInfo> + <MD_DataIdentification id="mon_id"> + <!-- insérer ici des propriétés filles --> + </MD_DataIdentification> + </identificationInfo> +</MD_MetaData></programlisting> + </entry> + <entry> + <programlisting language="xml"><MD_MetaData> + <identificationInfo idref="mon_id"/> +</MD_MetaData></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"><gmd:CI_Citation> - <gmd:series> - <gmd:CI_Series> - <!-- Some content here --> - </gmd:CI_Series> - </gmd:series> -</gmd:CI_Citation></programlisting> + <programlisting language="xml"><CI_Citation> + <series> + <CI_Series> + <!-- insérer ici des propriétés filles --> + </CI_Series> + </series> +</CI_Citation></programlisting> </entry> <entry> - <programlisting language="xml"><gmd:CI_Citation> - <gmd:series nilReason="unknown"/> -</gmd:CI_Citation></programlisting> + <programlisting language="xml"><CI_Citation> + <series nilReason="unknown"/> +</CI_Citation></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; }
