sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1415562 - in /sis/branches/JDK7: sis-utility/src/main/java/org/apache/sis/util/ sis-utility/src/main/java/org/apache/sis/xml/ src/main/docbook/fr/
Date Fri, 30 Nov 2012 09:49:27 GMT
Author: desruisseaux
Date: Fri Nov 30 09:49:26 2012
New Revision: 1415562

URL: http://svn.apache.org/viewvc?rev=1415562&view=rev
Log:
Reproduced some material from the developer guide to the javadoc.

Modified:
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilObject.java
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java
    sis/branches/JDK7/src/main/docbook/fr/XML.xml

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java?rev=1415562&r1=1415561&r2=1415562&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/CharSequences.java Fri
Nov 30 09:49:26 2012
@@ -42,24 +42,31 @@ import static org.apache.sis.util.String
  * no-break spaces}, tabulations and line feeds. The general policy in the SIS library is:
  *
  * <ul>
- *   <li><p>Use {@code isWhitespace(…)} when separating entities (words,
numbers, tokens).
- *       Using this method, characters separated by a no-break space are considered as
- *       part of the same entity (e.g. the French locale uses no-break space instead of
- *       coma as group separator in number representations), while line feeds and
- *       tabulations are accepted as valid entity separator.
- *       This {@code CharSequences} class consistently uses {@code isWhitespace(…)}.</p></li>
- *
- *   <li><p>Use {@code isSpaceChar(…)} when parsing a single entity. Using
this method,
- *       no-break spaces are considered as part of the entity (e.g. the above-cited
- *       group separator), while line feeds or tabulation mark entity boundaries.
- *       For this reason, the {@link java.text.Format} implementations in the SIS
- *       library typically use {@code isSpaceChar(…)}.</p></li>
+ *   <li>Use {@code isWhitespace(…)} when separating entities (words, numbers,
tokens, <i>etc.</i>)
+ *       in a list. Using that method, characters separated by a no-break space are considered
as
+ *       part of the same entity.</li>
+ *   <li>Use {@code isSpaceChar(…)} when parsing a single entity, for example
a single word.
+ *       Using this method, no-break spaces are considered as part of the entity while line
+ *       feeds or tabulations are entity boundaries.</li>
  * </ul>
  *
