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
Realizes the relations between some a type and muli objects, which hold names in different languages for those keys. Each instance can be used as a multi-lingual map in both directions among names and keys.

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)
      Only constructor.
      Parameters:
      keyClass - for identifying arguments which are themselves translateable.

  • Method Details

    • getKey

      @Opt public K getKey(String lang, String name)
      Returns 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)
      Returns 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)
      Returns 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()
      Returns the set of all contained languages
      Returns:
      a sorted copy of language keys

    • readLanguagesString

      public String readLanguagesString(String lang)
      Returns 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)
      Returns 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)
      Returns 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)
      Returns 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)
      Returns 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 - the priority list 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)
      Returns the name of a given key object in language chosen from a preference list.
      Parameters:
      key - the key which shall be translated
      pref - the priority list 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.
      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 the result of Object.toString().
      Parameters:
      key - to find the top-level text.
      pref - the priority list of languages. If list is empty, then a random result or Object.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 - priority list of languages. If list is empty, then a random result or toString() will be delivered.
      Returns:
      always a String value, never null.
      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 - the priority list 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.
      Parameters:
      key - to find the top-level text.
      pref - the priority list 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.
      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 - the priority list 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.
      Parameters:
      key - to find the top-level text.
      pref - the priority list 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.
      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 - the priority list 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.
      Parameters:
      key - to find the top-level text.
      pref - the priority list of languages.
      args - the arguments for formatting the top-level translation.
      Returns:
      always a String value, never null.
      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 - the priority list 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.
      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.
      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 formatting 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. The storing only happens if the key is currently undefined. Otherwise the existing assignments are used for translation and the variants argument is ignored. 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.

      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 of 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. The storing only happens if the key is currently undefined. Otherwise the existing assignments are used for translation and the variants argument is ignored.
      Parameters:
      key - for which the translations are defined.
      variants - list of pairs of String, each of language code and text.
      Returns:
      the translated key
      See Also:

    • insitu

      public String insitu(K key, List<String> langprefs, List<String> variants)
      Stores an in-situ definition into this translation catalog and returns the translated text immediately. The storing only happens if the key is currently undefined. Otherwise the existing assignments are used for translation and the variants argument is ignored. 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 format codes.
      (Its result can not be used as an argument for construction a message, when this shall be translated in a subsequent step. For those cases use INSITU(K, java.util.List<java.lang.String>) and process the returned key explicitly.)
      Parameters:
      key - for which the translations are defined.
      langprefs - the preferences to translate the key
      variants - list of pairs of String, each of language code and text.
      Returns:
      the translated key

    • insitu

      public String insitu(K key, List<String> langprefs, String... variants)
      Enters an in-situ definition into this translation catalog and returns the translated text immediately. The storing only happens if the key is currently undefined. Otherwise the existing assignments are used for translation and the variants argument is ignored.
      Parameters:
      key - for which the translations are defined.
      langprefs - the preferences to translate the key
      variants - list of pairs of String, each of language code and text.
      Returns:
      the translated key
      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. The storing only happens if the key is currently undefined. Otherwise the existing assignments are used for translation and the variants argument is ignored.

      This method allows to write the translation not in a separate file, but in the source code at the place where it is called, which may be more convenient for the coding situation.

      The translation of the arguments happens as with translateAllAndFormatRobust(Object,List,List).
      (Its result cannot be used as an argument for constructing a message, when this shall be translated in a subsequent step. For those cases use INSITU(K, java.util.List<java.lang.String>) and process the returned key explicitly..)

      Parameters:
      key - for which the translations are defined.
      langprefs - list of language preferences, as usual.
      variants - list of pairs of String, each of 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.
      Parameters:
      key - for which the translations are defined.
      langprefs - list of language preferences, as usual.
      variants - list of pairs of String, each of language code and text.
      args - objects formatted into the translated text by printf codes.
      Returns:
      the translated and formatted text.
      See Also:

    • put

      public Catalog<K> put(K key, String lang, String text)
      Add one particular combination of key object, language and name.

      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.