org.mmbase.util
Class LocalizedString

java.lang.Object
  extended by org.mmbase.util.LocalizedString
All Implemented Interfaces:
Serializable, Cloneable, PublicCloneable<LocalizedString>
Direct Known Subclasses:
WrappedLocalizedString

public class LocalizedString
extends Object
implements Serializable, PublicCloneable<LocalizedString>

A String which is localized. There are two mechanisms to find and provide translations: They can explicitely be set with set(java.lang.String, java.util.Locale) (e.g. during parsing an XML), or a resource-bundle can be associated with setBundle(java.lang.String), which will be used to find translations based on the key of this object.

The 'set' mechanism can also be driven by fillFromXml(java.lang.String, org.w3c.dom.Element), which provides a sensible way to fill the LocalizedString with setting from a sub element of XMLs.

The idea is that objects of this type can be used in stead of normal String objects, for error messages, descriptions and other texts which need localization (e.g. because they are exposed to end-users).

Since:
MMBase-1.8
Version:
$Id: LocalizedString.java 41036 2010-02-15 22:30:54Z michiel $
Author:
Michiel Meeuwissen
See Also:
Serialized Form

Constructor Summary
LocalizedString(String k)
           
 
Method Summary
 Map<Locale,String> asMap()
          Returns a Map representation of the localisation setting represented by this LocalizedString.
 LocalizedString clone()
           
static List<Locale> degrade(Locale locale)
           
static Locale degrade(Locale locale, Locale originalLocale)
          Degrades a Locale object to a more general Locale.
 boolean equals(Object o)
           
 void fillFromXml(String tagName, Element element)
          Given a certain tagname, and a DOM parent element, it configures this LocalizedString, using subtags with this tagname with 'xml:lang' attributes.
 String get(Locale locale)
          Gets the value for a certain locale.
protected  String getBundle()
           
 String getDebugString()
           
static Locale getDefault()
          Returns the default locale if set, or otherwise the system default (Locale.getDefault()).
 String getKey()
          Gets the key to use as a default and/or for obtaining a value from the bundle
static Locale getLocale(Element element)
          This utility takes care of reading the xml:lang attribute from an element
static Locale getLocale(String xmlLang)
           
 ReadonlyLocalizedString getReadonlyLocalizedString()
           
protected  Map<Locale,String> getValues()
           
static String getXmlLang(Locale locale)
          This utility determines the value of an xml:lang attribute.
 int hashCode()
           
 void set(String value, Locale locale)
          Sets the value for a certain locale.
 void setBundle(String b)
          A resource-bundle with given name can be associated to this LocalizedString.
static Locale setDefault(Locale locale)
          Sets a default locale for this JVM or web-app.
 void setKey(String key)
          Sets the key to use as a default and/or for obtaining a value from the bundle
static void setXmlLang(Element element, Locale locale)
          This utility takes care of setting the xml:lang attribute on an element.
 String toString()
           For LocalizedString this returns the String for the default Locale (see getDefault()).
static Collection<String> toStrings(Collection<LocalizedString> col, Locale locale)
          Converts a collection of localized strings to a collection of normal strings.
 void toXml(String tagName, String ns, Element element, String path)
          Writes this LocalizedString object back to an XML, i.e.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LocalizedString

public LocalizedString(String k)
Parameters:
k - The key of this String, if k == null then the first set will define it.
Method Detail

setDefault

public static Locale setDefault(Locale locale)
Sets a default locale for this JVM or web-app. When not using it, the locale is the system default. Several web-apps do run in one JVM however and it is very imaginable that you want a different default for the Locale.

Returns:
The previously set default locale. Should normally be null since it is odd to call this more than once.

getDefault

public static Locale getDefault()
Returns the default locale if set, or otherwise the system default (Locale.getDefault()).


toStrings

public static Collection<String> toStrings(Collection<LocalizedString> col,
                                           Locale locale)
Converts a collection of localized strings to a collection of normal strings.

Parameters:
col - Collection of LocalizedString objects
locale - Locale to be used for the call to get(Locale) which obviously is needed

