MetaBundle

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Ableverse™
Platform 6.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

av.meta
Class MetaBundle

java.lang.Object
  av.meta.MetaBundle

public final class MetaBundle
extends Object
extends Object

MetaBundles are used to read internationalized meta information from XML resources.

Meta bundles are named entities. Meta bundle names are case-sensitive and they follow the hierarchical naming rule:

Named Hierarchy

A meta bundle is said to be an ancestor of another meta bundle if its name followed by a dot is a prefix of the descendant meta bundle name. A meta bundle is said to be a parent of a child meta bundle if there are no ancestors between itself and the descendant meta bundle.

Each meta bundle has its own name, which by convention is the same as name of the associated java package or class, if used to supply meta data to that package or class.

And meta bundles with no package or class associated are also possible, they can be used to centralize configuration options, and organize these options in the named hierarchy so that options of the same xpath in an ancestor bundle can serve as the fail-safe defaults for descendant bundles. This also enables many descendant bundles share the common options in a common ancestor bundle, while they just write minimum overrides to reflect minor differences.

Note there is one and only one meta bundle is special in name, that's the bundle associated with the java default package. For less confusing of file names in this bundle, this special meta bundle is named default.

The meta bundle named default is the parent bundle of all bundles without any dot(.) in name.

And the default bundle has no parent bundle.

So there the default bundle and only the default bundle whose getParent() will return null.

The static get() series of methods (get(String), get(Class), get(Package)) will give you meta bundles from the Default Repository.

And each meta bundle is made up of a set of XML files, including a default file with no locale, and additional files one per language*country*variant for fully specialized locales at most. And XML files with only language or only language+country are also possible. These files resident in the same path, and have a common name as the main part for their file name. The file with no locale is named simply by appending the repository's File Extension (".meta" for the Default Repository) to their common path name. And a file with a locale will have the locale's meta id inserted between the common name and the File Extension as its name. A locale's meta id is calculated by localeMetaID(Locale). More specifically, take the Default Repository as an example, given a meta bundle named String bundleName, for a Locale locale, its XML file will have the path name:

bundleName.replace('.', '/') + localeMetaID(locale) + ".meta"

Here if locale == null, it refers to no locale, for which localeMetaID(Locale) will return an empty string such that fulfills the above naming convention.

Default XML Resource: The XML resource without a localeMetaID is called the Default XML Resource.

Localized XML Resource: The XML resource with a localeMetaID is called a Localized XML Resource.

All these XML files should be loadable by the MetaLoader configured for a MetaRepository when given the pathname calculated as above.

The inside structure of these files can be arbitrary XML content as long as Well-Formed. The root node name of these XML files is recommended be java by convention.

And comments are strongly encouraged inside these XML fils to explain how information there will be read and used by your program.

Meta information stored inside these XML files can be retrived via XPath expressions, by invoking the getXXX(String xpath,Locale l) and getXXXArray(String xpath,Locale l) series methods of this class. And for convenience, these methods also try automatically convert the evaluated text strings to various data presented in java types.

The getXXX(String xpath,Locale l) series methods are used to retrieve the first node or attribute value matching xpath, while the getXXXArray(String xpath,Locale l) series are used to retrieve all matching values as an array.

The locale parameter is to specify which locale you want to lookup, if null, it will use current system's default locale. And the xpath parameter is to specify the location to lookup. MetaBundle will always set the root node of an XML file as the current node to resolve relative xpathes. It is highly recommended you always use relative xpathes to lookup meta information, for the name of the root node is not strictly enforced. For the full syntax and usage information about XPath, please consult the standard published by w3c XML Path Language and standard java xml package javax.xml.xpath. Ableverse Meta Facility just use the standard XPath instances created by XPathFactory to evaluate values from underlying XML files.

By default meta bundles are automatically arranged only in the named hierarchy, other pathes (such as the bundle associated with super java class) will not be searched up. But there are times we just need it to do searches up java inheritance pather or others, Ableverse Meta Facility was designed very flexible that to support these styles. That is Super Bundles. There are two types of Super Bundle: Near Super Bundle and Far Super Bundle, which are managed by

addNearSuperBundle(MetaBundle)
removeNearSuperBundle(MetaBundle)
addFarSuperBundle(MetaBundle)
removeFarSuperBundle(MetaBundle)

But notice that Super Bundle changes have global effects, so make pretty sure that's what you want before write code modifies them.

While retrieving values, the searching algorithm through various meta bundles is:

1. The root meta in current bundle, which fully matches the specified locale.

