001: /*
002: * The contents of this file are subject to the Sapient Public License
003: * Version 1.0 (the "License"); you may not use this file except in compliance
004: * with the License. You may obtain a copy of the License at
005: * http://carbon.sf.net/License.html.
006: *
007: * Software distributed under the License is distributed on an "AS IS" basis,
008: * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
009: * the specific language governing rights and limitations under the License.
010: *
011: * The Original Code is The Carbon Component Framework.
012: *
013: * The Initial Developer of the Original Code is Sapient Corporation
014: *
015: * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
016: */
017:
018: package org.sape.carbon.core.config;
019:
020: import org.sape.carbon.core.config.node.Node;
021: import org.sape.carbon.core.config.node.NodeNotFoundException;
022: import org.sape.carbon.core.config.node.event.NodeEventListener;
023:
024: /**
025: * <p>
026: * The <code>ConfigurationService</code> provides access to a heirarchy of nodes
027: * that contain <code>Configuration</code> data. The main purpose of
028: * implementations of this class is to encapsulate the traversal of the
029: * hierachy.
030: * </p>
031: * <p>
032: * The name of a configuration is the name of each node in the path through
033: * the node hierachy to locate the configuration, each node name starting with
034: * '/'. For example, NodeA contains NodeB which contains NodeC which contains
035: * configuration data. The name of the configuration object contained within
036: * NodeC is /NodeA/NodeB/NodeC.
037: * </p>
038: *
039: * Copyright 2002 Sapient
040: * @see org.sape.carbon.core.config.node.Node
041: *
042: * @since carbon 1.0
043: * @author Mike Redd, January 2002
044: * @version $Revision: 1.21 $($Author: dvoet $ / $Date: 2003/05/05 21:21:15 $)
045: */
046: public interface ConfigurationService {
047:
048: /**
049: * <p>
050: * Returns a <code>Configuration</code> object that contains all of the
051: * configuration data in the <code>ConfigurationDocument</code> located by
052: * <code>configurationName</code>.
053: * </p>
054: * <p>
055: * The returned configuration may be a shared object that is read-only.
056: * If it is, the configuration's writable flag is set to false and
057: * exceptions will be thrown if an attempt is made to modify the object.
058: * </p>
059: *
060: * @param configurationName The name of the requested configuration
061: * @return Configuration object that may be used to access discrete
062: * configuration data.
063: *
064: * @throws org.sape.carbon.core.exception.InvalidParameterException
065: * when the configurationName
066: * does not contain configuration data or does not start with /.
067: * @throws ConfigurationAccessException when the configuration data
068: * can not be read.
069: * @throws ConfigurationNotFoundException when the configuration data
070: * can not be read.
071: */
072: Configuration fetchConfiguration(String configurationName);
073:
074: /**
075: * <p>
076: * Returns a <code>Configuration</code> object that contains all of the
077: * configuration data in the <code>ConfigurationDocument</code> located by
078: * <code>configurationName</code>.
079: * </p>
080: * <p>
081: * The returned configuration is a mutable object and not thread-safe.
082: * All access to this object should be in a single threaded or synchronized
083: * context.
084: * To commit the changes that have been made to this object use the
085: * storeConfiguration method.
086: * </p>
087: *
088: * @param configurationName The name of the requested configuration
089: * @return Configuration object that may be used to access discrete
090: * configuration data.
091: *
092: * @throws org.sape.carbon.core.exception.InvalidParameterException
093: * when the configurationName
094: * does not contain configuration data or does not start with /.
095: * @throws ConfigurationAccessException when the configuration data
096: * can not be read.
097: * @throws ConfigurationNotFoundException when the configuration data
098: * can not be read.
099: * @since carbon 1.1
100: */
101: Configuration fetchWritableConfiguration(String configurationName);
102:
103: /**
104: * <p>
105: * The <code>storeConfiguration</code> method persists configuration data
106: * contained in <code>config</code> to the underlying
107: * <code>ConfigurationDocument</code> named by
108: * <code>configurationName</code>. If the
109: * <code>ConfigurationDocument</code> does not exist, it is created
110: * along with all of its parent <code>Node</code>s.
111: * </p>
112: *
113: * @param configurationName The name of the Configuration Document
114: * where the configuration data should be stored.
115: * @param config Configuration data to be persisted to the underlying
116: * data store.
117: *
118: * @throws org.sape.carbon.core.exception.InvalidParameterException when the
119: * configurationName can not contain configuration data or does
120: * not start with /.
121: *
122: * @throws ConfigurationStoreException data can not be written to the
123: * backing store.
124: */
125: void storeConfiguration(String configurationName,
126: Configuration config) throws ConfigurationStoreException;
127:
128: /**
129: * <P>
130: * This method is the primary interface to create new instances of
131: * Configuration
132: * Objects. This method is capable of creating an empty configuration object
133: * for an interface that extends the
134: * {@link org.sape.carbon.core.config.Configuration} interface.
135: * </P>
136: *
137: * @param configurationType The Class of the configuration type to be
138: * created
139: * @return an empty instance of a configuration object implementing the
140: * provided class.
141: */
142: Configuration createConfiguration(Class configurationType);
143:
144: /**
145: * Traverses the internal node hierachy and returns the named node
146: *
147: * @param nodeName the '/' delimeted path to the node
148: * @return The node specifed by nodeName.
149: *
150: * @throws NodeNotFoundException when the cannot be found.
151: */
152: Node fetchNode(String nodeName) throws NodeNotFoundException;
153:
154: /**
155: * Adds a listener to the specified node.
156: *
157: * @param nodeName the '/' delimeted path to the node
158: * @param listener the object that will be notified of NodeEvents
159: *
160: * @throws NodeNotFoundException if nodeName does not exist
161: * @since carbon 1.1
162: */
163: void addNodeListener(String nodeName, NodeEventListener listener)
164: throws NodeNotFoundException;
165:
166: /**
167: * Returns true if the node exists in the configuration repository and
168: * false if it does not exist. This is meant to be an alternative to
169: * getting Node not found exceptions when you have nodes that aren't
170: * required.
171: *
172: * @param nodeName the '/' delimeted path to the node
173: * @return if the node exists
174: * @since carbon 1.1
175: */
176: boolean nodeExists(String nodeName);
177: }
|