User Manual 3.3 Errors management and internationalization - Historique des versions

Admin le 16 mars 2018 à 08:53

2018-03-16T08:53:05Z

← Version précédente		Version du 16 mars 2018 à 08:53
Ligne 1 :		Ligne 1 :


	== Introduction ==		== Introduction ==
	=== Scope ===		=== Scope ===

Admin le 16 mars 2018 à 08:51

2018-03-16T08:51:25Z

Voir les modifications

Admin : Admin a déplacé la page Errors management and internationalization vers User Manual 3.3 Errors management and internationalization sans laisser de redirection

2018-02-28T14:05:58Z

Admin a déplacé la page Errors management and internationalization vers User Manual 3.3 Errors management and internationalization sans laisser de redirection

← Version précédente		Version du 28 février 2018 à 14:05
(Aucune différence)

Admin : /* Scope */

2018-02-28T14:04:50Z

Scope

← Version précédente		Version du 28 février 2018 à 14:04
Ligne 13 :		Ligne 13 :
	Here is a use case of the Locale object :		Here is a use case of the Locale object :


	~~(((~~
	(% style="color: rgb(64, 128, 128);" %)~/~/ French locale		(% style="color: rgb(64, 128, 128);" %)~/~/ French locale
	Locale france <pre style="color: rgb(102, 102, 102);">=</pre> (% style="font-weight: bold; color: rgb(0, 128, 0);" %)new(%%) Locale<pre style="color: rgb(102, 102, 102);">(<pre style="color: rgb(186, 33, 33);">"fr"</pre><pre style="color: rgb(102, 102, 102);">,</pre> <pre style="color: rgb(186, 33, 33);">"FR"</pre>(% style="color: rgb(102, 102, 102);" %));</pre>		Locale france <pre style="color: rgb(102, 102, 102);">=</pre> (% style="font-weight: bold; color: rgb(0, 128, 0);" %)new(%%) Locale<pre style="color: rgb(102, 102, 102);">(<pre style="color: rgb(186, 33, 33);">"fr"</pre><pre style="color: rgb(102, 102, 102);">,</pre> <pre style="color: rgb(186, 33, 33);">"FR"</pre>(% style="color: rgb(102, 102, 102);" %));</pre>
Ligne 21 :		Ligne 19 :
	\\(% style="color: rgb(64, 128, 128);" %)~/~/ Belgium locale		\\(% style="color: rgb(64, 128, 128);" %)~/~/ Belgium locale
	(%%)Locale belgium <pre style="color: rgb(102, 102, 102);">=</pre> (% style="font-weight: bold; color: rgb(0, 128, 0);" %)new(%%) Locale<pre style="color: rgb(102, 102, 102);">(<pre style="color: rgb(186, 33, 33);">"fr"</pre><pre style="color: rgb(102, 102, 102);">,</pre> </pre><pre style="color: rgb(186, 33, 33);">"BE"</pre>(% style="color: rgb(102, 102, 102);" %));		(%%)Locale belgium <pre style="color: rgb(102, 102, 102);">=</pre> (% style="font-weight: bold; color: rgb(0, 128, 0);" %)new(%%) Locale<pre style="color: rgb(102, 102, 102);">(<pre style="color: rgb(186, 33, 33);">"fr"</pre><pre style="color: rgb(102, 102, 102);">,</pre> </pre><pre style="color: rgb(186, 33, 33);">"BE"</pre>(% style="color: rgb(102, 102, 102);" %));
	~~)))~~

	Moreover, some locales are defined as constants of the class. This is the case for French language (Locale.FRENCH), French locale (Locale.FRENCH) or English language (Locale.ENGLISH).		Moreover, some locales are defined as constants of the class. This is the case for French language (Locale.FRENCH), French locale (Locale.FRENCH) or English language (Locale.ENGLISH).
Ligne 34 :		Ligne 32 :


	~~(((~~
	ResourceBundle bundle <pre style="color: rgb(102, 102, 102);">= ResourceBundle</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getBundle</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"message"</pre>(% style="color: rgb(102, 102, 102);" %));		ResourceBundle bundle <pre style="color: rgb(102, 102, 102);">= ResourceBundle</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getBundle</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"message"</pre>(% style="color: rgb(102, 102, 102);" %));
	~~)))~~

	If the current locale (for example the default language of the operating system) is fr_FR, here is the order of the files research :		If the current locale (for example the default language of the operating system) is fr_FR, here is the order of the files research :
