ResourceManager (Nenya Core 1.6.1 API)

java.lang.Object
- com.threerings.resource.ResourceManager

```
public class ResourceManager
extends Object
```
The resource manager is responsible for maintaining a repository of resources that are synchronized with a remote source. This is accomplished in the form of sets of jar files (resource bundles) that contain resources and that are updated from a remote resource repository via HTTP. These resource bundles are organized into resource sets. A resource set contains one or more resource bundles and is defined much like a classpath.
The resource manager can load resources from the default resource set, and can make available named resource sets to entities that wish to do their own resource loading. If the resource manager fails to locate a resource in the default resource set, it falls back to loading the resource via the classloader (which will search the classpath).
Applications that wish to make use of resource sets and their associated bundles must call initBundles(java.lang.String, java.lang.String, com.threerings.resource.ResourceManager.InitObserver) after constructing the resource manager, providing the path to a resource definition file which describes these resource sets. The definition file will be loaded and the resource bundles defined within will be loaded relative to the resource directory. The bundles will be cached in the user's home directory and only reloaded when the source resources have been updated. The resource definition file looks something like the following:
```
 resource.set.default = sets/misc/config.jar: \
                        sets/misc/icons.jar
 resource.set.tiles = sets/tiles/ground.jar: \
                      sets/tiles/objects.jar: \
                      /global/resources/tiles/ground.jar: \
                      /global/resources/tiles/objects.jar
 resource.set.sounds = sets/sounds/sfx.jar: \
                       sets/sounds/music.jar: \
                       /global/resources/sounds/sfx.jar: \
                       /global/resources/sounds/music.jar
 
```
All resource set definitions are prefixed with resource.set. and all text following that string is considered to be the name of the resource set. The resource set named default is the default resource set and is the one that is searched for resources is a call to getResource(String).
When a resource is loaded from a resource set, the set is searched in the order that entries are specified in the definition.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ResourceManager.AWTInitObserver` An adapter that wraps an `ResourceManager.InitObserver` and routes all method invocations to the AWT thread.
`static interface`	`ResourceManager.InitObserver` Provides facilities for notifying an observer of the resource unpacking process.
`static interface`	`ResourceManager.LocaleHandler` Transforms a regular resource path into a locale-specific path.
`static interface`	`ResourceManager.ModificationObserver` Notifies observers of modifications to resources (as indicated by a change to their `File.lastModified()` property).

Constructor Summary

Constructors
Constructor and Description
`ResourceManager(String resourceRoot)` Constructs a resource manager which will load resources via the classloader, prepending `resourceRoot` to their path.
`ResourceManager(String resourceRoot, ClassLoader loader)` Creates a resource manager with the specified class loader via which to load classes.
`ResourceManager(String resourceRoot, String networkResourceRoot)` Creates a resource manager with a root path to resources over the network.
`ResourceManager(String fileResourceRoot, String networkResourceRoot, ClassLoader loader)` Creates a resource manager with a root path to resources over the network and the specified class loader via which to load classes.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`activateResourceProtocol()` Registers a protocol handler with URL to handle `resource:` URLs.
`void`	`addModificationObserver(String path, ResourceManager.ModificationObserver obs)` Adds a modification observer for the specified resource.
`boolean`	`checkBundle(String path)` Checks to see if the specified bundle exists, is unpacked and is ready to be used.
`void`	`checkForModifications()` Checks all observed resources for changes to their `File.lastModified()` properties, notifying their listeners if the files have been modified since the last call to this method.
`ClassLoader`	`getClassLoader()` Returns the class loader being used to load resources if/when there are no resource bundles from which to load them.
`BufferedImage`	`getImageResource(String path)` Fetches and decodes the specified resource into a `BufferedImage`.
`BufferedImage`	`getImageResource(String rset, String path)` Fetches and decodes the specified resource into a `BufferedImage`.
`InputStream`	`getResource(String path)` Fetches a resource from the local repository.
`InputStream`	`getResource(String rset, String path)` Returns an input stream from which the requested resource can be loaded.
`File`	`getResourceFile(String path)` Given a path relative to the resource directory, the path is properly jimmied (assuming we always use /) and combined with the resource directory to yield a `File` object that can be used to access the resource.
`HashSet<String>`	`getResourceList()` If we have a full list of the resources available, we return it.
`String`	`getResourcePath(File file)` Given a file within the resource directory, returns a resource path that can be passed to `getResourceFile(java.lang.String)` to locate the resource.
`ResourceBundle[]`	`getResourceSet(String name)` Returns a reference to the resource set with the specified name, or null if no set exists with that name.
`void`	`initBundles(String resourceDir, String configPath, ResourceManager.InitObserver initObs)` Initializes the bundle sets to be made available by this resource manager.
`void`	`initResourceDir(String resourceDir)` (Re)initializes the directory to search for resource files.
`static BufferedImage`	`loadImage(InputStream iis, boolean useFastIO)` Loads an image from the given input stream.
`void`	`removeModificationObserver(String path, ResourceManager.ModificationObserver obs)` Removes a modification observer from the list maintained for the specified resource.
`void`	`resolveBundle(String path, ResultListener<FileResourceBundle> listener)` Resolve the specified bundle (the bundle file must already exist in the appropriate place on the file system) and return it on the specified result listener.
`void`	`setClassLoader(ClassLoader loader)` Configures the class loader this manager should use to load resources if/when there are no bundles from which to load them.
`void`	`setLocaleHandler(ResourceManager.LocaleHandler localeHandler)` Configure a custom LocaleHandler.
`void`	`setLocalePrefix(String prefix)` Configure a default LocaleHandler with the specified prefix.
`void`	`setUnpackResources(boolean unpackResources)` Configures whether we unpack our resource bundles or not.

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

- Constructor Detail
  - ResourceManager
```
public ResourceManager(String resourceRoot)
```
    Constructs a resource manager which will load resources via the classloader, prepending resourceRoot to their path.
    
    Parameters:
    
    resourceRoot - the path to prepend to resource paths prior to attempting to load them via the classloader. When resources are bundled into the default resource bundle, they don't need this prefix, but if they're to be loaded from the classpath, it's likely that they'll live in some sort of resources directory to isolate them from the rest of the files in the classpath. This is not a platform dependent path (forward slash is always used to separate path elements).
  - ResourceManager
```
public ResourceManager(String resourceRoot,
                       ClassLoader loader)
```
    Creates a resource manager with the specified class loader via which to load classes. See ResourceManager(String) for further documentation.
  - ResourceManager
```
public ResourceManager(String resourceRoot,
                       String networkResourceRoot)
```
    Creates a resource manager with a root path to resources over the network. See ResourceManager(String) for further documentation.
  - ResourceManager
```
public ResourceManager(String fileResourceRoot,
                       String networkResourceRoot,
                       ClassLoader loader)
```
    Creates a resource manager with a root path to resources over the network and the specified class loader via which to load classes. See ResourceManager(String) for further documentation.
- Method Detail
  - activateResourceProtocol
```
public void activateResourceProtocol()
```
    Registers a protocol handler with URL to handle resource: URLs. The URLs take the form:
```
resource://bundle_name/resource_path
```
    Resources from the default bundle can be loaded via:
```
resource:///resource_path
```
  - setLocalePrefix
```
public void setLocalePrefix(String prefix)
```
    Configure a default LocaleHandler with the specified prefix.
  - setLocaleHandler
```
public void setLocaleHandler(ResourceManager.LocaleHandler localeHandler)
```
    Configure a custom LocaleHandler.
  - setUnpackResources
```
public void setUnpackResources(boolean unpackResources)
```
    Configures whether we unpack our resource bundles or not. This must be called before initBundles(java.lang.String, java.lang.String, com.threerings.resource.ResourceManager.InitObserver). One can also pass the -Dno_unpack_resources=true system property to disable resource unpacking.
  - initBundles
```
public void initBundles(String resourceDir,
                        String configPath,
                        ResourceManager.InitObserver initObs)
                 throws IOException
```
    Initializes the bundle sets to be made available by this resource manager. Applications that wish to make use of resource bundles should call this method after constructing the resource manager.
    
    Parameters:
    
    resourceDir - the base directory to which the paths in the supplied configuration file are relative. If this is null, the system property resource_dir will be used, if available.
    
    configPath - the path (relative to the resource dir) of the resource definition file.
    
    initObs - a bundle initialization observer to notify of unpacking progress and success or failure, or null if the caller doesn't care to be informed; note that in the latter case, the calling thread will block until bundle unpacking is complete.
    
    Throws:
    
    IOException - thrown if we are unable to read our resource manager configuration.
  - initResourceDir
```
public void initResourceDir(String resourceDir)
```
    (Re)initializes the directory to search for resource files.
    
    Parameters:
    
    resourceDir - the directory path, or null to set the resource dir to the value of the resource_dir system property.
  - getResourceFile
```
public File getResourceFile(String path)
```
    Given a path relative to the resource directory, the path is properly jimmied (assuming we always use /) and combined with the resource directory to yield a File object that can be used to access the resource.
    
    Returns:
    
    a file referencing the specified resource or null if the resource manager was never configured with a resource directory.
  - getResourcePath
```
public String getResourcePath(File file)
```
    Given a file within the resource directory, returns a resource path that can be passed to getResourceFile(java.lang.String) to locate the resource.
    
    Returns:
    
    a path referencing the specified resource or null if either the resource manager was never configured with a resource directory or the file is not contained within the resource directory.
  - checkBundle
```
public boolean checkBundle(String path)
```
    Checks to see if the specified bundle exists, is unpacked and is ready to be used.
  - resolveBundle
```
public void resolveBundle(String path,
                          ResultListener<FileResourceBundle> listener)
