org.sape.carbon.core.config.format
Interface ConfigurationFormatService

All Known Implementing Classes:

DefaultConfigurationFormatService

public interface ConfigurationFormatService

Implmentations of this interface will provide persistance mechanisms for Configuration objects.

Copyright 2002 Sapient

Since:

carbon 1.0

Version:

$Revision: 1.15 $($Author: dvoet $ / $Date: 2003/05/05 21:21:16 $)

Author:

Greg Hinkle, January 2002

Method Summary

void	alterChildConfiguration(Configuration parentConfig, String childName, Configuration newConfig) Alters the configuration named by childName within parentConfig, setting it to the value of newConfig.
Configuration	getChildConfiguration(Configuration parentConfig, String childName) Gets the child Configuration object of parentConfig that is named by the childName.
Set	getChildConfigurationNames(Configuration parentConfig) Gets the names of all the child configurations of parentConfig.
Configuration	newConfiguration(Class configurationClass) Creates a new configuration object of the type specified.
Configuration	readConfigurationStream(String name, InputStream in) Loads a Configuration object from the given InputStream.
void	writeConfigurationStream(Configuration configuration, OutputStream out) Stores the raw version of the provided Configuration object in the format that this format service implementation understands.

Method Detail

newConfiguration

public Configuration newConfiguration(Class configurationClass)

Creates a new configuration object of the type specified.

Parameters:

configurationClass - type of the configuration object to build

Returns:

the newly created configuration

readConfigurationStream

public Configuration readConfigurationStream(String name,
                                             InputStream in)
                                      throws ConfigurationFormatException

Loads a Configuration object from the given InputStream. This Configuration object will represent the full object-graph depiction of a live configuration.

Parameters:

name - The name of the configuration node

in - the InputStream from which the configuration will be read

Returns:

The Configuration object representing a live object graph of the data from the input stream

Throws:

ConfigurationFormatException - when there is a formatting error with the input stream

writeConfigurationStream

public void writeConfigurationStream(Configuration configuration,
                                     OutputStream out)
                              throws ConfigurationFormatException

Stores the raw version of the provided Configuration object in the format that this format service implementation understands.

Parameters:

out - The output stream to which the raw configuration data should be written

configuration - The Configuration object to be stored; may be any subclass of Configuration

Throws:

ConfigurationFormatException - When unable to write a configuration's raw format to the output stream

getChildConfiguration

public Configuration getChildConfiguration(Configuration parentConfig,
                                           String childName)

Gets the child Configuration object of parentConfig that is named by the childName. childName may be an indexed (see constructIndexedName). Returns null if it does not exist.

Parameters:

parentConfig - parent of requested child configuration

childName - child configuration name

Returns:

Configuration the requested child or null if it does not exist with in config

Since:

carbon 1.1

getChildConfigurationNames

public Set getChildConfigurationNames(Configuration parentConfig)

Gets the names of all the child configurations of parentConfig. The may be indexed (see constructIndexedName). Returns an empty set if names there are no children

Parameters:

parentConfig - parent of requested child configuration names

Returns:

Set all child names, never null

Since:

carbon 1.1

alterChildConfiguration

public void alterChildConfiguration(Configuration parentConfig,
                                    String childName,
                                    Configuration newConfig)

Alters the configuration named by childName within parentConfig, setting it to the value of newConfig. Note that if newConfig is has a name that falls outside of parentConfig a reference to newConfig is created, otherwise (newConfig.getConfigurationName().startsWith(parentConfig.getConfigurationName()) || newConfig.getConfigurationName() == null), the new value of childName is the actual value of newConfig. If the child does not exits, it is created. If newConfig is null, the child is removed.

Parameters:

parentConfig - the parent containing childName

childName - the child to be altered

newConfig - the new value for the child config

Since:

carbon 1.1