Package eu.bandm.tools.muli

Class Catalog<K>

  • Direct Known Subclasses:
    CatalogByString
    public class Catalog<K>
extends java.lang.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 Description
      protected static class  Catalog.Const
      Wrapper class to prevent the translation OF AN ARGUMENT, eg.

    • Field Summary

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

    • Constructor Summary

      Constructors 
      Constructor Description
      Catalog​(java.lang.Class<K> keyClass)  

    • Method Summary

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

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • keyClass

        protected java.lang.Class<K> keyClass
        Currently only required for recursive application, when translating ARGUMENTS of a format string.

      • mulitexts

        protected java.util.Map<K,​MuLi> mulitexts

      • catalogs

        protected java.util.Map<java.lang.String,​java.util.Map<java.lang.String,​K>> catalogs

    • Constructor Detail

      • Catalog

        public Catalog​(java.lang.Class<K> keyClass)

    • Method Detail

      • getKey

        @Opt
public K getKey​(java.lang.String lang,
                java.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 java.util.Set<K> getKeys()
        Returns:
        all key objects in an unmodifiable copy. (FIXME could be sorted if comparable =)

      • getKeys

        public java.util.Set<K> getKeys​(java.lang.String name)
        Delivers all key objects for a given name in all languages.

      • getKeys

        public java.util.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 java.util.SortedSet<java.lang.String> readLanguages()
        Delivers the set of all contained languages
        Returns:
        a sorted copy of language keys

      • readLanguagesString

        public java.lang.String readLanguagesString​(java.lang.String sep,
                                            java.lang.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 java.util.Map<java.lang.String,​K> readLanguageMap​(java.lang.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 java.lang.String get​(K key,
                                 java.lang.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,
                          java.lang.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,
                          java.util.List<java.lang.String> pref)
        See Also:
        get(K,String...)

      • translateRobust

        public java.lang.String translateRobust​(K key,
                                        java.util.List<java.lang.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 java.lang.String translateRobust​(K key,
                                        java.lang.String... pref)
        See Also:
        translateRobust(K,List)

      • translateArgsAndFormatRobust

        public java.lang.String translateArgsAndFormatRobust​(K key,
                                                     java.util.List<java.lang.String> pref,
                                                     java.util.List<java.lang.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 java.lang.String translateArgsAndFormatRobust​(K key,
                                                     java.util.List<java.lang.String> pref,
                                                     java.lang.Object... args)
        See Also:
        translateArgsAndFormatRobust(K,List.List)

      • translateKeyAndFormatRobust

        public java.lang.String translateKeyAndFormatRobust​(K key,
                                                    java.util.List<java.lang.String> pref,
                                                    java.util.List<java.lang.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 java.lang.String translateKeyAndFormatRobust​(K key,
                                                    java.util.List<java.lang.String> pref,
                                                    java.lang.Object... args)
        See Also:
        translateKeyAndFormatRobust(K,List,List)

      • translateAllAndFormatRobust

        public java.lang.String translateAllAndFormatRobust​(K key,
                                                    java.util.List<java.lang.String> pref,
                                                    java.util.List<java.lang.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 java.lang.String translateAllAndFormatRobust​(K key,
                                                    java.util.List<java.lang.String> pref,
                                                    java.lang.Object... args)
        See Also:
        translateAllAndFormatRobust(K,List,List)

      • _translateArgs

        protected java.util.List<java.lang.Object> _translateArgs​(java.util.List<java.lang.String> pref,
                                                          java.util.List<java.lang.Object> args)

      • _format

        protected java.lang.String _format​(java.lang.String text,
                                   java.util.List<java.lang.Object> args)

      • _format

        protected java.lang.String _format​(java.lang.String text,
                                   java.lang.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,
                java.util.List<java.lang.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 K INSITU​(K key,
                java.lang.String... variants)

      • insitu

        public java.lang.String insitu​(K key,
                               java.util.List<java.lang.String> langprefs,
                               java.util.List<java.lang.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 java.lang.String insitu​(K key,
                               java.util.List<java.lang.String> langprefs,
                               java.lang.String... pairs)
        See Also:
        insitu(Object,List,List)

      • insitu

        public java.lang.String insitu​(K key,
                               java.util.List<java.lang.String> langprefs,
                               java.util.List<java.lang.String> variants,
                               java.util.List<java.lang.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 java.lang.String insitu​(K key,
                               java.util.List<java.lang.String> langprefs,
                               java.util.List<java.lang.String> variants,
                               java.lang.Object... args)
        See Also:
        insitu(Object,List,List,List)

      • makeMuli

        protected MuLi makeMuli​(K key)

      • makeMap

        protected java.util.Map<java.lang.String,​K> makeMap​(java.lang.String lang)

      • put

        public void put​(K key,
                java.lang.String lang,
                java.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,
                java.lang.String... pairs)
        See Also:
        put(K,List)

      • put

        public void put​(K key,
                java.util.List<java.lang.String> pairs)
        Add one certain key object, and a list of languages and names
        Parameters:
        pairs - sequence of key/value pairs
        Throws:
        java.lang.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,
                   java.lang.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​(java.io.PrintStream s)
        For DEBUGGING: dump Catalog to printstream.
        Parameters:
        s - PrintStream to print to.

      • noTranslate

        public static Catalog.Const noTranslate​(java.lang.String s)