KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sape > carbon > core > config > format > ConfigurationFormatService


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.format;
19
20
21 import java.io.InputStream JavaDoc;
22 import java.io.OutputStream JavaDoc;
23 import java.util.Set JavaDoc;
24
25 import org.sape.carbon.core.config.Configuration;
26
27 /**
28  * <P>Implmentations of this interface will provide persistance mechanisms
29  * for <code>Configuration</code> objects.
30  * </P>
31  *
32  * Copyright 2002 Sapient
33  * @since carbon 1.0
34  * @author Greg Hinkle, January 2002
35  * @version $Revision: 1.15 $($Author: dvoet $ / $Date: 2003/05/05 21:21:16 $)
36  */
37 public interface ConfigurationFormatService {
38
39     /**
40      * <P>Creates a new configuration object of the type specified.</P>
41      *
42      * @param configurationClass type of the configuration object to build
43      * @return the newly created configuration
44      */
45     Configuration newConfiguration(Class JavaDoc configurationClass);
46
47     /**
48      * <P>Loads a <code>Configuration</code> object from the given
49      * <code>InputStream</code>. This Configuration object will represent
50      * the full object-graph depiction of a live configuration.</P>
51      *
52      * @param name The name of the configuration node
53      * @param in the {@link java.io.InputStream} from which
54      * the configuration will be read
55      * @throws ConfigurationFormatException when there is a formatting error
56      * with the input stream
57      * @return The Configuration object representing a live
58      * object graph of the data from the input stream
59      */
60     Configuration readConfigurationStream(String JavaDoc name, InputStream JavaDoc in)
61         throws ConfigurationFormatException;
62
63     /**
64      * <P>Stores the raw version of the provided <code>Configuration</code>
65      * object in the format that this format service implementation
66      * understands.</P>
67      *
68      * @param out The output stream to which the raw configuration
69      * data should be written
70      * @param configuration The Configuration object to be stored; may be any
71      * subclass of Configuration
72      * @throws ConfigurationFormatException When unable to write a
73      * configuration's raw format to the output stream
74      */
75     void writeConfigurationStream(
76         Configuration configuration,
77         OutputStream JavaDoc out)
78         throws ConfigurationFormatException;
79
80     /**
81      * Gets the child Configuration object of <code>parentConfig</code>
82      * that is named by the <code>childName</code>. <code>childName</code> may
83      * be an indexed (see constructIndexedName).
84      * Returns null if it does not exist.
85      *
86      * @param parentConfig parent of requested child configuration
87      * @param childName child configuration name
88      * @return Configuration the requested child or null if it does not exist
89      * with in config
90      * @since carbon 1.1
91      */
92     Configuration getChildConfiguration(
93         Configuration parentConfig,
94         String JavaDoc childName);
95
96     /**
97      * Gets the names of all the child configurations of parentConfig. The
98      * may be indexed (see constructIndexedName). Returns an empty set if
99      * names there are no children
100      *
101      * @param parentConfig parent of requested child configuration names
102      * @return Set all child names, never null
103      * @since carbon 1.1
104      */
105     Set JavaDoc getChildConfigurationNames(Configuration parentConfig);
106
107     /**
108      * Alters the configuration named by childName within parentConfig, setting
109      * it to the value of newConfig. Note that if newConfig is has a name
110      * that falls outside of parentConfig a reference to newConfig is created,
111      * otherwise
112      * (newConfig.getConfigurationName().startsWith(parentConfig.getConfigurationName()) || newConfig.getConfigurationName() == null),
113      * the new value of childName is the actual value of newConfig. If the
114      * child does not exits, it is created. If newConfig is null, the child
115      * is removed.
116      *
117      * @param parentConfig the parent containing childName
118      * @param childName the child to be altered
119      * @param newConfig the new value for the child config
120      * @since carbon 1.1
121      */
122     void alterChildConfiguration(
123         Configuration parentConfig,
124         String JavaDoc childName,
125         Configuration newConfig);
126
127 }
128
Popular Tags