001: /*
002: * Copyright (c) 2001 - 2005 ivata limited.
003: * All rights reserved.
004: * -----------------------------------------------------------------------------
005: * ivata masks may be redistributed under the GNU General Public
006: * License as published by the Free Software Foundation;
007: * version 2 of the License.
008: *
009: * These programs are free software; you can redistribute them and/or
010: * modify them under the terms of the GNU General Public License
011: * as published by the Free Software Foundation; version 2 of the License.
012: *
013: * These programs are distributed in the hope that they will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016: *
017: * See the GNU General Public License in the file LICENSE.txt for more
018: * details.
019: *
020: * If you would like a copy of the GNU General Public License write to
021: *
022: * Free Software Foundation, Inc.
023: * 59 Temple Place - Suite 330
024: * Boston, MA 02111-1307, USA.
025: *
026: *
027: * To arrange commercial support and licensing, contact ivata at
028: * http://www.ivata.com/contact.jsp
029: * -----------------------------------------------------------------------------
030: * $Log: CollectionHandling.java,v $
031: * Revision 1.5 2005/10/11 18:55:58 colinmacleod
032: * Fixed some checkstyle and javadoc issues.
033: *
034: * Revision 1.4 2005/10/02 14:06:32 colinmacleod
035: * Added/improved log4j logging.
036: *
037: * Revision 1.3 2005/04/09 18:04:17 colinmacleod
038: * Changed copyright text to GPL v2 explicitly.
039: *
040: * Revision 1.2 2005/01/06 22:21:45 colinmacleod
041: * Moved up a version number.
042: * Changed copyright notices to 2005.
043: * Updated the documentation:
044: * - started working on multiproject:site docu.
045: * - changed the logo.
046: * Added checkstyle and fixed LOADS of style issues.
047: * Added separate thirdparty subproject.
048: * Added struts (in web), util and webgui (in webtheme) from ivata op.
049: *
050: * Revision 1.3 2004/11/03 16:15:43 colinmacleod
051: * Cosmetic changes.
052: *
053: * Revision 1.2 2004/03/21 21:16:36 colinmacleod
054: * Shortened name to ivata op.
055: *
056: * Revision 1.1.1.1 2004/01/27 20:59:46 colinmacleod
057: * Moved ivata op to SourceForge.
058: *
059: * Revision 1.2 2003/10/15 14:13:53 colin
060: * fixing for XDoclet
061: *
062: * Revision 1.9 2003/02/24 19:27:31 colin
063: * restructured file paths
064: *
065: * Revision 1.8 2003/02/14 15:22:21 colin
066: * changed properties splice routine for force non-null, String values
067: *
068: * Revision 1.7 2003/02/04 17:43:52 colin
069: * copyright notice
070: *
071: * Revision 1.6 2003/01/31 10:39:02 colin
072: * added checking for null properties
073: *
074: * Revision 1.5 2002/11/12 10:10:42 colin
075: * extended convertTo/FromLines to let you specify deliminators
076: *
077: * Revision 1.4 2002/09/16 14:17:14 colin
078: * added convertToLines & convertFromLines
079: *
080: * Revision 1.3 2002/08/11 11:58:26 colin
081: * Added checking for null properties as parameter in poperty
082: * splicing method.
083: *
084: * Revision 1.2 2002/06/25 09:23:46 colin
085: * added Collection merge method
086: *
087: * Revision 1.1 2002/06/13 11:22:21 colin
088: * first version with rose model integration.
089: * -----------------------------------------------------------------------------
090: */
091: package com.ivata.mask.util;
092:
093: import org.apache.log4j.Logger;
094:
095: import java.util.Collection;
096: import java.util.Enumeration;
097: import java.util.Iterator;
098: import java.util.List;
099: import java.util.Properties;
100: import java.util.StringTokenizer;
101: import java.util.Vector;
102:
103: /**
104: * <p>
105: * This class contains extra routines for combining collection objects.
106: * </p>
107: *
108: * <p>
109: * Don't create an instance of this class; use the static final methods.
110: * </p>
111: *
112: * @since ivata masks 0.4 (2002-05-16)
113: * @author Colin MacLeod
114: * <a href='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
115: * @version $Revision: 1.5 $
116: */
117: public final class CollectionHandling {
118: /**
119: * Logger for this class.
120: */
121: private static final Logger logger = Logger
122: .getLogger(CollectionHandling.class);
123:
124: /**
125: * <p>
126: * Convert a string of strings separated by new lines into a collection of
127: * strings.
128: * </p>
129: *
130: * @param lines
131: * a single text containing many lines to be split.
132: * @return a <code>Collection</code> of <code>String</code> instances
133: * representing each line from the input.
134: */
135: public static List convertFromLines(final String lines) {
136: if (logger.isDebugEnabled()) {
137: logger.debug("convertFromLines(String lines = " + lines
138: + ") - start");
139: }
140:
141: List returnList = convertFromLines(lines, "\n\r");
142: if (logger.isDebugEnabled()) {
143: logger
144: .debug("convertFromLines(String) - end - return value = "
145: + returnList);
146: }
147: return returnList;
148: }
149:
150: /**
151: * <p>
152: * Convert a string of strings separated by deliminators into a collection
153: * of strings.
154: * </p>
155: *
156: * @param lines
157: * a single text containing many lines to be split.
158: * @param deliminators
159: * a <code>String</code> containing all possible deliminators
160: * to search for.
161: * @return a <code>Collection</code> of <code>String</code> instances
162: * representing each line from the input.
163: */
164: public static java.util.List convertFromLines(final String lines,
165: final String deliminators) {
166: if (logger.isDebugEnabled()) {
167: logger.debug("convertFromLines(String lines = " + lines
168: + ", String deliminators = " + deliminators
169: + ") - start");
170: }
171:
172: // prerequisites - can't do anything with nulls
173: if (lines == null) {
174: if (logger.isDebugEnabled()) {
175: logger.debug("convertFromLines - end - return value = "
176: + null);
177: }
178: return null;
179: }
180: Vector list = new Vector();
181: StringTokenizer tokenizer = new StringTokenizer(lines,
182: deliminators);
183: while (tokenizer.hasMoreTokens()) {
184: list.add(tokenizer.nextToken());
185: }
186:
187: if (logger.isDebugEnabled()) {
188: logger.debug("convertFromLines - end - return value = "
189: + list);
190: }
191: return list;
192: }
193:
194: /**
195: * <p>
196: * Convert a collection of strings to one long string, separated by new
197: * lines.
198: * </p>
199: *
200: * @param convertToLines
201: * a <code>Collection</code> of <code>String</code> instances
202: * representing each line of the output.
203: * @return a single text containing the elements of the input
204: * <code>Collection</code> separated by new line characters.
205: */
206: public static String convertToLines(final Collection convertToLines) {
207: if (logger.isDebugEnabled()) {
208: logger.debug("convertToLines(Collection convertToLines = "
209: + convertToLines + ") - start");
210: }
211:
212: String returnString = convertToLines(convertToLines, '\n');
213: if (logger.isDebugEnabled()) {
214: logger
215: .debug("convertToLines(Collection) - end - return value = "
216: + returnString);
217: }
218: return returnString;
219: }
220:
221: /**
222: * <p>
223: * Convert a collection of strings to one long string, separated by
224: * deliminators.
225: * </p>
226: *
227: * @param convertToLines
228: * a <code>Collection</code> of <code>String</code> instances
229: * representing each line of the output.
230: * @param deliminator
231: * a <code>char</code> containing deliminator to add after each
232: * element.
233: * @return a single text containing the elements of the input
234: * <code>Collection</code> separated by new line characters.
235: */
236: public static String convertToLines(
237: final Collection convertToLines, final char deliminator) {
238: if (logger.isDebugEnabled()) {
239: logger.debug("convertToLines(Collection convertToLines = "
240: + convertToLines + ", char deliminator = "
241: + deliminator + ") - start");
242: }
243:
244: // prerequisites - can't do anything with nulls
245: if (convertToLines == null) {
246: if (logger.isDebugEnabled()) {
247: logger.debug("convertToLines - end - return value = "
248: + null);
249: }
250: return null;
251: }
252: StringBuffer lines = new StringBuffer();
253: for (Iterator i = convertToLines.iterator(); i.hasNext();) {
254: lines.append((String) i.next());
255: // if this is not the last, add a newline seperator
256: if (i.hasNext()) {
257: lines.append(deliminator);
258: }
259: }
260: String returnString = lines.toString();
261: if (logger.isDebugEnabled()) {
262: logger.debug("convertToLines - end - return value = "
263: + returnString);
264: }
265: return returnString;
266: }
267:
268: /**
269: * <p>
270: * Copy elements from one collection to another. Adds all of the elements in
271: * <code>from</code> to those in <code>to</code>, if that element is
272: * not already present in <code>to</code>.
273: * </p>
274: *
275: * @param from
276: * the collection to copy elements from
277: * @param to
278: * the collection to copy elements to. This collection will be
279: * changed and all the elements of <code>from</code> which
280: * can't be found will be replaced.
281: */
282: public static void merge(final Collection from, final Collection to) {
283: if (logger.isDebugEnabled()) {
284: logger.debug("merge(Collection from = " + from
285: + ", Collection to = " + to + ") - start");
286: }
287:
288: for (Iterator i = from.iterator(); i.hasNext();) {
289: Object item = i.next();
290: if (!to.contains(item)) {
291: to.add(item);
292: }
293: }
294:
295: if (logger.isDebugEnabled()) {
296: logger.debug("merge(Collection, Collection) - end");
297: }
298: }
299:
300: /**
301: * <p>
302: * Creates a new properties instance which is a mixture of the two. Adds all
303: * of the properties in <code>fromProperties</code> to those in
304: * <code>toProperties</code>, overwriting any which exist already.
305: * </p>
306: *
307: * @param fromProperties
308: * the properties to base the new object on
309: * @param toProperties
310: * the properties to include if not already set
311: * @return a new <code>Properties</code> instance which contains all of
312: * the properties in <code>fromProperties</code> added to those in
313: * <code>toProperties</code>.
314: */
315: public static Properties splice(final Properties fromProperties,
316: final Properties toProperties) {
317: if (logger.isDebugEnabled()) {
318: logger.debug("splice(Properties fromProperties = "
319: + fromProperties + ", Properties toProperties = "
320: + toProperties + ") - start");
321: }
322:
323: Properties returnProperties = new java.util.Properties();
324: Enumeration enumeration;
325: // first add the to properties, so they'll be overwritten by the
326: // 'original' ones afterwards
327: if (toProperties != null) {
328: enumeration = toProperties.keys();
329: while (enumeration.hasMoreElements()) {
330: Object key = enumeration.nextElement();
331: Object value = toProperties.get(key);
332: if (value == null) {
333: throw new NullPointerException(
334: "ERROR in CollectionHandling.splice: "
335: + "value for key '" + key
336: + "' is null in 'to' properties.");
337: }
338: if (!java.lang.String.class.isInstance(value)) {
339: throw new RuntimeException(
340: "ERROR in CollectionHandling.splice: value '"
341: + value
342: + "' for key '"
343: + key
344: + "' has class '"
345: + value.getClass().getName()
346: + "' in 'to' properties. Only instances of "
347: + "java.lang.String are allowed.");
348: }
349: returnProperties.put(key, value);
350: }
351: }
352: // overwrite any of the properties with the from properties
353: if (fromProperties != null) {
354: enumeration = fromProperties.keys();
355: while (enumeration.hasMoreElements()) {
356: Object key = enumeration.nextElement();
357: Object value = fromProperties.get(key);
358: if (value == null) {
359: throw new NullPointerException(
360: "ERROR in CollectionHandling.splice: "
361: + "value for key '" + key
362: + "' is null in 'from' properties.");
363: }
364: if (!java.lang.String.class.isInstance(value)) {
365: throw new RuntimeException(
366: "ERROR in CollectionHandling.splice: value '"
367: + value + "' for key '" + key
368: + "' has class '"
369: + value.getClass().getName()
370: + "' in 'from' properties. "
371: + "Only instances of "
372: + "java.lang.String are allowed.");
373: }
374: returnProperties.put(key, value);
375: }
376: }
377:
378: if (logger.isDebugEnabled()) {
379: logger.debug("splice - end - return value = "
380: + returnProperties);
381: }
382: return returnProperties;
383: }
384:
385: /**
386: * <p>
387: * Private default constructor ensures utility class functionality.
388: * </p>
389: */
390: private CollectionHandling() {
391: }
392: }
|