org.mmbase.util

Class LocalizedString

java.lang.Object

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$

Author:

Michiel Meeuwissen

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
LocalizedString(String k)

Method Summary

Modifier and Type	Method and Description
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