Package eu.bandm.tools.muli

Class MuLi

java.lang.Object
eu.bandm.tools.muli.MuLi
public final class MuLi extends Object
Each MuLi represents a multi-lingual identifier or text. Its structure is 
 language ::= (String U syntheticLanguage)  
 MuLi ::= language -/-> String
SYNTHETIC_LANGUAGE is a special string value reserved for the cases in which a language differetiation is not applicable (e.g. for pure numeric strings or personal names).
The language values should follow the (older) ISO two-character language codes, as specified in ISO 639-2. These are the codes also used by "xml:lang", cf. RFC 4646 / RFC 4647 / IETF BCP 47.

At least they should not have the value of the SYNTHETIC_LANGUAGE string.

The look-up function getSpecific(String) delegates to a map object and has the usual java-like semantics, esp. returning null iff the argument is not in the domain.
Further, there is a special look-up function get(String...) of type 

 get : preference:(SEQ language)->MuLi.TextFound
with 
 
    MuLi.TextFound ::= (index:(NAT U{-1}) * language:String * result:String
The object of class MuLi.TextFound, as returned by the function, reflects the most left language in the original preference list for which an entry can be found in the MuLi object.
An index of =-1 indicated the fact that the found language is chosen by random and was not in the list of preferred languages.

ATTENTION
"language" parameters are currently encoded as "totally free" string values.
(1) A linkage to the "locale" mechanisms of java is not yet defined.
(2) A hash storage for all "language" strings (converting them to unique single objects) could be sensible, but has to be decided in connection with (1).

  • Field Details

    • SYNTHETIC_LANGUAGE

      public static final String SYNTHETIC_LANGUAGE
      Use this as key value for put and get in cases where no natural language is applicable. E.g. for technical notions, personal names, formulae.
      See Also:

    • texts

      protected Map<String,String> texts
      Map from the target languages to their text versions.

  • Constructor Details

    • MuLi

      public MuLi()
      Construct an empty instance.

    • MuLi

      public MuLi(Map<String,String> data)
      Initialize translations, Keys if the map must be language codes, the values the translations.
      Parameters:
      data - the initial translations

  • Method Details

    • getVersionValue

      public static String getVersionValue()
      Get the version of this class (and thus this package), as defined by the Maven publishing framework.
      Returns:
      the version of this class.

    • cloneUnmodifiable

      public MuLi cloneUnmodifiable()
      Returns an unmodifiable copy.
      Returns:
      an unmodifiable copy.

    • toString

      public String toString()
      Return a string representation.
      Overrides:
      toString in class Object
      Returns:
      a string representation. currently using java.util.Map default conversion.

    • getLanguages

      public Set<String> getLanguages()
      Returns an unmodifiable copy of all languages serving as keys.
      Returns:
      an unmodifiable copy of all languages serving as keys.

    • getSpecific

      @Opt public @Opt String getSpecific(String lang)
      Return the string stored under a particular key. This key represents the language of the requested naming. Is directly mapped to java.util.Map, i.e. returns null if the key is not in the map. In contrast to other get methods, no fall-back mechanisms take place.
      Parameters:
      lang - the language for which the translation is searched.
      Returns:
      the string stored for the given language.

    • containsLang

      public boolean containsLang(String lang)
      Return whether there is an entry in the given language. Equivalency holds: containsLang(l) == (getSpecific(l) != null).
      Parameters:
      lang - the language.
      Returns:
      whether there is an entry in the given language.

    • get

      @Opt public @Opt MuLi.TextFound get(String... preference)
      Return a MuLi.TextFound object representing the first string found when trying the listed languages from left to right. If no such translation is found, return an arbitrary one. If no translation exists, return null.
      Parameters:
      preference - list of languages to search.
      Returns:
      a MuLi.TextFound object representing the first string found.

    • get

      @Opt public @Opt MuLi.TextFound get(List<String> preference)
      Return a MuLi.TextFound object representing the first string found when trying the listed languages from left to right.
      See Also:

    • put

      public MuLi put(String lang, String text)
      Put a new key/value pair into the internal map. Existing entries will silently be overwritten.
      Parameters:
      lang - the key, should be a language code.
      text - the value, i.e. the translation into this language.
      Returns:
      this for method chaining.

    • put

      public MuLi put(Map<String,String> data)
      Put a multitude of key/value pairs into the internal map. The mapentries are separated into key and value, and passed to put(String,String).
      So, existing entries will silently be overwritten.
      Parameters:
      data - map of language to name
      Returns:
      this for method chaining.

    • put

      @Deprecated(forRemoval=true) public MuLi put(String... pairs)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use "put( Collections.literalMap(Object,Object))" instead!
      Put a multitude of key/value pairs into the internal map. The number of arguments must be even. The arguments are intepreted as key and value, alternatingly, and passed to put(String,String).
      So, existing entries will silently be overwritten.
      Parameters:
      pairs - sequence of key/value pairs
      Returns:
      this for method chaining.
      Throws:
      IllegalArgumentException - in case the number of Strings in not even.

    • put

      @Deprecated(forRemoval=false) public MuLi put(List<String> pairs)
      Deprecated.
      use "put(Collections.literalMap(Object,Object))" instead!
      Returns:
      this for method chaining.
      See Also: