Author: desruisseaux
Date: Sun Dec 9 16:01:19 2012
New Revision: 1419012
URL: http://svn.apache.org/viewvc?rev=1419012&view=rev
Log:
Documentation updates.
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/CodeLists.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultInternationalString.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultNameFactory.java
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/package-info.java
sis/branches/JDK7/src/main/docbook/fr/XML.xml
sis/branches/JDK7/src/main/docbook/fr/utility.xml
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java?rev=1419012&r1=1419011&r2=1419012&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java
(original)
+++
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java
Sun Dec 9 16:01:19 2012
@@ -18,12 +18,12 @@ package org.apache.sis.util;
/**
- * Specifies the degree of strictness when comparing two {@link
LenientComparable} objects
+ * Specifies the level of strictness when comparing two {@link
LenientComparable} objects
* for equality. This enumeration allows users to specify which kind of
differences can be
* tolerated between two objects: differences in implementation class,
differences in
* some kinds of property, or slight difference in numerical values.
*
- * <p>This enumeration is <em>ordered</em> from stricter to more lenient
degrees:</p>
+ * <p>This enumeration is <em>ordered</em> from stricter to more lenient
levels:</p>
*
* <ol>
* <li>{@link #STRICT} â All attributes of the compared objects
shall be strictly equal.</li>
@@ -31,13 +31,13 @@ package org.apache.sis.util;
* <li>{@link #IGNORE_METADATA} â Only the attributes relevant to the
object functionality are compared.</li>
* <li>{@link #APPROXIMATIVE} â Only the attributes relevant to the
object functionality are compared,
* with some tolerance threshold on numerical
values.</li>
- * <li>{@link #DEBUG}: â Special mode for figuring out why two
objects expected to be equal are not.</li>
+ * <li>{@link #DEBUG} â Special mode for figuring out why two
objects expected to be equal are not.</li>
* </ol>
*
- * If two objects are equal at some degree of strictness <var>E</var>, then
they should also
- * be equal at all degrees listed below <var>E</var> in the above list. For
example if two objects
- * are equal at the degree {@link #BY_CONTRACT}, then they should also be
equal at the degree
- * {@link #IGNORE_METADATA} but not necessarily at the degree {@link #STRICT}.
+ * If two objects are equal at some level of strictness <var>E</var>, then
they should also
+ * be equal at all levels listed below <var>E</var> in the above list. For
example if two objects
+ * are equal at the {@link #BY_CONTRACT} level, then they should also be equal
at the
+ * {@link #IGNORE_METADATA} level but not necessarily at the {@link #STRICT}
level.
*
* @author Martin Desruisseaux (Geomatys)
* @since 0.3 (derived from geotk-3.18)
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java?rev=1419012&r1=1419011&r2=1419012&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
(original)
+++
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
Sun Dec 9 16:01:19 2012
@@ -26,7 +26,7 @@ package org.apache.sis.util;
* {@section Conditions for equality}
* <ul>
* <li>{@link org.apache.sis.metadata.iso.MetadataEntity} subclasses
- * <ul class="verbose">
+ * <ol>
* <li>{@link ComparisonMode#STRICT STRICT} â Objects must be of the
same class
* and all attributes must be equal, including {@code xlink} and
others
* {@linkplain
org.apache.sis.metadata.iso.MetadataEntity#getIdentifiers() identifiers}.</li>
@@ -39,10 +39,10 @@ package org.apache.sis.util;
* <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â The same
attributes than the above
* {@code IGNORE_METADATA} mode are compared, but a slight
(implementation dependant)
* difference is tolerated in floating point numbers.</li>
- * </ul>
+ * </ol>
* </li>
* <li>{@link org.apache.sis.referencing.AbstractIdentifiedObject} subclasses
- * <ul class="verbose">
+ * <ol>
* <li>{@link ComparisonMode#STRICT STRICT} â Objects must be of the
same class
* and all attributes must be equal.</li>
* <li>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT} â The same
attributes than the above
@@ -60,11 +60,11 @@ package org.apache.sis.util;
* <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â The same
attributes than the above
* {@code IGNORE_METADATA} mode are compared, but a slight
(implementation dependant)
* difference is tolerated in floating point numbers.</li>
- * </ul>
+ * </ol>
* </li>
* <li>{@link
org.apache.sis.referencing.operation.transform.AbstractMathTransform} subclasses
* except {@link
org.apache.sis.referencing.operation.transform.LinearTransform}
- * <ul class="verbose">
+ * <ol>
* <li>{@link ComparisonMode#STRICT STRICT} â Objects must be of the
same class and all
* attributes must be equal, including the
* {@linkplain
org.apache.sis.referencing.operation.transform.AbstractMathTransform#getParameterValues()
parameter values}.</li>
@@ -80,11 +80,11 @@ package org.apache.sis.util;
* <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â The same
attributes than the above
* {@code IGNORE_METADATA} mode are compared, but a slight
(implementation dependant)
* difference is tolerated in floating point numbers.</li>
- * </ul>
+ * </ol>
* </li>
* <li>{@link org.apache.sis.referencing.operation.matrix.XMatrix} and
* {@link
org.apache.sis.referencing.operation.transform.LinearTransform} implementations
- * <ul class="verbose">
+ * <ol>
* <li>{@link ComparisonMode#STRICT STRICT} â Objects must be of the
same class, matrixes
* must have the same size and all matrix elements must be
equal.</li>
* <li>{@link ComparisonMode#BY_CONTRACT BY_CONTRACT} â Matrixes must
have the same size
@@ -95,7 +95,7 @@ package org.apache.sis.util;
* <li>{@link ComparisonMode#APPROXIMATIVE APPROXIMATIVE} â The same
attributes than the above
* {@code BY_CONTRACT} mode are compared, but a slight
(implementation dependant)
* difference is tolerated in floating point numbers.</li>
- * </ul>
+ * </ol>
* </li>
* </ul>
*
@@ -124,6 +124,11 @@ public interface LenientComparable {
* special mode for figuring out why two objects expected to be
equal are not.</li>
* </ol>
*
+ * Note that {@code this.equals(other, mode)} is <strong>not</strong>
guaranteed to be equals
+ * to {@code other.equals(this, mode)}. In particular, the {@code
BY_CONTRACT} level and all
+ * levels below it will typically compare only the properties known to
{@code this} instance,
+ * ignoring any properties that may be known only by the {@code
other}Â instance.
+ *
* @param other The object to compare to {@code this}.
* @param mode The strictness level of the comparison.
* @return {@code true} if both objects are equal.
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/CodeLists.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/CodeLists.java?rev=1419012&r1=1419011&r2=1419012&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/CodeLists.java
(original)
+++
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/CodeLists.java
Sun Dec 9 16:01:19 2012
@@ -85,9 +85,9 @@ public final class CodeLists extends Sta
* Examples:
*
* <ul>
- * <li>{@code getCodeName(AxisDirection#NORTH)} returns {@code
"north"}.</li>
- * <li>{@code getCodeName(CharacterSet#UTF_8)} returns {@code
"utf8"}.</li>
- * <li>{@code getCodeName(ImagingCondition#BLURRED_IMAGE)} returns
{@code "blurredImage"}.</li>
+ * <li>{@code getCodeName(AxisDirection.NORTH)} returns {@code
"north"}.</li>
+ * <li>{@code getCodeName(CharacterSet.UTF_8)} returns {@code
"utf8"}.</li>
+ * <li>{@code getCodeName(ImagingCondition.BLURRED_IMAGE)} returns
{@code "blurredImage"}.</li>
* </ul>
*
* @param code The code for which to get the name, or {@code null}.
@@ -114,9 +114,9 @@ public final class CodeLists extends Sta
* from that name. Examples:</p>
*
* <ul>
- * <li>{@code getCodeTitle(AxisDirection#NORTH)} returns {@code
"North"}.</li>
- * <li>{@code getCodeTitle(CharacterSet#UTF_8)} returns {@code
"UTF-8"}.</li>
- * <li>{@code getCodeTitle(ImagingCondition#BLURRED_IMAGE)} returns
{@code "Blurred image"}.</li>
+ * <li>{@code getCodeTitle(AxisDirection.NORTH)} returns {@code
"North"}.</li>
+ * <li>{@code getCodeTitle(CharacterSet.UTF_8)} returns {@code
"UTF-8"}.</li>
+ * <li>{@code getCodeTitle(ImagingCondition.BLURRED_IMAGE)} returns
{@code "Blurred image"}.</li>
* </ul>
*
* @param code The code from which to get a title, or {@code null}.
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultInternationalString.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultInternationalString.java?rev=1419012&r1=1419011&r2=1419012&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultInternationalString.java
(original)
+++
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultInternationalString.java
Sun Dec 9 16:01:19 2012
@@ -254,18 +254,12 @@ public class DefaultInternationalString
* The {@code null} locale (which stand for unlocalized message) is tried
last.
*
* {@section Handling of <code>null</code> argument value}
- * A {@code null}Â argument value can be given to this method for
- * requesting a "unlocalized" string - typically some programmatic strings
like
- * {@linkplain org.opengis.annotation.UML#identifier() UML identifiers}.
- * While such identifiers often look like English words, they are not
considered
- * as the {@linkplain Locale#ENGLISH English locale}. For example:
- *
- * <ul>
- * <li>Numbers are formatted using {@code Number.toString()} rather than
{@link java.text.NumberFormat}.</li>
- * <li>Dates are formatted according the ISO standard rather than the
English locale.</li>
- * </ul>
- *
- * In order to produce a value close to the common practice,
+ * A {@code null}Â argument value can be given to this method for
requesting a "unlocalized" string,
+ * typically some programmatic strings like {@linkplain
org.opengis.annotation.UML#identifier() UML
+ * identifiers}. While such identifiers often look like English words, the
{@code null} locale is
+ * not considered synonymous to the {@linkplain Locale#ENGLISH English
locale} since the values may
+ * differ in the way numbers and dates are formatted (e.g. using the ISO
8601 standard for dates
+ * instead than English conventions). In order to produce a value close to
the common practice,
* this method handles {@code null} argument value as below:
*
* <ul>
@@ -277,7 +271,7 @@ public class DefaultInternationalString
* <li>If no English string was found, this method looks for a string
for the
* {@linkplain Locale#getDefault() system default locale}.</li>
* <li>If none of the above steps found a string, then this method
returns
- * an arbitrary string (this behavior may change in future SIS
implementation).</li>
+ * an arbitrary string.</li>
* </ul>
*
* @param locale The locale to look for, or {@code null}.
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultNameFactory.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultNameFactory.java?rev=1419012&r1=1419011&r2=1419012&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultNameFactory.java
(original)
+++
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/DefaultNameFactory.java
Sun Dec 9 16:01:19 2012
@@ -43,6 +43,28 @@ import static org.apache.sis.util.type.D
/**
* A factory for creating {@link AbstractName} objects.
+ * This factory provides the following methods for creating name instances:
+ *
+ * <ul>
+ * <li>{@link #createTypeName(NameSpace, CharSequence)}</li>
+ * <li>{@link #createMemberName(NameSpace, CharSequence, TypeName)}</li>
+ * <li>{@link #createLocalName(NameSpace, CharSequence)}</li>
+ * <li>{@link #createGenericName(NameSpace, CharSequence[])} â for local
or scoped names</li>
+ * </ul>
+ *
+ * The following methods for creating miscellaneous name-related objects:
+ *
+ * <ul>
+ * <li>{@link #createNameSpace(GenericName, Map)}</li>
+ * <li>{@link #createInternationalString(Map)}</li>
+ * </ul>
+ *
+ * And the following methods for performing some analysis:
+ *
+ * <ul>
+ * <li>{@link #parseGenericName(NameSpace, CharSequence)}</li>
+ * <li>{@link #toArray(Object)} â SIS extension, not in GeoAPI
interface</li>
+ * </ul>
*
* @author Martin Desruisseaux (Geomatys)
* @since 0.3 (derived from geotk-2.1)
Modified:
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/package-info.java?rev=1419012&r1=1419011&r2=1419012&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/package-info.java
(original)
+++
sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/type/package-info.java
Sun Dec 9 16:01:19 2012
@@ -31,8 +31,10 @@
* <li>Implementations of {@link org.opengis.util.GenericName}:
* <ul>
* <li>{@link org.apache.sis.util.type.DefaultLocalName} for identifier
within a namespace.</li>
- * <li>{@link org.apache.sis.util.type.DefaultScopedName} for a
composite of a <cite>head</cite>
- * name and a <cite>tail</cite> name.</li>
+ * <li>{@link org.apache.sis.util.type.DefaultScopedName} for a
composite of a <cite>head</cite> name and a <cite>tail</cite> name.</li>
+ * <li>{@link org.apache.sis.util.type.DefaultMemberName} for
identifying a member of a record.</li>
+ * <li>{@link org.apache.sis.util.type.DefaultTypeName} for identifying
an attribute type associated to a member.</li>
+ * <li>{@link org.apache.sis.util.type.DefaultNameSpace} for identifying
the domain in which above names are defined.</li>
* </ul>
* </li>
* </ul>
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=1419012&r1=1419011&r2=1419012&view=diff
==============================================================================
--- sis/branches/JDK7/src/main/docbook/fr/XML.xml (original)
+++ sis/branches/JDK7/src/main/docbook/fr/XML.xml Sun Dec 9 16:01:19 2012
@@ -238,7 +238,7 @@
<programlisting language="xml"><MD_MetaData>
<identificationInfo>
<MD_DataIdentification id="mon_id">
- <!-- placer ici une définition de l'objet -->
+ <!-- insérer ici des propriétés filles -->
</MD_DataIdentification>
</identificationInfo>
</MD_MetaData></programlisting>
@@ -295,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.
@@ -345,7 +346,7 @@ public class MyClass {
<programlisting language="xml"><CI_Citation>
<series>
<CI_Series>
- <!-- Some content here -->
+ <!-- insérer ici des propriétés filles -->
</CI_Series>
</series>
</CI_Citation></programlisting>
Modified: sis/branches/JDK7/src/main/docbook/fr/utility.xml
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/src/main/docbook/fr/utility.xml?rev=1419012&r1=1419011&r2=1419012&view=diff
==============================================================================
--- sis/branches/JDK7/src/main/docbook/fr/utility.xml (original)
+++ sis/branches/JDK7/src/main/docbook/fr/utility.xml Sun Dec 9 16:01:19 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
