eu.bandm.tools.muli

Class Catalog<K>

java.lang.Object

eu.bandm.tools.muli.Catalog<K>

Direct Known Subclasses:

CatalogByString

public class Catalog<K>
extends Object

Each muli.Catalog represents a relation between a MuLi and objects of type [K], serving as keys. It can be used as a multi-lingual map, i.e. as a catalog in both directions.
Its structure is

   mulitexts: (K -/-> MuLi)
  
  catalogs: (language:String -/-> name:String -/-> K) 
 

Both structures are maintained synchronuously when calling the "put()" methods.
muli.Catalog objects are mutable. Currently there is no immutable derived class.
All the different put() methods add new relation elements to the existing maps. This can result in an override of one or more currently stored existing relation elements, but this is not checked.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	Catalog.Const Wrapper class to prevent the translation OF AN ARGUMENT, eg.

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<String,Map<String,K>>	catalogs
protected Class<K>	keyClass Currently only required for recursive application, when translating ARGUMENTS of a format string.
protected Map<K,MuLi>	mulitexts

Constructor Summary

Constructors

Constructor and Description
Catalog(Class<K> keyClass)

Method Summary

Modifier and Type	Method and Description
protected String	_format(String text, List<Object> args)
protected String	_format(String text, Object... args) The string formatting process as defined with String.format(String,Object...) is applied.
protected List<Object>	_translateArgs(List<String> pref, List<Object> args)
boolean	containsKey(K key)
void	dump(PrintStream s) For DEBUGGING: dump Catalog to printstream.
@Opt MuLi	get(K key) Delivers an unmodifiable copy of the MuLi for a given key object.
MuLi.TextFound	get(K key, List<String> pref)
MuLi.TextFound	get(K key, String... pref) Delivers the name of a given key object in language chosen from a preference list.
@Opt String	get(K key, String lang) Delivers the name of a given key object in a certain language.
K	getKey(String lang, String name) Delivers the key object for a given name in a given language
Set<K>	getKeys()
Set<K>	getKeys(MuLi muli) Delivers all key objects for the (language, name) combinations given by the MuLi argument.
Set<K>	getKeys(String name) Delivers all key objects for a given name in all languages.
K	INSITU(K key, List<String> variants) Enters an "in-situ" definition into this translation catalog and returns the (un-translated) key.
String	insitu(K key, List<String> langprefs, List<String> variants) Enters an "in-situ" definition into this translation catalog and returns the translated text immediately.
String	insitu(K key, List<String> langprefs, List<String> variants, List<Object> args) Enters an "in-situ" definition into this translation catalog and returns the translated text immediately.
String	insitu(K key, List<String> langprefs, List<String> variants, Object... args)
String	insitu(K key, List<String> langprefs, String... pairs)
protected Map<String,K>	makeMap(String lang)
protected MuLi	makeMuli(K key)
static Catalog.Const	noTranslate(String s)
void	put(K key, List<String> pairs) Add one certain key object, and a list of languages and names
void	put(K key, MuLi muli) Add one certain key object, and a MuLi mapping languages to names.
void	put(K key, String... pairs)
void	put(K key, String lang, String text) Add one certain key object, one language and one name.
void	putAll(Catalog<K> other) Add the contents of a second catalog.
Map<String,K>	readLanguageMap(String lang) Delivers the map String->K for a given language
SortedSet<String>	readLanguages() Delivers the set of all contained languages
String	readLanguagesString(String sep, String sep2) Delivers a list of all occuring languges, sorted alphabetically.
String	translateAllAndFormatRobust(K key, List<String> pref, List<Object> args) Translate the Key and all args by by calling #translateRobust(K,List).
String	translateAllAndFormatRobust(K key, List<String> pref, Object... args)
String	translateArgsAndFormatRobust(K key, List<String> pref, List<Object> args) Do NOT translate the key, but call "toString()".
String	translateArgsAndFormatRobust(K key, List<String> pref, Object... args)
String	translateKeyAndFormatRobust(K key, List<String> pref, List<Object> args) Translate the Key by calling #translateRobust(K,List).
String	translateKeyAndFormatRobust(K key, List<String> pref, Object... args)
String	translateRobust(K key, List<String> pref) Translate the key into one of the languages of the list "pref".
String	translateRobust(K key, String... pref)