Ligne 47 :		Ligne 45 :


	~~(((~~
	ResourceBundle bundle <pre style="color: rgb(102, 102, 102);">= ResourceBundle<pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getBundle</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"message"</pre><pre style="color: rgb(102, 102, 102);">,</pre> Locale</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">ENGLISH</pre>(% style="color: rgb(102, 102, 102);" %));		ResourceBundle bundle <pre style="color: rgb(102, 102, 102);">= ResourceBundle<pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getBundle</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"message"</pre><pre style="color: rgb(102, 102, 102);">,</pre> Locale</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">ENGLISH</pre>(% style="color: rgb(102, 102, 102);" %));
	~~)))~~

	Afterwards, in order to get an internationalized message, for example a message associated to the key “HelloWorld” in the properties file, the method getString(String key) must be used :		Afterwards, in order to get an internationalized message, for example a message associated to the key “HelloWorld” in the properties file, the method getString(String key) must be used :


	~~(((~~
	String message <pre style="color: rgb(102, 102, 102);">= bundle</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getString</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"HelloWorld"</pre>(% style="color: rgb(102, 102, 102);" %));		String message <pre style="color: rgb(102, 102, 102);">= bundle</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getString</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"HelloWorld"</pre>(% style="color: rgb(102, 102, 102);" %));
	~~)))~~

	=== Javadoc ===		=== Javadoc ===

Admin : 1 révision importée

2018-02-28T14:03:28Z

1 révision importée

← Version précédente		Version du 28 février 2018 à 14:03
(Aucune différence)

Admin le 28 février 2018 à 14:03

2018-02-28T14:03:28Z

Nouvelle page

== Introduction ==
=== Scope ===
A locale is a set of 2 parameters, one to define the user’s language, the other one to define the country. A locale is used to identify a country, a language or a dialect.

