Package org.jdesktop.application

# Class ResourceManager

java.lang.Object
org.jdesktop.application.AbstractBean
org.jdesktop.application.ResourceManager

public class ResourceManager extends AbstractBean
The application's `ResourceManager` provides read-only cached access to resources in `ResourceBundles` via the `ResourceMap` class. `ResourceManager` is a property of the `ApplicationContext` and most applications look up resources relative to it, like this:

     ApplicationContext appContext = Application.getInstance().getContext();
     ResourceMap resourceMap = appContext.getResourceMap(MyClass.class);
     String msg = resourceMap.getString("msg");
     Icon icon = resourceMap.getIcon("icon");
     Color color = resourceMap.getColor("color");

`ApplicationContext.getResourceMap()` just delegates to its `ResourceManager`. The `ResourceMap` in this example contains resources from the ResourceBundle named `MyClass`, and the rest of the chain contains resources shared by the entire application.

Resources for a class are defined by an eponymous `ResourceBundle` in a `resources` subpackage. It is possible to change name of the subpackage or even use resources from the class's package.

     public class MyApp extends SingleFrameApplication {
       public MyApp() {
           getContext().getResourceManager().setResourceFolder("myresourcessubpackage");
       }
    }

The Application class itself may also provide resources. A complete description of the naming conventions for ResourceBundles is provided by the `getResourceMap()` method.

The mapping from classes and `Application` to a list ResourceBundle names is handled by two protected methods: `getClassBundleNames`, `getApplicationBundleNames`. Subclasses could override these methods to append additional ResourceBundle names to the default lists.

Author:
  Hans Muller (Hans.Muller@Sun.COM)
See Also:
  - `ApplicationContext.getResourceManager()`
  - `ApplicationContext.getResourceMap(java.lang.Class)`
  - `ResourceMap`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`ResourceManager(ApplicationContext context)`
Construct a `ResourceManager`.

## Method Summary

Modifier and Type
Method
Description
`protected ResourceMap`
`createResourceMap(ClassLoader classLoader, ResourceMap parent, List<String> bundleNames)`
Called by `getResourceMap(java.lang.Class, java.lang.Class)` to construct `ResourceMaps`.
`List<String>`
`getApplicationBundleNames()`
The names of the ResourceBundles to be shared by the entire application.
`protected List<String>`
`getClassBundleNames(Class cls)`
Map from a class to a list of the names of the `ResourceBundles` specific to the class.
`protected final ApplicationContext`
`getContext()`
`PlatformType`
`getPlatform()`
The value of the special Application ResourceMap resource named "platform".
`String`
`getResourceFolder()`
Returns resources subpackage name
`ResourceMap`
`getResourceMap()`
Returns the chain of ResourceMaps that's shared by the entire application, beginning with the resources defined for the application's class, i.e.
`final ResourceMap`
`getResourceMap(Class cls)`
Return the ResourcedMap chain for the specified class.
`ResourceMap`
`getResourceMap(Class startClass, Class stopClass)`
Returns a `chain` of `ResourceMaps` that encapsulate the `ResourceBundles` for each class from `startClass` to (including) `stopClass`.
`void`
`setApplicationBundleNames(List<String> bundleNames)`
Specify the names of the ResourceBundles to be shared by the entire application.
`void`
`setPlatform(PlatformType platform)`
Defines the value of the special Application ResourceMap resource named "platform".
`void`
`setResourceFolder(String resourceFolder)`
Sets resources subpackage name.

### Methods inherited from class org.jdesktop.application.AbstractBean

