org.jdesktop.application
public class ResourceMap extends Object
ResourceMaps are typically obtained with the ApplicationContext
getResourceMap
method
which lazily creates per Application, package, and class ResourceMaps that
are linked together with the ResourceMap parent property.
An individual ResourceMap provides read-only access to all of the resources defined by the ResourceBundles named when the ResourceMap was created as well as all of its parent ResourceMaps. Resources are retrieved with the getObject method which requires both the name of the resource and its expected type. The latter is used to convert strings if neccessary. Converted values are cached. As a convenience, getObject wrapper methods for common GUI types, like getFont, and getColor, are provided.
The getObject method scans raw string resource values for ${resourceName} variable substitutions before performing string conversion. Variables named this way can refer to String resources defined anywhere in their ResourceMap or any parent ResourceMap. The special variable ${null} means that the value of the resource will be null.
ResourceMaps can be used to "inject" resource values into Swing
component properties and into object fields. The
injectComponents method uses Component names (Component.setName(java.lang.String)
) to match resources names with properties. The
injectFields method sets fields that have been tagged with
the @Resource annotation to the value of resources
with the same name.
injectComponents(java.awt.Component)
,
injectFields(java.lang.Object)
,
ResourceConverter
,
ResourceBundle
Modifier and Type | Class and Description |
---|---|
static class |
ResourceMap.InjectFieldException
Unchecked exception thrown by
injectFields(java.lang.Object) when
an error occurs while attempting to set a field (a field that
had been marked with @Resource). |
static class |
ResourceMap.LookupException
Unchecked exception thrown by
getObject(java.lang.String, java.lang.Class) when resource lookup
fails, for example because string conversion fails. |
static class |
ResourceMap.PropertyInjectionException
Unchecked exception thrown by
injectComponent(java.awt.Component) and
injectComponents(java.awt.Component) when a property value specified by
a resource can not be set. |
Modifier and Type | Field and Description |
---|---|
static String |
KEY_PLATFORM |
Constructor and Description |
---|
ResourceMap(ResourceMap parent,
ClassLoader classLoader,
List<String> bundleNames)
Creates a ResourceMap that contains all of the resources
defined in the named
ResourceBundle s as well as
(recursively) the parent ResourceMap. |
ResourceMap(ResourceMap parent,
ClassLoader classLoader,
String... bundleNames)
Just a convenience version of the constructor for the common case
where there's only one bundle name.
|
Modifier and Type | Method and Description |
---|---|
boolean |
containsKey(String key)
Returns true if this resourceMap or its parent (recursively) contains
the specified key.
|
protected boolean |
containsResourceKey(String key)
By default this method is used by
getObject to see
if a resource is defined by this ResourceMap. |
Boolean |
getBoolean(String key)
A convenience method that's shorthand for calling:
getObject(key, Boolean.class).
|
List<String> |
getBundleNames()
Returns the names of the ResourceBundles that define the
resources contained by this ResourceMap.
|
Byte |
getByte(String key)
A convenience method that's shorthand for calling:
getObject(key, Byte.class).
|
ClassLoader |
getClassLoader()
Returns the ClassLoader used to load the ResourceBundles for this
ResourceMap.
|
Color |
getColor(String key)
A convenience method that's shorthand for calling:
getObject(key, Color.class).
|
Double |
getDouble(String key)
A convenience method that's shorthand for calling:
getObject(key, Double.class).
|
Float |
getFloat(String key)
A convenience method that's shorthand for calling:
getObject(key, Float.class).
|
Font |
getFont(String key)
A convenience method that's shorthand for calling:
getObject(key, Font.class).
|
Icon |
getIcon(String key)
A convenience method that's shorthand for calling:
getObject(key, Icon.class).
|
ImageIcon |
getImageIcon(String key)
A convenience method that's shorthand for calling:
getObject(key, ImageIcon.class).
|
Integer |
getInteger(String key)
A convenience method that's shorthand for calling:
getObject(key, Integer.class).
|
Integer |
getKeyCode(String key)
A convenience method that's shorthand for calling:
getKeyStroke(key).getKeyCode().
|
KeyStroke |
getKeyStroke(String key)
A convenience method that's shorthand for calling:
getObject(key, KeyStroke.class).
|
Long |
getLong(String key)
A convenience method that's shorthand for calling:
getObject(key, Long.class).
|
Object |
getObject(String key,
Class type)
Returns the value of the resource named key, or null
if no resource with that name exists.
|
ResourceMap |
getParent()
Returns the parent ResourceMap, or null.
|
org.jdesktop.application.utils.PlatformType |
getPlatform() |
protected Object |
getResource(String key)
By default this method is used by
getObject to look up
resource values in the internal representation of the ResourceBundles named when this ResourceMap was constructed. |
protected Set<String> |
getResourceKeySet()
By default this method is used by
keySet to
get the names of the resources defined in this ResourceMap. |
String |
getResourcesDir()
Returns the resources directory that contains all of the ResourceBundles
in this ResourceMap.
|
Short |
getShort(String key)
A convenience method that's shorthand for calling:
getObject(key, Short.class).
|
String |
getString(String key,
Object... args)
If no arguments are specified, return the String value
of the resource named key.
|
void |
injectComponent(Component target)
Set each property in target to the value of
the resource named componentName.propertyName,
where componentName is the value of the
target component's name property, i.e.
|
void |
injectComponents(Component root)
Applies
injectComponent(java.awt.Component) to each Component in the
hierarchy with root root. |
void |
injectFields(Object target)
Set each field with a @Resource annotation in the target object,
to the value of a resource whose name is the simple name of the target
class followed by "." followed by the name of the field.
|
Set<String> |
keySet()
Return a unmodifiable
Set that contains all of the keys in
this ResourceMap and (recursively) its parent ResourceMaps. |
protected void |
putResource(String key,
Object value)
By default this method is used by
getObject to cache
values that have been retrieved, evaluated (as in ${key}
expressions), and string converted. |
void |
setPlatform(org.jdesktop.application.utils.PlatformType platform) |
public static final String KEY_PLATFORM
public ResourceMap(ResourceMap parent, ClassLoader classLoader, List<String> bundleNames)
ResourceBundle
s as well as
(recursively) the parent ResourceMap. The parent
may be null. Typically just one ResourceBundle is specified
however one might name additional ResourceBundles that contain
platform or Swing look and feel specific resources. When multiple
bundles are named, a resource defined in bundlen will
overide the same resource defined in bundles0..n-1.
In other words bundles named later in the argument list take
precendence over the bundles named earlier.
ResourceBundles are loaded with the specified ClassLoader. If classLoader is null, an IllegalArgumentException is thrown.
At least one bundleName must be specified and all of the bundleNames must be non-empty strings, or an IllegalArgumentException is thrown. The bundles are listed in priority order, highest priority first. In other words, resources in the the first ResourceBundle named first, shadow resources with the same name later in the list.
All of the bundleNames
must share a common package prefix. The package prefix
implicitly specifies the resources directory
(see getResourcesDir()
). For example, the resources
directory for bundle names "myapp.resources.foo" and
"myapp.resources.bar", would be "myapp/resources/". If
bundle names don't share a common package prefix, then
an IllegalArgumentException is thrown.
parent
- parent ResourceMap or nullclassLoader
- the ClassLoader to be used to load the ResourceBundlebundleNames
- names of the ResourceBundle to be loadedIllegalArgumentException
- if classLoader or any bundleName is
null, if no bundleNames are specified, if any bundleName is an
empty (zero length) String, or if all of the bundleNames don't
have a common package prefixResourceBundle
,
getParent()
,
getClassLoader()
,
getResourcesDir()
,
getBundleNames()
public ResourceMap(ResourceMap parent, ClassLoader classLoader, String... bundleNames)
this(parent, classLoader, Arrays.asList(bundleNames))
.parent
- classLoader
- bundleNames
- public ResourceMap getParent()
public List<String> getBundleNames()
public ClassLoader getClassLoader()
public String getResourcesDir()
String filename = myResourceMap.getResourcesDir() + "myIcon.png"; URL url = myResourceMap.getClassLoader().getResource(filename); new ImageIcon(iconURL);
public Set<String> keySet()
Set
that contains all of the keys in
this ResourceMap and (recursively) its parent ResourceMaps.getParent()
public boolean containsKey(String key)
getParent()
,
keySet()
public org.jdesktop.application.utils.PlatformType getPlatform()
public void setPlatform(org.jdesktop.application.utils.PlatformType platform)
protected Set<String> getResourceKeySet()
keySet
to
get the names of the resources defined in this ResourceMap.
This method lazily loads the ResourceBundles named
by the constructor.
The protected getResource
, putResource
, and
containsResourceKey
, getResourceKeySet
abstract
the internal representation of this ResourceMap's list of
ResourceBundles
. Most applications can ignore them.
getResource(java.lang.String)
,
putResource(java.lang.String, java.lang.Object)
,
containsResourceKey(java.lang.String)
protected boolean containsResourceKey(String key)
getObject
to see
if a resource is defined by this ResourceMap. This method lazily
loads the ResourceBundles named by the constructor.
The protected getResource
, putResource
, and
containsResourceKey
, getResourceKeySet
abstract
the internal representation of this ResourceMap's list of
ResourceBundles
. Most applications can ignore them.
If key
is null, an IllegalArgumentException is thrown.
key
- the name of the resourcekey
is defined in this ResourceMapgetResource(java.lang.String)
,
putResource(java.lang.String, java.lang.Object)
,
getResourceKeySet()
protected Object getResource(String key)
getObject
to look up
resource values in the internal representation of the ResourceBundles
named when this ResourceMap was constructed.
If a resource named key
is defined
then its value is returned, otherwise null.
The getResource
method lazily loads the
ResourceBundles named by the constructor.
The protected getResource
, putResource
, and
containsResourceKey
, getResourceKeySet
abstract
the internal representation of this ResourceMap's list of
ResourceBundles
. Most applications can ignore them.
If key
is null, an IllegalArgumentException is thrown.
key
- the name of the resourcekey
(can be null)putResource(java.lang.String, java.lang.Object)
,
containsResourceKey(java.lang.String)
,
getResourceKeySet()
protected void putResource(String key, Object value)
getObject
to cache
values that have been retrieved, evaluated (as in ${key}
expressions), and string converted. A subclass could override
this method to defeat caching or to refine the caching strategy.
The putResource
method lazily loads ResourceBundles.
The protected getResource
, putResource
, and
containsResourceKey
, getResourceKeySet
abstract
the internal representation of this ResourceMap's list of
ResourceBundles
. Most applications can ignore them.
If key
is null, an IllegalArgumentException is thrown.
key
- the name of the resourcevalue
- the value of the resource (can be null)getResource(java.lang.String)
,
containsResourceKey(java.lang.String)
,
getResourceKeySet()
public Object getObject(String key, Class type)
String resources may contain variables that name other resources. Each ${variable-key} variable is replaced with the value of a string resource named variable-key. For example, given the following resources:
Application.title = My Application ErrorDialog.title = Error: ${application.title} WarningDialog.title = Warning: ${application.title}The value of "WarningDialog.title" would be "Warning: My Application". To include "${" in a resource, insert a backslash before the "$". For example, the value of escString in the example below, would be "${hello}":
escString = \\${hello}Note that, in a properties file, the backslash character is used for line continuation, so we've had to escape that too. If the value of a resource is the special variable ${null}, then the resource will be removed from this ResourceMap.
The value returned by getObject will be of the specified type. If a string valued resource exists for key, and type is not String.class, the value will be converted using a ResourceConverter and the ResourceMap entry updated with the converted value.
If the named resource exists and an error occurs during lookup, then a ResourceMap.LookupException is thrown. This can happen if string conversion fails, or if resource parameters can't be evaluated, or if the existing resource is of the wrong type.
An IllegalArgumentException is thrown if key or type are null.
key
- resource nametype
- resource typeResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key or type are nullgetParent()
,
ResourceConverter.forType(java.lang.Class)
,
ResourceMap.LookupException
public String getString(String key, Object... args)
format
string,
which is applied to the arguments if it's non null.
For example, given the following resources
hello = Hello %sthen the value of getString("hello", "World") would be "Hello World".
key
- args
- ResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
,
String.format(String, Object...)
public final Boolean getBoolean(String key)
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final Integer getInteger(String key)
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final Long getLong(String key)
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final Short getShort(String key)
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final Byte getByte(String key)
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final Float getFloat(String key)
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final Double getDouble(String key)
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final Icon getIcon(String key)
getImageIcon(java.lang.String)
for more information.key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final ImageIcon getImageIcon(String key)
If the resource named key is a String, it should name an image file to be found in the resources subdirectory that also contains the ResourceBundle (typically a ".properties" file) that was used to create the corresponding ResourceMap.
For example, given the ResourceMap produced by Application.getClass(com.mypackage.MyClass.class), and a ResourceBundle called MyClass.properties in com.mypackage.resources:
openIcon = myOpenIcon.pngthen resourceMap.getIcon("openIcon") would load the image file called "myOpenIcon.png" from the resources subdirectory, effectively like this:
String filename = myResourceMap.getResourcesDir() + "myOpenIcon.png"; URL url = myResourceMap.getClassLoader().getResource(filename); new ImageIcon(iconURL);
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public final Font getFont(String key)
Font.decode(java.lang.String)
,
face-STYLE-size.
For example:
myFont = Arial-PLAIN-12
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalResourceConverteron
- if key is nullgetObject(java.lang.String, java.lang.Class)
,
ResourceConverter.forType(java.lang.Class)
,
Font.decode(java.lang.String)
public final Color getColor(String key)
myHexRGBColor = #RRGGBB myHexAlphaRGBColor = #AARRGGBB myRGBColor = R, G, B myAlphaRGBColor = R, G, B, AThe first two examples, with the leading "#" encode the color with 3 or 4 hex values and the latter with integer values between 0 and 255. In both cases the value represented by "A" is the color's (optional) alpha channel.
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- ResourceConverter is nullgetObject(java.lang.String, java.lang.Class)
,
ResourceConverter.forType(java.lang.Class)
public final KeyStroke getKeyStroke(String key)
KeyStroke.getKeyStroke(String s)
to convert strings.
For example, pressed F reports the "F" key, and control
pressed F reports Control-F. See the KeyStroke JavaDoc for
more information.key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
,
KeyStroke.getKeyStroke(char)
public Integer getKeyCode(String key)
key
- the name of the resourceResourceMap.LookupException
- if an error occurs during lookup or string conversionIllegalArgumentException
- if key is nullgetObject(java.lang.String, java.lang.Class)
public void injectComponent(Component target)
For example, given a button configured like this:
myButton = new JButton(); myButton.setName("myButton");And a ResourceBundle properties file with the following resources:
myButton.text = Hello World myButton.foreground = 0, 0, 0 myButton.preferredSize = 256, 256Then injectComponent(myButton) would initialize myButton's text, foreground, and preferredSize properties to Hello World, new Color(0,0,0), and new Dimension(256,256) respectively.
This method calls getObject(java.lang.String, java.lang.Class)
to look up resources
and it uses Introspector.getBeanInfo(java.lang.Class>)
to find
the target component's properties.
If target is null an IllegalArgumentException is thrown. If a
resource is found that matches the target component's name but
the corresponding property can't be set, an (unchecked) ResourceMap.PropertyInjectionException
is thrown.
target
- the Component to injectResourceMap.LookupException
- if an error occurs during lookup or string conversionResourceMap.PropertyInjectionException
- if a property specified by a resource can't be setIllegalArgumentException
- if target is nullinjectComponents(java.awt.Component)
,
getObject(java.lang.String, java.lang.Class)
,
ResourceConverter.forType(java.lang.Class)
public void injectComponents(Component root)
injectComponent(java.awt.Component)
to each Component in the
hierarchy with root root.root
- the root of the component hierarchyResourceMap.PropertyInjectionException
- if a property specified by a resource can't be setIllegalArgumentException
- if target is nullinjectComponent(java.awt.Component)
public void injectFields(Object target)
class MyClass { @Resource String sOne; @Resource(key="sTwo") String s2; @Resource int[] numbers = new int[2]; }Given the previous class and the following resource file:
MyClass.sOne = One sTwo = Two MyClass.numbers[0] = 10 MyClass.numbers[1] = 11Then injectFields(new MyClass()) would initialize the MyClass sOne field to "One", the s2 field to "Two", and the two elements of the numbers array to 10 and 11.
If target is null an IllegalArgumentException is thrown. If an error occurs during resource lookup, then an unchecked LookupException is thrown. If a target field marked with @Resource can't be set, then an unchecked InjectFieldException is thrown.
target
- the object whose fields will be initializedResourceMap.LookupException
- if an error occurs during lookup or string conversionResourceMap.InjectFieldException
- if a field can't be setIllegalArgumentException
- if target is nullgetObject(java.lang.String, java.lang.Class)