- * Note that the {@link String#trim()} method doesn't follow any of those policies and should
+ * <blockquote><font size="-1"><b>Example:</b> Numbers formatted
in the French locale use no-break
+ * spaces as group separators. When parsing a list of numbers, ordinary spaces around the
numbers
+ * may need to be ignored, but no-break spaces shall be considered as part of the numbers.
+ * Consequently {@code isWhitespace(…)} is appropriate for skipping spaces <em>between</em>
the numbers.
+ * But if there is spaces to skip <em>inside</em> a single number, then {@code
isSpaceChar(…)} is a
+ * good choice for accepting no-break spaces and for stopping the parse operation at tabulations
or
+ * line feed character. A tabulation or line feed between two characters is very likely to
separate
+ * two distinct values.</font></blockquote>
+ *
+ * In practice, the {@link java.text.Format} implementations in the SIS library typically
use
+ * {@code isSpaceChar(…)} while most of the rest of the SIS library, including this
+ * {@code CharSequences} class, consistently uses {@code isWhitespace(…)}.
+ *
+ * <p>Note that the {@link String#trim()} method doesn't follow any of those policies
and should
  * generally be avoided. That {@code trim()} method removes every ISO control characters
without
  * distinction about whether the characters are space or not, and ignore all Unicode spaces.
- * The {@link #trimWhitespaces(String) method defined in this class can be used as an alternative.
+ * The {@link #trimWhitespaces(String) method defined in this class can be used as an alternative.</p>
  *
  * {@section Handling of null values}
  * Most methods in this class accept a {@code null} {@code CharSequence} argument. In such
cases

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilObject.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilObject.java?rev=1415562&r1=1415561&r2=1415562&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilObject.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilObject.java Fri Nov
30 09:49:26 2012
@@ -18,14 +18,23 @@ package org.apache.sis.xml;
 
 
 /**
- * A marker interface for empty XML elements. Note that an "nil" XML element may not be an
- * empty Java object, since the Java object can still be associated with {@link XLink} or
- * {@link NilReason} attributes. Those attributes are not part of ISO 19115, but may appear
- * in ISO 19139 XML documents like below:
+ * A marker interface for empty XML elements providing an explanation about why the information
is absent.
+ * GeoAPI getter methods usually return a {@code null} value when no information is available
for
+ * a given attribute. However it is possible to specify why an information is absent, in
which case
+ * the corresponding getter method will rather return an instance of this {@code NilObject}
interface.
+ * The information may be absent for various reasons, including the attribute being inapplicable
in the metadata context
+ * ({@link NilReason#INAPPLICABLE}), the information probably exists but is unknown to the
data provider
+ * ({@link NilReason#UNKNOWN UNKNOW}), the information may not exist at all ({@link NilReason#MISSING
+ * MISSING}) or can not be divulged ({@link NilReason#WITHHELD WITHHELD}).
+ *
+ * <p>Nil objects appear most frequently in XML documents since if a mandatory ISO
19115 attribute
+ * is absent, then the ISO 19139 standard requires us to said why it is so. The following
example
+ * shows a {@code CI_Citation} fragment with an ordinary {@code CI_Series} element on
the left side,
+ * and an unknown {@code CI_Series} element on the right side:</p>
  *
  * <blockquote><table class="sis" border="1"><tr>
- *   <th>Non-empty {@code Series} element</th>
- *   <th>Empty {@code Series} element</th>
+ *   <th>Normal {@code Series} element</th>
+ *   <th>Unknown {@code Series} element</th>
  * </tr><tr><td>
  * {@preformat xml
  *   <gmd:CI_Citation>
@@ -44,11 +53,16 @@ package org.apache.sis.xml;
  * }
  * </td></tr></table></blockquote>
  *
- * The reason why an object is empty can be obtained by the {@link #getNilReason()} method.
+ * If the {@code CI_Series} element was completely omitted, then {@link org.opengis.metadata.citation.Citation#getSeries()}
+ * method would return {@code null} in Apache SIS implementation. But since a {@code nilReason}
is provided,
+ * then the SIS implementation of {@code getSeries()} will rather return an object which
implement
+ * both the {@code Series} and the {@code NilObject} interfaces, and the {@link #getNilReason()}
method
+ * on that instance will return the {@link NilReason#UNKNOWN} constant.
  *
  * {@section Instantiation}
- * The following example instantiates a {@link org.opengis.metadata.citation.Citation} object
- * which is empty because the information are missing:
+ * Instances of {@code NilObject} are created by first fetching the reason why the information
+ * is missing, then invoking {@link NilReason#createNilObject(Class)}. The following example
+ * instantiates a {@code Citation} object which is empty because the information are missing:
  *
  * {@preformat java
  *     Citation nil = NilReason.MISSING.createNilObject(Citation.class);

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java?rev=1415562&r1=1415561&r2=1415562&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/xml/NilReason.java Fri Nov
30 09:49:26 2012
@@ -315,11 +315,13 @@ public final class NilReason implements 
     }
 
     /**
-     * Returns an object of the given type which is nil for the reason represented by this
enum.
+     * Returns an object of the given type which is nil for the reason represented by this
instance.
      * This method returns an object which implement the given interface together with the
      * {@link NilObject} interface. The {@link NilObject#getNilReason()} method will return
-     * this enum, and all other methods (except the ones inherited from the {@link Object}
class)
-     * will return {@code null} or an empty collection as appropriate.
+     * this {@code NilReason} instance, and all other methods (except the ones inherited
from
+     * the {@code Object} class) will return an empty collection, empty array, {@code null},
+     * {@link Double#NaN NaN}, {@code 0} or {@code false}, in this preference order,
+     * depending on the method return type.
      *
      * @param  <T> The compile-time type of the {@code type} argument.
      * @param  type The object type as an <strong>interface</strong>.

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=1415562&r1=1415561&r2=1415562&view=diff
==============================================================================
--- sis/branches/JDK7/src/main/docbook/fr/XML.xml (original)
+++ sis/branches/JDK7/src/main/docbook/fr/XML.xml Fri Nov 30 09:49:26 2012
@@ -249,8 +249,7 @@ public class MyClass {
       <para>
         Dans l’exemple suivant, la partie gauche montre un élément <classname
role="OGC">CI_Citation</classname>
         contenant un élément <classname role="OGC">CI_Series</classname>,
alors que dans la partie droite la série est inconnue.
-        Si l’élément <classname role="OGC">CI_Series</classname> avait
été complètement omis
-        (ce qui est illégal selon les standards <acronym>ISO</acronym> mais
toléré par <acronym>SIS</acronym>),
+        Si l’élément <classname role="OGC">CI_Series</classname> avait
été complètement omis,
         alors la méthode <function role="GeoAPI">Citation.getSeries()</function>
retournerait <literal>null</literal> en Java.
         Mais en présence d’un attribut <literal role="OGC">nilReason</literal>,
l’implémentation <acronym>SIS</acronym>
         de <function role="SIS">getSeries()</function> retournera plutôt un
objet implémentant à la fois les interfaces



Mime
View raw message