|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.jgoodies.uif.application.ResourceMap
public final class ResourceMap
Adds type conversion, a hierarchy, and variable expansion to ResourceBundles.
Hierarchical ResourceMaps:
ResourceMaps are requested from the Application instance using
ApplicationContext.getResourceMap(Class)
. This method
looks for a class-level, package-level and application-level
ResourceBundle to build a hierarchy of ResourceMaps.
This hierarchy is used for a fallback mechanism during
the ResourceMap resource lookup.
The class-level and package-level ResourceBundles are optional, the application-level bundle is mandatory. The application-level ResourceMap is the parent of all package-level ResourceMaps. A package-level ResourceMap - if any - is the parent of the class-level ResourceMaps for all classes in that package. If the package-level bundle is absent, the application-wide ResourceMap is used as direct parent for the class-level ResourceMap - if any.
For class mypackage.MyClass and Application apppackage.MyApplication the following resource bundles are searched to build ResourceMaps: mypackage.resources.MyClass (optional class-level), mypackage.resources.Package (optional package-level), apppackage.resources.MyApplication (mandatory application-level).
Resource Lookup with Fallback: When looking for a resource, the ResourceMap first uses its own ResourceBundle. In case the resource is missing there, the lookup continues with the ResourceMap's parent ResourceMap. A resource lookup fails, if all ResourceMaps in this path miss the resource.
Type Conversion: General ResourceBundles can localize and return all types. However, the popular PropertyResourceBundle returns only strings. Many client application also need icons, images, fonts, colors, dates, key strokes, formatted messages, etc. This class converts resource bundle strings to frequently used types - if necessary.
Custom Converters:
Custom converters can be registered to convert types, if they are not already
supported. Use ResourceConverters.register(ResourceConverter)
.
Note: The ResourceMap resource lookup stores converted values.
And the current implementation doesn't release these resources.
This is fine for atomic values, but may result in a memory leak,
if a ResourceConverter returns a complex object or object graph
that lives longer than the ResourceMap.
Variable Expansion: String values can contain variables surrounded by "${" and "}", for example "${variable}". All variables are replaced by their associated values before the expanded string is returned or converted.
TODO: Consider converting images to a color and memory format compatible
with the current graphics configuration. See
GraphicsConfiguration#createCompatibleImage
TODO: Consider adding a feature to clear caches per resource map or for all resource maps. This may release memory. This feature requires to keep a list of all resource map instances, so that all caches for all resource maps can be cleared. The ApplicationContext doesn't contain all instance, because ResourceMap can be constructed per constructor.
ApplicationContext.getResourceMap(Class)
,
ResourceBundle
Constructor Summary | |
---|---|
ResourceMap(Class<?> type)
Constructs a resource map for the given class without a parent. |
|
ResourceMap(ResourceMap parent,
Class<?> type)
Constructs a resource map for the given parent and class. |
|
ResourceMap(ResourceMap parent,
ClassLoader classLoader,
String bundleBaseName)
Constructs a resource map for the given class loader and resource bundle base name. |
Method Summary | ||
---|---|---|
boolean |
getBoolean(String key)
Looks up and returns the boolean associated with the given resource key. |
|
ResourceBundle |
getBundle()
Lazily creates and returns this map's underlying resource bundle, or null if there's no associated bundle. |
|
String |
getBundleBaseName()
Returns the base name of this map's underlying resource bundle. |
|
byte |
getByte(String key)
Looks up and returns the byte associated with the given resource key. |
|
Calendar |
getCalendar(String key)
Looks up and returns a Calendar object associated with the given key. |
|
char |
getCharacter(String key)
Looks up and returns the char associated with the given resource key. |
|
ClassLoader |
getClassLoader()
Returns the class loader that is used to load icons, images, and other resources. |
|
Color |
getColor(String key)
Looks up and returns a Color object associated with the given key. |
|
Date |
getDate(String key)
Looks up and returns a Date object associated with the given key. |
|
Dimension |
getDimension(String key)
Looks up and returns a Dimension object associated with the given key. |
|
double |
getDouble(String key)
Looks up and returns the double associated with the given resource key. |
|
File |
getFile(String key)
Looks up and return a File object associated with the given resource key. |
|
float |
getFloat(String key)
Looks up and returns the float associated with the given resource key. |
|
Font |
getFont(String key)
Looks up and returns the Font value for the given resource key. |
|
String |
getFormatted(String key,
Object... args)
Deprecated. This method will be removed from a future UIF version. Use getString(String, Object...) instead. |
|
Icon |
getIcon(String key)
Returns an icon that will be loaded from the URL specified by the property value of the given key. |
|
Image |
getImage(String key)
Returns an image that will be loaded from the URL specified by the property value of the given key. |
|
ImageIcon |
getImageIcon(String key)
Returns an ImageIcon that will be loaded from the URL specified by the property value of the given key. |
|
Insets |
getInsets(String key)
Looks up and returns an Insets object associated with the given key. |
|
int |
getInt(String key)
Looks up and returns the int associated with the given resource key. |
|
KeyStroke |
getKeyStroke(String key)
Looks up and returns the KeyStroke associated with the given key. |
|
long |
getLong(String key)
Looks up and returns the long associated with the given resource key. |
|
MessageFormat |
getMessageFormat(String key)
Looks up and returns the MessageFormat associated with the given key. |
|
|
getObject(String key,
Class<T> type)
Looks up a resource value for the given resource key, converts it if necessary, and returns a value of the specified type . |
|
ResourceMap |
getParent()
Returns this map's parent that is used to look up resources, if a resource is missing in this map's resource bundle. |
|
String |
getResourceParentPath()
Returns the path to this map's resources package. |
|
short |
getShort(String key)
Looks up and returns the short associated with the given resource key. |
|
String |
getString(String key,
Object... args)
Looks up and returns a String associated with the given resource key. |
|
URL |
getURL(String key)
Looks up and returns the URL associated with the given resource key. |
|
String |
resolvePath(String path)
Adds this map's resource parent path, if the given path is relative, and removes the leading slash, if the path is absolute. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public ResourceMap(Class<?> type)
type
- used to load icons, images, and other resources
IllegalArgumentException
- if the class is nullpublic ResourceMap(ResourceMap parent, Class<?> type)
parent
- an optional parent resource map that will be used
if a resource is missing in this maptype
- used to load icons, images, and other resources
IllegalArgumentException
- if the class is nullpublic ResourceMap(ResourceMap parent, ClassLoader classLoader, String bundleBaseName)
parent
- an optional parent resource map that will be used
if a resource is missing in this mapclassLoader
- used to load icons, images, and other resourcesbundleBaseName
- this base name for map's underlying resource bundle
IllegalArgumentException
- if the class loader or bundle base name is nullMethod Detail |
---|
public ResourceMap getParent()
Application's rarely need access to this parent. Instead they lookup a resource and the lookup mechanism will automatically continue to look for a resource in the parent map.
public ClassLoader getClassLoader()
public String getBundleBaseName()
public ResourceBundle getBundle()
null
if there's no associated bundle.
All bundle access must use this method.Also useful for legacy APIs that haven't been designed for ResourceMap's.
null
if there's no associated bundle.public String getResourceParentPath()
public <T> T getObject(String key, Class<T> type)
type
.
If type is a primitive type, the returned value is an instance
of the associated object type.First looks up the value from this map's resource bundle. If no value is found, the lookup continues in this map's parent. If the value found is of the expected return type, it is returned. If it's no String, a ClassCastException is thrown, because the following conversion can convert only strings.
Before the string value is converted, a cache is searched. In case of a cache hit, this cached converted value is returned. Otherwise, a converter will be chosen for the given return type. If no converter can be found, an IllegalArgumentException is thrown. The string value is converted, stored in the cache of converted values, and finally returned.
key
- the resource bundle key to look fortype
- the type used for a conversion - if any - and the return type
MissingResourceException
- if the key is absent in this
map's bundle, as well in all parent map bundles - if any.
ClassCastException
- if the resource value is neither
of the return type, nor a String
IllegalArgumentException
- if the key or type is null,
or if the resource value needs
to be converted but has no associated converter
ResourceConverter.ResourceConversionException
- if the conversion
fails to convert the resource bundle string value to the expected return typepublic boolean getBoolean(String key)
key
- the key in the resource bundle
getObject(String, Class)
public byte getByte(String key)
Byte.valueOf(String)
.
key
- the key in the resource bundle
getObject(String, Class)
public Calendar getCalendar(String key)
MEDIUM
date instance in the English Locale.
If this fails, the converter parses with DateFormat's SHORT
date instance in the English Locale. If both attempts fail,
a ResourceConverter.ResourceConversionException
is thrown.Examples:
application.releaseDate=Dec 31, 2006 # month day, year application.buildDate=12/31/06 # month/day/year
key
- the key in the resource bundle
getObject(String, Class)
,
DateFormat.getDateInstance(int)
public char getCharacter(String key)
key
- the key in the resource bundle
getObject(String, Class)
public Color getColor(String key)
Color.decode(String)
. The decoder converts the string
to an integer and returns the specified opaque Color; it handles
string formats that are used to represent octal and hexadecimal numbers.Examples:
#R,G,B color1=1, 2, 3 #RRGGBB navigation.foreground=#000000 # black navigation.background=#EEF3FA # light blue #R,G,B,A translucent.1=17, 34, 51, 68 #AARRGGBB translucent.2=0x44112233 translucent.3=#44112233
key
- the key in the resource bundle
getObject(String, Class)
public Date getDate(String key)
MEDIUM
date instance in the English Locale.
If this fails, the converter parses with DateFormat's SHORT
date instance in the English Locale. If both attempts fail,
a ResourceConverter.ResourceConversionException
is thrown.Examples:
application.releaseDate=Dec 31, 2006 # month day, year application.buildDate=12/31/06 # month/day/year
key
- the key in the resource bundle
getObject(String, Class)
,
DateFormat.getDateInstance(int)
public Dimension getDimension(String key)
Examples:
mainPanel.size=400, 300 # width=400, height=300 button.minSize=75, 21 # width= 75, height= 21
key
- the key in the resource bundle
getObject(String, Class)
public double getDouble(String key)
Double.valueOf(String)
.
key
- the key in the resource bundle
getObject(String, Class)
public File getFile(String key)
File.File(String)
.
key
- the key in the resource bundle
getObject(String, Class)
public float getFloat(String key)
Float.valueOf(String)
.
key
- the key in the resource bundle
getObject(String, Class)
public Font getFont(String key)
Font.decode(String)
.
key
- the key in the resource bundle
getObject(String, Class)
public Icon getIcon(String key)
The default Icon converter as provided by ResourceConverters
uses Toolkit.getImage(URL)
and converts GIF, JPEG, and PNG.
key
- the resource bundle key for the icon's URL
getObject(String, Class)
public Image getImage(String key)
The default Image converter as provided by ResourceConverters
converts GIF, JPEG, PNG, and all other types supported by the
Java ImageIO API.
key
- the resource bundle key for the image's URL
getObject(String, Class)
public ImageIcon getImageIcon(String key)
The default ImageIcon converter as provided by ResourceConverters
uses Toolkit.getImage(URL)
and converts GIF, JPEG, and PNG.
key
- the resource bundle key for the icon's URL
getObject(String, Class)
public Insets getInsets(String key)
Example:
mainPanel.insets=14, 21, 16, 21 # top, left, bottom, right
key
- the key in the resource bundle
getObject(String, Class)
public int getInt(String key)
Integer.valueOf(String)
.
key
- the key in the resource bundle
getObject(String, Class)
public KeyStroke getKeyStroke(String key)
AWTKeyStroke.getAWTKeyStroke(String)
.Examples:
print.acceleratorKey=CRTL P print.acceleratorKey.mac=meta P
key
- the resource bundle key
getObject(String, Class)
public long getLong(String key)
Long.valueOf(String)
.
key
- the key in the resource bundle
getObject(String, Class)
public MessageFormat getMessageFormat(String key)
MessageFormat.MessageFormat(String)
.
key
- the key in the resource bundle
getObject(String, Class)
@Deprecated public String getFormatted(String key, Object... args)
getString(String, Object...)
instead.
key
- the key in the resource bundleargs
- optional format arguments forwarded to the MessageFormat
getObject(String, Class)
public short getShort(String key)
Short.valueOf(String)
.
key
- the key in the resource bundle
getObject(String, Class)
public String getString(String key, Object... args)
String.format
with the
given arguments.
key
- the key in the resource bundleargs
- optional format arguments forwarded to String#format
getObject(String, Class)
,
String.format(String, Object...)
public URL getURL(String key)
URL.URL(String)
. If that fails, the string is interpreted
as an unresolved absolute or relative resource path. The path
is resolved by adding this map's resource parent path (for relative paths)
or by removing a leading slash '/' (for absolute paths).
Next, it finds resource for this path using
ClassLoader.getResource(String)
and returns its URL.
key
- the key in the resource bundle
getObject(String, Class)
,
ClassLoader.getResource(String)
public String resolvePath(String path)
Useful for getting path information for resource values that are relative to this ResourceMap's path, for example when loading images or icons. Used by some resource converters to resolve relative paths.
path
- a relative or absolute path
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |