com.jgoodies.uif.application
Class ResourceMap

java.lang.Object
  extended by com.jgoodies.uif.application.ResourceMap

public final class ResourceMap
extends Object

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.

Version:
$Revision: 1.28 $
Author:
Karsten Lentzsch
See Also:
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.
<T> T
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

ResourceMap

public ResourceMap(Class<?> type)
Constructs a resource map for the given class without a parent. Uses the class' class loader for loading icons, images, and other resources. The base name of the associated resource bundle is the class' package + ".resources." + its simple name. For example for class MyPackage.MyClass, the bundle base name is "MyPackage.resources.MyClass". Relative resource paths are resolved using the package portion of the resource bundle base name.

Parameters:
type - used to load icons, images, and other resources
Throws:
IllegalArgumentException - if the class is null

ResourceMap

public ResourceMap(ResourceMap parent,
                   Class<?> type)
Constructs a resource map for the given parent and class. The optional parent resource map is used, if a resource is missing in this map's bundle. Uses the class' class loader for loading icons, images, and other resources. The base name of the associated resource bundle is the class' package + ".resources." + its simple name. For example for class MyPackage.MyClass, the bundle base name is "MyPackage.resources.MyClass". Relative resource paths are resolved using the package portion of the resource bundle base name.

Parameters:
parent - an optional parent resource map that will be used if a resource is missing in this map
type - used to load icons, images, and other resources
Throws:
IllegalArgumentException - if the class is null

ResourceMap

public ResourceMap(ResourceMap parent,
                   ClassLoader classLoader,
                   String bundleBaseName)
Constructs a resource map for the given class loader and resource bundle base name. The resource bundle - if any - will be created lazily. The optional parent resource map is used, if a resource is missing in this map's bundle. The specified class loader is used for loading icons, images, and other resources. Relative resource paths are resolved using the package portion of the resource bundle base name.

Parameters:
parent - an optional parent resource map that will be used if a resource is missing in this map
classLoader - used to load icons, images, and other resources
bundleBaseName - this base name for map's underlying resource bundle
Throws:
IllegalArgumentException - if the class loader or bundle base name is null
Method Detail

getParent

public 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.

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.

Returns:
the map that is used to lookup missing resources from

getClassLoader

public ClassLoader getClassLoader()
Returns the class loader that is used to load icons, images, and other resources.

Returns:
the ClassLoader used to read resources

getBundleBaseName

public String getBundleBaseName()
Returns the base name of this map's underlying resource bundle. The bundle may exist or not.

Returns:
the base name of this map's resource bundle

getBundle

public ResourceBundle getBundle()
Lazily creates and returns this map's underlying resource bundle, or 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.

Returns:
this map's underlying resource bundle or null if there's no associated bundle.

getResourceParentPath

public String getResourceParentPath()
Returns the path to this map's resources package. Used for relative paths when converting and loading icons, images, resource URLs, and other resources.

Returns:
the parent path of relative resources

getObject

public <T> T 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. 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.

Parameters:
key - the resource bundle key to look for
type - the type used for a conversion - if any - and the return type
Returns:
the resource bundle value in converted form - if necessary
Throws:
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 type

getBoolean

public boolean getBoolean(String key)
Looks up and returns the boolean associated with the given resource key. If the resource bundle returns a String, it is converted to boolean. This conversion accepts: true, false, yes, no, on, off ignoring the case.

Parameters:
key - the key in the resource bundle
Returns:
the boolean associated with the given resource key
See Also:
getObject(String, Class)

getByte

public byte getByte(String key)
Looks up and returns the byte associated with the given resource key. If the resource bundle returns a String, it is converted to a Byte. The conversion uses Byte.valueOf(String).

Parameters:
key - the key in the resource bundle
Returns:
the byte associated with the given resource key
See Also:
getObject(String, Class)

getCalendar

public Calendar getCalendar(String key)
Looks up and returns a Calendar object associated with the given key. If the resource bundle returns a String, it is converted to a Calendar. The conversion first parses the string value using DateFormat's 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
 

Parameters:
key - the key in the resource bundle
Returns:
a Calendar value associated with the given resource key
See Also:
getObject(String, Class), DateFormat.getDateInstance(int)

