/*
    * Copyright (c) 2001 - 2005 ivata limited.
    * All rights reserved.
    * -----------------------------------------------------------------------------
    * ivata masks may be redistributed under the GNU General Public
    * License as published by the Free Software Foundation;
    * version 2 of the License.
    *
    * These programs are free software; you can redistribute them and/or
   * modify them under the terms of the GNU General Public License
   * as published by the Free Software Foundation; version 2 of the License.
   *
   * These programs are distributed in the hope that they will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   *
   * See the GNU General Public License in the file LICENSE.txt for more
   * details.
   *
   * If you would like a copy of the GNU General Public License write to
   *
   * Free Software Foundation, Inc.
   * 59 Temple Place - Suite 330
   * Boston, MA 02111-1307, USA.
   *
   *
   * To arrange commercial support and licensing, contact ivata at
   *                  http://www.ivata.com/contact.jsp
   * -----------------------------------------------------------------------------
   * $Log: CollectionHandling.java,v $
   * Revision 1.3  2005/04/09 18:04:17  colinmacleod
   * Changed copyright text to GPL v2 explicitly.
   *
   * Revision 1.2  2005/01/06 22:21:45  colinmacleod
   * Moved up a version number.
   * Changed copyright notices to 2005.
   * Updated the documentation:
   *   - started working on multiproject:site docu.
   *   - changed the logo.
   * Added checkstyle and fixed LOADS of style issues.
   * Added separate thirdparty subproject.
   * Added struts (in web), util and webgui (in webtheme) from ivata op.
   *
   * Revision 1.3  2004/11/03 16:15:43  colinmacleod
   * Cosmetic changes.
   *
   * Revision 1.2  2004/03/21 21:16:36  colinmacleod
   * Shortened name to ivata op.
   *
   * Revision 1.1.1.1  2004/01/27 20:59:46  colinmacleod
   * Moved ivata op to SourceForge.
   *
   * Revision 1.2  2003/10/15 14:13:53  colin
   * fixing for XDoclet
   *
   * Revision 1.9  2003/02/24 19:27:31  colin
   * restructured file paths
   *
   * Revision 1.8  2003/02/14 15:22:21  colin
   * changed properties splice routine for force non-null, String values
   *
   * Revision 1.7  2003/02/04 17:43:52  colin
   * copyright notice
   *
   * Revision 1.6  2003/01/31 10:39:02  colin
   * added checking for null properties
   *
   * Revision 1.5  2002/11/12 10:10:42  colin
   * extended convertTo/FromLines to let you specify deliminators
   *
   * Revision 1.4  2002/09/16 14:17:14  colin
   * added convertToLines & convertFromLines
   *
   * Revision 1.3  2002/08/11 11:58:26  colin
   * Added checking for null properties as parameter in poperty
   * splicing method.
   *
   * Revision 1.2  2002/06/25 09:23:46  colin
   * added Collection merge method
   *
   * Revision 1.1  2002/06/13 11:22:21  colin
   * first version with rose model integration.
   * -----------------------------------------------------------------------------
   */
  package com.ivata.mask.util;
  import java.util.Collection;
  import java.util.Enumeration;
  import java.util.Iterator;
  import java.util.List;
  import java.util.Properties;
  import java.util.StringTokenizer;
  import java.util.Vector;
  /***
   * <p>
   * This class contains extra routines for combining collection objects.
   * </p>
   *
   * <p>
   * Don't create an instance of this class; use the static final methods.
  * </p>
  *
  * @since ivata masks 0.4 (2002-05-16)
  * @author Colin MacLeod
  * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
  * @version $Revision: 1.3 $
  */
 public final class CollectionHandling {
     /***
      * <p>
      * Convert a string of strings separated by new lines into a collection of
      * strings.
      * </p>
      *
      * @param lines
      *            a single text containing many lines to be split.
      * @return a <code>Collection</code> of <code>String</code> instances
      *         representing each line from the input.
      */
     public static List convertFromLines(final String lines) {
         return convertFromLines(lines, "\n\r");
     }
     /***
      * <p>
      * Convert a string of strings separated by deliminators into a collection
      * of strings.
      * </p>
      *
      * @param lines
      *            a single text containing many lines to be split.
      * @param deliminators
      *            a <code>String</code> containing all possible deliminators
      *            to search for.
      * @return a <code>Collection</code> of <code>String</code> instances
      *         representing each line from the input.
      */
     public static java.util.List convertFromLines(final String lines,
             final String deliminators) {
         // prerequisites - can't do anything with nulls
         if (lines == null) {
             return null;
         }
         Vector list = new Vector();
         StringTokenizer tokenizer = new StringTokenizer(lines, deliminators);
         while (tokenizer.hasMoreTokens()) {
             list.add(tokenizer.nextToken());
         }
         return list;
     }
     /***
      * <p>
      * Convert a collection of strings to one long string, separated by new
      * lines.
      * </p>
      *
      * @param convertToLines
      *            a <code>Collection</code> of <code>String</code> instances
      *            representing each line of the output.
      * @return a single text containing the elements of the input
      *         <code>Collection</code> separated by new line characters.
      */
     public static String convertToLines(final Collection convertToLines) {
         return convertToLines(convertToLines, '\n');
     }
     /***
      * <p>
      * Convert a collection of strings to one long string, separated by
      * deliminators.
      * </p>
      *
      * @param convertToLines
      *            a <code>Collection</code> of <code>String</code> instances
      *            representing each line of the output.
      * @param deliminator
      *            a <code>char</code> containing deliminator to add after each
      *            element.
      * @return a single text containing the elements of the input
      *         <code>Collection</code> separated by new line characters.
      */
     public static String convertToLines(final Collection convertToLines,
             final char deliminator) {
         // prerequisites - can't do anything with nulls
         if (convertToLines == null) {
             return null;
         }
         StringBuffer lines = new StringBuffer();
         for (Iterator i = convertToLines.iterator(); i.hasNext();) {
             lines.append((String) i.next());
             // if this is not the last, add a newline seperator
             if (i.hasNext()) {
                 lines.append(deliminator);
             }
         }
         return lines.toString();
     }
     /***
      * <p>
      * Copy elements from one collection to another. Adds all of the elements in
      * <code>from</code> to those in <code>to</code>, if that element is
      * not already present in <code>to</code>.
      * </p>
      *
      * @param from
      *            the collection to copy elements from
      * @param to
      *            the collection to copy elements to. This collection will be
      *            changed and all the elements of <code>from</code> which
      *            can't be found will be replaced.
      */
     public static void merge(final Collection from, final Collection to) {
         for (Iterator i = from.iterator(); i.hasNext();) {
             Object item = i.next();
             if (!to.contains(item)) {
                 to.add(item);
             }
         }
     }
     /***
      * <p>
      * Creates a new properties instance which is a mixture of the two. Adds all
      * of the properties in <code>fromProperties</code> to those in
      * <code>toProperties</code>, overwriting any which exist already.
      * </p>
      *
      * @param fromProperties
      *            the properties to base the new object on
      * @param toProperties
      *            the properties to include if not already set
      * @return a new <code>Properties</code> instance which contains all of
      *         the properties in <code>fromProperties</code> added to those in
      *         <code>toProperties</code>.
      */
     public static Properties splice(final Properties fromProperties,
             final Properties toProperties) {
         Properties returnProperties = new java.util.Properties();
         Enumeration enumeration;
         // first add the to properties, so they'll be overwritten by the
         // 'original' ones afterwards
         if (toProperties != null) {
             enumeration = toProperties.keys();
             while (enumeration.hasMoreElements()) {
                 Object key = enumeration.nextElement();
                 Object value = toProperties.get(key);
                 if (value == null) {
                     throw new NullPointerException(
                             "ERROR in CollectionHandling.splice: "
                                     + "value for key '" + key
                                     + "' is null in 'to' properties.");
                 }
                 if (!java.lang.String.class.isInstance(value)) {
                     throw new RuntimeException(
                             "ERROR in CollectionHandling.splice: value '"
                                     + value
                                     + "' for key '"
                                     + key
                                     + "' has class '"
                                     + value.getClass().getName()
                                     + "' in 'to' properties. Only instances of "
                                     + "java.lang.String are allowed.");
                 }
                 returnProperties.put(key, value);
             }
         }
         // overwrite any of the properties with the from properties
         if (fromProperties != null) {
             enumeration = fromProperties.keys();
             while (enumeration.hasMoreElements()) {
                 Object key = enumeration.nextElement();
                 Object value = fromProperties.get(key);
                 if (value == null) {
                     throw new NullPointerException(
                             "ERROR in CollectionHandling.splice: "
                                     + "value for key '" + key
                                     + "' is null in 'from' properties.");
                 }
                 if (!java.lang.String.class.isInstance(value)) {
                     throw new RuntimeException(
                             "ERROR in CollectionHandling.splice: value '"
                                     + value
                                     + "' for key '"
                                     + key
                                     + "' has class '"
                                     + value.getClass().getName()
                                     + "' in 'from' properties. "
                                     + "Only instances of "
                                     + "java.lang.String are allowed.");
                 }
                 returnProperties.put(key, value);
             }
         }
         return returnProperties;
     }
     /***
      * <p>
      * Private default constructor ensures utility class functionality.
      * </p>
      */
     private CollectionHandling() {
     }
 }