sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1757004 - in /sis/site/trunk: book/en/body.html book/en/utility.html book/fr/body.html book/fr/referencing.html book/fr/utility.html content/book/book.css
Date Sat, 20 Aug 2016 14:41:48 GMT
Author: desruisseaux
Date: Sat Aug 20 14:41:47 2016
New Revision: 1757004

URL: http://svn.apache.org/viewvc?rev=1757004&view=rev
Log:
Add a section about ObjectConverter.
Move to the end of the document, since this is not the core of Apache SIS purpose.

Modified:
    sis/site/trunk/book/en/body.html
    sis/site/trunk/book/en/utility.html
    sis/site/trunk/book/fr/body.html
    sis/site/trunk/book/fr/referencing.html
    sis/site/trunk/book/fr/utility.html
    sis/site/trunk/content/book/book.css

Modified: sis/site/trunk/book/en/body.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/body.html?rev=1757004&r1=1757003&r2=1757004&view=diff
==============================================================================
--- sis/site/trunk/book/en/body.html (original)
+++ sis/site/trunk/book/en/body.html Sat Aug 20 14:41:47 2016
@@ -43,10 +43,10 @@
 
     <main>
       <section><xi:include href="introduction.html"/></section>
-      <section><xi:include href="utility.html"/></section>
       <section><xi:include href="referencing.html"/></section>
       <section><xi:include href="geometry.html"/></section>
       <section><xi:include href="coverage.html"/></section>
+      <section><xi:include href="utility.html"/></section>
       <section><xi:include href="xml.html"/></section>
       <section><xi:include href="annexes.html"/></section>
     </main>

Modified: sis/site/trunk/book/en/utility.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/utility.html?rev=1757004&r1=1757003&r2=1757004&view=diff
==============================================================================
--- sis/site/trunk/book/en/utility.html (original)
+++ sis/site/trunk/book/en/utility.html Sat Aug 20 14:41:47 2016
@@ -36,9 +36,9 @@
 
     <h2 id="ComparisonMode">Comparison modes of objects</h2>
     <p>
-      There are various opinions on how to implement Java standard's <code>Object.equals(Object)</code>
method.
+      There are various opinions on how to implement Java standard’s <code>Object.equals(Object)</code>
method.
       According to some, it should be possible to compare different implementations of the
same interface or base class.
-      But to follow this policy, each interface or base class's javadoc must define the algorithms
that all implementations
+      But to follow this policy, each interface or base class’s javadoc must define
the algorithms that all implementations
       shall use for their <code>equals(Object)</code> and <code>hashCode()</code>
methods.
       This approach is common in <code>java.util.Collection</code> and its child
interfaces.
       Transferring this approach to certain GeoAPI interfaces, however, would be a difficult
task,
@@ -107,13 +107,93 @@
 
 
 