2. The root meta in current bundle, more generally matches the locale (locales without Locale.getVariant(), then without Locale.getCountry() constrains)
3. The root meta in current bundle, no locale (without even the Locale.getLanguage() constrain). If the specified locale does NOT have variant, country or language constrain, according root metas in 1 and 2 will be skipped.
4. For any near super bundles, repeat 1 to 3.
5. For this bundle's parent bundle (if not null, so would keep looking until the default bundle), repeat 1 to 3.
6. For any far super bundles, repeat 1 to 3.

The first found matching value will be returned, untill no one matches at end of the searching path, then it will throw a MetaNotFoundException, whose stack trace will print all searched locations.

After all, meta bundles from the Default Repository manage meta inforamtion stored in XML files with ".meta" name extention. While the Ableverse Meta Facility was designed to be generally reusable that can be configured to manage XML files in other name extentions. They can be used to present different kind of information, and from various source of storages. Can be loaded from anywhere with a MetaLoader implementation providing the accessibility. One example is the av.msg package, who uses ".msg.xml" name extention to present i18n message text. To leverage the meta facility to create your own meta infomation infrastructure, make an appropriate MetaLoader instance and construct a MetaRepostory instance with it, then the MetaRepository.get() series (MetaRepository.get(String), MetaRepository.get(Class), MetaRepository.get(Package) methods will give you meta bundles.

The configuration mechanism for logging support from Ableverse Message Facility is a live example of leveraging Ableverse Meta Facility for hierarchical configuration.

And the Ableverse Message Facility as a whole is a more comprehensive example of automaticly authoring and serving i18n data in java programs leveraging Ableverse Meta Facility.

Author:: Compl

Field Summary
`static String`	`DEFAULT_FILE_EXT_NAME` The default file name extention: ".meta"
`static MetaRepository`	`defaultRepository` The default repository used to get MetaBundles statically, loads XML resources with `".meta"` extension from the class path through a `ClassPathLoader`.

Method Summary
`void`	`addFarSuperBundle(MetaBundle superBundle)` Add a meta bundle to this bundle's far super meta bundle list.
`void`	`addNearSuperBundle(MetaBundle superBundle)` Add a meta bundle to this bundle's near super meta bundle list.
`static MetaBundle`	`get()` Get the meta bundle with the same qualified name of the calling class.
`static MetaBundle`	`get(Class<?> klass)` Get the meta bundle with the same qualified name of `klass`.
`static MetaBundle`	`get(Package pkg)` Get the meta bundle with the same qualified name of `pkg`.
`static MetaBundle`	`get(String name)` Get the meta bundle with name `name`
`Meta[]`	`getAllMetaArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`Meta[]`	`getAllMetaArray(String xpath, Locale l)`
`String[]`	`getAllStringArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`String[]`	`getAllStringArray(String xpath, Locale l)`
`boolean`	`getBoolean(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`boolean`	`getBoolean(String xpath, Locale l)`
`boolean[]`	`getBooleanArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`boolean[]`	`getBooleanArray(String xpath, Locale l)`
`static Locale`	`getContextLocale()` Get the context locale associated with current `Thread`.
`static Locale`	`getContextLocale(Locale ifNotSet)` Get the context locale associated with current `Thread`.
`Date`	`getDate(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`Date`	`getDate(String xpath, Locale l)`
`Date[]`	`getDateArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`Date[]`	`getDateArray(String xpath, Locale l)`
`double`	`getDouble(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`double`	`getDouble(String xpath, Locale l)`
`double[]`	`getDoubleArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`double[]`	`getDoubleArray(String xpath, Locale l)`
`float`	`getFloat(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`float`	`getFloat(String xpath, Locale l)`
`float[]`	`getFloatArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`float[]`	`getFloatArray(String xpath, Locale l)`
`int`	`getInteger(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`int`	`getInteger(String xpath, Locale l)`
`int[]`	`getIntegerArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`int[]`	`getIntegerArray(String xpath, Locale l)`
`long`	`getLong(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`long`	`getLong(String xpath, Locale l)`
`long[]`	`getLongArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`long[]`	`getLongArray(String xpath, Locale l)`
`Meta`	`getMeta(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`Meta`	`getMeta(String xpath, Locale l)`
`Meta[]`	`getMetaArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`Meta[]`	`getMetaArray(String xpath, Locale l)`
`String`	`getName()` Get this meta bundle's name.
`MetaBundle`	`getParent()` Get the parent bundle of this one.
`Meta`	`getRootMeta()` Return the root `Meta` for the context locale.
`Meta`	`getRootMeta(Locale l)` Return the root `Meta` for the specified locale.
`short`	`getShort(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`short`	`getShort(String xpath, Locale l)`
`short[]`	`getShortArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`short[]`	`getShortArray(String xpath, Locale l)`
`String`	`getString(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`String`	`getString(String xpath, Locale l)`
`String[]`	`getStringArray(String xpath)` Get value with the context locale previously specified for current `Thread` with `setContextLocale(Locale)`.
`String[]`	`getStringArray(String xpath, Locale l)`
`protected void`	`listMetas(String xpath, Locale l, Collection<Meta> submetas)`
`protected void`	`listStrings(String xpath, Locale l, Collection<String> strings)`
`static String`	`localeMetaID(Locale l)` This method reads the language, country and variant value from the Locale parameter, and concatenate them with a underscore character(_) prefixed to each part if that part presents (not a null or empty string).
`void`	`reload()` Clear this bundle's cache so that subsequent lookups will read fresh infromation from the XML file set.
`void`	`removeFarSuperBundle(MetaBundle superBundle)` Remove a meta bundle from this bundle's far super meta bundle list.
`void`	`removeNearSuperBundle(MetaBundle superBundle)` Remove a meta bundle from this bundle's near super meta bundle list.
`static void`	`setContextLocale(Locale locale)` Set the context locale, associate it with current `Thread`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

DEFAULT_FILE_EXT_NAME

public static final String DEFAULT_FILE_EXT_NAME

The default file name extention: ".meta"

See Also:: Constant Field Values

defaultRepository

public static final MetaRepository defaultRepository

The default repository used to get MetaBundles statically, loads XML resources with ".meta" extension from the class path through a ClassPathLoader.

Method Detail

localeMetaID

public static String localeMetaID(Locale l)

This method reads the language, country and variant value from the Locale parameter, and concatenate them with a underscore character(_) prefixed to each part if that part presents (not a null or empty string).

For example, Locale.CHINA's meta id is: "_zh_CN", while Locale.CHINESE's is "_zh".

Parameters:: l - the locale to calculate its meta id
Returns:: calculated meta id of l

get

public static MetaBundle get(Class<?> klass)

Get the meta bundle with the same qualified name of klass.

Parameters:: klass - any class
Returns:: the meta bundle with same name of klass

get

public static MetaBundle get(Package pkg)

Get the meta bundle with the same qualified name of pkg.

Parameters:: pkg - any package
Returns:: the meta bundle with same name of pkg

get

public static MetaBundle get(String name)

Get the meta bundle with name name

Parameters:: name - name of the target meta bundle
Returns:: the meta bundle with name name

get

public static MetaBundle get()

Get the meta bundle with the same qualified name of the calling class.

Note this relies on the Throwable.getStackTrace() to determine which class is invoking this method. It is perfectly supported by modern HotSpot™ Java™ Virtual Machines, but not so luckly with legacy JIT JVMs. Programs using this method will malfunction in such legacy JVMs.

Returns:: the meta bundle with the same name of the calling class

getContextLocale

public static Locale getContextLocale(Locale ifNotSet)

Get the context locale associated with current Thread. It is used by methods without explicit locale specified.

If no locale has been set for current thread, ifNotSet will be returned.

Returns:: the thread context locale

getContextLocale

public static Locale getContextLocale()

Get the context locale associated with current Thread. It is used by methods without explicit locale specified.

If no locale has been set for current thread, Locale.getDefault() will be returned.

Returns:: the thread context locale

setContextLocale

public static void setContextLocale(Locale locale)

Set the context locale, associate it with current Thread. It is used by methods without explicit locale specified.

Parameters:: locale - the new locale to be set as thread context locale

addFarSuperBundle

public void addFarSuperBundle(MetaBundle superBundle)

Add a meta bundle to this bundle's far super meta bundle list. If superMeta has already in this bundle's far super meta bundle list, it does nothing.

The far super meta bundles will be looked up in the order they were added after specified xpath is not found in this bundle and all its near super bundles and parent bundles

Parameters:: superBundle - the meta bundle to be added as this bundle's far super bundle

removeFarSuperBundle

public void removeFarSuperBundle(MetaBundle superBundle)

Remove a meta bundle from this bundle's far super meta bundle list. If superMeta is not in this bundle's far super meta bundle list, it does nothing.

The far super meta bundles will be looked up in the order they were added after specified xpath is not found in this bundle and all its near super bundles and parent bundles

Parameters:: superBundle - the meta bundle to be added as this bundle's far super bundle

addNearSuperBundle

public void addNearSuperBundle(MetaBundle superBundle)

Add a meta bundle to this bundle's near super meta bundle list. If superMeta has already in this bundle's near super meta list, it does nothing.

The near super meta bundles will be looked up in the order they were added immediately after specified xpath is not found in this bundle.

Parameters:: superBundle -

removeNearSuperBundle

public void removeNearSuperBundle(MetaBundle superBundle)

Remove a meta bundle from this bundle's near super meta bundle list. If superMeta is not in this bundle's near super meta list, it does nothing.

The near super meta bundles will be looked up in the order they were added immediately after specified xpath is not found in this bundle.

Parameters:: superBundle -

reload

public void reload()

Clear this bundle's cache so that subsequent lookups will read fresh infromation from the XML file set.

This is useful to refresh the meta information without restart the running program.

getRootMeta

public Meta getRootMeta(Locale l)

Return the root Meta for the specified locale.

A root meta is one Meta instance bound to the particular XML file of the specified locale. If such an XML file doesn't exist, then the returned meta will be a place holder meta, which means it only pass lookups forward to its parent meta. If there exists such an XML file according to Locale l, a meta bound to that XML file will be returned, and that meta will set the root node of that XML file as the current node, which will serve as the start point of resolving relative xpathes.

Parameters:: l - a locale, null to get the default root meta with no locale
Returns:: the root meta inside this bundle for Locale l

getRootMeta

public Meta getRootMeta()

Return the root Meta for the context locale.

getName

public String getName()

Get this meta bundle's name.

Returns:: this meta bundle's name

getParent

public MetaBundle getParent()

Get the parent bundle of this one.

Given a bundle with at least one dot(.) character in name, then its name with the last dot(.) character and all after trailing characters removed identifies its parent bundle.

Whereas the meta bundle named default is the parent bundle of all bundles without any dot(.) in name.

And the default bundle has no parent bundle.

So there the default bundle and only the default bundle whose getParent() will return null.

Returns:: the parent meta bundle of this one

getString

public String getString(String xpath,
                        Locale l)
                 throws MetaNotFoundException

Throws:: MetaNotFoundException

getStringArray

public String[] getStringArray(String xpath,
                               Locale l)
                        throws MetaNotFoundException

Throws:: MetaNotFoundException

listStrings

protected void listStrings(String xpath,
                           Locale l,
                           Collection<String> strings)
                    throws MetaNotFoundException

Throws:: MetaNotFoundException

getAllStringArray

public String[] getAllStringArray(String xpath,
                                  Locale l)
                           throws MetaNotFoundException

Throws:: MetaNotFoundException

getDate

public Date getDate(String xpath,
                    Locale l)
             throws MetaNotFoundException

Throws:: MetaNotFoundException

getDateArray

public Date[] getDateArray(String xpath,
                           Locale l)
                    throws MetaNotFoundException

Throws:: MetaNotFoundException

getShort

public short getShort(String xpath,
                      Locale l)
               throws MetaNotFoundException

Throws:: MetaNotFoundException

getShortArray

public short[] getShortArray(String xpath,
                             Locale l)
                      throws MetaNotFoundException

Throws:: MetaNotFoundException

getInteger

public int getInteger(String xpath,
                      Locale l)
               throws MetaNotFoundException

Throws:: MetaNotFoundException

getIntegerArray

public int[] getIntegerArray(String xpath,
                             Locale l)
                      throws MetaNotFoundException

Throws:: MetaNotFoundException

getLong

public long getLong(String xpath,
                    Locale l)
             throws MetaNotFoundException

Throws:: MetaNotFoundException

getLongArray

public long[] getLongArray(String xpath,
                           Locale l)
                    throws MetaNotFoundException

Throws:: MetaNotFoundException

getBoolean

public boolean getBoolean(String xpath,
                          Locale l)
                   throws MetaNotFoundException

Throws:: MetaNotFoundException

getBooleanArray

public boolean[] getBooleanArray(String xpath,
                                 Locale l)
                          throws MetaNotFoundException

Throws:: MetaNotFoundException

getFloat

public float getFloat(String xpath,
                      Locale l)
               throws MetaNotFoundException

Throws:: MetaNotFoundException

getFloatArray

public float[] getFloatArray(String xpath,
                             Locale l)
                      throws MetaNotFoundException

Throws:: MetaNotFoundException

getDouble

public double getDouble(String xpath,
                        Locale l)
                 throws MetaNotFoundException

Throws:: MetaNotFoundException

getDoubleArray

public double[] getDoubleArray(String xpath,
                               Locale l)
                        throws MetaNotFoundException

Throws:: MetaNotFoundException

getMeta

public Meta getMeta(String xpath,
                    Locale l)
             throws MetaNotFoundException

Throws:: MetaNotFoundException

getMetaArray

public Meta[] getMetaArray(String xpath,
                           Locale l)
                    throws MetaNotFoundException

Throws:: MetaNotFoundException

listMetas

protected void listMetas(String xpath,
                         Locale l,
                         Collection<Meta> submetas)
                  throws MetaNotFoundException

Throws:: MetaNotFoundException

getAllMetaArray

public Meta[] getAllMetaArray(String xpath,
                              Locale l)
                       throws MetaNotFoundException

Throws:: MetaNotFoundException