getCharacter

public char getCharacter(String key)
Looks up and returns the char associated with the given resource key. If the resource bundle returns a String, the first character is returned. The conversion fails if the resource String is not of length 1.

Parameters:
key - the key in the resource bundle
Returns:
the char associated with the given resource key, often the first (and only) char of the resource value string
See Also:
getObject(String, Class)

getColor

public Color getColor(String key)
Looks up and returns a Color object associated with the given key. If the resource bundle returns a String, it is converted to a Color using 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
 

Parameters:
key - the key in the resource bundle
Returns:
a Color value associated with the given resource key
See Also:
getObject(String, Class)

getDate

public Date getDate(String key)
Looks up and returns a Date object associated with the given key. If the resource bundle returns a String, it is converted to a Date. The conversion first parses the string value using DateFormat's 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
 

Parameters:
key - the key in the resource bundle
Returns:
a Date value associated with the given resource key
See Also:
getObject(String, Class), DateFormat.getDateInstance(int)

getDimension

public Dimension getDimension(String key)
Looks up and returns a Dimension object associated with the given key. If the resource bundle returns a String, it is converted to a Dimension. The parser expects two strings that represent an integer, separated by a comma.

Examples:

 mainPanel.size=400, 300    # width=400, height=300
 button.minSize=75, 21      # width= 75, height= 21
 

Parameters:
key - the key in the resource bundle
Returns:
a Dimension value associated with the given resource key
See Also:
getObject(String, Class)

getDouble

public double getDouble(String key)
Looks up and returns the double associated with the given resource key. If the resource bundle returns a String, it is converted to a Double. The conversion uses Double.valueOf(String).

Parameters:
key - the key in the resource bundle
Returns:
the double associated with the given resource key
See Also:
getObject(String, Class)

getFile

public File getFile(String key)
Looks up and return a File object associated with the given resource key. If the resource bundle returns a String, it is converted to a File using File.File(String).

Parameters:
key - the key in the resource bundle
Returns:
the File associated with the given resource key
See Also:
getObject(String, Class)

getFloat

public float getFloat(String key)
Looks up and returns the float associated with the given resource key. If the resource bundle returns a String, it is converted to a Float. The conversion uses Float.valueOf(String).

Parameters:
key - the key in the resource bundle
Returns:
the float associated with the given resource key
See Also:
getObject(String, Class)

getFont

public Font getFont(String key)
Looks up and returns the Font value for the given resource key. If the resource bundle returns a String, it is converted to a Font using Font.decode(String).

Parameters:
key - the key in the resource bundle
Returns:
the Font associated with the given resource key
See Also:
getObject(String, Class)

getIcon

public Icon getIcon(String key)
Returns an icon that will be loaded from the URL specified by the property value of the given key. The URL can be absolute, or relative to this ResourceMap's loader type (the type it has been requested for). For example exit.icon=images/exit.png is a relative path, exit.icon=/com/jgoodies/myapp/resources/images/exit.png is an absolute path.

The default Icon converter as provided by ResourceConverters uses Toolkit.getImage(URL) and converts GIF, JPEG, and PNG.

Parameters:
key - the resource bundle key for the icon's URL
Returns:
an Icon loaded from the URL at the key's value
See Also:
getObject(String, Class)

getImage

public Image getImage(String key)
Returns an image that will be loaded from the URL specified by the property value of the given key. The URL can be absolute, or relative to this ResourceMap's loader type (the type it has been requested for). For example bar.image=images/bluebar.jpg is a relative path, bar.image=/com/jgoodies/myapp/resources/images/bluebar.jpg is an absolute path.

The default Image converter as provided by ResourceConverters converts GIF, JPEG, PNG, and all other types supported by the Java ImageIO API.

Parameters:
key - the resource bundle key for the image's URL
Returns:
an Image loaded from the URL at the key's value
See Also:
getObject(String, Class)

getImageIcon

public ImageIcon getImageIcon(String key)
Returns an ImageIcon that will be loaded from the URL specified by the property value of the given key. The URL can be absolute, or relative to this ResourceMap's loader type (the type it has been requested for). For example exit.icon=images/exit.png is a relative path, exit.icon=/com/jgoodies/myapp/resources/images/exit.png is an absolute path.

