org.sape.carbon.core.config.node
Class AbstractConfigurationDocument

java.lang.Object
  |
  +--org.sape.carbon.core.config.node.AbstractNode
        |
        +--org.sape.carbon.core.config.node.AbstractConfigurationDocument

All Implemented Interfaces:

ConfigurationDocument, Node

Direct Known Subclasses:

ClassloaderConfigurationDocument, FileConfigurationDocument, JarConfigurationDocument, JNDIConfigurationDocument, NestedConfigurationDocument

public abstract class AbstractConfigurationDocument

extends AbstractNode

implements ConfigurationDocument

This implementation of ConfigurationDocument uses a ConfigurationFormatService to read and write Configurations from and to the backing data store and caches the results for future use. This implementation interfaces with the backing data store via sub-classes implementing the methods openInputStream and openOutputStream. This implementation caches the Configuration object upon the first call to readConfiguration. The cached version is cleared when writeConfiguration is called. Copyright 2002 Sapient

Since:

carbon 1.0

Version:

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

Author:

Douglas Voet, February 2002

Field Summary

protected Configuration	configuration Cached copy of the Configuration
private ConfigurationFormatService	formatter The ConfigurationFormatService used by this class.
private org.apache.commons.logging.Log	log Provides a handle to Apache-commons logger
private NodeFactory	nestedNodeFactory Document factory for nested configurations.

Fields inherited from class org.sape.carbon.core.config.node.AbstractNode

childNodes, nodeListeners

Fields inherited from interface org.sape.carbon.core.config.node.Node

DELIMITER

Constructor Summary

AbstractConfigurationDocument(Node parent, String name, ConfigurationFormatService formatter)
Constructor for AbstractConfigurationDocument.

AbstractConfigurationDocument(Node parent, String name, Object readOrAlterNodeLock, Object addOrLoadChildLock, ConfigurationFormatService formatter)

Method Summary

ConfigurationDocument	addNestedConfigurationDocument(String name, Configuration config) Adds a nested configuration object within this document with the name given by name and the value given by config.
protected void	closeInputStream(InputStream in) Closes the input stream.
protected void	closeOutputStream(OutputStream out) Closes the output stream.
protected Set	getAllChildNames() Retreives the names of all child configurations.
ConfigurationFormatService	getFormatService() Method getFormatService.
NodeFactory	getNestedNodeFactory() Returns the nested node factory for the configuration.
protected void	issueNodeModifiedEvent() Notifies all listenters that this document has been modified.
protected Node	loadChild(String nodeName) Loads the child specified by nodeName from the backing data store.
protected void	notifyNestedDocuments() This method notifies all nested configuration documents that the document has changed and their listeners should be notified.
protected abstract InputStream	openInputStream() This method should be overridden by classes implementing ConfigurationDocuments for specific data stores.
protected abstract OutputStream	openOutputStream() This method should be overridden by classes implementing ConfigurationDocuments for specific data stores.
Configuration	readConfiguration() This implementation uses the ConfigurationFormatService to read from the backing data store.
void	refresh() Refreshes the Node's underlying cache of data (assuming is has one)
int	remove() Permanently deletes the node and all of its child nodes from the backing store returning the total number of nodes deleted.
protected void	writeChildReferences(Configuration config) Writes out references to child configuration documents inside a config.
void	writeConfiguration(Configuration config) This implementation uses the ConfigurationFormatService to write to the backing data store.

Methods inherited from class org.sape.carbon.core.config.node.AbstractNode

addNodeListener, addNodeListener, addNodeListener, backingDataExists, containsChild, destroyBackingData, fetchChild, fetchChildren, getAbsoluteName, getAddOrLoadChildLock, getAllowsChildren, getName, getParent, getReadOrAlterNodeLock, isRemoved, issueChildLoadedEvent, issueNodeRemovedEvent, removeRemovedChildren, setRemoved, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.sape.carbon.core.config.node.Node

addNodeListener, addNodeListener, containsChild, fetchChild, fetchChildren, getAbsoluteName, getAllowsChildren, getName, getParent, isRemoved

Field Detail

log

private org.apache.commons.logging.Log log

Provides a handle to Apache-commons logger

configuration

protected Configuration configuration

Cached copy of the Configuration

formatter

private final ConfigurationFormatService formatter

The ConfigurationFormatService used by this class.

nestedNodeFactory

private final NodeFactory nestedNodeFactory

Document factory for nested configurations.

Constructor Detail

AbstractConfigurationDocument

public AbstractConfigurationDocument(Node parent,
                                     String name,
                                     Object readOrAlterNodeLock,
                                     Object addOrLoadChildLock,
                                     ConfigurationFormatService formatter)

Parameters:

parent -

name -

readOrAlterNodeLock -

AbstractConfigurationDocument

public AbstractConfigurationDocument(Node parent,
                                     String name,
                                     ConfigurationFormatService formatter)

Constructor for AbstractConfigurationDocument.

Parameters:

parent - the node's parent

name - the node's name

formatter - the ConfigurationFormatService object used to read and write Configuration to the backing data store

Throws:

NullPointerException - if formatter is null

Method Detail

readConfiguration

public Configuration readConfiguration()
                                throws NodeIOException,
                                       ConfigurationFormatException

This implementation uses the ConfigurationFormatService to read from the backing data store. It calls the abstract method openInputStream to open an InputStream to read the Configuration from then closes it before it exits.

This method is synchronized to prevent multiple readers from loading the Configuration at once and to make sure that no one is writing a new Configuration while someone else is reading.

Specified by:

readConfiguration in interface ConfigurationDocument

Returns:

the Configuration object within this ConfigurationDocument

Throws:

NodeIOException - indicates a generic exception writing the configuration