`addPropertyChangeListener, addPropertyChangeListener, firePropertyChange, firePropertyChange, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### ResourceManager

protected ResourceManager(ApplicationContext context)
Construct a `ResourceManager`. Typically applications will not create a ResourceManager directly, they'll retrieve the shared one from the `ApplicationContext` with:

     Application.getInstance().getContext().getResourceManager()

Or just look up `ResourceMaps` with the ApplicationContext convenience method:

     Application.getInstance().getContext().getResourceMap(MyClass.class)

FIXME - @param javadoc

Parameters:
  `context` -
See Also:
  - `ApplicationContext.getResourceManager()`
  - `ApplicationContext.getResourceMap(java.lang.Class)`

## Method Details

### getContext

protected final ApplicationContext getContext()

### getResourceMap

public ResourceMap getResourceMap(Class startClass, Class stopClass)
Returns a `chain` of `ResourceMaps` that encapsulate the `ResourceBundles` for each class from `startClass` to (including) `stopClass`. The final link in the chain is Application ResourceMap chain, i.e. the value of `getResourceMap()`.

The ResourceBundle names for the chain of ResourceMaps are defined by `getClassBundleNames(java.lang.Class)` and `getApplicationBundleNames()`. Collectively they define the standard location for `ResourceBundles` for a particular class as the `resources` subpackage. For example, the ResourceBundle for the single class `com.myco.MyScreen`, would be named `com.myco.resources.MyScreen`. Typical ResourceBundles are ".properties" files, so: `com/foo/bar/resources/MyScreen.properties`. The following table is a list of the ResourceMaps and their constituent ResourceBundles for the same example:

ResourceMap chain for class MyScreen in MyApp
| ResourceMap | ResourceBundle names | Typical ResourceBundle files
--- | --- | --- | ---
1 | class: com.myco.MyScreen | com.myco.resources.MyScreen | com/myco/resources/MyScreen.properties
2 | application: com.myco.MyApp | com.myco.resources.MyApp | com/myco/resources/MyApp.properties
3 | application: javax.swing.application.Application | javax.swing.application.resources.Application | javax.swing.application.resources.Application.properties

Note that inner classes are searched for by "simple" name - eg, for a class MyApp$InnerClass, the resource bundle must be named InnerClass.properties. See the notes on `classBundleBaseName`

None of the ResourceBundles are required to exist. If more than one ResourceBundle contains a resource with the same name then the one earlier in the list has precedence

ResourceMaps are constructed lazily and cached. One ResourceMap is constructed for each sequence of classes in the same package. Name of the resources subpackage can be customized with `setResourcesFolder()` method.

Parameters:
  `startClass` - the first class whose ResourceBundles will be included
  `stopClass` - the last class whose ResourceBundles will be included
Returns:
  a `ResourceMap` chain that contains resources loaded from `ResourceBundles` found in the resources subpackage for each class.
See Also:
  - `getClassBundleNames(java.lang.Class)`
  - `getApplicationBundleNames()`
  - `ResourceMap.getParent()`
  - `ResourceMap.getBundleNames()`

### getResourceMap

public final ResourceMap getResourceMap(Class cls)
Return the ResourcedMap chain for the specified class. This is just a convenince method, it's the same as: `getResourceMap(cls, cls)`.

Parameters:
  `cls` - the class that defines the location of ResourceBundles
Returns:
  a `ResourceMap` that contains resources loaded from `ResourceBundles` found in the resources subpackage of the specified class's package.
See Also:
  - `getResourceMap(Class, Class)`

### getResourceMap

public ResourceMap getResourceMap()
Returns the chain of ResourceMaps that's shared by the entire application, beginning with the resources defined for the application's class, i.e. the value of the ApplicationContext `applicationClass` property. If the `applicationClass` property has not been set, e.g. because the application has not been `launched` yet, then a ResourceMap for just `Application.class` is returned.

Returns:
  the Application's ResourceMap
See Also:
  - `ApplicationContext.getResourceMap()`
  - `ApplicationContext.getApplicationClass()`

### getApplicationBundleNames

public List<String> getApplicationBundleNames()
The names of the ResourceBundles to be shared by the entire application. The list is in priority order: resources defined by the first ResourceBundle shadow resources with the the same name that come later.

The default value for this property is a list of `per-class` ResourceBundle names, beginning with the `Application's` class and of each of its superclasses, up to `Application.class`. For example, if the Application's class was `com.foo.bar.MyApp`, and MyApp was a subclass of `SingleFrameApplication.class`, then the ResourceBundle names would be: ``