```
    Resolve the specified bundle (the bundle file must already exist in the appropriate place on the file system) and return it on the specified result listener. Note that the result listener may be notified before this method returns on the caller's thread if the bundle is already resolved, or it may be notified on a brand new thread if the bundle requires unpacking.
  - getClassLoader
```
public ClassLoader getClassLoader()
```
    Returns the class loader being used to load resources if/when there are no resource bundles from which to load them.
  - setClassLoader
```
public void setClassLoader(ClassLoader loader)
```
    Configures the class loader this manager should use to load resources if/when there are no bundles from which to load them.
  - getResource
```
public InputStream getResource(String path)
                        throws IOException
```
    Fetches a resource from the local repository.
    
    Parameters:
    
    path - the path to the resource (ie. "config/miso.properties"). This should not begin with a slash.
    
    Throws:
    
    IOException - thrown if a problem occurs locating or reading the resource.
  - getImageResource
```
public BufferedImage getImageResource(String path)
                               throws IOException
```
    Fetches and decodes the specified resource into a BufferedImage.
    
    Throws:
    
    FileNotFoundException - thrown if the resource could not be located in any of the bundles in the specified set, or if the specified set does not exist.
    
    IOException - thrown if a problem occurs locating or reading the resource.
  - getResource
```
public InputStream getResource(String rset,
                               String path)
                        throws IOException
```
    Returns an input stream from which the requested resource can be loaded. Note: this performs a linear search of all of the bundles in the set and returns the first resource found with the specified path, thus it is not extremely efficient and will behave unexpectedly if you use the same paths in different resource bundles.
    
    Throws:
    
    FileNotFoundException - thrown if the resource could not be located in any of the bundles in the specified set, or if the specified set does not exist.
    
    IOException - thrown if a problem occurs locating or reading the resource.
  - getImageResource
```
public BufferedImage getImageResource(String rset,
                                      String path)
                               throws IOException
```
    Fetches and decodes the specified resource into a BufferedImage.
    
    Throws:
    
    FileNotFoundException - thrown if the resource could not be located in any of the bundles in the specified set, or if the specified set does not exist.
    
    IOException - thrown if a problem occurs locating or reading the resource.
  - getResourceSet
```
public ResourceBundle[] getResourceSet(String name)
```
    Returns a reference to the resource set with the specified name, or null if no set exists with that name. Services that wish to load their own resources can allow the resource manager to load up a resource set for them, from which they can easily load their resources.
  - addModificationObserver
```
public void addModificationObserver(String path,
                                    ResourceManager.ModificationObserver obs)
```
    Adds a modification observer for the specified resource. Note that only a weak reference to the observer will be retained, and thus this will not prevent the observer from being garbage-collected.
  - removeModificationObserver
```
public void removeModificationObserver(String path,
                                       ResourceManager.ModificationObserver obs)
```
    Removes a modification observer from the list maintained for the specified resource.
  - checkForModifications
```
public void checkForModifications()
```
    Checks all observed resources for changes to their File.lastModified() properties, notifying their listeners if the files have been modified since the last call to this method.
  - getResourceList
```
public HashSet<String> getResourceList()
```
    If we have a full list of the resources available, we return it. A return value of null means that we do not know what's available and we'll have to try all possibilities. This is fine for most applications.
  - loadImage
```
public static BufferedImage loadImage(InputStream iis,
                                      boolean useFastIO)
                               throws IOException
```
    Loads an image from the given input stream. Supports formats supported by ImageIO as well as FastImageIO based on the useFastIO param.
    
    Throws:
    
    IOException

Class ResourceManager

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ResourceManager

ResourceManager

ResourceManager

ResourceManager

Method Detail

activateResourceProtocol

setLocalePrefix

setLocaleHandler

setUnpackResources

initBundles

initResourceDir

getResourceFile

getResourcePath

checkBundle

resolveBundle

getClassLoader

setClassLoader

getResource

getImageResource

getResource

getImageResource

getResourceSet

addModificationObserver

removeModificationObserver

checkForModifications

getResourceList

loadImage