Author: desruisseaux
Date: Sat Dec 8 16:46:05 2012
New Revision: 1418705
URL: http://svn.apache.org/viewvc?rev=1418705&view=rev
Log:
Added some content in the developer guide.
Modified:
sis/branches/JDK7/src/main/docbook/fr/XML.xml
sis/branches/JDK7/src/main/javadoc/stylesheet.css
Modified: sis/branches/JDK7/src/main/docbook/fr/XML.xml
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/src/main/docbook/fr/XML.xml?rev=1418705&r1=1418704&r2=1418705&view=diff
==============================================================================
--- sis/branches/JDK7/src/main/docbook/fr/XML.xml (original)
+++ sis/branches/JDK7/src/main/docbook/fr/XML.xml Sat Dec 8 16:46:05 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">
+ <!-- placer ici une définition de l'objet -->
+ </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>
@@ -265,18 +342,18 @@ public class MyClass {
<tbody>
<row>
<entry>
- <programlisting language="xml"><gmd:CI_Citation>
- <gmd:series>
- <gmd:CI_Series>
+ <programlisting language="xml"><CI_Citation>
+ <series>
+ <CI_Series>
<!-- Some content here -->
- </gmd:CI_Series>
- </gmd:series>
-</gmd:CI_Citation></programlisting>
+ </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/branches/JDK7/src/main/javadoc/stylesheet.css
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/src/main/javadoc/stylesheet.css?rev=1418705&r1=1418704&r2=1418705&view=diff
==============================================================================
--- sis/branches/JDK7/src/main/javadoc/stylesheet.css (original)
+++ sis/branches/JDK7/src/main/javadoc/stylesheet.css Sat Dec 8 16:46:05 2012
@@ -129,7 +129,7 @@ div.block ol {
div.block li > ul,
div.block li > ol {
margin-top: 0pt;
- margin-bottom: 0pt;
+ margin-bottom: 6pt;
}
div.block ul {
