net.jini.config

Class ConfigurationProvider

java.lang.Object

net.jini.config.ConfigurationProvider

public class ConfigurationProvider
extends Object

Provides a standard means for obtaining Configuration instances, using a configurable provider. This class cannot be instantiated. The configuration provider can be specified by providing a resource named "META-INF/services/net.jini.config.Configuration" containing the name of the provider class. If multiple resources with that name are available, then the one used will be the last one returned by ClassLoader.getResources. If the resource is not found, the ConfigurationFile class is used.

Downloaded code can specify its own class loader in a call to getInstance(String[], ClassLoader) in order to use the configuration provider specified in the JAR file from which it was downloaded.

The provider class must be a public, non-abstract class that implements Configuration, and has a public constructor that has String[] and ClassLoader parameters. The String[] parameter supplies provider-specific options, for example specifying a source location or values for particular entries. The constructor should throw ConfigurationNotFoundException if the configuration specified by the String[] options argument cannot be found, or if null was specified for the options argument and the class does not provide defaults. The constructor should use the class loader argument when loading resources and classes, and should interpret a null class loader argument as signifying the context class loader.

The resource file should contain the fully qualified name of the provider class. Space and tab characters surrounding each name, as well as blank lines, are ignored. The comment character is '#' (0x23); on each line, all characters following the first comment character are ignored. The resource file must be encoded in UTF-8.

Since:

2.0

Author:

Sun Microsystems, Inc.

Implementation Specifics:

This implementation uses the Logger named net.jini.config to log information at the following logging levels:

net.jini.config

Level	Description
FAILED	problems getting a configuration

Method Summary

Modifier and Type	Method and Description
static Configuration	getInstance(String[] options) Creates and returns an instance of the configuration provider, using the specified options.
static Configuration	getInstance(String[] options, ClassLoader cl) Creates and returns an instance of the configuration provider, using the specified options and class loader.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static Configuration getInstance(String[] options)
                                 throws ConfigurationException

Creates and returns an instance of the configuration provider, using the specified options. Specifying null for options uses provider-specific default options, if available. Uses the current thread's context class loader to load resources and classes, and supplies null as the class loader to the provider constructor.

Parameters:

options - values to use when constructing the configuration, or null if default options should be used

Returns:

an instance of the configuration provider constructed with the specified options and null for the class loader

Throws:

ConfigurationNotFoundException - if options specifies a source location that cannot be found, or if options is null and the provider does not supply default options

ConfigurationException - if an I/O exception occurs; if there are problems with the options argument or the format of the contents of any source location it specifies; if there is a problem with the contents of the resource file that names the configuration provider; if the configured provider class does not exist, is not public, is abstract, does not implement Configuration, or does not have a public constructor that has String[] and ClassLoader parameters; if the calling thread does not have permission to obtain information from the specified source; or if the provider does not have permission to access the context class loader. Any Error thrown while creating the provider instance is propagated to the caller; it is not wrapped in a ConfigurationException.

getInstance

public static Configuration getInstance(String[] options,
                                        ClassLoader cl)
                                 throws ConfigurationException

Creates and returns an instance of the configuration provider, using the specified options and class loader. Specifying null for options uses provider-specific default options, if available. Uses the specified class loader to load resources and classes, or the current thread's context class loader if cl is null. Supplies cl as the class loader to the provider constructor.

Downloaded code can specify its own class loader in a call to this method in order to use the configuration provider specified in the JAR file from which it was downloaded.

Parameters:

options - values to use when constructing the configuration, or null if default options should be used

cl - the class loader to load resources and classes, and to pass when constructing the provider. If null, uses the context class loader.

Returns:

an instance of the configuration provider constructed with the specified options and class loader

Throws:

ConfigurationNotFoundException - if options specifies a source location that cannot be found, or if options is null and the provider does not supply default options

ConfigurationException - if an I/O exception occurs; if there are problems with the options argument or the format of the contents of any source location it specifies; if there is a problem with the contents of the resource file that names the configuration provider; if the configured provider class does not exist, is not public, is abstract, does not implement Configuration, or does not have a public constructor that has String[] and ClassLoader parameters; if the calling thread does not have permission to obtain information from the specified source; or if cl is null and the provider does not have permission to access the context class loader. Any Error thrown while creating the provider instance is propagated to the caller; it is not wrapped in a ConfigurationException.