You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2017/11/17 20:07:56 UTC
svn commit: r1815623 - in /sis/site/trunk/content/book:
en/developer-guide.html fr/developer-guide.html
Author: desruisseaux
Date: Fri Nov 17 20:07:56 2017
New Revision: 1815623
URL: http://svn.apache.org/viewvc?rev=1815623&view=rev
Log:
Regenerate the developer guide.
Modified:
sis/site/trunk/content/book/en/developer-guide.html
sis/site/trunk/content/book/fr/developer-guide.html
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=1815623&r1=1815622&r2=1815623&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] Fri Nov 17 20:07:56 2017
@@ -16,7 +16,7 @@
<link href="../book.css" rel="stylesheet" type="text/css"/>
</head>
<body>
-<p style="margin-top: 30pt"><span style="font-size: 30pt; font-weight: 900">Introduction to Apache SIS®</span></p>
+<p style="margin-top: 30pt"><span style="font-size: 30pt; font-weight: 900">Introduction to Apache SIS™</span></p>
<p style="margin-bottom: 20pt">(English | <a href="../fr/developer-guide.html">Français</a>)</p>
<p><i>Martin Desruisseaux</i><br/>
Partially translated by <i>Christina Hough</i></p>
@@ -31,7 +31,7 @@ Partially translated by <i>Christina Hou
<li><a href="#GeoAPI">From conceptual models to Java interfaces: GeoAPI</a><ul>
<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="#CodeColors">Code colors</a></li></ul></li></ul></li>
+<li><a href="#ChosenTerms">Chosen terms</a></li></ul></li></ul></li>
<li><a href="#DataAccess">Geospatial data access</a></li>
<li><a href="#Coverage">Data coverages</a></li>
<li><a href="#Geometry">Geometries</a><ul>
@@ -122,7 +122,7 @@ Partially translated by <i>Christina Hou
<li><a href="#GeoAPI">From conceptual models to Java interfaces: GeoAPI</a><ul>
<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="#CodeColors">Code colors</a></li></ul></li></ul></nav>
+<li><a href="#ChosenTerms">Chosen terms</a></li></ul></li></ul></nav>
<p>
A geospatial information community is a collection of systems or individuals capable of exchanging their geospatial data
through the use of common standards, allowing them to communicate with one another.
@@ -154,7 +154,7 @@ Like databases, methods of accessing geo
In this case, however, the efforts have been more recent, and their integration in software — especially in older programs — is incomplete and not always coherent.
At the time of writing, no product to our knowledge has implemented all of the specifications in their entirety.
However, there are many implementations that cover a fairly large spectrum.
-One of these is the Apache <abbr>SIS</abbr>® library that is described in this document.
+One of these is the Apache <abbr>SIS</abbr>™ library that is described in this document.
</p><p>
Apache <abbr title="Spatial Information System">SIS</abbr> is characterized by a sustained effort to comply with standards.
In general, complying with standards demands a greater effort than would be required for an isolated development,
@@ -649,8 +649,8 @@ An instance can be created by:
Both approaches expect the same arguments (omitted in this example for brevity).
</div>
<p>
-In the default Apache SIS configuration, using <code class="GeoAPI">CRSFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code>
-is almost the same except that <code class="GeoAPI">Factory</code> may return existing instances instead than creating new instances,
+In the default Apache SIS configuration, using <code>FooFactory.createXXX(…)</code> or <code>new DefaultXXX(…)</code>
+is almost the same except that <code>FooFactory</code> may return existing instances instead than creating new instances,
and that exceptions thrown in case of invalid arguments are different types.
In more advanced configurations, using <code class="GeoAPI">Factory</code> reduces the
<a href="#ServiceLoader">direct dependencies toward Apache SIS</a>
@@ -658,8 +658,8 @@ and allows inversion of control.
</p><p>
The “<code>General</code>” prefix is sometime used instead than “<code>Default</code>”
to indicate that alternative implementations are available for some specific cases.
-For example the <code>Envelope</code> interface is implemented by at least two Apache SIS classes:
-<code class="SIS">GeneralEnvelope</code> and <code>Envelope2D</code>.
+For example the <code class="GeoAPI">Envelope</code> interface is implemented by at least two Apache SIS classes:
+<code class="SIS">GeneralEnvelope</code> and <code class="SIS">Envelope2D</code>.
The first implementation can represent envelopes with any number of dimensions
while the second implementation is specialized for two-dimensional envelopes.
</p><p>
@@ -678,27 +678,6 @@ However such instantiations should be do
<h2 id="AboutBook"><span class="section-number">1.3.</span> Conventions used in this guide</h2>
</header>
<p>
-Standards sometimes favour the application of certain generic terms to particular contexts,
-which may differ from the context in which other communities use these terms.
-For example, the terms <i>domain</i> and <i>range</i> may apply to arbitrary functions in order to designate
-a set of possible values of inputs and outputs respectively.
-But the functions to which they are applied by certain <abbr>ISO</abbr> standards are not the same as the functions to which they are applied by other libraries.
-For example, <abbr>ISO</abbr> 19123 applies these terms to <code class="OGC">CV_Coverage</code> objects,
-seen as functions in which the <i>domain</i> is the set of spatio-temporal coordinates encompassed by the data,
-and the <i>range</i> is the set of values encompassed.
-But <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>’s <abbr title="Network Common Data Form">netCDF</abbr> library
-applies these terms instead to the function of converting pixel indices (its <i>domain</i>) to spatial-temporal coordinates (its <i>range</i>).
-Thus the <abbr>UCAR</abbr> library’s <i>range</i> may be the <i>domain</i> of <abbr>ISO</abbr> 19123.
-</p><p>
-The Apache <abbr title="Spatial Information System">SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr title="Open Geospatial Consortium">OGC</abbr> and <abbr>ISO</abbr> norms.
-Particular care must be taken, however, with the interfaces between <abbr>SIS</abbr> and certain other external libraries,
-in order to reduce the risk of confusion.
-</p>
-
-
-
-<h3 id="CodeColors"><span class="section-number">1.3.1.</span> Code colors</h3>
-<p>
The elements defined in a computer language, such as classes and methods in Java or elements in an <abbr>XML</abbr> document,
appear in monospaced font.
In order to facilitate an understanding of the relationships between Apache <abbr title="Spatial Information System">SIS</abbr> and the standards, these elements are also represented using the following colour codes:
@@ -725,6 +704,27 @@ Example: <code>String</code>.
<p>
Text in gray boxes are for information purpose only and can be ignored.
</p>
+
+
+
+<h3 id="ChosenTerms"><span class="section-number">1.3.1.</span> Chosen terms</h3>
+<p>
+Standards sometimes favour the application of certain generic terms to particular contexts,
+which may differ from the context in which other communities use these terms.
+For example, the terms <i>domain</i> and <i>range</i> may apply to arbitrary functions in order to designate
+a set of possible values of inputs and outputs respectively.
+But the functions to which they are applied by certain <abbr title="International Organization for Standardization">ISO</abbr> standards are not the same as the functions to which they are applied by other libraries.
+For example, <abbr>ISO</abbr> 19123 applies these terms to <code class="OGC">CV_Coverage</code> objects,
+seen as functions in which the <i>domain</i> is the set of spatio-temporal coordinates encompassed by the data,
+and the <i>range</i> is the set of values encompassed.
+But <abbr title="University Corporation for Atmospheric Research">UCAR</abbr>’s <abbr title="Network Common Data Form">netCDF</abbr> library
+applies these terms instead to the function of converting pixel indices (its <i>domain</i>) to spatial-temporal coordinates (its <i>range</i>).
+Thus the <abbr>UCAR</abbr> library’s <i>range</i> may be the <i>domain</i> of <abbr>ISO</abbr> 19123.
+</p><p>
+The Apache <abbr title="Spatial Information System">SIS</abbr> library prefers as much as possible to use terms in the sense of <abbr title="Open Geospatial Consortium">OGC</abbr> and <abbr>ISO</abbr> norms.
+Particular care must be taken, however, with the interfaces between <abbr>SIS</abbr> and certain other external libraries,
+in order to reduce the risk of confusion.
+</p>
</section>
</section>
@@ -766,8 +766,8 @@ in a unique metadata model in order to h
This approach — to select a single metadata model as the <em>pivot model</em> — is often used by other libraries.
For example Apache Tika uses <cite>Dublin Core</cite> as the pivot metadata model,
while Java Image I/O defines its own standard metadata model in its <code>javax.imageio.metadata</code> package.
-For Apache <abbr>SIS</abbr>, the chosen pivot model is the <cite><abbr title="International Organization for Standardization">ISO</abbr> 19115-1:2014 — Fundamentals</cite>
-international standard, completed by <cite><abbr>ISO</abbr> 19115-2 — Extensions for imagery and gridded data</cite>.
+For Apache <abbr>SIS</abbr>, the chosen pivot model is the <abbr title="International Organization for Standardization">ISO</abbr> <cite>19115-1:2014 — Fundamentals</cite>
+international standard, completed by <abbr>ISO</abbr> 19115-2 — <cite>Extensions for imagery and gridded data</cite>.
This model organizes metadata in a tree structure where each information is accessible by a well-defined path,
regardless the origin of that information.
For example if a data format can provides a geographic bounding box encompassing all data,
@@ -797,10 +797,10 @@ This example produces the following outp
<pre><samp>The geographic bounding box is:
Geographic Bounding Box
- ├─West bound longitude…………………………… 108°20′10,464″E
- ├─East bound longitude…………………………… 110°26′39,66″E
- ├─South bound latitude…………………………… 10°29′59,604″N
- └─North bound latitude…………………………… 12°37′25,716″N</samp></pre>
+ ├─West bound longitude…………………………… 108°20′10.464″E
+ ├─East bound longitude…………………………… 110°26′39.66″E
+ ├─South bound latitude…………………………… 10°29′59.604″N
+ └─North bound latitude…………………………… 12°37′25.716″N</samp></pre>
<p>
The Java code in this example extracts metadata elements by Java method invocations like <code class="GeoAPI">getExtents()</code>,
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=1815623&r1=1815622&r2=1815623&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] Fri Nov 17 20:07:56 2017
@@ -16,7 +16,7 @@
<link href="../book.css" rel="stylesheet" type="text/css"/>
</head>
<body>
-<p style="margin-top: 30pt"><span style="font-size: 30pt; font-weight: 900">Introduction à Apache SIS®</span></p>
+<p style="margin-top: 30pt"><span style="font-size: 30pt; font-weight: 900">Introduction à Apache SIS™</span></p>
<p style="margin-bottom: 20pt">(<a href="../en/developer-guide.html">English</a> | Français)</p>
<p><i>Martin Desruisseaux</i><br/>
<i>Christina Hough</i> (pour la traduction anglaise)</p>
@@ -31,7 +31,7 @@
<li><a href="#GeoAPI">Des modèles conceptuels vers des interfaces Java: GeoAPI</a><ul>
<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="#CodeColors">Code de couleurs</a></li></ul></li></ul></li>
+<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="#Coverage">Couvertures de données (Coverages)</a></li>
<li><a href="#Geometry">Géométries</a><ul>
@@ -121,7 +121,7 @@
<li><a href="#GeoAPI">Des modèles conceptuels vers des interfaces Java: GeoAPI</a><ul>
<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="#CodeColors">Code de couleurs</a></li></ul></li></ul></nav>
+<li><a href="#ChosenTerms">Choix des termes</a></li></ul></li></ul></nav>
<p>
Une communauté d’informations géospatiales est un ensemble de systèmes ou d’individus capables d’échanger
leurs données géospatiales grâce à des définitions et des standards communs ainsi qu’une reconnaissance réciproque.
@@ -156,7 +156,7 @@ Mais les efforts en ce sens sont plus r�
sont incomplètes et pas toujours cohérentes.
Au moment d’écrire ces lignes, aucun produit de notre connaissance n’implémente la totalité des spécifications.
Mais on trouve de nombreuses implémentations couvrant un spectre plus ou moins large.
-La bibliothèque Apache <abbr>SIS</abbr>® décrite dans ce document en est une.
+La bibliothèque Apache <abbr>SIS</abbr>™ décrite dans ce document en est une.
</p><p>
Apache <abbr title="Spatial Information System">SIS</abbr> se caractérise par un effort soutenu de respect des standards.
De manière générale, le respect des standards exige un effort plus grand que ce qu’aurait requis un développement isolé,
@@ -681,8 +681,8 @@ Les deux approches attendent les mêmes
</div>
<p>
Dans la configuration par défaut de Apache SIS,
-utiliser <code class="GeoAPI">CRSFactory.createXXX(…)</code> ou <code>new DefaultXXX(…)</code> revient presque au même
-excepté que les <code class="GeoAPI">Factory</code> peuvent retourner des instances existantes
+utiliser <code>FooFactory.createXXX(…)</code> ou <code>new DefaultXXX(…)</code> revient presque au même
+excepté que les <code>FooFactory</code> peuvent retourner des instances existantes
plutôt que de créer systématiquement de nouvelles instances,
et que les exceptions en cas d’arguments invalides sont de types différents.
Dans des configurations plus avancées, l’usage des <code class="GeoAPI">Factory</code> permet de
@@ -691,8 +691,8 @@ et de permettre une inversion de contrô
</p><p>
Le préfix « <code>General</code> » est parfois utilisé à la place de « <code>Default</code> »
afin de signaler que des implémentations alternatives existent pour des cas spécifiques.
-Par exemple l’interface <code>Envelope</code> est implémentée par au moins deux classes de Apache SIS:
-<code class="SIS">GeneralEnvelope</code> et <code>Envelope2D</code>.
+Par exemple l’interface <code class="GeoAPI">Envelope</code> est implémentée par au moins deux classes de Apache SIS:
+<code class="SIS">GeneralEnvelope</code> et <code class="SIS">Envelope2D</code>.
La première implémentation peut représenter des enveloppes de n’importe quelle dimension
alors que la seconde implémentation est spécialisée pour les enveloppes à deux dimensions.
</p><p>
@@ -713,27 +713,6 @@ lorsqu’il n’est vraiment pas possibl
<h2 id="AboutBook"><span class="section-number">1.3.</span> Conventions utilisées dans ce guide</h2>
</header>
<p>
-Les standards privilégient parfois l’application de certains termes génériques à des contextes particuliers,
-qui peuvent différer du contexte dans lequel d’autres communautés emploient ces termes.
-Par exemple les termes <i>domain</i> et <i>range</i> peuvent s’appliquer à des fonctions arbitraires
-pour désigner l’ensemble des valeurs possibles en entrés et en sorties respectivement.
-Mais les fonctions auxquelles certains standards <abbr title="International Organization for Standardization">ISO</abbr>
-les appliquent ne sont pas les mêmes que les fonctions auxquelles d’autres bibliothèques les appliquent.
-Par exemple <abbr>ISO</abbr> 19123 applique ces termes aux objets <code class="OGC">CV_Coverage</code>,
-vus comme des fonctions dont le domaine est l’ensemble des coordonnées spatio-temporelles de la couverture de données
-et le <i>range</i> l’ensemble des valeurs de la couverture.
-Mais la bibliothèque <abbr title="Network Common Data Form">netCDF</abbr> de l’<abbr title="University Corporation for Atmospheric Research">UCAR</abbr>
-applique plutôt ces termes à la fonction convertissant les indices de pixels (son domaine) vers les coordonnées spatio-temporelles (son <i>range</i>).
-Ainsi, un <i>range</i> de la bibliothèque de l’<abbr>UCAR</abbr> peut être le domaine de <abbr>ISO</abbr> 19123.
-</p><p>
-La bibliothèque Apache <abbr title="Spatial Information System">SIS</abbr> privilégie autant que possible l’utilisation des termes dans le sens des normes <abbr title="Open Geospatial Consortium">OGC</abbr> et <abbr>ISO</abbr>.
-Mais un soin particulier doit être apporté aux interfaces entre <abbr>SIS</abbr> et certaines bibliothèques externes, afin de réduire les risques de confusions.
-</p>
-
-
-
-<h3 id="CodeColors"><span class="section-number">1.3.1.</span> Code de couleurs</h3>
-<p>
Les éléments définis dans un langage informatique, tels que les classes ou méthodes en Java
ainsi que les éléments dans un fichier <abbr>XML</abbr>, apparaissent avec une police de caractères mono-espacée.
Afin de faciliter la compréhension des liens qui existent entre Apache <abbr title="Spatial Information System">SIS</abbr> et les standards,
@@ -762,6 +741,27 @@ Exemple: <code>String</code>.
Des compléments d’information apparaissent dans des boîtes grises.
Le lecteur peut ignorer ces boîtes grises sans que cela ne nuise à la compréhension du texte.
</p>
+
+
+
+<h3 id="ChosenTerms"><span class="section-number">1.3.1.</span> Choix des termes</h3>
+<p>
+Les standards privilégient parfois l’application de certains termes génériques à des contextes particuliers,
+qui peuvent différer du contexte dans lequel d’autres communautés emploient ces termes.
+Par exemple les termes <i>domain</i> et <i>range</i> peuvent s’appliquer à des fonctions arbitraires
+pour désigner l’ensemble des valeurs possibles en entrés et en sorties respectivement.
+Mais les fonctions auxquelles certains standards <abbr title="International Organization for Standardization">ISO</abbr>
+les appliquent ne sont pas les mêmes que les fonctions auxquelles d’autres bibliothèques les appliquent.
+Par exemple <abbr>ISO</abbr> 19123 applique ces termes aux objets <code class="OGC">CV_Coverage</code>,
+vus comme des fonctions dont le domaine est l’ensemble des coordonnées spatio-temporelles de la couverture de données
+et le <i>range</i> l’ensemble des valeurs de la couverture.
+Mais la bibliothèque <abbr title="Network Common Data Form">netCDF</abbr> de l’<abbr title="University Corporation for Atmospheric Research">UCAR</abbr>
+applique plutôt ces termes à la fonction convertissant les indices de pixels (son domaine) vers les coordonnées spatio-temporelles (son <i>range</i>).
+Ainsi, un <i>range</i> de la bibliothèque de l’<abbr>UCAR</abbr> peut être le domaine de <abbr>ISO</abbr> 19123.
+</p><p>
+La bibliothèque Apache <abbr title="Spatial Information System">SIS</abbr> privilégie autant que possible l’utilisation des termes dans le sens des normes <abbr title="Open Geospatial Consortium">OGC</abbr> et <abbr>ISO</abbr>.
+Mais un soin particulier doit être apporté aux interfaces entre <abbr>SIS</abbr> et certaines bibliothèques externes, afin de réduire les risques de confusions.
+</p>
</section>
</section>
@@ -805,8 +805,8 @@ Cette approche, consistant à choisir un
Par exemple Apache Tika utilise le standard <cite>Dublin Core</cite> comme modèle pivot,
alors que Java Image I/O définit son propre modèle standard dans le paquet <code>javax.imageio.metadata</code>.
Pour Apache <abbr>SIS</abbr>, le modèle pivot choisi est le standard international de méta-données en information géographique
-<cite><abbr title="International Organization for Standardization">ISO</abbr> 19115-1:2014 — principes de base</cite>, complété par
-<cite><abbr>ISO</abbr> 19115-2 — extensions pour l’acquisition et le traitement</cite>.
+<abbr title="International Organization for Standardization">ISO</abbr> 19115-1:2014 — <cite>principes de base</cite>, complété par
+<abbr>ISO</abbr> 19115-2 — <cite>extensions pour l’acquisition et le traitement</cite>.
Ce modèle organise les méta-données dans une arborescence où chaque information est accessible via un chemin bien défini,
peu importe l’origine de cette information.
Par exemple si un format de données peut nous fournir les coordonnées géographiques d’une boîte englobant toutes les données,