ConfigurationFormatException - indicates an error formating the config document

See Also:

ConfigurationService.fetchConfiguration(String)

writeConfiguration

public void writeConfiguration(Configuration config)
                        throws NodeIOException,
                               ConfigurationFormatException

This implementation uses the ConfigurationFormatService to write to the backing data store. It calls the abstract method openOutpuStream to open an OutputStream to write the Configuration to then closes it before it exits.

This method is synchronized internally to prevent multiple writes from saving Configurations concurrently and to make sure that no one is writing a new Configuration while someone else is reading.

Specified by:

writeConfiguration in interface ConfigurationDocument

Parameters:

config - the Configuration to write to the backing data store

Throws:

NodeIOException - indicates a generic exception writing the configuration

ConfigurationFormatException - indicates an error formating the config document

See Also:

ConfigurationService.storeConfiguration(String, Configuration)

remove

public int remove()
           throws NodeRemovalException

Description copied from interface: Node

Permanently deletes the node and all of its child nodes from the backing store returning the total number of nodes deleted.

Specified by:

remove in interface Node

Overrides:

remove in class AbstractNode

Returns:

The total number of nodes deleted. This number should always be at least '1' when the operation completed successfully.

Throws:

NodeRemovalException - when the node or one of its children can not be deleted. When this exception is thrown, some nodes may have been deleted while other may have not.

See Also:

synchronized to ensure no one is fetching or adding children while this method is removing them

addNestedConfigurationDocument

public ConfigurationDocument addNestedConfigurationDocument(String name,
                                                            Configuration config)
                                                     throws NodeCreationException

Description copied from interface: ConfigurationDocument

Adds a nested configuration object within this document with the name given by name and the value given by config. If config represents an existing ConfigurationDocument, a reference to that document is created, otherwise, the configuration is embedded within this document.

Specified by:

addNestedConfigurationDocument in interface ConfigurationDocument

Parameters:

name - the name of the configuration to add. This should not use indexed notation. If the property is indexed, config will be added to the end of the list. Retrieval then needs to use the indexed notation.

config - the config object to add. If this object belongs to another configuration document, a reference is created to that document. Otherwise, the config is embedded within this document.

Returns:

ConfigurationDocument the added document

Throws:

NodeCreationException - if there is a problem creating the nested document.

See Also:

AbstractNode#addNestedConfigurationDocument

getFormatService

public ConfigurationFormatService getFormatService()

Description copied from interface: ConfigurationDocument

Method getFormatService.

Specified by:

getFormatService in interface ConfigurationDocument

Returns:

ConfigurationFormatService

See Also:

ConfigurationDocument.getFormatService()

refresh

public void refresh()

Description copied from interface: Node

Refreshes the Node's underlying cache of data (assuming is has one)

Specified by:

refresh in interface Node

Overrides:

refresh in class AbstractNode

See Also:

Node.refresh()

notifyNestedDocuments

protected void notifyNestedDocuments()

This method notifies all nested configuration documents that the document has changed and their listeners should be notified.

Since:

carbon 1.1

openInputStream

protected abstract InputStream openInputStream()
                                        throws Exception

This method should be overridden by classes implementing ConfigurationDocuments for specific data stores. The returned InputStream should be a stream of data that can be read by the ConfigurationFormatService and converted to a Configuration object.

This method is called by readConfiguration.

Returns:

InputStream the InputStream from which to read the Configuration object within this ConfigurationDocument

Throws:

Exception - if an exception occurs openning the stream

closeInputStream

protected void closeInputStream(InputStream in)
                         throws Exception

Closes the input stream.

Parameters:

in - the stream to open

Throws:

Exception - indicates an exception occured closing the stream

openOutputStream

protected abstract OutputStream openOutputStream()
                                          throws Exception

This method should be overridden by classes implementing ConfigurationDocuments for specific data stores. The returned OutputStream should be a stream of data that can be written to by the ConfigurationFormatService.

This method is called by writeConfiguration.

Returns:

OutputStream the OutputStream to which to write the Configuration object within this ConfigurationDocument

Throws:

Exception - if an exception occurs openning the stream

closeOutputStream

protected void closeOutputStream(OutputStream out)
                          throws Exception

Closes the output stream.

Parameters:

out - the stream to close

Throws:

Exception - indicates an error closing the stream

getAllChildNames

protected Set getAllChildNames()

Retreives the names of all child configurations.

Specified by:

getAllChildNames in class AbstractNode

Returns:

names of all child configurations

loadChild

protected Node loadChild(String nodeName)
                  throws NodeNotFoundException

Description copied from class: AbstractNode

Loads the child specified by nodeName from the backing data store. Called by fetchChild when the child has not yet been cached.

Specified by:

loadChild in class AbstractNode

Parameters:

nodeName - the name of the node to load

Returns:

Node the loaded node

Throws:

NodeNotFoundException - if the backing data for the specifed node could not be found in the data store.

See Also:

AbstractNode.loadChild(String)

writeChildReferences

protected void writeChildReferences(Configuration config)
                             throws ConfigurationFormatException

Writes out references to child configuration documents inside a config.

Parameters:

config - config to persist out child references

Throws:

ConfigurationFormatException - indicates an error writing out the child reference

getNestedNodeFactory

public NodeFactory getNestedNodeFactory()

Description copied from interface: ConfigurationDocument

Returns the nested node factory for the configuration.

Specified by:

getNestedNodeFactory in interface ConfigurationDocument

Returns:

the nested node factory

See Also:

ConfigurationDocument.getNestedNodeFactory()

issueNodeModifiedEvent

protected void issueNodeModifiedEvent()

Notifies all listenters that this document has been modified. Note that this should be not be called from a synchronized context.

Since:

carbon 2.2