CascadingConfiguration


1   /*
2   
3    ============================================================================
4                      The Apache Software License, Version 1.1
5    ============================================================================
6    
7    Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved.
8    
9    Redistribution and use in source and binary forms, with or without modifica-
10   tion, are permitted provided that the following conditions are met:
11   
12   1. Redistributions of  source code must  retain the above copyright  notice,
13      this list of conditions and the following disclaimer.
14   
15   2. Redistributions in binary form must reproduce the above copyright notice,
16      this list of conditions and the following disclaimer in the documentation
17      and/or other materials provided with the distribution.
18   
19   3. The end-user documentation included with the redistribution, if any, must
20      include  the following  acknowledgment:  "This product includes  software
21      developed  by the  Apache Software Foundation  (http://www.apache.org/)."
22      Alternately, this  acknowledgment may  appear in the software itself,  if
23      and wherever such third-party acknowledgments normally appear.
24   
25   4. The names "Jakarta", "Avalon", "Excalibur" and "Apache Software Foundation"  
26      must not be used to endorse or promote products derived from this  software 
27      without  prior written permission. For written permission, please contact 
28      apache@apache.org.
29   
30   5. Products  derived from this software may not  be called "Apache", nor may
31      "Apache" appear  in their name,  without prior written permission  of the
32      Apache Software Foundation.
33   
34   THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
35   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
36   FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
37   APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
38   INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
39   DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
40   OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
41   ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
42   (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
43   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44   
45   This software  consists of voluntary contributions made  by many individuals
46   on  behalf of the Apache Software  Foundation. For more  information on the 
47   Apache Software Foundation, please see <http://www.apache.org/>.
48   
49  */
50  
51  package org.apache.excalibur.configuration;
52  
53  import org.apache.avalon.framework.configuration.Configuration;
54  import org.apache.avalon.framework.configuration.ConfigurationException;
55  import org.apache.avalon.framework.configuration.DefaultConfiguration;
56  
57  /**
58   * The CascadingConfiguration is a classic Configuration backed by parent
59   * Configuration.  Operations such as getChild return a CascadingConfiguration
60   * encapsulating both a primary and parent configuration.  Requests for attribute
61   * values are resolved against the base configuration initially.  If the result
62   * of the resolution is unsucessful, the request is applied against the parent
63   * configuration.  As a parent may also be a CascadingConfiguration, the evaluation
64   * will be applied until a value is resolved against a class parent Configuration.
65   * @author Stephen McConnell <mcconnell@osm.net>
66   */
67  public class CascadingConfiguration implements Configuration
68  {
69      //=============================================================================
70      // state
71      //=============================================================================
72  
73      /**
74       * The primary configuration.
75       */
76      private final Configuration m_base;
77  
78      /**
79       * The fallback configuration.
80       */
81      private final Configuration m_parent;
82  
83      //=============================================================================
84      // constructors
85      //=============================================================================
86  
87      /**
88       * Create a CascadingConfiguration with specified parent.  The base
89       * configuration shall override a parent configuration on request for
90       * attribute values and configuration body values.  Unresolved request
91       * are redirected up the parent chain until a classic configuration is
92       * reached.  Request for child configurations will return a
93       * new CascadingConfiguration referencing the child of the base and
94       * the child of the primary (i.e. a child configuration chain).
95       *
96       * @param base the base Configuration
97       * @param parent the parent Configuration
98       */
99      public CascadingConfiguration( final Configuration base, final Configuration parent )
100     {
101         if( base == null )
102         {
103             m_base = new DefaultConfiguration( "-", null );
104         }
105         else
106         {
107             m_base = base;
108         }
109         if( parent == null )
110         {
111             m_parent = new DefaultConfiguration( "-", null );
112         }
113         else
114         {
115             m_parent = parent;
116         }
117     }
118 
119     //=============================================================================
120     // Configuration
121     //=============================================================================
122 
123     /**
124      * Return the name of the base node.
125      * @return name of the <code>Configuration</code> node.
126      */
127     public String   getName()
128     {
129         return m_base.getName();
130     }
131 
132     /**
133      * Return a string describing location of the base Configuration.
134      * Location can be different for different mediums (ie "file:line" for normal XML files or
135      * "table:primary-key" for DB based configurations);
136      *
137      * @return a string describing location of Configuration
138      */
139     public String   getLocation()
140     {
141         return m_base.getLocation();
142     }
143 
144     /**
145      * Returns the namespace the main Configuration node
146      * belongs to.
147      * @exception ConfigurationException may be thrown by the underlying configuration
148      * @since 4.1
149      * @return a Namespace identifying the namespace of this Configuration.
150      */
151     public String   getNamespace() throws ConfigurationException
152     {
153         return m_base.getNamespace();
154     }
155 
156     /**
157      * Return a new <code>CascadingConfiguration</code> instance encapsulating the
158      * specified child node of the base and parent node.
159      *
160      * @param child The name of the child node.
161      * @return Configuration
162      */
163     public Configuration getChild( String   child )
164     {
165         return new CascadingConfiguration( m_base.getChild( child ), m_parent.getChild( child ) );
166     }
167 
168     /**
169      * Return a <code>Configuration</code> instance encapsulating the specified
170      * child node.
171      *
172      * @param child The name of the child node.
173      * @param createNew If <code>true</code>, a new <code>Configuration</code>
174      * will be created and returned if the specified child does not exist in either
175      * the base or parent configuratioin. If <code>false</code>, <code>null</code>
176      * will be returned when the specified child doesn't exist in either the base or
177      * the parent.
178      * @return Configuration
179      */
180     public Configuration getChild( String   child, boolean createNew )
181     {
182         if( createNew )
183         {
184             return getChild( child );
185         }
186         Configuration c = m_base.getChild( child, false );
187         if( c != null )
188         {
189             return c;
190         }
191         return m_parent.getChild( child, false );
192     }
193 
194     /**
195      * Return an <code>Array</code> of <code>Configuration</code>
196      * elements containing all node children of both base and parent configurations.
197      * The array order will reflect the order in the source config file, commencing
198      * with the base configuration.
199      *
200      * @return All child nodes
201      */
202     public Configuration[] getChildren()
203     {
204         Configuration[] b = m_base.getChildren();
205         Configuration[] p = m_parent.getChildren();
206         Configuration[] result = new Configuration[ b.length + p.length ];
207         System.arraycopy( b, 0, result, 0, b.length );
208         System.arraycopy( p, 0, result, b.length, p.length );
209         return result;
210     }
211 
212     /**
213      * Return an <code>Array</code> of <code>Configuration</code>
214      * elements containing all node children with the specified name from
215      * both base and parent configurations. The array
216      * order will reflect the order in the source config file commencing
217      * with the base configuration.
218      *
219      * @param name The name of the children to get.
220      * @return The child nodes with name <code>name</code>
221      */
222     public Configuration[] getChildren( String   name )
223     {
224         Configuration[] b = m_base.getChildren( name );
225         Configuration[] p = m_parent.getChildren( name );
226         Configuration[] result = new Configuration[ b.length + p.length ];
227         System.arraycopy( b, 0, result, 0, b.length );
228         System.arraycopy( p, 0, result, b.length, p.length );
229         return result;
230     }
231 
232     /**
233      * Return an array of all attribute names in both base and parent.
234      * <p>
235      * <em>The order of attributes in this array can not be relied on.</em> As
236      * with XML, a <code>Configuration</code>'s attributes are an
237      * <em>unordered</em> set. If your code relies on order, eg
238      * <tt>conf.getAttributeNames()[0]</tt>, then it is liable to break if a
239      * different XML parser is used.
240      * </p>
241      * @return an array of all attribute names
242      */
243     public String  [] getAttributeNames()
244     {
245         java.util.Vector   vector = new java.util.Vector  ();
246         String  [] names = m_base.getAttributeNames();
247         String  [] names2 = m_parent.getAttributeNames();
248         for( int i = 0; i < names.length; i++ )
249         {
250             vector.add( names[ i ] );
251         }
252         for( int i = 0; i < names2.length; i++ )
253         {
254             if( vector.indexOf( names2[ i ] ) < 0 )
255             {
256                 vector.add( names2[ i ] );
257             }
258         }
259         return (String  [])vector.toArray( new String  [ 0 ] );
260     }
261 
262     /**
263      * Return the value of specified attribute.  If the base configuration
264      * does not contain the attribute, the equivialent operation is applied to
265      * the parent configuration.
266      *
267      * @param paramName The name of the parameter you ask the value of.
268      * @return String value of attribute.
269      * @exception ConfigurationException If no attribute with that name exists.
270      */
271     public String   getAttribute( String   paramName ) throws ConfigurationException
272     {
273         try
274         {
275             return m_base.getAttribute( paramName );
276         }
277         catch( ConfigurationException e )
278         {
279             return m_parent.getAttribute( paramName );
280         }
281     }
282 
283     /**
284      * Return the <code>int</code> value of the specified attribute contained
285      * in this node or the parent.
286      * @param paramName The name of the parameter you ask the value of.
287      * @return int value of attribute
288      * @exception ConfigurationException If no parameter with that name exists.
289      *                                   or if conversion to <code>int</code> fails.
290      */
291     public int getAttributeAsInteger( String   paramName ) throws ConfigurationException
292     {
293         try
294         {
295             return m_base.getAttributeAsInteger( paramName );
296         }
297         catch( ConfigurationException e )
298         {
299             return m_parent.getAttributeAsInteger( paramName );
300         }
301     }
302 
303     /**
304      * Returns the value of the attribute specified by its name as a
305      * <code>long</code>.
306      *
307      * @param name The name of the parameter you ask the value of.
308      * @return long value of attribute
309      * @exception ConfigurationException If no parameter with that name exists.
310      *                                   or if conversion to <code>long</code> fails.
311      */
312     public long getAttributeAsLong( String   name ) throws ConfigurationException
313     {
314         try
315         {
316             return m_base.getAttributeAsLong( name );
317         }
318         catch( ConfigurationException e )
319         {
320             return m_parent.getAttributeAsLong( name );
321         }
322     }
323 
324     /**
325      * Return the <code>float</code> value of the specified parameter contained
326      * in this node.
327      * @param paramName The name of the parameter you ask the value of.
328      * @return float value of attribute
329      * @exception ConfigurationException If no parameter with that name exists.
330      *                                   or if conversion to <code>float</code> fails.
331      */
332     public float getAttributeAsFloat( String   paramName ) throws ConfigurationException
333     {
334         try
335         {
336             return m_base.getAttributeAsFloat( paramName );
337         }
338         catch( ConfigurationException e )
339         {
340             return m_parent.getAttributeAsFloat( paramName );
341         }
342     }
343 
344     /**
345      * Return the <code>boolean</code> value of the specified parameter contained
346      * in this node.
347      *
348      * @param paramName The name of the parameter you ask the value of.
349      * @return boolean value of attribute
350      * @exception ConfigurationException If no parameter with that name exists.
351      *                                   or if conversion to <code>boolean</code> fails.
352      */
353     public boolean getAttributeAsBoolean( String   paramName ) throws ConfigurationException
354     {
355         try
356         {
357             return m_base.getAttributeAsBoolean( paramName );
358         }
359         catch( ConfigurationException e )
360         {
361             return m_parent.getAttributeAsBoolean( paramName );
362         }
363     }
364 
365     /**
366      * Return the <code>String</code> value of the node.
367      *
368      * @return the value of the node.
369      * @exception ConfigurationException May be raised by underlying
370      *                                   base or parent configuration.
371      */
372     public String   getValue() throws ConfigurationException
373     {
374         try
375         {
376             return m_base.getValue();
377         }
378         catch( ConfigurationException e )
379         {
380             return m_parent.getValue();
381         }
382     }
383 
384     /**
385      * Return the <code>int</code> value of the node.
386      * @return int the value as an integer
387      * @exception ConfigurationException If conversion to <code>int</code> fails.
388      */
389     public int getValueAsInteger() throws ConfigurationException
390     {
391         try
392         {
393             return m_base.getValueAsInteger();
394         }
395         catch( ConfigurationException e )
396         {
397             return m_parent.getValueAsInteger();
398         }
399     }
400 
401     /**
402      * Return the <code>float</code> value of the node.
403      *
404      * @return the value of the node.
405      * @exception ConfigurationException If conversion to <code>float</code> fails.
406      */
407     public float getValueAsFloat() throws ConfigurationException
408     {
409         try
410         {
411             return m_base.getValueAsFloat();
412         }
413         catch( ConfigurationException e )
414         {
415             return m_parent.getValueAsFloat();
416         }
417     }
418 
419     /**
420      * Return the <code>boolean</code> value of the node.
421      *
422      * @return the value of the node.
423      * @exception ConfigurationException If conversion to <code>boolean</code> fails.
424      */
425     public boolean getValueAsBoolean() throws ConfigurationException
426     {
427         try
428         {
429             return m_base.getValueAsBoolean();
430         }
431         catch( ConfigurationException e )
432         {
433             return m_parent.getValueAsBoolean();
434         }
435     }
436 
437     /**
438      * Return the <code>long</code> value of the node.
439      *
440      * @return the value of the node.
441      * @exception ConfigurationException If conversion to <code>long</code> fails.
442      */
443     public long getValueAsLong() throws ConfigurationException
444     {
445         try
446         {
447             return m_base.getValueAsLong();
448         }
449         catch( ConfigurationException e )
450         {
451             return m_parent.getValueAsLong();
452         }
453     }
454 
455     /**
456      * Returns the value of the configuration element as a <code>String</code>.
457      * If the configuration value is not set, the default value will be
458      * used.
459      *
460      * @param defaultValue The default value desired.
461      * @return String value of the <code>Configuration</code>, or default
462      *          if none specified.
463      */
464     public String   getValue( String   defaultValue )
465     {
466         try
467         {
468             return m_base.getValue();
469         }
470         catch( ConfigurationException e )
471         {
472             return m_parent.getValue( defaultValue );
473         }
474     }
475 
476     /**
477      * Returns the value of the configuration element as an <code>int</code>.
478      * If the configuration value is not set, the default value will be
479      * used.
480      *
481      * @param defaultValue The default value desired.
482      * @return int value of the <code>Configuration</code>, or default
483      *          if none specified.
484      */
485     public int getValueAsInteger( int defaultValue )
486     {
487         try
488         {
489             return m_base.getValueAsInteger();
490         }
491         catch( ConfigurationException e )
492         {
493             return m_parent.getValueAsInteger( defaultValue );
494         }
495     }
496 
497     /**
498      * Returns the value of the configuration element as a <code>long</code>.
499      * If the configuration value is not set, the default value will be
500      * used.
501      *
502      * @param defaultValue The default value desired.
503      * @return long value of the <code>Configuration</code>, or default
504      *          if none specified.
505      */
506     public long getValueAsLong( long defaultValue )
507     {
508         try
509         {
510             return m_base.getValueAsLong();
511         }
512         catch( ConfigurationException e )
513         {
514             return m_parent.getValueAsLong( defaultValue );
515         }
516     }
517 
518     /**
519      * Returns the value of the configuration element as a <code>float</code>.
520      * If the configuration value is not set, the default value will be
521      * used.
522      *
523      * @param defaultValue The default value desired.
524      * @return float value of the <code>Configuration</code>, or default
525      *          if none specified.
526      */
527     public float getValueAsFloat( float defaultValue )
528     {
529         try
530         {
531             return m_base.getValueAsFloat();
532         }
533         catch( ConfigurationException e )
534         {
535             return m_parent.getValueAsFloat( defaultValue );
536         }
537     }
538 
539     /**
540      * Returns the value of the configuration element as a <code>boolean</code>.
541      * If the configuration value is not set, the default value will be
542      * used.
543      *
544      * @param defaultValue The default value desired.
545      * @return boolean value of the <code>Configuration</code>, or default
546      *          if none specified.
547      */
548     public boolean getValueAsBoolean( boolean defaultValue )
549     {
550         try
551         {
552             return m_base.getValueAsBoolean();
553         }
554         catch( ConfigurationException e )
555         {
556             return m_parent.getValueAsBoolean( defaultValue );
557         }
558     }
559 
560     /**
561      * Returns the value of the attribute specified by its name as a
562      * <code>String</code>, or the default value if no attribute by
563      * that name exists or is empty.
564      *
565      * @param name The name of the attribute you ask the value of.
566      * @param defaultValue The default value desired.
567      * @return String value of attribute. It will return the default
568      *         value if the named attribute does not exist, or if
569      *         the value is not set.
570      */
571     public String   getAttribute( String   name, String   defaultValue )
572     {
573         try
574         {
575             return m_base.getAttribute( name );
576         }
577         catch( ConfigurationException e )
578         {
579             return m_parent.getAttribute( name, defaultValue );
580         }
581     }
582 
583     /**
584      * Returns the value of the attribute specified by its name as a
585      * <code>int</code>, or the default value if no attribute by
586      * that name exists or is empty.
587      *
588      * @param name The name of the attribute you ask the value of.
589      * @param defaultValue The default value desired.
590      * @return int value of attribute. It will return the default
591      *         value if the named attribute does not exist, or if
592      *         the value is not set.
593      */
594     public int getAttributeAsInteger( String   name, int defaultValue )
595     {
596         try
597         {
598             return m_base.getAttributeAsInteger( name );
599         }
600         catch( ConfigurationException e )
601         {
602             return m_parent.getAttributeAsInteger( name, defaultValue );
603         }
604     }
605 
606     /**
607      * Returns the value of the attribute specified by its name as a
608      * <code>long</code>, or the default value if no attribute by
609      * that name exists or is empty.
610      *
611      * @param name The name of the attribute you ask the value of.
612      * @param defaultValue The default value desired.
613      * @return long value of attribute. It will return the default
614      *          value if the named attribute does not exist, or if
615      *          the value is not set.
616      */
617     public long getAttributeAsLong( String   name, long defaultValue )
618     {
619         try
620         {
621             return m_base.getAttributeAsLong( name );
622         }
623         catch( ConfigurationException e )
624         {
625             return m_parent.getAttributeAsLong( name, defaultValue );
626         }
627     }
628 
629     /**
630      * Returns the value of the attribute specified by its name as a
631      * <code>float</code>, or the default value if no attribute by
632      * that name exists or is empty.
633      *
634      * @param name The name of the attribute you ask the value of.
635      * @param defaultValue The default value desired.
636      * @return float value of attribute. It will return the default
637      *          value if the named attribute does not exist, or if
638      *          the value is not set.
639      */
640     public float getAttributeAsFloat( String   name, float defaultValue )
641     {
642         try
643         {
644             return m_base.getAttributeAsFloat( name );
645         }
646         catch( ConfigurationException e )
647         {
648             return m_parent.getAttributeAsFloat( name, defaultValue );
649         }
650     }
651 
652     /**
653      * Returns the value of the attribute specified by its name as a
654      * <code>boolean</code>, or the default value if no attribute by
655      * that name exists or is empty.
656      *
657      * @param name The name of the attribute you ask the value of.
658      * @param defaultValue The default value desired.
659      * @return boolean value of attribute. It will return the default
660      *         value if the named attribute does not exist, or if
661      *         the value is not set.
662      */
663     public boolean getAttributeAsBoolean( String   name, boolean defaultValue )
664     {
665         try
666         {
667             return m_base.getAttributeAsBoolean( name );
668         }
669         catch( ConfigurationException e )
670         {
671             return m_parent.getAttributeAsBoolean( name, defaultValue );
672         }
673     }
674 }
675 
676 
677 
678
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags