Eclipse Rich Ajax Platform Release 1.3

## org.eclipse.rwt.resources
Interface IResourceManager

public interface IResourceManager

The resource manager is responsible for registering resources like images, css files etc. which are available on the applications classpath. The registered files will be read out from their libraries and delivered if requested. Usually resources are stored in libraries in the WEB-INF/lib directory of a web-application

This interface is not intended to be implemented by clients.

Since:
  1.0

Nested Class Summary
`static class` `IResourceManager.RegisterOptions` An enumeration used to specify additional behavior when registering a resource.

Method Summary
`String` `getCharset(String name)` Returns the charset of a registered resource as it was specified in the call to `register(String,String)` or `register(String,String,ResourceOption)`.
`ClassLoader` `getContextLoader()` Returns the `ClassLoader` that should be used to load or register resources in case that these resources are not available for the RAP context loader.
`String` `getLocation(String name)` Returns a location within the web-applications context where the resource will be available for the browser to download.
`InputStream` `getRegisteredContent(String name)` Returns the content of the registered resource with the given name.
`URL` `getResource(String name)` Finds the resource with the given name.
`InputStream` `getResourceAsStream(String name)` Returns an input stream for reading the specified resource.
`Enumeration` `getResources(String name)` Finds all the resources with the given name.
`boolean` `isRegistered(String name)` Returns whether the resource with the given name has already been registered with this IResourceManager instance.
`void` `register(String name)` Registers a resource which is located on the web-applications classpath.
`void` `register(String name, InputStream is)` Registers a given resource for download with the given name relative to the context root.
`void` `register(String name, InputStream is, String charset, IResourceManager.RegisterOptions options)` Registers a text resource that is encoded with the given `charset` for download with the given name relative to the context root.
`void` `register(String name, String charset)` Registers a text resource which is located on the web-applications classpath and encoded with the given `charset`.
`void` `register(String name, String charset, IResourceManager.RegisterOptions options)` Registers a text resource which is located on the web-applications classpath and encoded with the given `charset`.
`void` `setContextLoader(ClassLoader classLoader)` If resources are not available for the RAP context classloader, it may be necessary to specify a classloader before using one of the `registerXXX` or `getResourceXXX` methods.
`boolean` `unregister(String name)` Unregisters the resource with the given `name`.

Method Detail

### register

    public void register(String name)

  Registers a resource which is located on the web-applications classpath.

  Parameters:
    `name` - filename which identifies the resource to register. The filename must be relative to a classpath root, e.g. a gif 'my.gif' located within the package 'org.eclipse.rap' is identified as 'org/eclipse/rap/my.gif'. Must not be `null`.

### register

    public void register(String name,
                         InputStream is)

  Registers a given resource for download with the given name relative to the context root.

  Parameters:
    `name` - filename that represents the download path relative to the applications context root.
    `is` - the content of the resource to register.

### register

    public void register(String name,
                         String charset)

  Registers a text resource which is located on the web-applications classpath and encoded with the given `charset`.

  Parameters:
    `name` - filename which identifies the resource to register. The filename must be relative to a classpath root, e.g. a gif 'my.gif' located within the package 'org.eclipse.rap' is identified as 'org/eclipse/rap/my.gif'
    `charset` - the name of the charset which was used when the resource was stored.

### register

    public void register(String name,
                         String charset,
                         IResourceManager.RegisterOptions options)

  Registers a text resource which is located on the web-applications classpath and encoded with the given `charset`.

  By specifying an `option` other than `NONE` the resource will be versioned and/or compressed. As compressing is only intended for resources that contain JavaScript, versioning might be useful for other resources as well. When versioning is enabled a version number is appended to the resources' name which is derived from its content.

  Parameters:
    `name` - - filename which identifies the resource to register. The filename must be relative to a classpath root, e.g. a gif 'my.gif' located within the package 'org.eclipse.rap' is identified as 'org/eclipse/rap/my.gif'. Must not be `null`.
    `charset` - - the name of the charset which was used when the resource was stored. Must not be `null`.
    `options` - - an enumeration which specifies whether the resource will be versioned and/or compressed. Must not be `null`.

### register

    public void register(String name,
                         InputStream is,
                         String charset,
                         IResourceManager.RegisterOptions options)

  Registers a text resource that is encoded with the given `charset` for download with the given name relative to the context root.

  By specifying an `option` other than `NONE` the resource will be versioned and/or compressed. As compressing is only intended for resources that contain JavaScript, versioning might be useful for other resources as well. When versioning is enabled a version number is appended to the resources' name which is derived from its content.

  Parameters:
    `name` - filename that represents the download path relative to the applications context root.
    `is` - the content of the resource to register.
    `charset` - - the name of the charset which was used when the resource was stored. Must not be `null`.
    `options` - - an enumeration which specifies whether the resource will be versioned and/or compressed. Must not be `null`.