Methods inherited from class java.lang.Object

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

Field Detail

keyClass

protected Class<K> keyClass

Currently only required for recursive application, when translating ARGUMENTS of a format string.

mulitexts

protected Map<K,MuLi> mulitexts

catalogs

protected Map<String,Map<String,K>> catalogs

Constructor Detail

Catalog

public Catalog(Class<K> keyClass)

Method Detail

getKey

@Opt
public K getKey(String lang,
                     String name)

Delivers the key object for a given name in a given language

Returns:

the found key object, or null in case the combination of language and name has not been put.

getKeys

public Set<K> getKeys()

Returns:

all key objects in an unmodifiable copy. (FIXME could be sorted if comparable =)

getKeys

public Set<K> getKeys(String name)

Delivers all key objects for a given name in all languages.

getKeys

public Set<K> getKeys(MuLi muli)

Delivers all key objects for the (language, name) combinations given by the MuLi argument.
(MuLi.syntheticLanguage,name) matches ALL languages.

readLanguages

public SortedSet<String> readLanguages()

Delivers the set of all contained languages

Returns:

a sorted copy of language keys

readLanguagesString

public String readLanguagesString(String sep,
                                  String sep2)

Delivers a list of all occuring languges, sorted alphabetically.

Parameters:

sep - the separator between two languges keys.

Returns:

a String containing all language keys

readLanguageMap

public Map<String,K> readLanguageMap(String lang)

Delivers the map String->K for a given language

Returns:

an unmodifiable map

get

@Opt
public @Opt MuLi get(K key)

Delivers an unmodifiable copy of the MuLi for a given key object.

get

@Opt
public @Opt String get(K key,
                            String lang)