The default ImageIcon converter as provided by ResourceConverters uses Toolkit.getImage(URL) and converts GIF, JPEG, and PNG.

Parameters:
key - the resource bundle key for the icon's URL
Returns:
an ImageIcon loaded from the URL at the key's value
See Also:
getObject(String, Class)

getInsets

public Insets getInsets(String key)
Looks up and returns an Insets object associated with the given key. If the resource bundle returns a String, it is converted to an Insets object. The parser expects four strings that represent an integer, separated by a comma.

Example:

 mainPanel.insets=14, 21, 16, 21   # top, left, bottom, right
 

Parameters:
key - the key in the resource bundle
Returns:
an Insets value associated with the given resource key
See Also:
getObject(String, Class)

getInt

public int getInt(String key)
Looks up and returns the int associated with the given resource key. If the resource bundle returns a String, it is converted to an Integer. The conversion uses Integer.valueOf(String).

Parameters:
key - the key in the resource bundle
Returns:
the int associated with the given resource key
See Also:
getObject(String, Class)

getKeyStroke

public KeyStroke getKeyStroke(String key)
Looks up and returns the KeyStroke associated with the given key. If the resource bundle returns a String, it is converted to a KeyStroke using AWTKeyStroke.getAWTKeyStroke(String).

Examples:

 print.acceleratorKey=CRTL P
 print.acceleratorKey.mac=meta P
 

Parameters:
key - the resource bundle key
Returns:
the KeyStroke associated with the given resource key
See Also:
getObject(String, Class)

getLong

public long getLong(String key)
Looks up and returns the long associated with the given resource key. If the resource bundle returns a String, it is converted to a Long. The conversion uses Long.valueOf(String).

Parameters:
key - the key in the resource bundle
Returns:
the long associated with the given resource key
See Also:
getObject(String, Class)

getMessageFormat

public MessageFormat getMessageFormat(String key)
Looks up and returns the MessageFormat associated with the given key. If the resource bundle returns a String, it is converted to a MessageFormat. The conversion uses MessageFormat.MessageFormat(String).

Parameters:
key - the key in the resource bundle
Returns:
the MessageFormat associated with the given resource key
See Also:
getObject(String, Class)

getFormatted

@Deprecated
public String getFormatted(String key,
                                      Object... args)
Deprecated. This method will be removed from a future UIF version. Use getString(String, Object...) instead.

Looks up and returns a String or MessageFormat associated with the given resource key. If no arguments are provided, a plain String is returned. Otherwise the resource type is assumed to be a MessageFormat that will then be formatted with the given arguments.

Parameters:
key - the key in the resource bundle
args - optional format arguments forwarded to the MessageFormat
Returns:
the String value found for the given resource key, formatted with the optional arguments - if any
See Also:
getObject(String, Class)

getShort

public short getShort(String key)
Looks up and returns the short associated with the given resource key. If the resource bundle returns a String, it is converted to a Short. The conversion uses Short.valueOf(String).

Parameters:
key - the key in the resource bundle
Returns:
the short associated with the given resource key
See Also:
getObject(String, Class)

getString

public String getString(String key,
                        Object... args)
Looks up and returns a String associated with the given resource key. If no arguments are provided, the plain String is returned. Otherwise the string will be formatted using String.format with the given arguments.

Parameters:
key - the key in the resource bundle
args - optional format arguments forwarded to String#format
Returns:
the String value found for the given resource key, formatted with the optional arguments - if any
See Also:
getObject(String, Class), String.format(String, Object...)

getURL

public URL getURL(String key)
Looks up and returns the URL associated with the given resource key. If the resource bundle returns a String, it is converted to a URL. The conversion first checks whether the string represents a URL using 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.

Parameters:
key - the key in the resource bundle
Returns:
the URL or resource URL associated with the given resource key
See Also:
getObject(String, Class), ClassLoader.getResource(String)

resolvePath

public 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.

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.

Parameters:
path - a relative or absolute path
Returns:
the absolute path


Copyright © 2000-2008 JGoodies Karsten Lentzsch. All Rights Reserved.