### unregister

    public boolean unregister(String name)

  Unregisters the resource with the given `name`.

  Parameters:
    `name` - the name that represents the resource. Must not be `null`.
  Returns:
    `true` is returned if unregstering the resource was succesful; `false` otherwise.
  Since:
    1.3

### getCharset

    public String getCharset(String name)

  Returns the charset of a registered resource as it was specified in the call to `register(String,String)` or `register(String,String,ResourceOption)`.

  Parameters:
    `name` - - the name of the resource to obtain the charset from. Must not be `null`.
  Returns:
    the charset name or `null` if none was specified.

### isRegistered

    public boolean isRegistered(String name)

  Returns whether the resource with the given name has already been registered with this IResourceManager instance.

  Parameters:
    `name` - filename which identifies the registered resource. The filename must be relative to a classpath root, e.g. a gif 'my.gif' located within the package 'org.eclipse.rap' is identified as 'org/eclipse/rap/my.gif'. Must not be `null`.
  Returns:
    if the resource is already registered

### getLocation

    public String getLocation(String name)

  Returns a location within the web-applications context where the resource will be available for the browser to download.

  Parameters:
    `name` - filename which identifies the registered resource. The filename must be relative to a classpath root, e.g. a gif 'my.gif' located within the package 'org.eclipse.rap' is identified as 'org/eclipse/rap/my.gif'. Must not be `null`.
  Returns:
    the location where the resource will be available for the browser

### getResource

    public URL getResource(String name)

  Finds the resource with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code.

  Note: This method searchs the classpath of the current web-application and should be used instead of `ClassLoader.getResource(String)` to avoid finding problems on some application servers that use their own classloader implementations.

  Parameters:
    `name` - A '`/`'-separated path name that identifies the resource.
  Returns:
    A `URL` object for reading the resource, or `null` if the resource could not be found or the invoker doesn't have adequate privileges to get the resource.

### getResourceAsStream

    public InputStream getResourceAsStream(String name)

  Returns an input stream for reading the specified resource. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code.

  Note: This method searchs the classpath of the current web-application and should be used instead of `ClassLoader.getResourceAsStream(String)` to avoid finding problems on some application servers that use their own classloader implementations.

  Parameters:
    `name` - A '`/`'-separated path name that identifies the resource.
  Returns:
    An input stream for reading the resource, or `null` if the resource could not be found.

### getResources

    public Enumeration getResources(String name)
                             throws IOException

  Finds all the resources with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code.

  Note: This method searchs the classpath of the current web-application and should be used instead of `ClassLoader.getResources(String)` to avoid finding problems on some application servers that use their own classloader implementations.

  Parameters:
    `name` - A '`/`'-separated path name that identifies the resource.
  Returns:
    An enumeration of ``URL`` objects for the resource. If no resources could be found, the enumeration will be empty. Resources that classloaders doesn't have access to will not be in the enumeration.
  Throws:
    `IOException` - If I/O errors occur

### setContextLoader

    public void setContextLoader(ClassLoader classLoader)

  If resources are not available for the RAP context classloader, it may be necessary to specify a classloader before using one of the `registerXXX` or `getResourceXXX` methods. Note that in case of the `getResourceXXX` methods the calls are simply delegated to the specified classloader.

  Usage:

         IResourceManager manager = W4TContext.getResourceManager();
         ClassLoader contextLoader = ... // retrieve the classloader
         manager.setContextLoader( contextLoader );
         try {
           manager.register( "resources/images/myimage.gif" );
         } finally {
           manager.setContextLoader( null );
         }

  Parameters:
    `classLoader` - the classloader that has access to the resources that should be loaded or registered via this `IResourceManager` or `null` to unset the context loader after usage.

### getContextLoader

    public ClassLoader getContextLoader()

  Returns the `ClassLoader` that should be used to load or register resources in case that these resources are not available for the RAP context loader. May return `null` if no context loader is specified.

  Returns:
    the classloader to use

### getRegisteredContent

    public InputStream getRegisteredContent(String name)

  Returns the content of the registered resource with the given name.

  Parameters:
    `name` - the name of the resource
  Returns:
    an input stream to the contents of the resource, or `null` if no such resource exists
  Since:
    1.1

Eclipse Rich Ajax Platform Release 1.3

Copyright (c) Innoopract Informationssysteme GmbH and others 2002, 2011. All rights reserved.