+    <h2 id="ObjectConverters">Object converters</h2>
+    <p>
+      There is sometime a need to convert instances from a <var>source</var>
Java type to a <var>target</var> Java type
+      while those types are unknown at compile time.
+      Various projects (Apache Common Convert, Spring, <i>etc.</i>)
+      have created their own interface for performing object conversions between types known
only at runtime.
+      Details vary, but such interfaces typically look like below:
+    </p>
+    <pre>interface ObjectConverter&lt;S,T&gt; {   // Some projects use only
"Converter" as interface name.
+    T apply(S object);             // Another method name commonly found in other projects
is "convert".
+}</pre>
+    <p>
+      Like other projects, Apache <abbr>SIS</abbr> also defines its own <code>ObjectConverter</code>
interface.
+      The main difference between <abbr>SIS</abbr> converter interface and the
interfaces found in other projects
+      is that <abbr>SIS</abbr> converters provide some information about their
mathematical properties.
+      An Apache <abbr>SIS</abbr> converter can have zero, one or many of the
following properties:
+    </p>
+    <dl>
+      <dt><dfn>Injective</dfn></dt>
+      <dd>A function is injective if no pair of <var>S</var> values can
produce the same <var>T</var> value.
+        <div class="example"><p><b>Example:</b>
+            the <code>Integer</code> → <code>String</code> conversion
performed by <code>Integer.toString()</code>
+            is an <cite>injective</cite> function because if two <code>Integer</code>
values are not equal,
+            then it is guaranteed that their conversions will result in different <code>String</code>
values.
+            However the <code>String</code> → <code>Integer</code>
conversion performed by <code>Integer.valueOf(String)</code>
+            is <strong>not</strong> an injective function
+            because many distinct <code>String</code> values can be converted
to the same <code>Integer</code> value.
+            For example converting the "42", "+42" and "0042" character strings all result
in the same 42 integer value.
+        </p></div>
+      </dd>
+
+      <dt><dfn>Surjective</dfn></dt>
+      <dd>A function is surjective if each values of <var>T</var> can be
created from at least one value of <var>S</var>.
+        <div class="example"><p><b>Example:</b>
+            the <code>String</code> → <code>Integer</code> conversion
performed by <code>Integer.valueOf(String)</code>
+            is a <cite>surjective</cite> function because every <code>Integer</code>
value can be created from at least one <code>String</code> value.
+            However the <code>Integer</code> → <code>String</code>
conversion performed by <code>Integer.toString()</code>
+            is <strong>not</strong> a surjective function because it can not
produce all possible <code>String</code> values.
+            For example there is no way to produce the "ABC" value with the <code>Integer.toString()</code>
method.
+        </p></div>
+      </dd>
+
+      <dt><dfn>Bijective</dfn></dt>
+      <dd>A function is bijective if there is a one-to-one relationship between <var>S</var>
and <var>T</var> values.
+        <div class="example"><p><b>Note:</b>
+          the <cite>bijective</cite> property is defined here for clarity, but
actually does not have an explicit item
+          in Apache <abbr>SIS</abbr> <code>FunctionProperty</code>
enumeration.
+          It is not necessary since a function that is both <cite>injective</cite>
and <cite>surjective</cite> is necessarily bijective.
+        </p></div>
+      </dd>
+
+      <dt><dfn>Order preserving</dfn></dt>
+      <dd>A function is order preserving if any sequence of increasing <var>S</var>
values is mapped to a sequence of increasing <var>T</var> values.
+        <div class="example"><p><b>Example:</b>
+          conversion from <code>Integer</code> to <code>Long</code>
preserve the natural ordering of elements.
+          However conversions from <code>Integer</code> to <code>String</code>
do <strong>not</strong> preserve natural ordering,
+          because some sequences of increasing integer values are ordered differently when
their string representations are sorted by lexicographic order.
+          For example 1, 2, 10 become "1", "10", "2".
+        </p></div>
+      </dd>
+
+      <dt><dfn>Order reversing</dfn></dt>
+      <dd>A function is order reversing if any sequence of increasing <var>S</var>
values is mapped to a sequence of decreasing <var>T</var> values.
+        <div class="example"><p><b>Example:</b>
+          a conversion that reverses the sign of numbers.
+        </p></div>
+      </dd>
+    </dl>
+    <p>
+      Above information may seem unnecessary when values are converted without taking in
account the context in which the values appear.
+      But when the value to convert is part of a bigger object, then above information can
affect the way the converted value will be used.
+      For example conversion of a [<var>min</var> … <var>max</var>]
range is straightforward when the converter is <cite>order preserving</cite>.
+      But if the converter is <cite>order reversing</cite>, then the minimum
and maximum values need to be interchanged.
+      For example if the converter reverses the sign of values, then the converted range
is [-<var>max</var> … -<var>min</var>].
+      If the converter is neither order preserving or order reversing, then range conversion
is not allowed at all
+      (because it does not contain the same set of values) even if the minimum and maximum
values could be converted individually.
+    </p>
+
+
+
     <h2 id="Internationalization">Internationalization</h2>
     <p>
       In an architecture where a program executed on a server provides its data to multiple
clients,
-      the server's locale conventions are not necessarily the same as those of the clients.
+      the server’s locale conventions are not necessarily the same as those of the clients.
       Conventions may differ in language, but also in the way they write numeric values
       (even between two countries that speak the same language) as well in time zone.
-      To produce messages that conform to the client's conventions, <abbr>SIS</abbr>
uses
+      To produce messages that conform to the client’s conventions, <abbr>SIS</abbr>
uses
       two approaches, distinguished by their level of granularity: at the level of the messages
themselves,
       or at the level of the objects that create the messages.
       The approach used also determines whether it is possible to share the same instance
of an object for all languages.
@@ -170,7 +250,7 @@
     </p>
     <div class="example"><p><b>Example:</b>
       <abbr>SIS</abbr> includes only one instance of the <code>OperationMethod</code>
-      type representing the Mercator projection, regardless of the client's language.
+      type representing the Mercator projection, regardless of the client’s language.
       But its <code class="GeoAPI">getName()</code> method (indirectly) provides
an instance of
       <code>InternationalString</code>, so that <code>toString(Locale.ENGLISH)</code>
returns <cite>Mercator projection</cite>
       while <code>toString(Locale.FRENCH)</code> returns <cite>Projection
de Mercator</cite>.

