Java > Open Source Codes > org > apache > commons > collections > ExtendedProperties


1 /*
2  * Copyright 2001-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections;
17
18 import java.io.File ;
19 import java.io.FileInputStream ;
20 import java.io.IOException ;
21 import java.io.InputStream ;
22 import java.io.InputStreamReader ;
23 import java.io.LineNumberReader ;
24 import java.io.OutputStream ;
25 import java.io.PrintWriter ;
26 import java.io.Reader ;
27 import java.io.UnsupportedEncodingException ;
28 import java.util.ArrayList ;
29 import java.util.Enumeration ;
30 import java.util.Hashtable ;
31 import java.util.Iterator ;
32 import java.util.List ;
33 import java.util.NoSuchElementException ;
34 import java.util.Properties ;
35 import java.util.StringTokenizer ;
36 import java.util.Vector ;
37
38 /**
39  * This class extends normal Java properties by adding the possibility
40  * to use the same key many times concatenating the value strings
41  * instead of overwriting them.
42  * <p>
43  * <b>Please consider using the <code>PropertiesConfiguration</code> class in
44  * Commons-Configuration as soon as it is released.</b>
45  * <p>
46  * The Extended Properties syntax is explained here:
47  *
48  * <ul>
49  * <li>
50  * Each property has the syntax <code>key = value</code>
51  * </li>
52  * <li>
53  * The <i>key</i> may use any character but the equal sign '='.
54  * </li>
55  * <li>
56  * <i>value</i> may be separated on different lines if a backslash
57  * is placed at the end of the line that continues below.
58  * </li>
59  * <li>
60  * If <i>value</i> is a list of strings, each token is separated
61  * by a comma ','.
62  * </li>
63  * <li>
64  * Commas in each token are escaped placing a backslash right before
65  * the comma.
66  * </li>
67  * <li>
68  * Backslashes are escaped by using two consecutive backslashes i.e. \\
69  * </li>
70  * <li>
71  * If a <i>key</i> is used more than once, the values are appended
72  * like if they were on the same line separated with commas.
73  * </li>
74  * <li>
75  * Blank lines and lines starting with character '#' are skipped.
76  * </li>
77  * <li>
78  * If a property is named "include" (or whatever is defined by
79  * setInclude() and getInclude() and the value of that property is
80  * the full path to a file on disk, that file will be included into
81  * the ConfigurationsRepository. You can also pull in files relative
82  * to the parent configuration file. So if you have something
83  * like the following:
84  *
85  * include = additional.properties
86  *
87  * Then "additional.properties" is expected to be in the same
88  * directory as the parent configuration file.
89  *
90  * Duplicate name values will be replaced, so be careful.
91  *
92  * </li>
93  * </ul>
94  *
95  * <p>Here is an example of a valid extended properties file:
96  *
97  * <p><pre>
98  * # lines starting with # are comments
99  *
100  * # This is the simplest property
101  * key = value
102  *
103  * # A long property may be separated on multiple lines
104  * longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
105  * aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
106  *
107  * # This is a property with many tokens
108  * tokens_on_a_line = first token, second token
109  *
110  * # This sequence generates exactly the same result
111  * tokens_on_multiple_lines = first token
112  * tokens_on_multiple_lines = second token
113  *
114  * # commas may be escaped in tokens
115  * commas.escaped = Hi\, what'up?
116  * </pre>
117  *
118  * <p><b>NOTE</b>: this class has <b>not</b> been written for
119  * performance nor low memory usage. In fact, it's way slower than it
120  * could be and generates too much memory garbage. But since
121  * performance is not an issue during intialization (and there is not
122  * much time to improve it), I wrote it this way. If you don't like
123  * it, go ahead and tune it up!
124  *
125  * @since Commons Collections 1.0
126  * @version $Revision: 1.23 $ $Date: 2004/06/21 23:39:25 $
127  *
128  * @author <a HREF="mailto:stefano@apache.org">Stefano Mazzocchi</a>
129  * @author <a HREF="mailto:jon@latchkey.com">Jon S. Stevens</a>
130  * @author <a HREF="mailto:daveb@miceda-data">Dave Bryson</a>
131  * @author <a HREF="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
132  * @author <a HREF="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
133  * @author <a HREF="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
134  * @author <a HREF="mailto:kjohnson@transparent.com">Kent Johnson</a>
135  * @author <a HREF="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
136  * @author <a HREF="mailto:ipriha@surfeu.fi">Ilkka Priha</a>
137  * @author Janek Bogucki
138  * @author Mohan Kishore
139  * @author Stephen Colebourne
140  */
141 public class ExtendedProperties extends Hashtable {
142     
143     /**
144      * Default configurations repository.
145      */
146     private ExtendedProperties defaults;
147
148     /**
149      * The file connected to this repository (holding comments and
150      * such).
151      *
152      * @serial
153      */
154     protected String file;
155
156     /**
157      * Base path of the configuration file used to create
158      * this ExtendedProperties object.
159      */
160     protected String basePath;
161
162     /**
163      * File separator.
164      */
165     protected String fileSeparator = System.getProperty("file.separator");
166
167     /**
168      * Has this configuration been intialized.
169      */
170     protected boolean isInitialized = false;
171
172     /**
173      * This is the name of the property that can point to other
174      * properties file for including other properties files.
175      */
176     protected static String include = "include";
177
178     /**
179      * These are the keys in the order they listed
180      * in the configuration file. This is useful when
181      * you wish to perform operations with configuration
182      * information in a particular order.
183      */
184     protected ArrayList keysAsListed = new ArrayList ();
185
186     protected final static String START_TOKEN="${";
187     protected final static String END_TOKEN="}";
188
189
190     /**
191      * Interpolate key names to handle ${key} stuff
192      *
193      * @param base string to interpolate
194      * @return returns the key name with the ${key} substituted
195      */
196     protected String interpolate(String base) {
197         // COPIED from [configuration] 2003-12-29
198 return (interpolateHelper(base, null));
199     }
200
201     /**
202      * Recursive handler for multiple levels of interpolation.
203      *
204      * When called the first time, priorVariables should be null.
205      *
206      * @param base string with the ${key} variables
207      * @param priorVariables serves two purposes: to allow checking for
208      * loops, and creating a meaningful exception message should a loop
209      * occur. It's 0'th element will be set to the value of base from
210      * the first call. All subsequent interpolated variables are added
211      * afterward.
212      *
213      * @return the string with the interpolation taken care of
214      */
215     protected String interpolateHelper(String base, List priorVariables) {
216         // COPIED from [configuration] 2003-12-29
217 if (base == null) {
218             return null;
219         }
220
221         // on the first call initialize priorVariables
222 // and add base as the first element
223 if (priorVariables == null) {
224             priorVariables = new ArrayList ();
225             priorVariables.add(base);
226         }
227
228         int begin = -1;
229         int end = -1;
230         int prec = 0 - END_TOKEN.length();
231         String variable = null;
232         StringBuffer result = new StringBuffer ();
233
234         // FIXME: we should probably allow the escaping of the start token
235 while (((begin = base.indexOf(START_TOKEN, prec + END_TOKEN.length())) > -1)
236             && ((end = base.indexOf(END_TOKEN, begin)) > -1)) {
237             result.append(base.substring(prec + END_TOKEN.length(), begin));
238             variable = base.substring(begin + START_TOKEN.length(), end);
239
240             // if we've got a loop, create a useful exception message and throw
241 if (priorVariables.contains(variable)) {
242                 String initialBase = priorVariables.remove(0).toString();
243                 priorVariables.add(variable);
244                 StringBuffer priorVariableSb = new StringBuffer ();
245
246                 // create a nice trace of interpolated variables like so:
247 // var1->var2->var3
248 for (Iterator it = priorVariables.iterator(); it.hasNext();) {
249                     priorVariableSb.append(it.next());
250                     if (it.hasNext()) {
251                         priorVariableSb.append("->");
252                     }
253                 }
254
255                 throw new IllegalStateException (
256                     "infinite loop in property interpolation of " + initialBase + ": " + priorVariableSb.toString());
257             }
258             // otherwise, add this variable to the interpolation list.
259 else {
260                 priorVariables.add(variable);
261             }
262
263             //QUESTION: getProperty or getPropertyDirect
264 Object value = getProperty(variable);
265             if (value != null) {
266                 result.append(interpolateHelper(value.toString(), priorVariables));
267
268                 // pop the interpolated variable off the stack
269 // this maintains priorVariables correctness for
270 // properties with multiple interpolations, e.g.
271 // prop.name=${some.other.prop1}/blahblah/${some.other.prop2}
272 priorVariables.remove(priorVariables.size() - 1);
273             } else if (defaults != null && defaults.getString(variable, null) != null) {
274                 result.append(defaults.getString(variable));
275             } else {
276                 //variable not defined - so put it back in the value
277 result.append(START_TOKEN).append(variable).append(END_TOKEN);
278             }
279             prec = end;
280         }
281         result.append(base.substring(prec + END_TOKEN.length(), base.length()));
282
283         return result.toString();
284     }
285     
286     /**
287      * Inserts a backslash before every comma and backslash.
288      */
289     private static String escape(String s) {
290         StringBuffer buf = new StringBuffer (s);
291         for (int i = 0; i < buf.length(); i++) {
292             char c = buf.charAt(i);
293             if (c == ',' || c == '\\') {
294                 buf.insert(i, '\\');
295                 i++;
296             }
297         }
298         return buf.toString();
299     }
300     
301     /**
302      * Removes a backslash from every pair of backslashes.
303      */
304     private static String unescape(String s) {
305         StringBuffer buf = new StringBuffer (s);
306         for (int i = 0; i < buf.length() - 1; i++) {
307             char c1 = buf.charAt(i);
308             char c2 = buf.charAt(i + 1);
309             if (c1 == '\\' && c2 == '\\') {
310                 buf.deleteCharAt(i);
311             }
312         }
313         return buf.toString();
314     }
315
316     /**
317      * Counts the number of successive times 'ch' appears in the
318      * 'line' before the position indicated by the 'index'.
319      */
320     private static int countPreceding(String line, int index, char ch) {
321         int i;
322         for (i = index - 1; i >= 0; i--) {
323             if (line.charAt(i) != ch) {
324                 break;
325             }
326         }
327         return index - 1 - i;
328     }
329
330     /**
331      * Checks if the line ends with odd number of backslashes
332      */
333     private static boolean endsWithSlash(String line) {
334         if (!line.endsWith("\\")) {
335             return false;
336         }
337         return (countPreceding(line, line.length() - 1, '\\') % 2 == 0);
338     }
339
340     /**
341      * This class is used to read properties lines. These lines do
342      * not terminate with new-line chars but rather when there is no
343      * backslash sign a the end of the line. This is used to
344      * concatenate multiple lines for readability.
345      */
346     static class PropertiesReader extends LineNumberReader {
347         /**
348          * Constructor.
349          *
350          * @param reader A Reader.
351          */
352         public PropertiesReader(Reader reader) {
353             super(reader);
354         }
355
356         /**
357          * Read a property.
358          *
359          * @return a String property
360          * @throws IOException if there is difficulty reading the source.
361          */
362         public String readProperty() throws IOException {
363             StringBuffer buffer = new StringBuffer ();
364
365             try {
366                 while (true) {
367                     String line = readLine().trim();
368                     if ((line.length() != 0) && (line.charAt(0) != '#')) {
369                         if (endsWithSlash(line)) {
370                             line = line.substring(0, line.length() - 1);
371                             buffer.append(line);
372                         } else {
373                             buffer.append(line);
374                             break;
375                         }
376                     }
377                 }
378             } catch (NullPointerException ex) {
379                 return null;
380             }
381
382             return buffer.toString();
383         }
384     }
385
386     /**
387      * This class divides into tokens a property value. Token
388      * separator is "," but commas into the property value are escaped
389      * using the backslash in front.
390      */
391     static class PropertiesTokenizer extends StringTokenizer {
392         /**
393          * The property delimiter used while parsing (a comma).
394          */
395         static final String DELIMITER = ",";
396
397         /**
398          * Constructor.
399          *
400          * @param string A String.
401          */
402         public PropertiesTokenizer(String string) {
403             super(string, DELIMITER);
404         }
405
406         /**
407          * Check whether the object has more tokens.
408          *
409          * @return True if the object has more tokens.
410          */
411         public boolean hasMoreTokens() {
412             return super.hasMoreTokens();
413         }
414
415         /**
416          * Get next token.
417          *
418          * @return A String.
419          */
420         public String nextToken() {
421             StringBuffer buffer = new StringBuffer ();
422
423             while (hasMoreTokens()) {
424                 String token = super.nextToken();
425                 if (endsWithSlash(token)) {
426                     buffer.append(token.substring(0, token.length() - 1));
427                     buffer.append(DELIMITER);
428                 } else {
429                     buffer.append(token);
430                     break;
431                 }
432             }
433
434             return buffer.toString().trim();
435         }
436     }
437
438     /**
439      * Creates an empty extended properties object.
440      */
441     public ExtendedProperties() {
442         super();
443     }
444
445     /**
446      * Creates and loads the extended properties from the specified file.
447      *
448      * @param file the filename to load
449      * @throws IOException if a file error occurs
450      */
451     public ExtendedProperties(String file) throws IOException {
452         this(file, null);
453     }
454
455     /**
456      * Creates and loads the extended properties from the specified file.
457      *
458      * @param file the filename to load
459      * @param defaultFile a second filename to load default values from
460      * @throws IOException if a file error occurs
461      */
462     public ExtendedProperties(String file, String defaultFile) throws IOException {
463         this.file = file;
464
465         basePath = new File (file).getAbsolutePath();
466         basePath = basePath.substring(0, basePath.lastIndexOf(fileSeparator) + 1);
467
468         FileInputStream in = null;
469         try {
470             in = new FileInputStream (file);
471             this.load(in);
472         } finally {
473             try {
474                 if (in != null) {
475                     in.close();
476                 }
477             } catch (IOException ex) {}
478         }
479
480         if (defaultFile != null) {
481             defaults = new ExtendedProperties(defaultFile);
482         }
483     }
484
485     /**
486      * Indicate to client code whether property
487      * resources have been initialized or not.
488      */
489     public boolean isInitialized() {
490         return isInitialized;
491     }
492
493     /**
494      * Gets the property value for including other properties files.
495      * By default it is "include".
496      *
497      * @return A String.
498      */
499     public String getInclude() {
500         return include;
501     }
502
503     /**
504      * Sets the property value for including other properties files.
505      * By default it is "include".
506      *
507      * @param inc A String.
508      */
509     public void setInclude(String inc) {
510         include = inc;
511     }
512
513     /**
514      * Load the properties from the given input stream.
515      *
516      * @param input the InputStream to load from
517      * @throws IOException if an IO error occurs
518      */
519     public void load(InputStream input) throws IOException {
520         load(input, null);
521     }
522
523     /**
524      * Load the properties from the given input stream
525      * and using the specified encoding.
526      *
527      * @param input the InputStream to load from
528      * @param enc the encoding to use
529      * @throws IOException if an IO error occurs
530      */
531     public synchronized void load(InputStream input, String enc) throws IOException {
532         PropertiesReader reader = null;
533         if (enc != null) {
534             try {
535                 reader = new PropertiesReader(new InputStreamReader (input, enc));
536                 
537             } catch (UnsupportedEncodingException ex) {
538                 // Another try coming up....
539 }
540         }
541         
542         if (reader == null) {
543             try {
544                 reader = new PropertiesReader(new InputStreamReader (input, "8859_1"));
545                 
546             } catch (UnsupportedEncodingException ex) {
547                 // ISO8859-1 support is required on java platforms but....
548 // If it's not supported, use the system default encoding
549 reader = new PropertiesReader(new InputStreamReader (input));
550             }
551         }
552
553         try {
554             while (true) {
555                 String line = reader.readProperty();
556                 int equalSign = line.indexOf('=');
557
558                 if (equalSign > 0) {
559                     String key = line.substring(0, equalSign).trim();
560                     String value = line.substring(equalSign + 1).trim();
561
562                     // Configure produces lines like this ... just ignore them
563 if ("".equals(value)) {
564                         continue;
565                     }
566
567                     if (getInclude() != null && key.equalsIgnoreCase(getInclude())) {
568                         // Recursively load properties files.
569 File file = null;
570
571                         if (value.startsWith(fileSeparator)) {
572                             // We have an absolute path so we'll use this
573 file = new File (value);
574                             
575                         } else {
576                             // We have a relative path, and we have two
577 // possible forms here. If we have the "./" form
578 // then just strip that off first before continuing.
579 if (value.startsWith("." + fileSeparator)) {
580                                 value = value.substring(2);
581                             }
582
583                             file = new File (basePath + value);
584                         }
585
586                         if (file != null && file.exists() && file.canRead()) {
587                             load(new FileInputStream (file));
588                         }
589                     } else {
590                         addProperty(key, value);
591                     }
592                 }
593             }
594         } catch (NullPointerException ex) {
595             // Should happen only when EOF is reached.
596 return;
597         } finally {
598             // Loading is initializing
599 isInitialized = true;
600         }
601     }
602
603     /**
604      * Gets a property from the configuration.
605      *
606      * @param key property to retrieve
607      * @return value as object. Will return user value if exists,
608      * if not then default value if exists, otherwise null
609      */
610     public Object getProperty(String key) {
611         // first, try to get from the 'user value' store
612 Object obj = this.get(key);
613
614         if (obj == null) {
615             // if there isn't a value there, get it from the
616 // defaults if we have them
617 if (defaults != null) {
618                 obj = defaults.get(key);
619             }
620         }
621
622         return obj;
623     }
624     
625     /**
626      * Add a property to the configuration. If it already
627      * exists then the value stated here will be added
628      * to the configuration entry. For example, if
629      *
630      * <code>resource.loader = file</code>
631      *
632      * is already present in the configuration and you
633      *
634      * <code>addProperty("resource.loader", "classpath")</code>
635      *
636      * Then you will end up with a Vector like the
637      * following:
638      *
639      * <code>["file", "classpath"]</code>
640      *
641      * @param key the key to add
642      * @param value the value to add
643      */
644     public void addProperty(String key, Object value) {
645         if (value instanceof String ) {
646             String str = (String ) value;
647             if (str.indexOf(PropertiesTokenizer.DELIMITER) > 0) {
648                 // token contains commas, so must be split apart then added
649 PropertiesTokenizer tokenizer = new PropertiesTokenizer(str);
650                 while (tokenizer.hasMoreTokens()) {
651                     String token = tokenizer.nextToken();
652                     addPropertyInternal(key, unescape(token));
653                 }
654             } else {
655                 // token contains no commas, so can be simply added
656 addPropertyInternal(key, unescape(str));
657             }
658         } else {
659             addPropertyInternal(key, value);
660         }
661
662         // Adding a property connotes initialization
663 isInitialized = true;
664     }
665
666     /**
667      * Adds a key/value pair to the map. This routine does
668      * no magic morphing. It ensures the keylist is maintained
669      *
670      * @param key the key to store at
671      * @param value the decoded object to store
672      */
673     private void addPropertyDirect(String key, Object value) {
674         // safety check
675 if (!containsKey(key)) {
676             keysAsListed.add(key);
677         }
678         put(key, value);
679     }
680
681     /**
682      * Adds a decoded property to the map w/o checking for commas - used
683      * internally when a property has been broken up into
684      * strings that could contain escaped commas to prevent
685      * the inadvertent vectorization.
686      * <p>
687      * Thanks to Leon Messerschmidt for this one.
688      *
689      * @param key the key to store at
690      * @param value the decoded object to store
691      */
692     private void addPropertyInternal(String key, Object value) {
693         Object current = this.get(key);
694
695         if (current instanceof String ) {
696             // one object already in map - convert it to a vector
697 Vector v = new Vector (2);
698             v.addElement(current);
699             v.addElement(value);
700             put(key, v);
701             
702         } else if (current instanceof Vector ) {
703             // already a vector - just add the new token
704 ((Vector ) current).addElement(value);
705             
706         } else {
707             // brand new key - store in keysAsListed to retain order
708 if (!containsKey(key)) {
709                 keysAsListed.add(key);
710             }
711             put(key, value);
712         }
713     }
714
715     /**
716      * Set a property, this will replace any previously
717      * set values. Set values is implicitly a call
718      * to clearProperty(key), addProperty(key,value).
719      *
720      * @param key the key to set
721      * @param value the value to set
722      */
723     public void setProperty(String key, Object value) {
724         clearProperty(key);
725         addProperty(key, value);
726     }
727     
728     /**
729      * Save the properties to the given output stream.
730      * <p>
731      * The stream is not closed, but it is flushed.
732      *
733      * @param output an OutputStream, may be null
734      * @param header a textual comment to act as a file header
735      * @throws IOException if an IO error occurs
736      */
737     public synchronized void save(OutputStream output, String header) throws IOException {
738         if (output == null) {
739             return;
740         }
741         PrintWriter theWrtr = new PrintWriter (output);
742         if (header != null) {
743             theWrtr.println(header);
744         }
745         
746         Enumeration theKeys = keys();
747         while (theKeys.hasMoreElements()) {
748             String key = (String ) theKeys.nextElement();
749             Object value = get(key);
750             if (value != null) {
751                 if (value instanceof String ) {
752                     StringBuffer currentOutput = new StringBuffer ();
753                     currentOutput.append(key);
754                     currentOutput.append("=");
755                     currentOutput.append(escape((String ) value));
756                     theWrtr.println(currentOutput.toString());
757                     
758                 } else if (value instanceof Vector ) {
759                     Vector values = (Vector ) value;
760                     Enumeration valuesEnum = values.elements();
761                     while (valuesEnum.hasMoreElements()) {
762                         String currentElement = (String ) valuesEnum.nextElement();
763                         StringBuffer currentOutput = new StringBuffer ();
764                         currentOutput.append(key);
765                         currentOutput.append("=");
766                         currentOutput.append(escape(currentElement));
767                         theWrtr.println(currentOutput.toString());
768                     }
769                 }
770             }
771             theWrtr.println();
772             theWrtr.flush();
773         }
774     }
775
776     /**
777      * Combines an existing Hashtable with this Hashtable.
778      * <p>
779      * Warning: It will overwrite previous entries without warning.
780      *
781      * @param props the properties to combine
782      */
783     public void combine(ExtendedProperties props) {
784         for (Iterator it = props.getKeys(); it.hasNext();) {
785             String key = (String ) it.next();
786             setProperty(key, props.get(key));
787         }
788     }
789     
790     /**
791      * Clear a property in the configuration.
792      *
793      * @param key the property key to remove along with corresponding value
794      */
795     public void clearProperty(String key) {
796         if (containsKey(key)) {
797             // we also need to rebuild the keysAsListed or else
798 // things get *very* confusing
799 for (int i = 0; i < keysAsListed.size(); i++) {
800                 if (( keysAsListed.get(i)).equals(key)) {
801                     keysAsListed.remove(i);
802                     break;
803                 }
804             }
805             remove(key);
806         }
807     }
808
809     /**
810      * Get the list of the keys contained in the configuration
811      * repository.
812      *
813      * @return an Iterator over the keys
814      */
815     public Iterator getKeys() {
816         return keysAsListed.iterator();
817     }
818
819     /**
820      * Get the list of the keys contained in the configuration
821      * repository that match the specified prefix.
822      *
823      * @param prefix the prefix to match
824      * @return an Iterator of keys that match the prefix
825      */
826     public