org.sape.carbon.core.config
Interface ConfigurationService

All Known Implementing Classes:

Config, DefaultRootConfigurationService

public interface ConfigurationService

The ConfigurationService provides access to a heirarchy of nodes that contain Configuration data. The main purpose of implementations of this class is to encapsulate the traversal of the hierachy.

The name of a configuration is the name of each node in the path through the node hierachy to locate the configuration, each node name starting with '/'. For example, NodeA contains NodeB which contains NodeC which contains configuration data. The name of the configuration object contained within NodeC is /NodeA/NodeB/NodeC.

Copyright 2002 Sapient

Since:

carbon 1.0

Version:

$Revision: 1.22 $($Author: dvoet $ / $Date: 2003/12/11 18:43:31 $)

Author:

Mike Redd, January 2002

See Also:

Node

Method Summary

void	addNodeListener(String nodeName, ConfigurationEventListener listener) Adds a listener to the specified node.
void	addNodeListener(String nodeName, NodeEventListener listener) Deprecated. use addNodeListener(String nodeName, ConfigurationEventListener listener) instead
Configuration	createConfiguration(Class configurationType) This method is the primary interface to create new instances of Configuration Objects.
Configuration	fetchConfiguration(String configurationName) Returns a Configuration object that contains all of the configuration data in the ConfigurationDocument located by configurationName.
Node	fetchNode(String nodeName) Traverses the internal node hierachy and returns the named node
Configuration	fetchWritableConfiguration(String configurationName) Returns a Configuration object that contains all of the configuration data in the ConfigurationDocument located by configurationName.
boolean	nodeExists(String nodeName) Returns true if the node exists in the configuration repository and false if it does not exist.
void	storeConfiguration(String configurationName, Configuration config) The storeConfiguration method persists configuration data contained in config to the underlying ConfigurationDocument named by configurationName.

Method Detail

fetchConfiguration

public Configuration fetchConfiguration(String configurationName)

Returns a Configuration object that contains all of the configuration data in the ConfigurationDocument located by configurationName.

The returned configuration may be a shared object that is read-only. If it is, the configuration's writable flag is set to false and exceptions will be thrown if an attempt is made to modify the object.

Parameters:

configurationName - The name of the requested configuration

Returns:

Configuration object that may be used to access discrete configuration data.

Throws:

InvalidParameterException - when the configurationName does not contain configuration data or does not start with /.

ConfigurationAccessException - when the configuration data can not be read.

ConfigurationNotFoundException - when the configuration data can not be read.

fetchWritableConfiguration

public Configuration fetchWritableConfiguration(String configurationName)

Returns a Configuration object that contains all of the configuration data in the ConfigurationDocument located by configurationName.

The returned configuration is a mutable object and not thread-safe. All access to this object should be in a single threaded or synchronized context. To commit the changes that have been made to this object use the storeConfiguration method.

Parameters:

configurationName - The name of the requested configuration

Returns:

Configuration object that may be used to access discrete configuration data.

Throws:

InvalidParameterException - when the configurationName does not contain configuration data or does not start with /.

ConfigurationAccessException - when the configuration data can not be read.

ConfigurationNotFoundException - when the configuration data can not be read.

Since:

carbon 1.1

storeConfiguration

public void storeConfiguration(String configurationName,
                               Configuration config)
                        throws ConfigurationStoreException

The storeConfiguration method persists configuration data contained in config to the underlying ConfigurationDocument named by configurationName. If the ConfigurationDocument does not exist, it is created along with all of its parent Nodes.

Parameters:

configurationName - The name of the Configuration Document where the configuration data should be stored.

config - Configuration data to be persisted to the underlying data store.

Throws:

InvalidParameterException - when the configurationName can not contain configuration data or does not start with /.

ConfigurationStoreException - data can not be written to the backing store.

createConfiguration

public Configuration createConfiguration(Class configurationType)

This method is the primary interface to create new instances of Configuration Objects. This method is capable of creating an empty configuration object for an interface that extends the Configuration interface.

Parameters:

configurationType - The Class of the configuration type to be created

Returns:

an empty instance of a configuration object implementing the provided class.

fetchNode

public Node fetchNode(String nodeName)
               throws NodeNotFoundException

Traverses the internal node hierachy and returns the named node

Parameters:

nodeName - the '/' delimeted path to the node

Returns:

The node specifed by nodeName.

Throws:

NodeNotFoundException - when the cannot be found.

addNodeListener

public void addNodeListener(String nodeName,
                            NodeEventListener listener)
                     throws NodeNotFoundException

Deprecated. use addNodeListener(String nodeName, ConfigurationEventListener listener) instead

Adds a listener to the specified node.

Parameters:

nodeName - the '/' delimeted path to the node

listener - the object that will be notified of NodeEvents

Throws:

NodeNotFoundException - if nodeName does not exist

Since:

carbon 1.1

addNodeListener

public void addNodeListener(String nodeName,
                            ConfigurationEventListener listener)
                     throws NodeNotFoundException

Adds a listener to the specified node.

Parameters:

nodeName - the '/' delimeted path to the node

listener - the object that will be notified of NodeEvents

Throws:

NodeNotFoundException - if nodeName does not exist

Since:

carbon 2.2

nodeExists

public boolean nodeExists(String nodeName)

Returns true if the node exists in the configuration repository and false if it does not exist. This is meant to be an alternative to getting Node not found exceptions when you have nodes that aren't required.

Parameters:

nodeName - the '/' delimeted path to the node

Returns:

if the node exists

Since:

carbon 1.1