sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1776456 - in /sis/site/trunk/book: en/utility.html fr/utility.html
Date Thu, 29 Dec 2016 18:05:24 GMT
Author: desruisseaux
Date: Thu Dec 29 18:05:24 2016
New Revision: 1776456

URL: http://svn.apache.org/viewvc?rev=1776456&view=rev
Log:
Clarification of SIS policy regarding Exception.getLocalizedMessage().

Modified:
    sis/site/trunk/book/en/utility.html
    sis/site/trunk/book/fr/utility.html

Modified: sis/site/trunk/book/en/utility.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/en/utility.html?rev=1776456&r1=1776455&r2=1776456&view=diff
==============================================================================
--- sis/site/trunk/book/en/utility.html [UTF-8] (original)
+++ sis/site/trunk/book/en/utility.html [UTF-8] Thu Dec 29 18:05:24 2016
@@ -205,36 +205,37 @@
       Some classes are only designed to function according to one locale convention at a
time.
       This is of course true for the standard implementations of <code>java.text.Format</code>,
       as they are entirely dedicated to the work of internationalization.
-      But it is also the case for other less obvious classes like <code>javax.imageio.ImageReader</code>/<code>ImageWriter</code>
-      and for <code>Exception</code> subclasses.
+      But it is also the case for other less obvious classes like <code>javax.imageio.ImageReader</code>
and <code>ImageWriter</code>.
       When one of these classes is implemented by <abbr>SIS</abbr>,
       we identify it by implementing the <code>org.apache.sis.util.Localized</code>
interface.
       The <code class="SIS">getLocale()</code> method of this interface can determine
the locale conventions
       by which the instance produces its message.
     </p>
     <p>
-      Some sub-classes of <code>Exception</code> defined by <abbr>SIS</abbr>
also implement the <code>Localized</code> interface.
-      For these exceptions, the error message may be produced according to two locale conventions,
-      for either the administrator or the client respectively:
-      <code>getMessage()</code> returns the exception message according to the
system default conventions,
-      while <code>getLocalizedMessage()</code> returns the exception message
according to the locale conventions specified
-      by <code class="SIS">getLocale()</code>.
-      This <code>Locale</code> will be determined by the <code>Localized</code>
object that threw the exception.
+      Another class that provides different methods for different locales is <code>java.lang.Throwable</code>.
+      The standard Java <abbr>API</abbr> defines two methods for getting the
error message:
+      <code>getMessage()</code> and <code>getLocalizedMessage()</code>.
+      Usually those two methods return the same character sequences,
+      but some exceptions thrown by Apache <abbr>SIS</abbr> may use different
locales.
+      The policy that <abbr>SIS</abbr> tries to apply on a <em>best-effort</em>
basis is:
     </p>
+    <ul>
+      <li><code>getMessage()</code> returns the message in the <abbr
title="Java Virtual Machine">JVM</abbr> default locale.
+          In a client-server architecture, this is often the locale on the server side.
+          This is the recommended language for logging messages to be read by system administrators.</li>
+      <li><code>getLocalizedMessage()</code> returns the message in a locale
that depends on the context
+          in which the exception has been thrown. This is often the locale used by a particular
<code>Format</code>
+          or <code class="SIS">DataStore</code> instance, and can be presumed
to be the locale on the client side.
+          This is the recommended language to show in the user application.</li>
+    </ul>
+
     <div class="example"><p><b>Example:</b>
-      Given an environment in which the default language is English and an <code>AngleFormat</code>
object is created to
-      read angles according to French conventions.
-      If a <code>ParseException</code> is thrown when using this formatter, <code>getMessage()</code>
returns the error message in English,
-      while <code>getLocalizedMessage()</code> returns the error message in French.
+      If an error occurred while a Japanese client connected to an European server, the localized
message may be sent
+      to the client in Japanese language as given by <code>getLocalizedMessage()</code>
while the same error may be
+      logged on the server side in the French (for example) language as given by <code>getMessage()</code>.
+      This allows system administrator to analyze the issue without the need to understand
client’s language.
     </p></div>
     <p>
-      The exceptions defined by <abbr>SIS</abbr> do not implement all of the
<code>Localized</code> interface.
-      Only those most likely to be shown to the user are localized in this way.
-      <code>ParseException</code> are good candidates because they often occur
due to an incorrect entry by the client.
-      By contrast, <code>NullPointerException</code> are generally caused by
a programming error;
-      they may be localized in the system default language, but that is usually all.
-    </p>
-    <p>
       The utility class <code>org.apache.sis.util.Exceptions</code> provides
convenience methods to get messages
       according to the conventions of a given locale, when this information is available.
     </p>

Modified: sis/site/trunk/book/fr/utility.html
URL: http://svn.apache.org/viewvc/sis/site/trunk/book/fr/utility.html?rev=1776456&r1=1776455&r2=1776456&view=diff
==============================================================================
--- sis/site/trunk/book/fr/utility.html [UTF-8] (original)
+++ sis/site/trunk/book/fr/utility.html [UTF-8] Thu Dec 29 18:05:24 2016
@@ -206,35 +206,38 @@
       C’est évidemment le cas des implémentations standards de <code>java.text.Format</code>,
       puisqu’elles sont entièrement dédiées au travail d’internationalisation.
       Mais c’est aussi le cas de d’autres classes moins évidentes comme
-      <code>javax.imageio.ImageReader</code>/<code>ImageWriter</code>
ainsi que les sous-classes de <code>Exception</code>.
+      <code>javax.imageio.ImageReader</code> et <code>ImageWriter</code>.
       Lorsque une de ces classes est implémentée par <abbr>SIS</abbr>,
       nous l’identifions en implémentant l’interface <code>org.apache.sis.util.Localized</code>.
       La méthode <code class="SIS">getLocale()</code> de cette interface permet
alors de déterminer
       selon quelles conventions locales l’instance produira ses messages.
     </p>
     <p>
-      Certaines sous-classes de <code>Exception</code> définies par <abbr>SIS</abbr>
implémentent aussi l’interface <code>Localized</code>.
-      Pour ces exceptions, le message d’erreur peut être produit selon deux conventions
locales selon qu’il s’adresse à l’administrateur du système ou au client:
-      <code>getMessage()</code> retourne le message de l’exception selon les
conventions par défaut du système, alors que
-      <code>getLocalizedMessage()</code> retourne le message de l’exception
selon les conventions locales spécifiées par <code class="SIS">getLocale()</code>.
-      Ce <code>Locale</code> sera lui-même déterminé par l’objet <code>Localized</code>
qui a lancé l’exception.
+      Une autre classe qui fournit différentes méthodes pour différentes langues est <code>java.lang.Throwable</code>.
+      L’<abbr>API</abbr> standard du Java définie deux méthodes pour obtenir
un message d’erreur:
+      <code>getMessage()</code> et <code>getLocalizedMessage()</code>.
+      Habituellement, ces deux méthodes retournent la même chaîne de caractères.
+      Toutefois certaines exceptions lancées par Apache <abbr>SIS</abbr> peuvent
utiliser différentes langues.
+      La politique que <abbr>SIS</abbr> tente d’appliquer autant que possible
est:
     </p>
+    <ul>
+      <li><code>getMessage()</code> retourne le message dans la langue
par défaut de la <abbr title="Java Virtual Machine">JVM</abbr>.
+          Dans une architecture client-serveur, c’est souvent la langue du système hébergeant
le serveur.
+          C’est la méthode recommandée pour enregistrer des messages dans le journal
des événements,
+          à l’intention des administrateurs systèmes.</li>
+      <li><code>getLocalizedMessage()</code> retourne le message dans une
langue qui dépend du contexte dans lequel l’exception s’est produite.
+          C’est souvent la langue qui a été configurée pour une instance particulière
de <code>Format</code> ou <code class="SIS">DataStore</code>,
+          que l’on peut présumer être la langue du client se connectant au serveur.
+          C’est la méthode recommandée pour afficher un message dans une fenêtre sur
le poste de l’utilisateur.</li>
+    </ul>
+
     <div class="example"><p><b>Exemple:</b>
-      Supposons que dans un environnement où la langue par défaut serait l’anglais,
-      un objet <code>AngleFormat</code> est construit pour lire des angles selon
les conventions françaises.
-      Si une <code>ParseException</code> est lancée lors de l’utilisation
de ce formateur,
-      alors <code>getMessage()</code> retournera le message d’erreur en anglais
-      tandis que <code>getLocalizedMessage()</code> retournera le message d’erreur
en français.
+      Si une erreur s’est produite alors qu’un client japonais s’est connecté à un
serveur européen,
+      le message fournit par <code>getLocalizedMessage()</code> pourra être
envoyé à l’utilisateur au Japon
+      alors que le message fournit par <code>getMessage()</code> pourra être
enregistré dans le journal des événements du serveur.
+      Ainsi, l’administrateur système pourra plus facilement analyser l’erreur même
s’il ne connaît pas la langue du client.
     </p></div>
     <p>
-      Les exceptions définies par <abbr>SIS</abbr> n’implémentent pas toutes
l’interface <code>Localized</code>.
-      Seules celles dont le message est le plus susceptible d’être montré à l’utilisateur
sont ainsi localisées.
-      Les <code>ParseException</code> sont de bonnes candidates puisqu’elles
surviennent souvent
-      suite à une saisie incorrecte du client. En revanche les <code>NullPointerException</code>
-      sont généralement la conséquence d’une erreur de programmation;
-      elles peuvent être localisées dans la langue par défaut du système, mais ça sera
généralement tout.
-    </p>
-    <p>
       La classe utilitaire <code>org.apache.sis.util.Exceptions</code> fournit
       des méthodes de commodité pour obtenir des messages selon des conventions locales
spécifiées
       lorsque cette information est disponible.



Mime
View raw message