Modified: sis/site/trunk/book/fr/body.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/body.html?rev=1757004&r1=1757003&r2=1757004&view=diff
==============================================================================
--- sis/site/trunk/book/fr/body.html (original)
+++ sis/site/trunk/book/fr/body.html Sat Aug 20 14:41:47 2016
@@ -43,10 +43,10 @@
 
     <main>
       <section><xi:include href="introduction.html"/></section>
-      <section><xi:include href="utility.html"/></section>
       <section><xi:include href="referencing.html"/></section>
       <section><xi:include href="geometry.html"/></section>
       <section><xi:include href="coverage.html"/></section>
+      <section><xi:include href="utility.html"/></section>
       <section><xi:include href="xml.html"/></section>
       <section><xi:include href="annexes.html"/></section>
     </main>

Modified: sis/site/trunk/book/fr/referencing.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/referencing.html?rev=1757004&r1=1757003&r2=1757004&view=diff
==============================================================================
--- sis/site/trunk/book/fr/referencing.html (original)
+++ sis/site/trunk/book/fr/referencing.html Sat Aug 20 14:41:47 2016
@@ -255,7 +255,7 @@
       Mais si l’ordre (<var>x</var>, <var>y</var>) est désiré
pour des raisons de compatibilité avec d’anciens standards <abbr>OGC</abbr>
ou avec d’autres logiciels,
       alors les <abbr>CRS</abbr> peuvent être modifiés de manière à
avoir la longitude en premier avec un appel à la méthode suivante:
     </p>
-    <pre>CoordinateReferenceSystem crs = …;    // CRS obtenu de n’importe
quel façon.
+    <pre>CoordinateReferenceSystem crs = …;  // CRS obtenu de n’importe quelle
façon.
 crs = AbstractCRS.castOrCopy(crs).forConvention(AxesConvention.RIGHT_HANDED)</pre>
     <p>
       Parmi les anciens standards de l’<abbr>OGC</abbr> qui utilisaient
un ordre des axes non-conforme,

Modified: sis/site/trunk/book/fr/utility.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/utility.html?rev=1757004&r1=1757003&r2=1757004&view=diff
==============================================================================
--- sis/site/trunk/book/fr/utility.html (original)
+++ sis/site/trunk/book/fr/utility.html Sat Aug 20 14:41:47 2016
@@ -104,6 +104,89 @@
 
 
 
