Source code: com/gersonworks/xml/util/XMLProperties.java

   /*
    * XMLProperties library - A utility class which reads property lists from
    * an XML document
    * Copyright (C) 21 January 2004 Gerson Galang
    * This library is free software; you can redistribute it and/or
    * modify it under the terms of the GNU Lesser General Public
    * License as published by the Free Software Foundation; either
    * version 2.1 of the License, or (at your option) any later version.
    *
   * This library is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   * Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public
   * License along with this library; if not, write to the Free Software
   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   * For any questions or suggestions, you can email me at :
   * Email: gerson721@gawab.com
  */
  
  package com.gersonworks.xml.util;
  
  import java.util.Iterator;
  import java.util.Map;
  import java.util.HashMap;
  import java.util.Set;
  import java.util.Properties;
  import java.util.Map.Entry;
  
  import java.io.File;
  import java.io.InputStream;
  import java.io.OutputStream;
  import java.io.Writer;
  import java.io.PrintWriter;
  
  /**
   * The XMLProperties class represents a way of storing and retrieving properties
   * data into and from an XML file. Each property key corresponds to an
   * XMLPropertyValues object which may contain one or more property values.
   * <p>
   * Since the idea of implementing this class came from how the
   * java.util.Properties class works, most of the methods provided by this class
   * are similar to the functionality provided by the java.util.Properties'
   * methods.
   * <p>
   * The main difference of this class from java.util.Properties class is that
   * a property in XMLProperties may contain one or more property values. Another
   * difference is that this class now reads in an XML document.
   * <p>
   * The order of how the keys were originally sorted cannot be guaranteed when
   * the loaded property list is stored back into the XML properties file. It was
   * implemented this way for simplicity. What I can only guarantee is that all
   * the keys and its corresponding value/s will be in the properties file.
   * <p>
   * The XMLProperties class reads an XML document of the following format:
   *
   * <pre>
   *  &lt;properties&gt;
   *  &lt;!-- This is my XML configuration file --&gt;
   *  &nbsp;&nbsp;&lt;property key=&quot;key1&quot;&gt;
   *  &nbsp;&nbsp;&nbsp;&nbsp;&lt;value&gt;key1Value1&lt;/value&gt;
   *  &nbsp;&nbsp;&nbsp;&nbsp;&lt;value&gt;key1Value2&lt;/value&gt;
   *  &nbsp;&nbsp;&lt;/property&gt;
   *  &nbsp;&nbsp;&lt;property key=&quot;key2&quot;&gt;
   *  &nbsp;&nbsp;&nbsp;&nbsp;&lt;value&gt;&lt;/value&gt;
   *  &nbsp;&nbsp;&lt;/property&gt;
   *  &lt;/properties&gt;
   * </pre>
   *
   * XMLProperties can only recognize the following elements:
   * <p>
   *   <ol>
   *     <li>
   *        <tt>properties</tt> - is the <tt>root</tt> element of the XML
   *        properties document. This element is usually composed of more than
   *        one <tt>property</tt> elements but it is also possible for this
   *        element to be an empty element.
   *     </li>
   *     <li>
   *        <tt>property</tt> - is the child of the properties element and the
   *        parent of the value element. The <tt>property</tt> element has a
   *        <tt>key</tt> attribute which serves as the key to the property values.
   *        The <tt>property</tt> element is only allowed to have the
   *        <tt>value</tt> element as its child. It cannot contain any text (or
   *        simple) contents under it.
   *      </li>
   *      <li>
   *        <tt>value</tt> - is the child of the property element. There should be
   *        at least one <tt>value</tt> element for each <tt>property</tt>
   *        element. The <tt>value</tt> element can be an empty element but it
   *        cannot contain any other elements except a text (or a simple) content.
   *     </li>
   *   </ol>
   * <p>
   * The rules specified by each element should be followed to avoid
   * XMLPropertiesFormatException to be thrown. This exception is always thrown
   * whenever an unrecognized element is inserted into the XML properties
   * document.
  *
  * <p>Copyright: Copyright (c) 21 January 2004</p>
  * @author Gerson Galang
  * @version 1.1, 29 January 2004
  * @see java.util.Properties
  */
 public class XMLProperties {
 
   // the map wrapped by this class
   private Map xmlProperties;
 
   protected XMLProperties defaultXMLProps;
 
   /**
    * Creates an empty property list with no defaults.
    */
   public XMLProperties() {
     xmlProperties = new HashMap();
     defaultXMLProps = null;
   }
 
   /**
    * Creates an empty property list with a default XMLProperties.
    *
    * @param defaultXMLProps the default XMLProperties
    * @since XMLProperties version 1.1
    */
   public XMLProperties(XMLProperties defaultXMLProps) {
     xmlProperties = new HashMap();
     this.defaultXMLProps = defaultXMLProps;
   }
 
   /**
    * Creates an empty property list with a default java.util.Properties.
    *
    * @param defaultJavaProps the default java.util.Properties
    * @since XMLProperties version 1.1
    */
   public XMLProperties(Properties defaultJavaProps) {
     xmlProperties = new HashMap();
     defaultXMLProps = new XMLProperties();
     Set mapEntrySet = defaultJavaProps.entrySet();
     // Map's putAll() method cannot be used in adding the properties
     // into this class' property list because java.util.Properties has
     // a different format for its property value.
     for (Iterator mapIterator = mapEntrySet.iterator();
          mapIterator.hasNext(); ) {
       Map.Entry mapEntry = (Map.Entry)mapIterator.next();
       defaultXMLProps.setProperty(mapEntry.getKey().toString(),
                   mapEntry.getValue().toString());
     }
   }
 
   /**
    * Locates the property values for the corresponding key.
    *
    * @param key the property key.
    * @return the property values of the input key, or null if key is not found.
    */
   public XMLPropertyValues getPropertyValues(String key) {
     return getPropertyValues(key, null);
   }
 
   /**
    * Locates the property values for the corresponding key. If the key is not
    * found, the search returns the default XMLPropertyValues parameter of this
    * method.
    *
    * @param key the property key.
    * @param defaultValues the default XMLPropertyValues object to be returned
    * if the key is not found.
    * @return the property values of the input key or the defaultValues if the
    * key is not found.
    */
   public XMLPropertyValues getPropertyValues(String key,
                                          XMLPropertyValues defaultValues) {
     XMLPropertyValues temp = (XMLPropertyValues)xmlProperties.get(key);
     if (temp == null) {
       if (defaultXMLProps != null) {
         // check defaultXMLProps. it might contain the property values for
         // the specified property key
         return defaultXMLProps.getPropertyValues(key, defaultValues);
       } else {
         // if nothing is returned and defaultXMLProps is null, return
         // defaultValues
         return defaultValues;
       }
     }
     return temp;
   }
 
   /**
    * Locates the property value for the corresponding key and property value's
    * index. If the property key is found but the index is not within the
    * property values' range, the method will throw an XMLPropertiesException.
    *
    * @param key the property key.
    * @param index a number from 0 to XMLProperyValues.size() - 1. This is the
    * index of the value in the property values collection.
    * @return the property value which corresponds to the given key and index.
    */
   public String getPropertyValue(String key, int index)
       throws XMLPropertiesException {
     XMLPropertyValues temp = getPropertyValues(key);
     if (temp == null) {
       if (defaultXMLProps != null) {
         // check defaultXMLProps. it might contain the property values for
         // the specified property key
         return defaultXMLProps.getPropertyValue(key, index);
       } else {
         // return null if key has not been found
         return null;
       }
     }
     // check if index is within the property values' range
     try {
       return temp.getValue(index);
     } catch (IndexOutOfBoundsException e) {
       // wrap IndexOutOfBoundsException in XMLPropertiesException
       throw new XMLPropertiesException("Index is not within the range");
     }
   }
 
   /**
    * Locates the property value for the corresponding key and property value's
    * index. This method will return the defaultValue if the property key is not
    * found, or if the value's index is not within the range of the found
    * propertyValues.
    *
    * @param key the property key.
    * @param index is a number from 0 to XMLProperyValues.size() - 1. This is the
    * index of the value in the property values collection.
    * @param defaultValue the default value to be returned.
    * @return the found value, or the default value if the key is not found.
    */
   public String getPropertyValue(String key, int index,
                                               String defaultValue) {
     XMLPropertyValues temp = getPropertyValues(key);
     if (temp == null) {
       if (defaultXMLProps != null) {
         // check defaultXMLProps. it might contain the property values for
         // the specified property key
         return defaultXMLProps.getPropertyValue(key, index, defaultValue);
       } else {
         // return null if key has not been found
         return defaultValue;
       }
     }
     // check if index is within the list's range
     try {
       return temp.getValue(index);
     } catch (IndexOutOfBoundsException e) {
       // the value at index has not been found, just return the defaultValue
       return defaultValue;
     }
   }
 
   /**
    * Reads the property list key-value/s pair from the properties file.
    *
    * @param propertiesFile the XMLProperties file.
    */
   public synchronized void load(File propertiesFile) {
     XMLPropertiesHandler handler = new XMLPropertiesHandler(propertiesFile);
     xmlProperties = handler.getProperties();
   }
 
   /**
    * Reads the property list of key-value/s pair from the properties URI.
    *
    * @param propertiesURI the URI of the XMLProperties.
    */
   public synchronized void load(String propertiesURI) {
     XMLPropertiesHandler handler = new XMLPropertiesHandler(propertiesURI);
     xmlProperties = handler.getProperties();
   }
 
   /**
    * Reads the property list of key-value/s pairs from the input stream
    *
    * @param inStream the InputStream containing the XMLProperties.
    * @since XMLProperties version 1.1
    */
   public synchronized void load(InputStream inStream) {
     XMLPropertiesHandler handler = new XMLPropertiesHandler(inStream);
     xmlProperties = handler.getProperties();
   }
 
   /**
    * Returns an iterator of all the keys in the property list.
    *
    * @return an iterator of all the keys in the property list.
    */
   public synchronized Iterator getPropertyNames() {
     return xmlProperties.keySet().iterator();
   }
 
   /**
    * Puts the key-value pair parameter into the property list. If the argument
    * key exists in the property list, the old XMLPropertyValues object will
    * be returned, otherwise null will be returned.
    *
    * @param key the property key.
    * @param value the property value.
    * @return the old XMLPropertyValues object if key used to be in the property
    * list, or null otherwise.
    */
   public synchronized XMLPropertyValues setProperty(String key, String value) {
     // add the value to the XMLPropertyValues object first
     XMLPropertyValues tempValues = new XMLPropertyValues();
     tempValues.addValue(value);
     return (XMLPropertyValues)xmlProperties.put(key, tempValues);
   }
 
   /**
    * Puts the key-values pair parameter into the property list. If the argument
    * key exists in the property list, the old XMLPropertyValues object will
    * be returned, otherwise null will be returned.
    *
    * @param key the property key
    * @param values the property values
    * @return the old XMLPropertyValues object if key used to be in the property
    * list, or null otherwise.
    */
   public synchronized XMLPropertyValues setProperty(String key,
                           XMLPropertyValues values) {
     return (XMLPropertyValues)xmlProperties.put(key, values);
   }
 
   /**
    * Writes the property list wrapped by this class into a Writer object.
    *
    * @param writer a Writer object.
    */
   public synchronized void store(Writer writer) {
     store(writer, null);
   }
 
   /**
    * Writes the property list wrapped by this class into the output stream.
    *
    * @param outStream the output stream.
    * @since XMLProperties version 1.1
    */
   public synchronized void store(OutputStream outStream) {
     store(new PrintWriter(outStream), null);
   }
 
   /**
    * Writes the property list wrapped by this class into the output stream.
    * This method adds additional header information to the output through the
    * use of the headerComment.
    *
    * @param outStream the output stream.
    * @param headerComment the header comment going to be written in the output
    * stream.
    * @since XMLProperties version 1.1
    */
   public synchronized void store(OutputStream outStream, String headerComment) {
     store(new PrintWriter(outStream), headerComment);
   }
 
 
   /**
    * Writes the property list wrapped by this class into a Writer object.
    * This method adds additional header information to the output through the
    * use of the headerComment.
    *
    * @param writer a Writer object.
    * @param headerComment the header comment going to be written in the output.
    */
   public synchronized void store(Writer writer, String headerComment) {
     PrintWriter printWriter = new PrintWriter(writer);
     printWriter.println("<?xml version=\"1.0\" encoding=\"iso-8859-1\" ?> ");
     if (headerComment != null) {
       printWriter.println("<!-- " + headerComment + " -->");
     }
     printWriter.println("<properties>");
     Set keySet = xmlProperties.keySet();
     for (Iterator keyIter = keySet.iterator(); keyIter.hasNext(); ) {
       String propertyKey = keyIter.next().toString();
       XMLPropertyValues propertyValues =
           (XMLPropertyValues)xmlProperties.get(propertyKey);
       printWriter.println("  <property key=\"" + propertyKey + "\">");
       for (Iterator valueIter = propertyValues.iterator(); valueIter.hasNext(); ) {
         // modified this section of the code on version 1.2
         // reason: i just like the xml properties document in this format
         printWriter.println("    <value>" + valueIter.next() + "</value>");
       }
       printWriter.println("  </property>");
     }
     printWriter.println("</properties>");
     printWriter.flush();
   }
 
 
 
 
   /**
    * Returns an iterator of all XMLPropertyValues objects in the property list.
    *
    * @return an iterator of all the XMLPropertyValues objects in the property
    * list.
    * @since XMLProperties version 1.1
    */
   public synchronized Iterator getPropertyValuesIterator() {
     return xmlProperties.values().iterator();
   }
 
   /**
    * This method converts this class to its equivalent java.util.Properties
    * object. It should be noted that only the first element (or propery value)
    * of all the XMLPropertyValues objects in this class' property list will
    * be stored in the output java.util.Properties object. The property list
    * of the defaults are also not stored in the output java.util.Properties
    * object.
    *
    * @return the equivalent java.util.Properties object of this object.
    * @since XMLProperties version 1.1
    */
   public synchronized Properties getJavaUtilProperties() {
     Properties tempProperties = new Properties();
     Set keySet = xmlProperties.keySet();
     for (Iterator keyIter = keySet.iterator(); keyIter.hasNext(); ) {
       String propertyKey = keyIter.next().toString();
       // Map's putAll() method cannot be used because only the first value
       // of the propertyValues object should be added to java.util.Properties'
       // property list.
       tempProperties.setProperty(propertyKey, getPropertyValue(propertyKey, 0));
     }
     return tempProperties;
   }
 
   /**
    * Removes all the entries from the property list.
    *
    * @since XMLProperties version 1.1
    */
   public void clear() {
     xmlProperties.clear();
   }
 
   /**
    * Checks if the specified key is in the property list.
    *
    * @param key the key to be checked.
    * @return true if the key is in the property list, false otherwise.
    * @since XMLProperties version 1.1
    */
   public boolean containsKey(String key) {
     return xmlProperties.containsKey(key);
   }
 
   /**
    * Returns true if XMLProperties maps one or more keys for this value.
    *
    * @param value the value stored in an XMLPropertyValues object
    * @return true if the value is found in any of the property values mapped
    * by any of the keys in the property list.
    * @since XMLProperties version 1.1
    */
   public synchronized boolean containsValue(String value) {
     // go through all the property values objects stored by xmlProperties
     for (Iterator propsValuesIter = getPropertyValuesIterator();
          propsValuesIter.hasNext(); ) {
       for (Iterator propsValueIter =
            ((XMLPropertyValues)propsValuesIter.next()).iterator();
            propsValueIter.hasNext(); ) {
         if (propsValueIter.next().toString().equals(value)) {
           return true;
         }
       }
     }
     return false;
   }
 
   /**
    * Returns true if the property list is empty.
    *
    * @return true if the property list is empty, false otherwise.
    * @since XMLProperties version 1.1
    */
   public boolean isEmpty() {
     return xmlProperties.isEmpty();
   }
 
   /**
    * Removes the property specified by the property key.
    *
    * @param key the key of the property to be removed
    * @return the XMLPropertyValues object mapped by the specified key, null
    * othewise.
    * @since XMLProperties version 1.1
    */
   public XMLPropertyValues remove(String key) {
     return (XMLPropertyValues)xmlProperties.remove(key);
   }
 
   /**
    * Returns the number of elements in the property list.
    *
    * @return the number of entries in the property list.
    * @since XMLProperties version 1.1
    */
   public int size() {
     return xmlProperties.size();
   }
 
 }