DefaultConfiguration


1   /* ====================================================================
2    * The Apache Software License, Version 1.1
3    *
4    * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
5    * reserved.
6    *
7    * Redistribution and use in source and binary forms, with or without
8    * modification, are permitted provided that the following conditions
9    * are met:
10   *
11   * 1. Redistributions of source code must retain the above copyright
12   *    notice, this list of conditions and the following disclaimer.
13   *
14   * 2. Redistributions in binary form must reproduce the above copyright
15   *    notice, this list of conditions and the following disclaimer in
16   *    the documentation and/or other materials provided with the
17   *    distribution.
18   *
19   * 3. The end-user documentation included with the redistribution,
20   *    if any, must include the following acknowledgment:
21   *    "This product includes software developed by the
22   *    Apache Software Foundation (http://www.apache.org/)."
23   *    Alternately, this acknowledgment may appear in the software
24   *    itself, if and wherever such third-party acknowledgments
25   *    normally appear.
26   *
27   * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
28   *    must not be used to endorse or promote products derived from this
29   *    software without prior written permission. For written
30   *    permission, please contact apache@apache.org.
31   *
32   * 5. Products derived from this software may not be called "Apache",
33   *    nor may "Apache" appear in their name, without prior written
34   *    permission of the Apache Software Foundation.
35   *
36   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39   * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47   * SUCH DAMAGE.
48   * ====================================================================
49   *
50   * This software consists of voluntary contributions made by many
51   * individuals on behalf of the Apache Software Foundation. For more
52   * information on the Apache Software Foundation, please see
53   * <http://www.apache.org/>.
54   */
55  package org.apache.avalon.framework.configuration;
56  
57  import java.io.Serializable  ;
58  import java.util.ArrayList  ;
59  import java.util.HashMap  ;
60  
61  /**
62   * This is the default <code>Configuration</code> implementation.
63   *
64   * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
65   * @version CVS $Revision: 1.32 $ $Date: 2003/02/11 16:19:27 $
66   */
67  public class DefaultConfiguration
68      extends AbstractConfiguration
69      implements Serializable  
70  {
71      /**
72       * An empty (length zero) array of configuration objects.
73       */
74      protected static final Configuration[] EMPTY_ARRAY = new Configuration[ 0 ];
75  
76      private final String   m_name;
77      private final String   m_location;
78      private final String   m_namespace;
79      private final String   m_prefix;
80      private HashMap   m_attributes;
81      private ArrayList   m_children;
82      private String   m_value;
83      private boolean m_readOnly;
84  
85      /**
86       * Create a new <code>DefaultConfiguration</code> instance.
87       * @param name a <code>String</code> value
88       */
89      public DefaultConfiguration( final String   name )
90      {
91          this( name, null, "", "" );
92      }
93  
94      /**
95       * Create a new <code>DefaultConfiguration</code> instance.
96       * @param name a <code>String</code> value
97       * @param location a <code>String</code> value
98       */
99      public DefaultConfiguration( final String   name, final String   location )
100     {
101         this( name, location, "", "" );
102     }
103 
104     /**
105      * Create a new <code>DefaultConfiguration</code> instance.
106      * @param name config node name
107      * @param location Builder-specific locator string
108      * @param ns Namespace string (typically a URI). Should not be null; use ""
109      * if no namespace.
110      * @param prefix A short string prefixed to element names, associating
111      * elements with a longer namespace string. Should not be null; use "" if no
112      * namespace.
113      * @since 4.1
114     */
115     public DefaultConfiguration( final String   name,
116                                  final String   location,
117                                  final String   ns,
118                                  final String   prefix )
119     {
120         m_name = name;
121         m_location = location;
122         m_namespace = ns;
123         m_prefix = prefix;  // only used as a serialization hint. Cannot be null
124     }
125 
126     /**
127      * Returns the name of this configuration element.
128      * @return a <code>String</code> value
129      */
130     public String   getName()
131     {
132         return m_name;
133     }
134 
135     /**
136      * Returns the namespace of this configuration element
137      * @return a <code>String</code> value
138      * @throws ConfigurationException if an error occurs
139      * @since 4.1
140      */
141     public String   getNamespace() throws ConfigurationException
142     {
143         if( null != m_namespace )
144         {
145             return m_namespace;
146         }
147         else
148         {
149             throw new ConfigurationException
150                 ( "No namespace (not even default \"\") is associated with the "
151                   + "configuration element \"" + getName()
152                   + "\" at " + getLocation() );
153         }
154     }
155 
156     /**
157      * Returns the prefix of the namespace
158      * @return a <code>String</code> value
159      * @throws ConfigurationException if prefix is not present (<code>null</code>).
160      * @since 4.1
161      */
162     protected String   getPrefix() throws ConfigurationException
163     {
164         if( null != m_prefix )
165         {
166             return m_prefix;
167         }
168         else
169         {
170             throw new ConfigurationException
171                 ( "No prefix (not even default \"\") is associated with the "
172                   + "configuration element \"" + getName()
173                   + "\" at " + getLocation() );
174         }
175 
176     }
177 
178     /**
179      * Returns a description of location of element.
180      * @return a <code>String</code> value
181      */
182     public String   getLocation()
183     {
184         return m_location;
185     }
186 
187     /**
188      * Returns the value of the configuration element as a <code>String</code>.
189      *
190      * @param defaultValue the default value to return if value malformed or empty
191      * @return a <code>String</code> value
192      */
193     public String   getValue( final String   defaultValue )
194     {
195         if( null != m_value )
196         {
197             return m_value;
198         }
199         else
200         {
201             return defaultValue;
202         }
203     }
204 
205     /**
206      * Returns the value of the configuration element as a <code>String</code>.
207      *
208      * @return a <code>String</code> value
209      * @throws ConfigurationException If the value is not present.
210      */
211     public String   getValue() throws ConfigurationException
212     {
213         if( null != m_value )
214         {
215             return m_value;
216         }
217         else
218         {
219             throw new ConfigurationException( "No value is associated with the "
220                                               + "configuration element \"" + getName()
221                                               + "\" at " + getLocation() );
222         }
223     }
224 
225     /**
226      * Return an array of all attribute names.
227      * @return a <code>String[]</code> value
228      */
229     public String  [] getAttributeNames()
230     {
231         if( null == m_attributes )
232         {
233             return new String  [ 0 ];
234         }
235         else
236         {
237             return (String  [])m_attributes.keySet().toArray( new String  [ 0 ] );
238         }
239     }
240 
241     /**
242      * Return an array of <code>Configuration</code>
243      * elements containing all node children.
244      *
245      * @return The child nodes with name
246      */
247     public Configuration[] getChildren()
248     {
249         if( null == m_children )
250         {
251             return new Configuration[ 0 ];
252         }
253         else
254         {
255             return (Configuration[])m_children.toArray( new Configuration[ 0 ] );
256         }
257     }
258 
259     /**
260      * Returns the value of the attribute specified by its name as a
261      * <code>String</code>.
262      *
263      * @param name a <code>String</code> value
264      * @return a <code>String</code> value
265      * @throws ConfigurationException If the attribute is not present.
266      */
267     public String   getAttribute( final String   name )
268         throws ConfigurationException
269     {
270         final String   value =
271             ( null != m_attributes ) ? (String  )m_attributes.get( name ) : null;
272 
273         if( null != value )
274         {
275             return value;
276         }
277         else
278         {
279             throw new ConfigurationException( 
280                "No attribute named \"" + name + "\" is "
281                + "associated with the configuration element \""
282                + getName() + "\" at " + getLocation() );
283         }
284     }
285 
286     /**
287      * Return the first <code>Configuration</code> object child of this
288      * associated with the given name.
289      * @param name a <code>String</code> value
290      * @param createNew a <code>boolean</code> value
291      * @return a <code>Configuration</code> value
292      */
293     public Configuration getChild( final String   name, final boolean createNew )
294     {
295         if( null != m_children )
296         {
297             final int size = m_children.size();
298             for( int i = 0; i < size; i++ )
299             {
300                 final Configuration configuration = (Configuration)m_children.get( i );
301                 if( name.equals( configuration.getName() ) )
302                 {
303                     return configuration;
304                 }
305             }
306         }
307 
308         if( createNew )
309         {
310             return new DefaultConfiguration( name, "-" );
311         }
312         else
313         {
314             return null;
315         }
316     }
317 
318     /**
319      * Return an array of <code>Configuration</code> objects
320      * children of this associated with the given name.
321      * <br>
322      * The returned array may be empty but is never <code>null</code>.
323      *
324      * @param name The name of the required children <code>Configuration</code>.
325      * @return a <code>Configuration[]</code> value
326      */
327     public Configuration[] getChildren( final String   name )
328     {
329         if( null == m_children )
330         {
331             return new Configuration[ 0 ];
332         }
333         else
334         {
335             final ArrayList   children = new ArrayList  ();
336             final int size = m_children.size();
337 
338             for( int i = 0; i < size; i++ )
339             {
340                 final Configuration configuration = (Configuration)m_children.get( i );
341                 if( name.equals( configuration.getName() ) )
342                 {
343                     children.add( configuration );
344                 }
345             }
346 
347             return (Configuration[])children.toArray( new Configuration[ 0 ] );
348         }
349     }
350 
351     /**
352      * Append data to the value of this configuration element.
353      *
354      * @param value a <code>String</code> value
355      * @deprecated Use setValue() instead
356      */
357     public void appendValueData( final String   value )
358     {
359         checkWriteable();
360 
361         if( null == m_value )
362         {
363             m_value = value;
364         }
365         else
366         {
367             m_value += value;
368         }
369     }
370 
371     /**
372      * Set the value of this <code>Configuration</code> object to the specified string.
373      *
374      * @param value a <code>String</code> value
375      */
376     public void setValue( final String   value )
377     {
378         checkWriteable();
379 
380         m_value = value;
381     }
382 
383     /**
384      * Set the value of the specified attribute to the specified string.
385      *
386      * @param name name of the attribute to set
387      * @param value a <code>String</code> value
388      */
389     public void setAttribute( final String   name, final String   value )
390     {
391         checkWriteable();
392 
393         if( null == m_attributes )
394         {
395             m_attributes = new HashMap  ();
396         }
397         m_attributes.put( name, value );
398     }
399 
400     /**
401      * Add an attribute to this configuration element, returning its old
402      * value or <b>null</b>.
403      *
404      * @param name a <code>String</code> value
405      * @param value a <code>String</code> value
406      * @return a <code>String</code> value
407      * @deprecated Use setAttribute() instead
408      */
409     public String   addAttribute( final String   name, String   value )
410     {
411         checkWriteable();
412 
413         if( null == m_attributes )
414         {
415             m_attributes = new HashMap  ();
416         }
417 
418         return (String  )m_attributes.put( name, value );
419     }
420 
421     /**
422      * Add a child <code>Configuration</code> to this configuration element.
423      * @param configuration a <code>Configuration</code> value
424      */
425     public void addChild( final Configuration configuration )
426     {
427         checkWriteable();
428 
429         if( null == m_children )
430         {
431             m_children = new ArrayList  ();
432         }
433 
434         m_children.add( configuration );
435     }
436 
437     /**
438      * Add all the attributes, children and value
439      * from specified configuration element to current
440      * configuration element.
441      *
442      * @param other the {@link Configuration} element
443      */
444     public void addAll( final Configuration other )
445     {
446         checkWriteable();
447 
448         setValue( other.getValue( null ) );
449         addAllAttributes( other );
450         addAllChildren( other );
451     }
452 
453     /**
454      * Add all attributes from specified configuration
455      * element to current configuration element.
456      *
457      * @param other the {@link Configuration} element
458      */
459     public void addAllAttributes( final Configuration other )
460     {
461         checkWriteable();
462 
463         final String  [] attributes = other.getAttributeNames();
464         for( int i = 0; i < attributes.length; i++ )
465         {
466             final String   name = attributes[ i ];
467             final String   value = other.getAttribute( name, null );
468             setAttribute( name, value );
469         }
470     }
471 
472     /**
473      * Add all child <code>Configuration</code> objects from specified
474      * configuration element to current configuration element.
475      *
476      * @param other the other {@link Configuration} value
477      */
478     public void addAllChildren( final Configuration other )
479     {
480         checkWriteable();
481 
482         final Configuration[] children = other.getChildren();
483         for( int i = 0; i < children.length; i++ )
484         {
485             addChild( children[ i ] );
486         }
487     }
488 
489     /**
490      * Remove a child <code>Configuration</code> to this configuration element.
491      * @param configuration a <code>Configuration</code> value
492      */
493     public void removeChild( final Configuration configuration )
494     {
495         checkWriteable();
496 
497         if( null == m_children )
498         {
499             return;
500         }
501         m_children.remove( configuration );
502     }
503 
504     /**
505      * Return count of children.
506      * @return an <code>int</code> value
507      */
508     public int getChildCount()
509     {
510         if( null == m_children )
511         {
512             return 0;
513         }
514 
515         return m_children.size();
516     }
517 
518     /**
519      * Make this configuration read-only.
520      *
521      */
522     public void makeReadOnly()
523     {
524         m_readOnly = true;
525     }
526 
527     /**
528      * heck if this configuration is writeable.
529      *
530      * @throws IllegalStateException if this configuration s read-only
531      */
532     protected final void checkWriteable()
533         throws IllegalStateException  
534     {
535         if( m_readOnly )
536         {
537             throw new IllegalStateException  
538                 ( "Configuration is read only and can not be modified" );
539         }
540     }
541 }
542
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags