Package 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.

  • Field Details

    • 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 Details

    • Catalog

      public Catalog(Class<K> keyClass)

  • Method Details

    • 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

      @Opt public @Opt 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:

    • 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:

    • 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(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.
      Returns:
      always a String value, never null.

    • translateArgsAndFormatRobust

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

    • translateKeyAndFormatRobust

      public String translateKeyAndFormatRobust(K key, List<String> pref, List<Object> args)
      Translate the Key by calling translateRobust(Object,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:

    • translateAllAndFormatRobust

      public String translateAllAndFormatRobust(K key, List<String> pref, List<Object> args)
      Translate the Key and all args by 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.
      Returns:
      always a String value, never null.

    • translateAllAndFormatRobust

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

    • _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 some coding situation.
      This variant returns the key, so it can be used as a sub-expression for the main text in a message expression.
      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 K INSITU(K key, String... variants)

    • 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 -
      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

      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 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 -
      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:

    • 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

      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.

    • putAll

      public void putAll(Catalog<K> other, String prefix)
      Add the contents of a second catalog with a prefix added to every translation. 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)