The language parameter is composed by 2 lower cases whose list is defined by the [http://www.loc.gov/standards/iso639-2/php/code_list.php ISO 639-2 Langage Code List] [R1]. For instance, “fr” means French whereas “en” means English.

The country parameter is composed by 2 upper cases whose list is defined by the [http://www.iso.org/iso/fr/country_codes/iso_3166_code_lists/french_country_names_and_code_elements.htm ISO 3166 French Country Names and Code Elements] [R2]. France is designated by “FR”, Belgium by “BE” and United Kingdom by “GB”.

The association of a language parameter and a country parameter leads to a full definition of all language varieties. As a result, the fr_FR locale points out French language spoken in France whereas the fr_BE locale points out French language spoken in Belgium.

Here is a use case of the Locale object :

(((
(% style="color: rgb(64, 128, 128);" %)~/~/ French locale
Locale france <pre style="color: rgb(102, 102, 102);">=</pre> (% style="font-weight: bold; color: rgb(0, 128, 0);" %)new(%%) Locale<pre style="color: rgb(102, 102, 102);">(<pre style="color: rgb(186, 33, 33);">"fr"</pre><pre style="color: rgb(102, 102, 102);">,</pre> <pre style="color: rgb(186, 33, 33);">"FR"</pre>(% style="color: rgb(102, 102, 102);" %));</pre>
\\(% style="color: rgb(64, 128, 128);" %)~/~/ French locale language
(%%)Locale french <pre style="color: rgb(102, 102, 102);">=</pre> (% style="font-weight: bold; color: rgb(0, 128, 0);" %)new(%%) Locale<pre style="color: rgb(102, 102, 102);">(<pre style="color: rgb(186, 33, 33);">"fr"</pre>(% style="color: rgb(102, 102, 102);" %));</pre>
\\(% style="color: rgb(64, 128, 128);" %)~/~/ Belgium locale
(%%)Locale belgium <pre style="color: rgb(102, 102, 102);">=</pre> (% style="font-weight: bold; color: rgb(0, 128, 0);" %)new(%%) Locale<pre style="color: rgb(102, 102, 102);">(<pre style="color: rgb(186, 33, 33);">"fr"</pre><pre style="color: rgb(102, 102, 102);">,</pre> </pre><pre style="color: rgb(186, 33, 33);">"BE"</pre>(% style="color: rgb(102, 102, 102);" %));
)))

Moreover, some locales are defined as constants of the class. This is the case for French language (Locale.FRENCH), French locale (Locale.FRENCH) or English language (Locale.ENGLISH).

The second Java component i18n is the ResourceBundle. It is in charge of retrieving a given locale. However, the ResourceBundle is an abstract class, therefore a concrete implementation of the ResoureBundle, namely the PropertyResourceBundle, is used. This implementation is based on a basic file name, “properties”, and, for a given locale, it goes for the translation if it is available. To do that, it checks if a properties file, whose name is <basic file name>_<language code>_<country code>, exists.

If necessary it goes for a translation that is more common, that is to say only based on the language and whose properties file would be named <basic file name>_<language code>.

If the need still arises, it goes for the basic file to retrieve a translation.

For example, in the following code :

(((
ResourceBundle bundle <pre style="color: rgb(102, 102, 102);">= ResourceBundle</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getBundle</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"message"</pre>(% style="color: rgb(102, 102, 102);" %));
)))

If the current locale (for example the default language of the operating system) is fr_FR, here is the order of the files research :

1. message_fr_FR.propertie,
1. message_fr.properties,
1. message.properties.

It is possible to get back a particular ResourceBundle by specifying explicitly the locale to be used :

(((
ResourceBundle bundle <pre style="color: rgb(102, 102, 102);">= ResourceBundle<pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getBundle</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"message"</pre><pre style="color: rgb(102, 102, 102);">,</pre> Locale</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">ENGLISH</pre>(% style="color: rgb(102, 102, 102);" %));
)))

Afterwards, in order to get an internationalized message, for example a message associated to the key “HelloWorld” in the properties file, the method getString(String key) must be used :

(((
String message <pre style="color: rgb(102, 102, 102);">= bundle</pre><pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">getString</pre><pre style="color: rgb(102, 102, 102);">(</pre><pre style="color: rgb(186, 33, 33);">"HelloWorld"</pre>(% style="color: rgb(102, 102, 102);" %));
)))

=== Javadoc ===
{{specialInclusion prefix=$theme_sub section="Javadoc"/}}

=== Links ===
{{specialInclusion prefix=$theme_sub section="Links"/}}

=== Useful Documents ===
{{specialInclusion prefix=$theme_sub section="UsefulDocs"/}}

=== Package Overview ===
{{specialInclusion prefix=$theme_sub section="PkgOverview"/}}

== Features Description ==
=== Exception and internationalization ===
As indicated in the SRS document (requirements PBD-LOG_850), we should create an error message only when it is the only option i.e. nor Java basic errors neither Commons Math or Orekit errors suit. In this case, it is mandatory to add a particular error message, the procedure is the following one :

* Find a unique identifier (one key, see the following chapter for the definition rule) for the message and a short and relevant text,
* Modify the PatriusMessages class and add it to the enumeration, in US English which is the default language, e;g. FOO_MESSAGE("foo message for testing purpose") or BAR_MESSAGE("another foo message for testing purpose {0} {1}") with 2 expected arguments,
* Add this message to the translation files PatriusMessages_<language>.properties, one per language, in the directory …/src/main/resources/META-INF/localization, with the following form “key=text”. The text is translated in the required language, one has to be carful with the arguments location if there are some of them (they can be inverted).

N.B. : For languages which use accents like French, each accented character has to be written with a specific coding. The list of the characters and their equivalent coding is available on the following web site : http://www.utf8-chartable.de/

If a class is necessary for a specific message type, it has to inherit from the one of the following java classes : Exception or RuntimeException.

Example (see the Commons Math library for a complete example) :

(((
(% style="font-weight: bold; color: rgb(0, 128, 0);" %)public (% style="font-weight: bold; color: rgb(0, 128, 0);" %)class(%%) (% style="font-weight: bold; color: rgb(0, 0, 255);" %)MyFutileException(%%) (% style="font-weight: bold; color: rgb(0, 128, 0);" %)extends(%%) Exception (% style="font-weight: bold; color: rgb(0, 128, 0);" %)implements(%%) ExceptionContextProvider <pre style="color: rgb(102, 102, 102);">{</pre>
<pre style="color: rgb(102, 102, 102);">...</pre>
(% style="font-weight: bold; color: rgb(0, 128, 0);" %)private(%%) ExceptionContext exceptionContext <pre style="color: rgb(102, 102, 102);">;</pre> <pre style="color: rgb(64, 128, 128);">/~*~* compulsory variable*/</pre>
<pre style="color: rgb(102, 102, 102);">...</pre>
MyFutileException<pre style="color: rgb(102, 102, 102);">((% style="font-weight: bold; color: rgb(0, 128, 0);" %)final</pre> Locale locale<pre style="color: rgb(102, 102, 102);">,(% style="font-weight: bold; color: rgb(0, 128, 0);" %)final</pre> Object <pre style="color: rgb(102, 102, 102);">...</pre> args<pre style="color: rgb(102, 102, 102);">)</pre> <pre style="color: rgb(102, 102, 102);">{</pre>
exceptionContext<pre style="color: rgb(102, 102, 102);">.<pre style="color: rgb(125, 144, 41);">addMessage</pre><pre style="color: rgb(102, 102, 102);">(</pre>locale<pre style="color: rgb(102, 102, 102);">,</pre>PatriusMessages<pre style="color: rgb(102, 102, 102);">.</pre><pre style="color: rgb(125, 144, 41);">PDB_FUTILE_EXCEPTION</pre>(% style="color: rgb(102, 102, 102);" %),</pre>args<pre style="color: rgb(102, 102, 102);">)</pre>
<pre style="color: rgb(102, 102, 102);">}</pre>
<pre style="color: rgb(102, 102, 102);">...</pre>
(% style="color: rgb(102, 102, 102);" %)}
)))

In this case, a unique identifier as well as the original text of the message and its translations are also needed in the translation files.

== Getting Started ==
{{specialInclusion prefix=$theme_sub section="GettingStarted"/}}

== Contents ==
=== Interfaces ===
{{specialInclusion prefix=$theme_sub section="Interfaces"/}}

=== Classes ===
{{specialInclusion prefix=$theme_sub section="Classes"/}}

== Tutorials ==
=== Tutorial 1 ===
{{specialInclusion prefix=$theme_sub section="Tuto1"/}}

=== Tutorial 2 ===
{{specialInclusion prefix=$theme_sub section="Tuto2"/}}

== [[File:lightBulb.png]] Tips & Tricks ==
{{specialInclusion prefix=$theme_sub section="Tips"/}}