org.pentaho.platform.api.engine
Interface IPluginResourceLoader

All Known Implementing Classes:
PluginResourceLoader

public interface IPluginResourceLoader

This class presents an abstraction layer for accessing resources from within a platform plugin. The idea is you do not need to know how to absolutely resolve the resources you need. For example: You don't need to know the absolute path if your resources are on a file-system. All you need to know in order to obtain a resource is the relative path to the resource. "Relative" means relative to the base location of your plugin. For a filesystem example, let's say that your plugin is installed in "/home/user/plugins/myplugin" and you need the file "/home/user/plugins/myplugin/html/my.html", you would ask this class for the resource "html/my.html"

Author:
aphillips

Method Summary
 List<URL> findResources(Class<?> pluginClass, String namePattern)
          A searching method, yielding a list of plugin-related resources as URLs.
 List<URL> findResources(ClassLoader classLoader, String namePattern)
           
 String getPluginSetting(Class<?> pluginClass, String key)
          Searches for the plugin setting with the specified key.
 String getPluginSetting(Class<?> pluginClass, String key, String defaultValue)
          Searches for the plugin setting with the specified key.
 String getPluginSetting(ClassLoader pluginClassLoader, String key, String defaultValue)
          Searches for the plugin setting with the specified key.
 byte[] getResourceAsBytes(Class<? extends Object> pluginClass, String resourcePath)
          Gets a plugin-related resource in the form of an array of bytes.
 InputStream getResourceAsStream(Class<?> pluginClass, String resourcePath)
          Gets a plugin-related resource in the form of an InputStream.
 InputStream getResourceAsStream(ClassLoader classLoader, String resourcePath)
          Gets a plugin-related resource in the form of an InputStream.
 String getResourceAsString(Class<? extends Object> pluginClass, String resourcePath)
          Gets a plugin-related resource in the form of a String.
 String getResourceAsString(Class<? extends Object> pluginClass, String resourcePath, String charsetName)
          Gets a plugin-related resource in the form of a String.
 ResourceBundle getResourceBundle(Class<?> pluginClass, String baseName)
          Retrieves a localized resource bundle for the plugin represented by pluginClass.
 

Method Detail

getResourceAsBytes

byte[] getResourceAsBytes(Class<? extends Object> pluginClass,
                          String resourcePath)
Gets a plugin-related resource in the form of an array of bytes. The relevant plugin is inferred from pluginClass. An example of resource path is "resources/html/my.html". IPluginResourceLoader is able to resolve relative paths as it knows where to look for plugin classes and resources.

Parameters:
pluginClass - a class that is part of the plugin package, used to identify the plugin
resourcePath - the (relative) path to a resource
Returns:
a resource as an array of bytes or null if the resource is not found

getResourceAsString

String getResourceAsString(Class<? extends Object> pluginClass,
                           String resourcePath)
                           throws UnsupportedEncodingException
Gets a plugin-related resource in the form of a String. The relevant plugin is inferred from pluginClass. An example of resource path is "resources/html/my.html". IPluginResourceLoader is able to resolve relative paths as it knows where to look for plugin classes and resources.

This method defaults the character encoding (how this default is chosen is up to the implementor).

Parameters:
pluginClass - a class that is part of the plugin package, used to identify the plugin
resourcePath - the (relative) path to a resource
Returns:
a resource as a String or null if the resource is not found
Throws:
UnsupportedEncodingException - if there is a problem encoding the string

getResourceAsString

String getResourceAsString(Class<? extends Object> pluginClass,
                           String resourcePath,
                           String charsetName)
                           throws UnsupportedEncodingException
Gets a plugin-related resource in the form of a String. The relevant plugin is inferred from pluginClass. An example of resource path is "resources/html/my.html". IPluginResourceLoader is able to resolve relative paths as it knows where to look for plugin classes and resources.

Parameters:
pluginClass - a class that is part of the plugin package, used to identify the plugin
resourcePath - the (relative) path to a resource
charsetName - the character set to encode the string
Returns:
a resource as a String or null if the resource is not found
Throws:
UnsupportedEncodingException - if there is a problem encoding the string

getResourceAsStream

InputStream getResourceAsStream(Class<?> pluginClass,
                                String resourcePath)
Gets a plugin-related resource in the form of an InputStream. The relevant plugin is inferred from pluginClass. An example of resource path is "resources/html/my.html". IPluginResourceLoader is able to resolve relative paths as it knows where to look for plugin classes and resources.

Parameters:
pluginClass - a class that is part of the plugin package, used to identify the plugin
resourcePath - the (relative) path to a resource
Returns:
a resource as an InputStream or null if the resource is not found

getResourceAsStream

InputStream getResourceAsStream(ClassLoader classLoader,
                                String resourcePath)
Gets a plugin-related resource in the form of an InputStream. An example of resource path is "resources/html/my.html". IPluginResourceLoader is able to resolve relative paths as it knows where to look for plugin classes and resources.

Parameters:
classLoader - the ClassLoader which was used to load a plugin
resourcePath - the (relative) path to a resource
Returns:
a resource as an InputStream or null if the resource is not found

findResources

List<URL> findResources(Class<?> pluginClass,
                        String namePattern)
A searching method, yielding a list of plugin-related resources as URLs. This method allows advanced searching by using the namePattern argument. namePattern supports '?' and '*' characters, representing single and multiple wildcard characters respectively.

Parameters:
pluginClass -
namePattern - a resource name pattern supporting wildcards
Returns:
a list of URLs to the matching resources or empty list if none are found

findResources

List<URL> findResources(ClassLoader classLoader,
                        String namePattern)
See Also:
findResources(Class, String)

getResourceBundle

ResourceBundle getResourceBundle(Class<?> pluginClass,
                                 String baseName)
Retrieves a localized resource bundle for the plugin represented by pluginClass. baseName is a fully qualified package name or relative path to a bundle name. For example, a baseName of "resources.messages" might represent: Implementations of getResourceBundle(Class, String) should behave similar to ResourceBundle.getBundle(String)

Parameters:
pluginClass - a class that is part of the plugin package, used to identify the plugin
baseName - points to a particular resource bundle
Returns:
a ResourceBundle
Throws:
MissingResourceException - if resource bundle not found
See Also:
ResourceBundle

getPluginSetting

String getPluginSetting(Class<?> pluginClass,
                        String key)
Searches for the plugin setting with the specified key. The method returns null if the setting is not found.

Parameters:
pluginClass - a class that is part of the plugin package, used to identify the plugin
key - the setting key
Returns:
the plugin setting value or null if setting not found

getPluginSetting

String getPluginSetting(Class<?> pluginClass,
                        String key,
                        String defaultValue)
Searches for the plugin setting with the specified key.

Parameters:
pluginClass - a class that is part of the plugin package, used to identify the plugin
key - the setting key
defaultValue - the value to return if no value is found for the setting key
Returns:
the plugin setting value or defaultValue if setting not found

getPluginSetting

String getPluginSetting(ClassLoader pluginClassLoader,
                        String key,
                        String defaultValue)
Searches for the plugin setting with the specified key.

Parameters:
pluginClassLoader - the classloader that was used to load the plugin, must be a PluginClassLoader
key - the setting key
defaultValue - the value to return if no value is found for the setting key
Returns:
the plugin setting value or defaultValue if setting not found