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