KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > helpers > GenericParameters


1 /**
2  * $Id: GenericParameters.java 180 2007-03-15 12:56:38Z ssmc $
3  * Copyright 2004 iDare Media, Inc. All rights reserved.
4  *
5  * Originally written by iDare Media, Inc. for release into the public domain. This
6  * library, source form and binary form, is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public License (LGPL) as published
8  * by the Free Software Foundation; either version 2.1 of the License, or (at your option)
9  * any later version.<p>
10  *
11  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
12  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13  * See the GNU LGPL for more details.<p>
14  *
15  * You should have received a copy of the GNU Lesser General Public License along with this
16  * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite
17  * 330, Boston, MA 02111-1307 USA. The GNU LGPL can be found online at
18  * http://www.fsf.org/copyleft/lesser.html<p>
19  *
20  * This product has been influenced by several projects within the open-source community.
21  * The JWare developers wish to acknowledge the open-source community's support. For more
22  * information regarding the open-source products used within JWare, please visit the
23  * JWare website.
24  *----------------------------------------------------------------------------------------*
25  * WEBSITE- http://www.jware.info EMAIL- inquiries@jware.info
26  *----------------------------------------------------------------------------------------*
27  **/
28
29 package com.idaremedia.antx.helpers;
30
31 import java.util.Collection JavaDoc;
32 import java.util.Iterator JavaDoc;
33 import java.util.Map JavaDoc;
34 import java.util.Properties JavaDoc;
35 import java.util.StringTokenizer JavaDoc;
36
37 import org.apache.tools.ant.Project;
38 import org.apache.tools.ant.ProjectComponent;
39
40 import com.idaremedia.apis.FixtureStarter;
41
42 /**
43  * Simple collection of {@linkplain InnerNameValuePair key-value} pairs. Duplicates are
44  * permitted (last item added wins). Every parameter's name is normalized to its
45  * US lowercase equivalent to ensure they can be used directly with Ant's macro and
46  * dynamic attribute facilities. GenericParameters can be used as internal data structs,
47  * or public-facing script components.
48  * <p/>
49  * <b>Example Usage:</b><pre>
50  * &lt;parameters&gt;
51  * &lt;parameter name="name" value="Larry"/&gt;
52  * &lt;parameter name="weight" value="165lbs"/&gt;
53  * &lt;/parameters&gt;
54  *
55  * -OR (shorthand)-
56  *
57  * &lt;parameters list="prune;tag=latest"/&gt;
58  * </pre>
59  *
60  * @since JWare/AntX 0.5
61  * @author ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
62  * @version 0.5
63  * @.safety single
64  * @.group impl,helper
65  **/
66
67 public class GenericParameters extends ProjectComponent implements Cloneable JavaDoc
68 {
69     /**
70      * Initializes a new empty parameters collection bean.
71      **/
72     public GenericParameters()
73     {
74     }
75
76
77
78     /**
79      * Initializes a new empty parameters collection bean
80      * associated with project.
81      * @param project this parameter object's enclosing project
82      **/
83     public GenericParameters(Project project)
84     {
85         setProject(project);
86     }
87
88
89
90     /**
91      * Returns an independent (deep) clone of this parameters
92      * set. The individual items of the clone are also independent;
93      * changes to them are not reflected in this set.
94      */
95     public Object JavaDoc clone()
96     {
97         try {
98            GenericParameters copy= (GenericParameters)super.clone();
99            copy.m_items = FixtureStarter.newMapCopy(m_items);
100            if (size()>0) {
101                Iterator JavaDoc itr= copy.m_items.entrySet().iterator();
102                while (itr.hasNext()) {
103                    Map.Entry JavaDoc e = (Map.Entry JavaDoc)itr.next();
104                    e.setValue(((InnerNameValuePair)e.getValue()).clone());
105                }
106            }
107            return copy;
108         } catch(CloneNotSupportedException JavaDoc clnx) {
109             throw new Error JavaDoc();
110         }
111     }
112
113
114
115     /**
116      * Adds a new name-value pair to this collection. The new
117      * item is <em>not</em> checked for duplicity. If another item
118      * with equivalent name already exists, it is replaced
119      * unconditionally.
120      * @param item new configured item (must be named)
121      * @throws BuildException if incoming item not named.
122      **/
123     public void addConfiguredParameter(InnerNameValuePair item)
124     {
125         item.verifyNamed();
126         item.setName(Tk.lowercaseFrom(item.getName()));
127         m_items.put(item.getName(),item);
128     }
129
130
131
132     /**
133      * Synonym for {@linkplain #addConfiguredParameter addConfiguredParameter}
134      * that is more appropriate for some uses of this bean.
135      * @param item new configured item (must be named)
136      */
137     public final void addConfiguredArg(InnerNameValuePair item)
138     {
139         addConfiguredParameter(item);
140     }
141
142
143
144     /**
145      * Synonym for {@linkplain #addConfiguredParameter addConfiguredParameter}
146      * that is more appropriate for some uses of this bean.
147      * @param item new configured item (must be named)
148      */
149     public final void addConfiguredProperty(InnerNameValuePair item)
150     {
151         addConfiguredParameter(item);
152     }
153
154
155
156     /**
157      * Adds a collection of name-value pairs to this collection
158      * using a simple semi-colon delimited list. If the list is
159      * <i>null</i>, this collection is cleared of all current
160      * entries. Each item in the list be in one of the following
161      * forms:<ul>
162      * <li>&lt;name&gt;: where the value is automatically assigned as "true".</li>
163      * <li>&lt;name=&gt; where the value is assigned as the empty string.</li>
164      * <li>&lt;name=value&gt; where the value is assigned whatever "value" is.</li>
165      * </ul>
166      * @param paramlist the pairs
167      **/
168     public void setList(String JavaDoc paramlist)
169     {
170         if (paramlist!=null) {
171             StringTokenizer JavaDoc st= new StringTokenizer JavaDoc(paramlist,";");
172             while (st.hasMoreTokens()) {
173                 
174                 String JavaDoc kv = st.nextToken();
175                 InnerNameValuePair nvp = newNVPair();
176                 int i= kv.indexOf("=");
177                 
178                 if (i>0) {
179                     String JavaDoc key = kv.substring(0,i);
180                     String JavaDoc value = "";
181                     if (i<kv.length()-1) {
182                         value = kv.substring(i+1);
183                     }
184                     nvp.setName(key);
185                     nvp.setValue(value);
186                 } else {
187                     nvp.setName(kv);
188                     nvp.setValue(Strings.TRUE);
189                 }
190                 
191                 addConfiguredParameter(nvp);
192             }
193         } else {
194             m_items.clear();
195         }
196     }
197
198
199
200     /**
201      * Returns <i>true</i> if this collection is empty.
202      **/
203     public final boolean isEmpty()
204     {
205         return m_items.isEmpty();
206     }
207
208
209
210     /**
211      * Returns the number of parameters in this collection.
212      **/
213     public final int size()
214     {
215         return m_items.size();
216     }
217
218
219
220     /**
221      * Returns this parameters object's underlying name-value
222      * items collection. The returned collection is still connected
223      * to this data object, so modifications via its iterators are
224      * reflected back to this object. Never returns <i>null</i>.
225      **/
226     public final Collection JavaDoc values()
227     {
228         return m_items.values();
229     }
230
231
232
233     /**
234      * Returns an independent map of this collection's
235      * name-value items. The returned map contains
236      * {@linkplain InnerNameValuePair} items as values.
237      **/
238     public Map JavaDoc copyOfParameterObjects()
239     {
240         return FixtureStarter.newMapCopy(m_items);
241     }
242
243
244
245     /**
246      * Returns an independent Properties map of this collection's
247      * name-value items as simplified name-stringvalue pairs.
248      * The returned map contains the item names and string
249      * values. Property references are resolved from given project.
250      * @param P [optional] project used to resolve property references.
251      * @param altForm alternative form of property references allowed.
252      **/
253     public Properties JavaDoc copyOfSimpleKeyValues(final Project P, boolean altForm)
254     {
255         Properties JavaDoc copy = new Properties JavaDoc();
256         if (!m_items.isEmpty()) {
257             Iterator JavaDoc itr= m_items.entrySet().iterator();
258             while (itr.hasNext()) {
259                 Map.Entry JavaDoc e = (Map.Entry JavaDoc)itr.next();
260                 copy.put(e.getKey(),
261                     ((InnerNameValuePair)e.getValue()).getValue(P,altForm));
262             }
263         }
264         return copy;
265     }
266
267
268
269     /**
270      * Returns an independent Properties map of this collection's
271      * name-value items as simplified name-stringvalue pairs.
272      * The returned map contains the item names and string
273      * values.
274      * @param P [optional] project used to resolve property references.
275      **/
276     public final Properties JavaDoc copyOfSimpleKeyValues(final Project P)
277     {
278         return copyOfSimpleKeyValues(P,false);
279     }
280
281
282
283     /**
284      * Combine another parameters collection with this one.
285      * Shorthand for calling {@linkplain #addConfiguredParameter
286      * addConfiguredParameter} repeatedly. Existing parameters
287      * are replaced unconditionally with newer versions.
288      * @param other parameters to be merged (non-null)
289      **/
290     public void mergeOther(GenericParameters other)
291     {
292         Iterator JavaDoc itr = other.copyOfParameterObjects().values().iterator();
293         while (itr.hasNext()) {
294             addConfiguredParameter((InnerNameValuePair)itr.next());
295         }
296     }
297
298
299
300     /**
301      * Combine another parameters collection in form of a standard
302      * Java Properties object. Existing parameters are replaced
303      * unconditionally with newer versions.
304      * @param other other name-value pairs to be merged (non-null)
305      **/
306     public void mergeOther(Properties JavaDoc other)
307     {
308         Iterator JavaDoc itr = other.entrySet().iterator();
309         while (itr.hasNext()) {
310             Map.Entry JavaDoc e = (Map.Entry JavaDoc)itr.next();
311             put(e.getKey().toString(),(String JavaDoc)e.getValue());
312         }
313     }
314
315
316
317     /**
318      * Convenient look method for a particular parameter.
319      * @param name parameter's name (non-null)
320      * @return parameter or <i>null</i> if no match
321      **/
322     public InnerNameValuePair get(String JavaDoc name)
323     {
324         name = Tk.lowercaseFrom(name);
325         return (InnerNameValuePair)m_items.get(name);
326     }
327
328
329
330     /**
331      * Convenient look method for a particular parameter.
332      * @param name parameter's name (non-null)
333      * @return parameter or <i>null</i> if no match
334      **/
335     public final String JavaDoc getv(String JavaDoc name)
336     {
337         InnerNameValuePair e = get(name);
338         if (e!=null) {
339             return e.getValue();
340         }
341         return null;
342     }
343
344
345
346     /**
347      * Factory method to create a new name-value pair for inclusion
348      * in this collection. By default returns standard InnerNameValuePair
349      * objects.
350      * @since JWare/AntX 0.5
351      **/
352     protected InnerNameValuePair newNVPair()
353     {
354         return new InnerNameValuePair();
355     }
356
357
358
359     /**
360      * Common function to put a single name-value pair into this
361      * parameters object.
362      * @param name new item's unnormalized name (non-null)
363      * @param value new item's value
364      **/
365     protected void put(String JavaDoc name, String JavaDoc value)
366     {
367         InnerNameValuePair item = newNVPair();
368         item.setName(Tk.lowercaseFrom(name.toString()));
369         item.setValue(value);
370         m_items.put(item.getName(),item);
371     }
372
373     private Map JavaDoc m_items = FixtureStarter.newMap(11,0.8f);
374 }
375
376 /* end-of-GenericParameters.java */
Popular Tags