ConfigurationService


1   /*
2    * The contents of this file are subject to the Sapient Public License
3    * Version 1.0 (the "License"); you may not use this file except in compliance
4    * with the License. You may obtain a copy of the License at
5    * http://carbon.sf.net/License.html.
6    *
7    * Software distributed under the License is distributed on an "AS IS" basis,
8    * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
9    * the specific language governing rights and limitations under the License.
10   *
11   * The Original Code is The Carbon Component Framework.
12   *
13   * The Initial Developer of the Original Code is Sapient Corporation
14   *
15   * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
16   */
17  
18  package org.sape.carbon.core.config;
19  
20  import org.sape.carbon.core.config.node.Node;
21  import org.sape.carbon.core.config.node.NodeNotFoundException;
22  import org.sape.carbon.core.config.node.event.NodeEventListener;
23  
24  /**
25   * <p>
26   * The <code>ConfigurationService</code> provides access to a heirarchy of nodes
27   * that contain <code>Configuration</code> data.  The main purpose of
28   * implementations of this class is to encapsulate the traversal of the
29   * hierachy.
30   * </p>
31   * <p>
32   * The name of a configuration is the name of each node in the path through
33   * the node hierachy to locate the configuration, each node name starting with
34   * '/'.  For example, NodeA contains NodeB which contains NodeC which contains
35   * configuration data. The name of the configuration object contained within
36   * NodeC is /NodeA/NodeB/NodeC.
37   * </p>
38   *
39   * Copyright 2002 Sapient
40   * @see org.sape.carbon.core.config.node.Node
41   *
42   * @since carbon 1.0
43   * @author Mike Redd, January 2002
44   * @version $Revision: 1.21 $($Author: dvoet $ / $Date: 2003/05/05 21:21:15 $)
45   */
46  public interface ConfigurationService {
47  
48      /**
49       * <p>
50       * Returns a <code>Configuration</code> object that contains all of the
51       * configuration data in the <code>ConfigurationDocument</code> located by
52       * <code>configurationName</code>.
53       * </p>
54       * <p>
55       * The returned configuration may be a shared object that is read-only.
56       * If it is, the configuration's writable flag is set to false and
57       * exceptions will be thrown if an attempt is made to modify the object.
58       * </p>
59       *
60       * @param configurationName The name of the requested configuration
61       * @return Configuration object that may be used to access discrete
62       * configuration data.
63       *
64       * @throws org.sape.carbon.core.exception.InvalidParameterException
65       *         when the configurationName
66       * does not contain configuration data or does not start with /.
67       * @throws ConfigurationAccessException when the configuration data
68       * can not be read.
69       * @throws ConfigurationNotFoundException when the configuration data
70       * can not be read.
71       */
72      Configuration fetchConfiguration(String   configurationName);
73  
74      /**
75       * <p>
76       * Returns a <code>Configuration</code> object that contains all of the
77       * configuration data in the <code>ConfigurationDocument</code> located by
78       * <code>configurationName</code>.
79       * </p>
80       * <p>
81       * The returned configuration is a mutable object and not thread-safe.
82       * All access to this object should be in a single threaded or synchronized
83       * context.
84       * To commit the changes that have been made to this object use the
85       * storeConfiguration method.
86       * </p>
87       *
88       * @param configurationName The name of the requested configuration
89       * @return Configuration object that may be used to access discrete
90       * configuration data.
91       *
92       * @throws org.sape.carbon.core.exception.InvalidParameterException
93       *         when the configurationName
94       * does not contain configuration data or does not start with /.
95       * @throws ConfigurationAccessException when the configuration data
96       * can not be read.
97       * @throws ConfigurationNotFoundException when the configuration data
98       * can not be read.
99       * @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, Configuration config)
126         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 }
178
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags