Package eu.bandm.tools.muli

Class Catalog<K>

java.lang.Object
eu.bandm.tools.muli.Catalog<K>
Type Parameters:
K - the type of the keys, for which names in different languages can be retrieved.
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.

  • Field Details

    • keyClass

      protected Class<K> keyClass
      Currently only required for recursive application, when translating the arguments for a format string.

    • mulitexts

      protected Map<K,MuLi> mulitexts
      The entried for the keys: translation into different languages.

    • catalogs

      protected Map<String,Map<String,K>> catalogs
      Reverse direction: maps language -> name -> K

  • Constructor Details

    • Catalog

      public Catalog(Class<K> keyClass)
      Constructor.
      Parameters:
      keyClass - for identifying arguments which are themselves translateable.

  • Method Details

    • getKey

      @Opt public K getKey(String lang, String name)
      Delivers the key object for a given name in a given language
      Parameters:
      lang - the language for which the name is defined
      name - the name for the key in the 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 this catalog.
      Returns:
      all key objects in an unmodifiable copy.

    • getKeys

      public Set<K> getKeys(String name)
      Delivers all key objects for a given name in all languages.
      Parameters:
      name - the translation text for which all keys are retrieved.
      Returns:
      set of all keys which deliver the name in some language.

    • getKeys

      public Set<K> getKeys(MuLi muli)
      Delivers all key objects for the (language, name) combinations given by the MuLi argument. This can find homonyms in the same language as in the MuLi.
      (MuLi.SYNTHETIC_LANGUAGE,name) matches ALL languages.
      Parameters:
      muli - combinations of languages and translations.
      Returns:
      set of all keys which deliver one of the combinations.

    • readLanguages

      public SortedSet<String> readLanguages()
      Delivers the set of all contained languages
      Returns:
      a sorted copy of language keys

    • readLanguagesString

      public String readLanguagesString(String lang)
      Delivers a list of all occuring languages, sorted alphabetically.
      Parameters:
      lang - the language to format the list (currently only "en" is treated specially.
      Returns:
      a String containing all language keys, formatted.

    • readLanguageMap

      @Opt public @Opt Map<String,K> readLanguageMap(String lang)
      Delivers the map String->K for a given language
      Parameters:
      lang - the language for which all translations are retrieved.
      Returns:
      an unmodifiable map

    • get

      @Opt public @Opt MuLi get(K key)
      Delivers an unmodifiable copy of the MuLi for a given key object.
      Parameters:
      key - the key for which the MuLi translation list is retrieved.
      Returns:
      the MuLi translation list is retrieved for the key.

    • getSpecific

      @Opt public @Opt String getSpecific(K key, String lang)
      Delivers the name of a given key object in a certain language.
      Parameters:
      key - the key for which a translation is searched.
      lang - the language for which a translation is searched.
      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.
      Parameters:
      key - to search for.
      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. and the language and translation are chosen by random.
      Parameters:
      key - to search for.
      pref - of languages. If list is empty, then a random result will be delivered anyhow.
      Returns:
      null in case that the key has never been stored.

    • get

      @Opt public MuLi.TextFound get(K key, List<String> pref)
      Delivers the name of a given key object in language chosen from a preference list.
      See Also:

    • 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()".
      Parameters:
      key - to find the top-level text.
      pref - of languages. If list is empty, then a random result or "toString()" will be delivered.
      Returns:
      always a String value, never null.

    • translateRobust

      public String translateRobust(K key, String... pref)
      Translate the key into one of the languages of the list "pref".
      Parameters:
      key - to find the top-level text.
      pref - of languages. If list is empty, then a random result or "toString()" will be delivered.
      See Also:

    • translateArgsAndFormatRobust

      public String translateArgsAndFormatRobust(K key, List<String> pref, List<Object> args)
      Translate all arguments and then format the top-level text. Do NOT translate the key, but call "toString()".
      Translate all Objects in "args" by calling translateRobust(Object,List). Translating an "arg" means to apply translateRobust(Object,List) iff "arg" is instance of keyClass, otherwise leave it unaltered.
      Then apply string formatting.
      Parameters:
      key - to find the top-level text.
      pref - of languages. If list is empty, then a random result or "toString()" will be delivered.
      args - the arguments for formatting the top-level translation.
      Returns:
      always a String value, never null.

    • translateArgsAndFormatRobust

      public String translateArgsAndFormatRobust(K key, List<String> pref, Object... args)
      Translate all arguments and then format the top-level text.
      See Also:

    • translateKeyAndFormatRobust

      public String translateKeyAndFormatRobust(K key, List<String> pref, List<Object> args)
      Translate the Key by calling translateRobust(Object,List), but do not translate the args.
      Then apply string formatting.
      Parameters:
      key - to find the top-level text.
      pref - of languages. If list is empty, then a random result or "toString()" will be delivered.
      args - the arguments for formatting the top-level translation.
      Returns:
      always a String value, never null.

    • translateKeyAndFormatRobust

      public String translateKeyAndFormatRobust(K key, List<String> pref, Object... args)
      Translate the Key by calling translateRobust(Object,List), but do not translate the args.
      See Also:

    • translateAllAndFormatRobust

      public String translateAllAndFormatRobust(K key, List<String> pref, List<Object> args)
      Translate the Key and all args and format them. This is done by calling translateRobust(Object,List).
      Translating an "arg" means to apply translateRobust(Object,List) iff "arg" is instance of keyClass, otherwise leave it unaltered.
      Then apply string formatting.
      Parameters:
      key - to find the top-level text.
      pref - of languages. If list is empty, then a random result or "toString()" will be delivered.
      args - the arguments for formatting the top-level translation.
      Returns:
      always a String value, never null.

    • translateAllAndFormatRobust

      public String translateAllAndFormatRobust(K key, List<String> pref, Object... args)
      Translate the Key and all args and format them.
      See Also:

    • _translateArgs

      protected List<Object> _translateArgs(List<String> pref, List<Object> args)
      Step through the list of arguments and traslate them, if they are of the key type »K«.

      (This is not applied if K==String, by using CatalogByString. Then simple strings will never be translated, but embedded PreMessages will be translated even recursively.)

      Parameters:
      pref - of languages. If list is empty, then a random result or "toString()" will be delivered.
      args - the arguments for formatting the top-level translation.
      Returns:
      the list of translated or untouched argments.

    • _format

      protected String _format(String text, List<Object> args)
      Format the text with the given arguments.
      See Also:

    • _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.
      Parameters:
      text - top-level text to format.
      args - arguments
      Returns:
      a String value in any case. Either correctly formatted or with embedded foramtting error messages.

    • 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 particular coding situations.
      This variant returns the key, so it can be used as a sub-expression for the main text in a message expression.

      The name in uppercase characters is chosen because the invocation of this method is a kind of inline constant definition.
      ATTENTION: Is only suited for simple situations: If any translation for the given key exists, nothing will be stored. Thus multiple calls with the same key yield unpredictable results, and incremental = multi-source translations for the same key are not possible.

      Parameters:
      key - for which the translations are defined.
      variants - list of PAIRS of String, each language code and text.
      Returns:
      the untranslated key

    • INSITU

      public K INSITU(K key, String... variants)
      Enters an "in-situ" definition into this translation catalog and returns the (un-translated) key.
      See Also:

    • 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 some coding situation.
      This is the variant for constant texts, with no embedded "printf" codes.
      (Its result can not be used as an argument for construction a message, when this shall be translated in a subsequent step. For this case use INSITU(K, java.util.List<java.lang.String>).)
      Parameters:
      key - for which the translations are defined.
      langprefs - the preferences to translate the key
      variants - list of PAIRS of String, each language code and text
      Returns:
      the translated key

    • insitu

      public String insitu(K key, List<String> langprefs, String... pairs)
      Enters an "in-situ" definition into this translation catalog and returns the translated text immediately.
      See Also:

    • 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(Object,List,List).
      (Its result can not be used as an argument for constructing a message, when this shall be translated in a subsequent step. For this case use INSITU(K, java.util.List<java.lang.String>).)
      Parameters:
      key - for which the translations are defined.
      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.
      Returns:
      the translated and formatted text.

    • insitu

      public String insitu(K key, List<String> langprefs, List<String> variants, Object... args)
      Enters an "in-situ" definition into this translation catalog and returns the translated text immediately.
      See Also:

    • put

      public Catalog<K> put(K key, String lang, String text)
      Add one particular combination of key object, language and 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.
      Parameters:
      key - for which the translation is defined.
      lang - for which the translation is defined.
      text - of the translation.
      Returns:
      this, for method chaining.

    • put

      public Catalog<K> put(K key, String... pairs)
      Add one particular combination of key object, language and name.
      Parameters:
      key - for which the translation is defined.
      pairs - sequence of key/value pairs
      Returns:
      this, for method chaining.
      Throws:
      IllegalArgumentException - in case the number of Strings is not even.
      See Also:

    • put

      public Catalog<K> put(K key, List<String> pairs)
      Add one particular key object, and a list of languages and names
      Parameters:
      key - for which the translation is defined.
      pairs - sequence of key/value pairs
      Returns:
      this, for method chaining.
      Throws:
      IllegalArgumentException - in case the number of Strings is not even.

    • put

      public Catalog<K> put(K key, MuLi muli)
      Add one certain key object, and a MuLi mapping languages to names.
      Parameters:
      key - for which the translation is defined.
      muli - represnting the combinations of languages and names.
      Returns:
      this, for method chaining.

    • putAll

      public Catalog<K> putAll(Catalog<K> other)
      Add the contents of a second catalog. The added contents overrides existing contents, no concistency checks are applied.
      Parameters:
      other - catalog to add to this catalog.
      Returns:
      this, for method chaining.

    • putAll

      public Catalog<K> putAll(Catalog<K> other, String prefix)
      Add the contents of a second catalog with a prefix added to every translation. The added contents overrides existing contents, no concistency checks are applied.
      Parameters:
      other - catalog to add to this catalog.
      prefix - text prepended to every entry.
      Returns:
      this, for method chaining.

    • dump

      public void dump(PrintStream s)
      For debugging: dump Catalog to printstream.
      Parameters:
      s - PrintStream to print to.

    • noTranslate

      @Deprecated(forRemoval=false) public static <L> Catalog.Const<L> noTranslate(L s)
      Deprecated.
      ONLY for CatalogByString !!
      Factory method.
      Type Parameters:
      L - the class of the value to wrap.
      Parameters:
      s - the value to wrap.
      Returns:
      a wrapper object.