1 package org.codehaus.plexus.configuration;
2
3 /*
4 * Copyright 2001-2006 Codehaus Foundation.
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 /**
20 * A configuration data hierarchy for configuring aspects of plexus. For
21 * example, to populate a ComponentDescriptor. Implementation of
22 * PlexusConfiguration may be populated by any means, for example, by XML file.
23 */
24 public interface PlexusConfiguration {
25 // ----------------------------------------------------------------------
26 // Name handling
27 // ----------------------------------------------------------------------
28
29 /**
30 * Returns the name of this configuration.
31 * @return the name of this configuration
32 */
33 String getName();
34
35 /**
36 * Sets the name of this configuration.
37 * @param name The name of the configuration.
38 */
39 void setName(String name);
40
41 // ----------------------------------------------------------------------
42 // Value handling
43 // ----------------------------------------------------------------------
44
45 /**
46 * Returns the value of this configuration.
47 * @return the value of this configuration
48 * @throws PlexusConfigurationException in case of an error.
49 */
50 String getValue() throws PlexusConfigurationException;
51
52 /**
53 * Returns the value of this configuration, or default if one cannot be
54 * found.
55 * @param defaultValue value to return if none is found
56 * @return the value of this configuration
57 */
58 String getValue(String defaultValue);
59
60 /**
61 * Set the value of a configuration element.
62 * @param value The value of the configuration element.
63 */
64 void setValue(String value);
65
66 /**
67 * Set the value of a configuration element and return the PlexusConfiguration object
68 * so that further operations can be carried out.
69 * @param value set the value.
70 * @return {@link PlexusConfiguration}
71 */
72 PlexusConfiguration setValueAndGetSelf(String value);
73
74 // ----------------------------------------------------------------------
75 // Attribute handling
76 // ----------------------------------------------------------------------
77
78 /**
79 * Sets an attribute on this configuration.
80 * @param name name of the attribute
81 * @param value the value of the attribute.
82 */
83 void setAttribute(String name, String value);
84
85 /**
86 * Returns an array of attribute names.
87 * @return an array of attribute names
88 */
89 String[] getAttributeNames();
90
91 /**
92 * Returns the value of the named attribute.
93 * @param paramName The name of the attribute.
94 * @return the value of the named attribute
95 * @throws PlexusConfigurationException in case of an error.
96 */
97 String getAttribute(String paramName) throws PlexusConfigurationException;
98
99 /**
100 * Returns the value of the named attribute, or default if one cannot be
101 * found.
102 * @param name The name of the attribute.
103 * @param defaultValue value to return if none is found
104 * @return the value of the named attribute
105 */
106 String getAttribute(String name, String defaultValue);
107
108 // ----------------------------------------------------------------------
109 // Child handling
110 // ----------------------------------------------------------------------
111
112 /**
113 * Returns the child configuration of the given name.
114 * @param child the name of the child to return
115 * @return the child configuration of the given name
116 */
117 PlexusConfiguration getChild(String child);
118
119 /**
120 * Returns the child configuration at the given location.
121 * @param i the position of the child under this configuration
122 * @return the child configuration at the given location
123 */
124 PlexusConfiguration getChild(int i);
125
126 /**
127 * Returns the child configuration of the given name.
128 * @param child the name of the child to return
129 * @param createChild true if a new child should be create, if none found
130 * @return the child configuration of the given name, or new child if
131 * created
132 */
133 PlexusConfiguration getChild(String child, boolean createChild);
134
135 /**
136 * Returns an array of all child configurations.
137 * @return an array of all child configurations
138 */
139 PlexusConfiguration[] getChildren();
140
141 /**
142 * Returns an array of all child configurations with the given name.
143 * @param name the name of the children configurations to return
144 * @return an array of all child configurations with the given name
145 */
146 PlexusConfiguration[] getChildren(String name);
147
148 /**
149 * Adds a configuration under this configuration, which acts as
150 * a parent.
151 * @param configuration the child configuration to add
152 */
153 void addChild(PlexusConfiguration configuration);
154
155 /**
156 * Add a child element with a given name and return the newly created element.
157 * @param name The name of the element.
158 * @return {@link PlexusConfiguration}
159 */
160 PlexusConfiguration addChild(String name);
161
162 /**
163 * Add a child element with a given name, and given value and return the
164 * newly created element.
165 * @param name The name of the child element.
166 * @param value The value of the child element.
167 * @return {@link PlexusConfiguration}
168 */
169 PlexusConfiguration addChild(String name, String value);
170
171 /**
172 * Returns the number of directly children under this configuration.
173 * @return the number of directly children under this configuration.
174 */
175 int getChildCount();
176 }