Delivers the name of a given key object in a certain language.
(Do not mix up with #get(K,String...) which always returns some default! Bad naming design! FIXME)

Returns:

null if no such name had been stored.

containsKey

public boolean containsKey(K key)

Returns:

whether at least one language has an entry for the key.

get

@Opt
public MuLi.TextFound get(K key,
                               String... pref)

Delivers the name of a given key object in language chosen from a preference list. This delegates to MuLi.get(String...), i.e. if no language in the list matches, the index field in the resulting TextFound will be -1.

Returns:

null in case that the key has never been stored.

get

@Opt
public MuLi.TextFound get(K key,
                               List<String> pref)

See Also:

get(K,String...)

translateRobust

public String translateRobust(K key,
                              List<String> pref)

Translate the key into one of the languages of the list "pref". If no such translation is found, then into an arbitrary selected language. If there is no single translation into any language then return "toString()".

Returns:

always a String value, never null.

translateRobust

public String translateRobust(K key,
                              String... pref)

See Also:

translateRobust(K,List)

translateArgsAndFormatRobust

public String translateArgsAndFormatRobust(K key,
                                           List<String> pref,
                                           List<Object> args)

Do NOT translate the key, but call "toString()".
Translate all Objects in "args" by calling #translateRobust(K,List). Translating an "arg" means to apply #translateRobust(K,List) iff "arg" is instance of keyClass, otherwise leave it unaltered.
Then apply string formatting.

Returns:

always a String value, never null.

translateArgsAndFormatRobust

public String translateArgsAndFormatRobust(K key,
                                           List<String> pref,
                                           Object... args)

See Also:

translateArgsAndFormatRobust(K,List.List)

translateKeyAndFormatRobust

public String translateKeyAndFormatRobust(K key,
                                          List<String> pref,
                                          List<Object> args)

Translate the Key by calling #translateRobust(K,List).
Do NOT translate the args.
Then apply string formatting.

Returns:

always a String value, never null.

translateKeyAndFormatRobust

public String translateKeyAndFormatRobust(K key,
                                          List<String> pref,
                                          Object... args)

See Also:

translateKeyAndFormatRobust(K,List,List)

translateAllAndFormatRobust

public String translateAllAndFormatRobust(K key,
                                          List<String> pref,
                                          List<Object> args)

Translate the Key and all args by by calling #translateRobust(K,List).
Translating an "arg" means to apply #translateRobust(K,List) iff "arg" is instance of keyClass, otherwise leave it unaltered.
Then apply string formatting.

Returns:

always a String value, never null.

translateAllAndFormatRobust

public String translateAllAndFormatRobust(K key,
                                          List<String> pref,
                                          Object... args)

See Also:

translateAllAndFormatRobust(K,List,List)

_translateArgs

protected List<Object> _translateArgs(List<String> pref,
                                      List<Object> args)

_format

protected String _format(String text,
                         List<Object> args)

_format

protected String _format(String text,
                         Object... args)

The string formatting process as defined with String.format(String,Object...) is applied.
Whenever a formatting error occurs, this fact is represented as text and incorporated into the returned String value. So the process never fails, but the problems will be visible, normally in the output to the user.
ATTENTION
FIXME make this behaviour configurable !?!?

INSITU

public K INSITU(K key,
                List<String> variants)

Enters an "in-situ" definition into this translation catalog and returns the (un-translated) key. As a side effect the translations are stored for later retrieval. This allows to write the translation not in a separate file, but in the code at the place where it is called, which may be more convenient for soem coding situation.
This variant returns the key, so it can be used as an argument for MuLiMessageReceiver methods.
ATTENTION more than one calls with the same key are illegal and bring unpredictable results, because only one of both storings will be executed.

Parameters:

key -

variants - list of PAIRS of String, each language code and text

insitu

public String insitu(K key,
                     List<String> langprefs,
                     List<String> variants)

Enters an "in-situ" definition into this translation catalog and returns the translated text immediately. As a side effect the translations are stored for later retrieval. This allows to write the translation not in a separate file, but in the code at the place where it is called, which may be more convenient for soem coding situation.
This is the variant for constant texts, with no embedded "printf" codes.
(Its result can not be used as an argument to a MuLiMessageReceiver method, because this implies a (second) translation step. For this case use INSITU(K, java.util.List<java.lang.String>).

Parameters:

key -

langprefs - list of language preferences for the retrieved text, as usual

variants - list of PAIRS of String, each language code and text

insitu

public String insitu(K key,
                     List<String> langprefs,
                     String... pairs)

See Also:

insitu(Object,List,List)

insitu

public String insitu(K key,
                     List<String> langprefs,
                     List<String> variants,
                     List<Object> args)

Enters an "in-situ" definition into this translation catalog and returns the translated text immediately. As a side effect the translations are stored for later retrieval. This allows to write the translation not in a separate file, but in the code at the place where it is called, which may be more convenient for soem coding situation.
The translation of the arguments happens as with translateAllAndFormatRobust(K,List,List).
(Its result can not be used as an argument to a MuLiMessageReceiver method, because this implies a (second) translation step. For this case use INSITU(K, java.util.List<java.lang.String>).

Parameters:

key -

langprefs - list of language preferences, as usual

variants - list of PAIRS of String, each language code and text

args - objects formatted into the translated text by printf codes

insitu

public String insitu(K key,
                     List<String> langprefs,
                     List<String> variants,
                     Object... args)

See Also:

insitu(Object,List,List,List)

makeMuli

protected MuLi makeMuli(K key)

makeMap

protected Map<String,K> makeMap(String lang)

put

public void put(K key,
                String lang,
                String text)

Add one certain key object, one language and one name.
Attention:
Existing map entries will silently be overwritten, but no further clean-up happens automatically. So re-usage of Catalog objects is not recommended:

   put (k1, L1, text_1)
   put (k1, L2, text_2)
   put (k1, L1, text_1_new)

... may lead to unintended combinations.

put

public void put(K key,
                String... pairs)

See Also:

put(K,List)

put

public void put(K key,
                List<String> pairs)

Add one certain key object, and a list of languages and names

Parameters:

pairs - sequence of key/value pairs

Throws:

IllegalArgumentException - in case the number of Strings in not even.

put

public void put(K key,
                MuLi muli)

Add one certain key object, and a MuLi mapping languages to names.

putAll

public void putAll(Catalog<K> other)

Add the contents of a second catalog. ATTENTION: overriding is hard, and no concistency checks are applied.

dump

public void dump(PrintStream s)

For DEBUGGING: dump Catalog to printstream.

Parameters:

s - PrintStream to print to.

noTranslate

public static Catalog.Const noTranslate(String s)