Skip to content
This repository was archived by the owner on Jun 11, 2023. It is now read-only.

Commit 62b217e

Browse files
NaoghumanNaoghuman
committed
#74 [doc] Update every sub-section from 'Conventions'. Add examples to them.
1 parent b283dcc commit 62b217e

File tree

2 files changed

+255
-24
lines changed

2 files changed

+255
-24
lines changed

‎README.md

Lines changed: 254 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
12
Lib-I18n
23
===
34

@@ -28,6 +29,10 @@ Content
2829
- [How to use the builder I18NBindingBuilder](#HoToUsBiBu)
2930
- [How to use the builder I18NMessageBuilder](#HoToUsMeBu)
3031
* [Conventions](#Conventions)
32+
- [Convention: 'baseBundleName' from ResourceBundle](#CoBaFrRe)
33+
- [Convention: 'Key not found' in ResourceBundle](#CoKeInReBu)
34+
- [Convention: Defined supported Locales, default and actual Locale](#CoDeSuDeAcLo)
35+
- [Convention: Basic validation](#CoBaVa)
3136
* [Features](#Features)
3237
* [JavaDoc](#JavaDoc)
3338
* [Download](#Download)
@@ -272,34 +277,260 @@ Conventions<a name="Conventions" />
272277
---
273278

274279
In this chapter, the interested developer can find out all about the conventions
275-
in the library `Lib-I18N`:
280+
from the library `Lib-I18N`:
281+
282+
### Convention: 'baseBundleName' from ResourceBundle<a name="CoBaFrRe" />
276283

277-
__Convention__: 'baseBundleName' from ResourceBundle
278-
* If a [ResourceBundle] with the defined 'baseBundleName' can't be found a
284+
If a [ResourceBundle] with the defined 'baseBundleName' can't be found a spezific
279285
MissingResourceException will be thrown.
280286

281-
__Convention__: 'Key not found' in ResourceBundle
282-
* If a key can't be found in the defined ResourceBundle then
283-
* the String pattern '&lt;key&gt;' will returned instead and
284-
* the 'warning' message will be logged: "Can't find key(%s) in resourcebundle. Return: %s"
285-
286-
__Convention__: Defined supported Locales, default and actual Locale.
287-
* Supported Locales
288-
Defines all supported [Locale]s in the momentary session.
289-
* Default Locale
290-
If the supported Locales doesn't contained the default Locale then the Locale#ENGLISH
291-
will be used instead.
292-
* Actual Locale
293-
If the upported Locales doesn't contained the actual Locale then the default Locale
294-
will be used instead.
295-
296-
__Convention__: Basic validation
297-
* Every attributes in the builders and in all setters will be check against minimal
298-
preconditions with [DefaultI18NValidator].
299-
* Getters attributs will only checked if they are initial only instantiate and not
300-
declarated.
287+
```java
288+
public final class DefaultI18NResourceBundle implements I18NResourceBundle {
289+
...
290+
private ResourceBundle getResourceBundle() {
291+
ResourceBundle bundle = null;
292+
try {
293+
bundle = ResourceBundle.getBundle(this.getBaseBundleName(), this.getActualLocale());
294+
} catch (MissingResourceException mre) {
295+
LoggerFacade.getDefault().error(this.getClass(),
296+
String.format("Can't access the ResourceBundle[path=%s, actual-locale=%s]",
297+
this.getBaseBundleName(), this.getActualLocale().getDisplayLanguage()),
298+
mre);
299+
}
300+
301+
return bundle;
302+
}
303+
...
304+
}
305+
```
306+
307+
### Convention: 'Key not found' in ResourceBundle<a name="CoKeInReBu" />
308+
309+
If a `key` can't be found in the defined ResourceBundle then
310+
* the String pattern '&lt;key&gt;' will returned and
311+
* the following 'warning' message will be logged:
312+
`"Can't find key(%s) in resourcebundle. Return: %s"`
313+
314+
```java
315+
public final class DefaultI18NResourceBundle implements I18NResourceBundle {
316+
...
317+
@Override
318+
public String getMessage(final String key, final Object... arguments) {
319+
DefaultI18NValidator.requireNonNullAndNotEmpty(key);
320+
DefaultI18NValidator.requireNonNullAndNotEmpty(arguments);
321+
DefaultI18NValidator.requireResourceBundleExist(this.getBaseBundleName(), this.getActualLocale());
322+
323+
final ResourceBundle bundle = getResourceBundle();
324+
String value = MessageFormat.format(PATTERN_KEY_NAME, key);
325+
326+
if (bundle != null) {
327+
try {
328+
value = MessageFormat.format(bundle.getString(key), arguments);
329+
} catch (MissingResourceException mre) {
330+
LoggerFacade.getDefault().warn(this.getClass(),
331+
String.format("Can't find key(%s) in resourcebundle. Return: %s", key, value),
332+
mre);
333+
}
334+
}
335+
336+
return value;
337+
}
338+
...
339+
}
340+
```
341+
342+
343+
### Convention: Defined supported Locales, default and actual Locale<a name="CoDeSuDeAcLo" />
344+
345+
_Supported Locales_
346+
* Defines all supported [Locale]s in the momentary session.
347+
* This array should reflectes all your defined languages .properties files.
348+
349+
```java
350+
public final class I18NResourceBundleBuilder {
351+
...
352+
private static final class I18NResourceBundleBuilderImpl implements
353+
FirstStep, ForthStep, LastStep, SecondStep, ThirdStep
354+
{
355+
...
356+
@Override
357+
public ThirdStep supportedLocales(final Locale... locales) {
358+
LoggerFacade.getDefault().debug(this.getClass(), "I18NResourceBundleBuilderImpl.supportedLocales(Locale...)"); // NOI18N
359+
360+
final List<Locale> list = Arrays.asList(locales);
361+
DefaultI18NValidator.requireNonNullAndNotEmpty(list);
362+
363+
final ObservableList<Locale> observableList = FXCollections.observableArrayList();
364+
observableList.addAll(list);
365+
properties.put(ATTR__SUPPORTED_LOCALES, new SimpleObjectProperty(observableList));
366+
367+
return this;
368+
}
369+
370+
@Override
371+
public ThirdStep supportedLocales(final ObservableList<Locale> locales) {
372+
LoggerFacade.getDefault().debug(this.getClass(), "I18NResourceBundleBuilderImpl.supportedLocales(ObservableList<Locale>)"); // NOI18N
373+
374+
DefaultI18NValidator.requireNonNullAndNotEmpty(locales);
375+
properties.put(ATTR__SUPPORTED_LOCALES, new SimpleObjectProperty(locales));
376+
377+
return this;
378+
}
379+
...
380+
}
381+
}
382+
```
383+
384+
```java
385+
public final class I18NFacade implements I18NBinding, I18NResourceBundle {
386+
...
387+
@Override
388+
public ObservableList<Locale> getSupportedLocales() {
389+
return i18NResourceBundle.getSupportedLocales();
390+
}
391+
392+
@Override
393+
public void setSupportedLocales(final ObservableList<Locale> locales) {
394+
i18NResourceBundle.setSupportedLocales(locales);
395+
}
396+
397+
@Override
398+
public void setSupportedLocales(final Locale... locales) {
399+
i18NResourceBundle.setSupportedLocales(locales);
400+
}
401+
...
402+
}
403+
```
404+
405+
```java
406+
public final class DefaultI18NResourceBundle implements I18NResourceBundle {
407+
...
408+
@Override
409+
public ObservableList<Locale> getSupportedLocales() {
410+
DefaultI18NValidator.requireNonNull(supportedLocales);
411+
412+
return supportedLocales;
413+
}
414+
415+
@Override
416+
public void setSupportedLocales(final ObservableList<Locale> locales) {
417+
DefaultI18NValidator.requireNonNullAndNotEmpty(locales);
418+
419+
supportedLocales.clear();
420+
supportedLocales.addAll(locales);
421+
}
422+
423+
@Override
424+
public void setSupportedLocales(final Locale... locales) {
425+
final List<Locale> list = Arrays.asList(locales);
426+
DefaultI18NValidator.requireNonNullAndNotEmpty(list);
427+
428+
supportedLocales.clear();
429+
supportedLocales.addAll(list);
430+
}
431+
...
432+
}
433+
```
434+
435+
_Default Locale_
436+
* If the supported Locales doesn't contained the default Locale then the `Locale#ENGLISH` instead
437+
will be return.
438+
439+
```java
440+
public final class DefaultI18NResourceBundle implements I18NResourceBundle {
441+
...
442+
@Override
443+
public void setDefaultLocale(final Locale locale) {
444+
DefaultI18NValidator.requireNonNull(locale);
445+
446+
defaultLocale = this.getSupportedLocales().contains(locale) ? locale : Locale.ENGLISH;
447+
}
448+
...
449+
}
450+
```
451+
452+
_Actual Locale_
453+
* If the upported Locales doesn't contained the actual Locale then the `default` Locale instead
454+
will be return.
455+
456+
```java
457+
458+
public final class DefaultI18NResourceBundle implements I18NResourceBundle {
459+
...
460+
@Override
461+
public void setActualLocale(final Locale locale) {
462+
DefaultI18NValidator.requireNonNull(locale);
463+
464+
actualLocaleProperty.set(this.getSupportedLocales().contains(locale) ? locale : defaultLocale);
465+
}
466+
...
467+
}
468+
```
469+
470+
471+
### Convention: Basic validation<a name="CoBaVa" />
472+
473+
* Every `functionality` in the builders and in the default implementations will checked
474+
against minimal preconditions with the validator [DefaultI18NValidator].
475+
* `Getters` and `Setters` functionalities are only checked if they are initial only
476+
instantiate and not declarated.
301477
* For example a String will be validate if it's not NULL and not EMPTY.
302478

479+
```java
480+
public final class I18NResourceBundleBuilder {
481+
...
482+
private static final class I18NResourceBundleBuilderImpl implements
483+
FirstStep, ForthStep, LastStep, SecondStep, ThirdStep
484+
{
485+
...
486+
@Override
487+
public SecondStep baseBundleName(final String baseBundleName) {
488+
LoggerFacade.getDefault().debug(this.getClass(), "I18NResourceBundleBuilderImpl.baseBundleName(String)"); // NOI18N
489+
490+
DefaultI18NValidator.requireNonNullAndNotEmpty(baseBundleName);
491+
properties.put(ATTR__BASE_BUNDLE_NAME, new SimpleStringProperty(baseBundleName));
492+
493+
return this;
494+
}
495+
...
496+
}
497+
}
498+
```
499+
500+
```java
501+
public final class DefaultI18NResourceBundle implements I18NResourceBundle {
502+
...
503+
@Override
504+
public String getBaseBundleName() {
505+
DefaultI18NValidator.requireNonNullAndNotEmpty(baseBundleName);
506+
507+
return baseBundleName;
508+
}
509+
510+
@Override
511+
public void setBaseBundleName(final String baseBundleName) {
512+
DefaultI18NValidator.requireNonNullAndNotEmpty(baseBundleName);
513+
514+
this.baseBundleName = baseBundleName;
515+
}
516+
...
517+
}
518+
```
519+
520+
```java
521+
public final class DefaultI18NBinding implements I18NBinding {
522+
...
523+
@Override
524+
public StringBinding createStringBinding(final String key, Object... arguments) {
525+
DefaultI18NValidator.requireNonNullAndNotEmpty(key);
526+
DefaultI18NValidator.requireNonNullAndNotEmpty(arguments);
527+
528+
return Bindings.createStringBinding(() -> I18NFacade.getDefault().getMessage(key, arguments), I18NFacade.getDefault().actualLocaleProperty());
529+
}
530+
...
531+
}
532+
```
533+
303534

304535

305536
Features<a name="Features" />

‎release/Release_v0.7.1_2019-02-dd_HH-mm.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Lib-I18N is written in JavaFX, [Maven] and [NetBeans].
2929
#### Documentation
3030
#77 [doc] Add tag 'p' after all lists in JavaDoc.
3131
#76 [doc] Update JavaDoc in I18NBinding.
32+
#74 [doc] Update every sub-section from 'Conventions'. Add examples to them.
3233
#73 [doc] Update section 'Conventions', sub-section 'key-not-found'.
3334

3435

@@ -47,7 +48,6 @@ Naoghuman
4748

4849

4950
[//]: # (Issues which will be integrated in this release)
50-
#74 [doc] Update every sub-section from 'Conventions'. Add examples to them.
5151

5252

5353

0 commit comments

Comments
 (0)