View Javadoc
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      // ----------------------------------------------------------------------
27      // Name handling
28      // ----------------------------------------------------------------------
29  
30      /**
31       * Returns the name of this configuration.
32       * @return the name of this configuration
33       */
34      String getName();
35      
36      /**
37       * Sets the name of this configuration.
38       * @param name
39       */
40      void setName(String name);
41  
42      // ----------------------------------------------------------------------
43      // Value handling
44      // ----------------------------------------------------------------------
45  
46      /**
47       * Returns the value of this configuration.
48       * @return the value of this configuration
49       * @throws PlexusConfigurationException
50       */
51      String getValue()
52          throws PlexusConfigurationException;
53  
54      /**
55       * Returns the value of this configuration, or default if one cannot be
56       * found.
57       * @param defaultValue value to return if none is found
58       * @return the value of this configuration
59       */
60      String getValue( String defaultValue );
61  
62      /**
63       * Set the value of a configuration element.
64       * @param value
65       * @return
66       */
67      void setValue( String value );
68  
69      /**
70       * Set the value of a configuration element and return the PlexusConfiguration object
71       * so that further operations can be carried out.
72       * @param value
73       * @return
74       */
75      PlexusConfiguration setValueAndGetSelf( String value );
76  
77      // ----------------------------------------------------------------------
78      // Attribute handling
79      // ----------------------------------------------------------------------
80      
81      /**
82       * Sets an attribute on this configuration.
83       * @param name
84       * @param value
85       */
86      void setAttribute( String name, String value );
87  
88      /**
89       * Returns an array of attribute names.
90       * @return an array of attribute names
91       */
92      String[] getAttributeNames();
93  
94      /**
95       * Returns the value of the named attribute.
96       * @return the value of the named attribute
97       * @throws PlexusConfigurationException
98       */
99      String getAttribute( String paramName )
100         throws PlexusConfigurationException;
101 
102     /**
103      * Returns the value of the named attribute, or default if one cannot be
104      * found.
105      * @param defaultValue value to return if none is found
106      * @return the value of the named attribute
107      */
108     String getAttribute( String name, String defaultValue );
109 
110     // ----------------------------------------------------------------------
111     // Child handling
112     // ----------------------------------------------------------------------
113 
114     /**
115      * Returns the child configuration of the given name.
116      * @param child the name of the child to return
117      * @return the child configuration of the given name
118      */
119     PlexusConfiguration getChild( String child );
120 
121     /**
122      * Returns the child configuration at the given location.
123      * @param i the position of the child under this configuration
124      * @return the child configuration at the given location
125      */
126     PlexusConfiguration getChild( int i );
127 
128     /**
129      * Returns the child configuration of the given name.
130      * @param child the name of the child to return
131      * @param createChild true if a new child should be create, if none found
132      * @return the child configuration of the given name, or new child if
133      *  created
134      */
135     PlexusConfiguration getChild( String child, boolean createChild );
136 
137     /**
138      * Returns an array of all child configurations.
139      * @return an array of all child configurations
140      */
141     PlexusConfiguration[] getChildren();
142 
143     /**
144      * Returns an array of all child configurations with the given name.
145      * @param name the name of the children configurations to return
146      * @return an array of all child configurations with the given name
147      */
148     PlexusConfiguration[] getChildren( String name );
149 
150     /**
151      * Adds a configuration under this configuration, which acts as
152      * a parent.
153      * @param configuration the child configuration to add
154      */
155     void addChild( PlexusConfiguration configuration );
156 
157     /**
158      * Add a child element with a given name and return the newly created element.
159      * @param name
160      * @return
161      */
162     PlexusConfiguration addChild( String name );
163 
164     /**
165      * Add a child element with a given name, and given value and return the
166      * newly created element.
167      * @param name
168      * @return
169      */
170     PlexusConfiguration addChild( String name, String value );
171 
172     /**
173      * Returns the number of directly children under this configuration.
174      * @return the number of directly children under this configuration.
175      */
176     int getChildCount();
177 }