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


Copyright 1999-2003 Sapient Corporation. All Rights Reserved.