+    <h2 id="ObjectConverters">Object converters</h2>
+    <p>
+      Il est parfois nécessaire de convertir une instance d’un type source <code>&lt;S&gt;</code>
vers un type destination <code>&lt;T&gt;</code>
+      alors que ces types ne sont pas connus au moment de la compilation.
+      Divers projets (Apache Common Convert, Spring, <i>etc.</i>)
+      ont créé leur propres interfaces pour effectuer des conversions d’objets
entre des types connus seulement au moment de l’exécution.
+      Les détails varient, mais ces interfaces ressemblent typiquement à l’interface
suivante:
+    </p>
+    <pre>interface ObjectConverter&lt;S,T&gt; {   // Certains projets utilisent
seulement "Converter" comme nom d’interface.
+    T apply(S object);             // Un autre nom de méthode souvent utilisé par les
autres projets est "convert".
+}</pre>
+    <p>
+      Comme d’autres projets, Apache <abbr>SIS</abbr> définit sa propre
interface <code>ObjectConverter</code>.
+      La principale différence entre l’interface de <abbr>SIS</abbr>
est celle que l’on retrouve dans d’autres projets
+      est que <abbr>SIS</abbr> fournit des informations à propos de certaines
propriétés mathématiques des convertisseurs.
+      Un convertisseur de Apache <abbr>SIS</abbr> peut avoir aucune, une ou plusieurs
des propriétés suivantes:
+    </p>
+    <dl>
+      <dt><dfn>Injective</dfn></dt>
+      <dd>Une fonction est injective si aucune paire de valeurs de <var>S</var>
ne peut produire la même valeur de <var>T</var>.
+        <div class="example"><p><b>Exemple:</b>
+          la conversion <code>Integer</code> → <code>String</code>
effectuée par <code>Integer.toString()</code>
+          est une fonction <cite>injective</cite> car si deux valeurs de type
<code>Integer</code> ne sont pas égales,
+          alors il est garanti que leurs conversions produiront différentes valeurs de
<code>String</code>.
+          En revanche la conversion <code>String</code> → <code>Integer</code>
effectuée par <code>Integer.valueOf(String)</code>
+          n’est <strong>pas</strong> une fonction injective
+          parce que plusieurs valeurs distinctes de type <code>String</code>
peuvent être converties vers la même valeur de type <code>Integer</code>.
+          Par exemple les conversions des chaînes de caractères "42", "+42" et "0042"
donnent toutes la même valeur entière 42.
+        </p></div>
+      </dd>
+
+      <dt><dfn>Surjective</dfn></dt>
+      <dd>Une fonction est surjective si chaque valeur de <var>T</var>
peut être produite à partir d’au moins une valeur de <var>S</var>.
+        <div class="example"><p><b>Exemple:</b>
+          la conversion <code>String</code> → <code>Integer</code>
effectuée par <code>Integer.valueOf(String)</code>
+          est une fonction <cite>surjective</cite> car chaque valeur de type
<code>Integer</code> peut être produite
+          à partir d’un moins une valeur de <code>String</code>.
+          En revanche la conversion <code>Integer</code> → <code>String</code>
effectuée par <code>Integer.toString()</code>
+          n’est <strong>pas</strong> une fonction surjective parce qu’elle
ne peut pas produire toutes les valeurs possibles de type <code>String</code>.
+          Par exemple il n’y a aucun moyen de produire la valeur "ABC" avec la méthode
<code>Integer.toString()</code>.
+        </p></div>
+      </dd>
+
+      <dt><dfn>Bijective</dfn></dt>
+      <dd>Une fonction est bijective s’il y a une relation de un-à-un entre
les valeurs de <var>S</var> et de <var>T</var>.
+        <div class="example"><p><b>Note:</b>
+          la propriété <cite>bijective</cite> est définie ici pour des
raisons de clarté,
+          mais en fait n’a pas d’item explicite dans l’énumération <code>FunctionProperty</code>
de Apache <abbr>SIS</abbr>.
+          Ce n’est pas nécessaire puisqu’une fonction qui est à la fois <cite>injective</cite>
et <cite>surjective</cite>
+          est nécessairement bijective.
+        </p></div>
+      </dd>
+
+      <dt><dfn>Préservant l’ordre</dfn></dt>
+      <dd>Une fonction préserve l’ordre si toute séquence de valeurs <var>S</var>
croissantes correspond à une séquence de valeurs <var>T</var> croissantes.
+        <div class="example"><p><b>Exemple:</b>
+          la conversion du type <code>Integer</code> vers <code>Long</code>
préserve l’ordre naturel des éléments.
+          Toutefois la conversion du type <code>Integer</code> vers <code>String</code>
ne préserve <strong>pas</strong> l’ordre naturel,
+          parce que des séquences des nombres entiers croissants ont un ordre différents
+          lorsque les chaînes de caractères sont classées par ordre lexicographique.
+          Par exemple 1, 2, 10 devient "1", "10", "2".
+        </p></div>
+      </dd>
+
+      <dt><dfn>Renversant l’ordre</dfn></dt>
+      <dd>Une fonction renverse l’ordre si toute séquence de valeurs <var>S</var>
croissantes correspond à une séquence de valeurs <var>T</var> décroissantes.
+        <div class="example"><p><b>Exemple:</b>
+          une conversion qui inverse le signe des nombres.
+        </p></div>
+      </dd>
+    </dl>
+    <p>
+      Ces informations peuvent sembler inutiles lorsque l’on convertit des valeurs sans
tenir compte du contexte où elles apparaissent.
+      Mais lorsque la valeur à convertir fait parti d’un objet plus gros, alors ces
informations peuvent impacter la façon dont la valeur convertie sera utilisée.
+      Par exemple la conversion d’une plage de valeurs représentée par [<var>min</var>
… <var>max</var>] est directe lorsque la fonction de conversion préserve
l’ordre.
+      Mais si la fonction de conversion renverse l’ordre, alors les valeurs minimale
et maximale doivent être interchangées.
+      Par exemple si la fonction de conversion inverse le signe des valeurs, alors la plage
convertie sera [-<var>max</var> … -<var>min</var>].
+      Si la fonction de conversion ne préserve ni ne renverse l’ordre, alors la plage
de valeurs ne peut pas être convertie du tout
+      (parce qu’elle ne contiendrait plus le même ensemble de valeurs) même si
les valeurs individuelles auraient pu être converties.
+    </p>
+
+
+
     <h2 id="Internationalization">Internationalisation</h2>
     <p>
       Dans une architecture où un programme exécuté sur un serveur fournit ses données
à plusieurs clients,

Modified: sis/site/trunk/content/book/book.css
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/book/book.css?rev=1757004&r1=1757003&r2=1757004&view=diff
==============================================================================
--- sis/site/trunk/content/book/book.css (original)
+++ sis/site/trunk/content/book/book.css Sat Aug 20 14:41:47 2016
@@ -29,6 +29,13 @@ ul.toc ul {
 }
 
 /*
+ * Definition list
+ */
+dl {
+  padding-left: 21px;
+}
+
+/*
  * Links to previous and next chapters.
  */
 div.chapter-links {



Mime
View raw message