js.util

Class I18nRepository

java.lang.Object

js.util.I18nRepository

All Implemented Interfaces:

Iterable<I18nFile>

public class I18nRepository
extends Object
implements Iterable<I18nFile>

Repository for files organized by locale. I18N repository has multiple sets of files with identical names, grouped by locale, see ASCII diagram below. Support for multiple locale can miss in which case this repository degenerates to a standard filesystem directory.

Repository has a base directory that contains a number of locale directories. By convention uses locale language tag - see Locale.toLanguageTag(), to name these locale directories. Is not allowed to mix locale directory with other sub-directories, that is, base directory should contain only valid locale directories. Files set are stored into locale directory with optional sub-path.

Language tag should contain only lower case language and optional upper case country, separated by hyphen. Language is encoded ISO 639 alpha-2 and for country uses ISO 3166 alpha-2. There is no support for locale variant, script or extension.

 BASE / LOCALEi / SUB-PATH / FILEi
                           / FILEj
                           ~
      / LOCALEj / SUB-PATH / FILEi
                           / FILEj
 

In order to create an I18N repository one needs a configuration object, see I18nRepository(Config); in next section are described needed properties. To simplify integration there is a dedicated configuration builder. Once instantiated, repository can create I18N files pool then scan for files. If files pattern is provided scan only matching files. Scanning process takes care to initialize I18N file locale from locale directory name.

If repository is created without multiple locale support, created I18N pool instance is single locale and I18N file locale is not initialized and ignored by pool.

 // create and configure I18N repository
 ConfigBuilder builder = new I18nRepository.ConfigBuilder(repositoryPath);
 I18nRepository repository = new I18nRepository(builder.build());
 
 // create single or multiple locale I18N pool accordingly repository support
 I18nPool pool = repository.getPoolInstance();
 
 // traverses all files from repository, that is, from all locale
 for(I18nFile i18nFile : repository) {
   // create object instance and initialize it from file content
   File file = i18nFile.getFile();
   Template template = new Template(file);
 
   // store created object instance on cache, bound to file name and detected locale
   pool.put(file.getName(), template, i18nFile.getLocale());
 }
 

Repository instance is configured using a Config instance that is created by a builder, see I18nRepository.ConfigBuilder. Configuration builder needs repository path and optional files pattern. Repository path is a standard directories path but with ${locale} variable indicating locale directory position into directories hierarchy, e.g. /var/www/vhosts/site/${locale}/emails/. Directory path can be relative or absolute. If files pattern is not provided accept all files.

Version:

final

Author:

Iulian Rotaru

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	I18nRepository.ConfigBuilder Configuration builder for I18N repository.
private static class	I18nRepository.MultipleLocale Multiple locale I18N repository.
private static class	I18nRepository.SingleLocale I18N repository implementation optimized for single locale.

Field Summary

Fields

Modifier and Type	Field and Description
private Iterable<I18nFile>	iterable Iterable over I18N files from repository.
private boolean	multiLocale Flag true if I18N repository has support for multiple locale.

Constructor Summary

Constructors

Constructor and Description
I18nRepository(Config config) Create I18N repository instance and configure it.

Method Summary

Modifier and Type	Method and Description
<T> I18nPool<T>	getPoolInstance() Factory method for I18N pool instances.
Iterator<I18nFile>	iterator() Implements iterable interface so that repository can be traversed via for-each loop.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

iterable

private final Iterable<I18nFile> iterable

Iterable over I18N files from repository.

multiLocale

private final boolean multiLocale

Flag true if I18N repository has support for multiple locale.

Constructor Detail

I18nRepository

public I18nRepository(Config config)
               throws IOException

Create I18N repository instance and configure it. See I18nRepository.ConfigBuilder for configuration object properties.

Parameters:

config - configuration object.

Throws:

IllegalArgumentException - if configured base directory does not denote an existing directory.

IOException - if reading directories content fails, perhaps for lack of authorization.

BugError - if no files matching files pattern found or missing locale directory.

Method Detail

getPoolInstance

public <T> I18nPool<T> getPoolInstance()

Factory method for I18N pool instances. Returned pool instance may be single or multiple locale, depending on this repository configuration, see multiLocale. This factory method just delegates I18nPoolFactory.

Type Parameters:

T - instance type.

Returns:

I18N pool instance.

iterator

public Iterator<I18nFile> iterator()

Implements iterable interface so that repository can be traversed via for-each loop.

Specified by:

iterator in interface Iterable<I18nFile>