1. com.foo.bar.resources.MyApp
2. javax.swing.application.resources.SingleFrameApplication
3. javax.swing.application.resources.Application

The default value of this property is computed lazily and cached. If it's reset, then all ResourceMaps cached by `getResourceMap` will be updated.

Returns:
  names of the ResourceBundles
See Also:
  - `setApplicationBundleNames(java.util.List<java.lang.String>)`
  - `getResourceMap(java.lang.Class, java.lang.Class)`
  - `getClassBundleNames(java.lang.Class)`
  - `ApplicationContext.getApplication()`

### setApplicationBundleNames

public void setApplicationBundleNames(List<String> bundleNames)
Specify the names of the ResourceBundles to be shared by the entire application. More information about the property is provided by the `getApplicationBundleNames()` method.

Parameters:
  `bundleNames` -
See Also:
  - `setApplicationBundleNames(java.util.List<java.lang.String>)`

### getClassBundleNames

protected List<String> getClassBundleNames(Class cls)
Map from a class to a list of the names of the `ResourceBundles` specific to the class. The list is in priority order: resources defined by the first ResourceBundle shadow resources with the the same name that come later.

By default this method returns one ResourceBundle whose name is the same as the class's name, but in the `"resources"` subpackage.

For example, given a class named `com.foo.bar.MyClass`, the ResourceBundle name would be `"com.foo.bar.resources.MyClass"`. If MyClass is an inner class, only its "simple name" is used. For example, given an inner class named `com.foo.bar.OuterClass$InnerClass`, the ResourceBundle name would be `"com.foo.bar.resources.InnerClass"`.

This method is used by the `getResourceMap` methods to compute the list of ResourceBundle names for a new `ResourceMap`. ResourceManager subclasses can override this method to add additional class-specific ResourceBundle names to the list.

Parameters:
  `cls` - the named ResourceBundles are specific to `cls`.
Returns:
  the names of the ResourceBundles to be loaded for `cls`
See Also:
  - `getResourceMap(java.lang.Class, java.lang.Class)`
  - `getApplicationBundleNames()`

### createResourceMap

protected ResourceMap createResourceMap(ClassLoader classLoader, ResourceMap parent, List<String> bundleNames)
Called by `getResourceMap(java.lang.Class, java.lang.Class)` to construct `ResourceMaps`. By default this method is effectively just:

     return new ResourceMap(parent, classLoader, bundleNames);

Custom ResourceManagers might override this method to construct their own ResourceMap subclasses.

Parameters:
  `classLoader` - the ClassLoader to be used to load the ResourceBundle
  `parent` - parent ResourceMap or null
  `bundleNames` - names of the ResourceBundle to be loaded
Returns:
  a new resource map

### getPlatform

public PlatformType getPlatform()
The value of the special Application ResourceMap resource named "platform".

Returns:
  the value of the platform resource
See Also:
  - `setPlatform(org.jdesktop.application.utils.PlatformType)`

### setPlatform

public void setPlatform(PlatformType platform)
Defines the value of the special Application ResourceMap resource named "platform". This resource can be used to define platform specific resources. For example:

     myLabel.text.osx = A value that's appropriate for OSX
     myLabel.text.default = A value for other platforms
     myLabel.text = myLabel.text.${platform}

By default the value of this resource is "osx" if the underlying operating environment is Apple OSX or "default". To distinguish other platforms one can reset this property based on the value of the `"os.name"` system property.

This method should be called as early as possible, typically in the Application `initialize` method.

Parameters:
  `platform` -
See Also:
  - `getPlatform()`
  - `System.getProperty(java.lang.String)`

### getResourceFolder

public String getResourceFolder()
Returns resources subpackage name

Returns:
  resource folder name

### setResourceFolder

public void setResourceFolder(String resourceFolder)
Sets resources subpackage name. If resourceFolder is `null` or empty no subpackage is used.

Parameters:
  `resourceFolder` - resources subpackage name