ConfigurationDocument


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.node;
19  
20  import org.sape.carbon.core.config.Configuration;
21  import org.sape.carbon.core.config.format.ConfigurationFormatException;
22  import org.sape.carbon.core.config.format.ConfigurationFormatService;
23  
24  /**
25   * A <code>ConfigurationDocument</code> is a <code>Node</code> that contains
26   * configuration information.  This interface contains methods to read
27   * and write <code>Configuration</code> objects from and to a data store.
28   *
29   * Copyright 2002 Sapient
30   * @see org.sape.carbon.core.config.Configuration
31   *
32   * @since carbon 1.0
33   * @author Douglas Voet, March 2002
34   * @version $Revision: 1.10 $($Author: dvoet $ / $Date: 2003/05/05 21:21:18 $)
35   */
36  public interface ConfigurationDocument extends Node {
37  
38      /**
39       * Accesses the underlying data store to persist the configuration data
40       * of <code>config</code> to the location represented by this
41       * <code>Node</code>.
42       *
43       * @see org.sape.carbon.core.config.ConfigurationService#storeConfiguration(String, Configuration)
44       * @param config The Configuration Container in the current node.
45       *
46       * @throws ConfigurationFormatException when the configuration
47       *         data can not be persisted.
48       * @throws NodeIOException indicates an error reading a node
49       */
50      void writeConfiguration(Configuration config)
51          throws NodeIOException, ConfigurationFormatException;
52  
53      /**
54       * Accesses the underlying data store to load the configuration data
55       * from to the location represented by this <code>Node</code>.
56       *
57       * @see org.sape.carbon.core.config.ConfigurationService#fetchConfiguration(String)
58       * @return Configuration object encapsulating the requested configuration
59       * @throws ConfigurationFormatException when the configuration
60       *         data can not be read.
61       * @throws NodeIOException indicates an error reading a node
62       */
63      Configuration readConfiguration()
64          throws NodeIOException, ConfigurationFormatException;
65  
66      /**
67       * Adds a nested configuration object within this document with the name
68       * given by name and the value given by config. If config represents an
69       * existing ConfigurationDocument, a reference to that document is
70       * created, otherwise, the configuration is embedded within this document.
71       *
72       * @param name the name of the configuration to add. This should not use
73       *        indexed notation. If the property is indexed, config will
74       *        be added to the end of the list. Retrieval then needs to
75       *        use the indexed notation.
76       * @param config the config object to add. If this object belongs to
77       *        another configuration document, a reference is created
78       *        to that document.  Otherwise, the config is embedded
79       *        within this document.
80       * @return ConfigurationDocument the added document
81       * @throws NodeCreationException if there is a problem creating the
82       *         nested document.
83       */
84      ConfigurationDocument addNestedConfigurationDocument(
85          String   name,
86          Configuration config)
87          throws NodeCreationException;
88  
89      /**
90       * Method getFormatService.
91       * @return ConfigurationFormatService
92       */
93      ConfigurationFormatService getFormatService();
94  
95      /**
96       * Returns the nested node factory for the configuration.
97       *
98       * @return the nested node factory
99       */
100     NodeFactory getNestedNodeFactory();
101 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags