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 2016/12/29 18:05:24 UTC
svn commit: r1776456 - in /sis/site/trunk/book: en/utility.html
fr/utility.html
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\u2019s 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\u2019est �videmment le cas des impl�mentations standards de <code>java.text.Format</code>,
puisqu\u2019elles sont enti�rement d�di�es au travail d\u2019internationalisation.
Mais c\u2019est aussi le cas de d\u2019autres 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\u2019identifions en impl�mentant l\u2019interface <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\u2019instance produira ses messages.
</p>
<p>
- Certaines sous-classes de <code>Exception</code> d�finies par <abbr>SIS</abbr> impl�mentent aussi l\u2019interface <code>Localized</code>.
- Pour ces exceptions, le message d\u2019erreur peut �tre produit selon deux conventions locales selon qu\u2019il s\u2019adresse � l\u2019administrateur du syst�me ou au client:
- <code>getMessage()</code> retourne le message de l\u2019exception selon les conventions par d�faut du syst�me, alors que
- <code>getLocalizedMessage()</code> retourne le message de l\u2019exception 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\u2019objet <code>Localized</code> qui a lanc� l\u2019exception.
+ Une autre classe qui fournit diff�rentes m�thodes pour diff�rentes langues est <code>java.lang.Throwable</code>.
+ L\u2019<abbr>API</abbr> standard du Java d�finie deux m�thodes pour obtenir un message d\u2019erreur:
+ <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\u2019appliquer 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\u2019est souvent la langue du syst�me h�bergeant le serveur.
+ C\u2019est la m�thode recommand�e pour enregistrer des messages dans le journal des �v�nements,
+ � l\u2019intention des administrateurs syst�mes.</li>
+ <li><code>getLocalizedMessage()</code> retourne le message dans une langue qui d�pend du contexte dans lequel l\u2019exception s\u2019est produite.
+ C\u2019est 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\u2019on peut pr�sumer �tre la langue du client se connectant au serveur.
+ C\u2019est la m�thode recommand�e pour afficher un message dans une fen�tre sur le poste de l\u2019utilisateur.</li>
+ </ul>
+
<div class="example"><p><b>Exemple:</b>
- Supposons que dans un environnement o� la langue par d�faut serait l\u2019anglais,
- 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\u2019utilisation de ce formateur,
- alors <code>getMessage()</code> retournera le message d\u2019erreur en anglais
- tandis que <code>getLocalizedMessage()</code> retournera le message d\u2019erreur en fran�ais.
+ Si une erreur s\u2019est produite alors qu\u2019un client japonais s\u2019est connect� � un serveur europ�en,
+ le message fournit par <code>getLocalizedMessage()</code> pourra �tre envoy� � l\u2019utilisateur au Japon
+ alors que le message fournit par <code>getMessage()</code> pourra �tre enregistr� dans le journal des �v�nements du serveur.
+ Ainsi, l\u2019administrateur syst�me pourra plus facilement analyser l\u2019erreur m�me s\u2019il ne conna�t pas la langue du client.
</p></div>
<p>
- Les exceptions d�finies par <abbr>SIS</abbr> n\u2019impl�mentent pas toutes l\u2019interface <code>Localized</code>.
- Seules celles dont le message est le plus susceptible d\u2019�tre montr� � l\u2019utilisateur sont ainsi localis�es.
- Les <code>ParseException</code> sont de bonnes candidates puisqu\u2019elles surviennent souvent
- suite � une saisie incorrecte du client. En revanche les <code>NullPointerException</code>
- sont g�n�ralement la cons�quence d\u2019une 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.