getKey

public String getKey()
Gets the key to use as a default and/or for obtaining a value from the bundle


setKey

public void setKey(String key)
Sets the key to use as a default and/or for obtaining a value from the bundle


get

public String get(Locale locale)
Gets the value for a certain locale. If no match is found, it falls back to the key.


set

public void set(String value,
                Locale locale)
Sets the value for a certain locale. If the value for a more general locale is still unset, it will also set that (so, it sets also nl when setting nl_BE if nl still is unset).


asMap

public Map<Locale,String> asMap()
Returns a Map representation of the localisation setting represented by this LocalizedString. It is an unmodifiable mapping: Locale -> localized value.


getValues

protected Map<Locale,String> getValues()

getBundle

protected String getBundle()

setBundle

public void setBundle(String b)
A resource-bundle with given name can be associated to this LocalizedString. If no translations were explicitely added, it can be used to look up the translation in the bundle, using the key.


toString

public String toString()
For LocalizedString this returns the String for the default Locale (see getDefault()).

Overrides:
toString in class Object

getDebugString

public String getDebugString()

getLocale

public static Locale getLocale(Element element)
This utility takes care of reading the xml:lang attribute from an element

Parameters:
element - a DOM element
Returns:
A Locale object, or null if the element did not have, or had an empty, xml:lang attribute

getLocale

public static Locale getLocale(String xmlLang)
Since:
MMBase-1.8.1

degrade

public static Locale degrade(Locale locale,
                             Locale originalLocale)
Degrades a Locale object to a more general Locale. Principally this means that first the 'variant' will be dropped and then the country. As an extra the 'variant' is also degraded progressively. This is done by taking away parts (from the end) which are separated by underscore characters. Also, after degrading the country, also locales are tried with no country, but with a variant only. So e.g. nl_BE_a_b is degraded to nl_BE_a, then nl_BE, then nl__a_b, then nl__a, then nl.

Parameters:
locale - The locale to be degraded
originalLocale - The original locale (used to find back the original variant after dropping the country)
Returns:
A degraded Locale or null if the locale could not be degraded any further.
Since:
MMBase-1.8.5

degrade

public static List<Locale> degrade(Locale locale)
Since:
MMBase-1.9.2

getXmlLang

public static String getXmlLang(Locale locale)
This utility determines the value of an xml:lang attribute. So, given a Locale it produces a String.

Parameters:
locale - A java locale
Returns:
A string that can be used as the value for an XML xml:lang attribute.
Since:
MMBase-1.8.1

setXmlLang

public static void setXmlLang(Element element,
                              Locale locale)
This utility takes care of setting the xml:lang attribute on an element.

Parameters:
element - Element on which the xml:lang attribute is going to be set
locale - Java's Locale object
Since:
MMBase-1.8.1

fillFromXml

public void fillFromXml(String tagName,
                        Element element)
Given a certain tagname, and a DOM parent element, it configures this LocalizedString, using subtags with this tagname with 'xml:lang' attributes. This boils down to repeative calls to set(String, Locale).


toXml

public void toXml(String tagName,
                  String ns,
                  Element element,
                  String path)
Writes this LocalizedString object back to an XML, i.e. it searches for and creates sub-elements (identified by xml:lang attributes) of a certain given parent element, and sets the node-text-value of those elements corresponding to the locale.

Parameters:
tagName - Tag-name of the to be used sub-elements
ns - Namespace of the to be created sub-elements, or null
element - The parent element which must contain the localized elements.
path - A comma separated list of names of tags which must skipped, before appending childs. See DocumentReader.appendChild(Element, Element, String).
Since:
MMBase-1.8.1

clone

public LocalizedString clone()
Specified by:
clone in interface PublicCloneable<LocalizedString>
Overrides:
clone in class Object

equals

public boolean equals(Object o)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

getReadonlyLocalizedString

public ReadonlyLocalizedString getReadonlyLocalizedString()
Since:
MMBase-1.9.2


MMBase 2.0-SNAPSHOT - null