KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > solo > PropertiesList


1 /**
2  * $Id: PropertiesList.java 186 2007-03-16 13:42:35Z ssmc $
3  * Copyright 2004-2005 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.solo;
30
31 import java.io.File JavaDoc;
32 import java.io.IOException JavaDoc;
33 import java.io.InputStream JavaDoc;
34 import java.net.URL JavaDoc;
35 import java.util.Iterator JavaDoc;
36 import java.util.List JavaDoc;
37 import java.util.Map JavaDoc;
38 import java.util.Properties JavaDoc;
39
40 import org.apache.tools.ant.BuildException;
41 import org.apache.tools.ant.Project;
42 import org.apache.tools.ant.types.Reference;
43
44 import com.idaremedia.antx.AntX;
45 import com.idaremedia.antx.AntXFixture;
46 import com.idaremedia.antx.FixtureComponent;
47 import com.idaremedia.antx.FixtureExaminer;
48 import com.idaremedia.antx.Iteration;
49 import com.idaremedia.antx.apis.AntLibFriendly;
50 import com.idaremedia.antx.helpers.GenericParameters;
51 import com.idaremedia.antx.helpers.InnerNameValuePair;
52 import com.idaremedia.antx.helpers.InputFileLoader;
53 import com.idaremedia.antx.helpers.Strings;
54 import com.idaremedia.antx.ownhelpers.LocalTk;
55 import com.idaremedia.antx.ownhelpers.ReferenceHandle;
56 import com.idaremedia.antx.parameters.FlexSourceSupport;
57 import com.idaremedia.antx.starters.ListFriendly;
58
59 /**
60  * List of string name-value pairs that can be used as source for loop iteration,
61  * macro arguments, overlays, value URIs, etc. When printed as a string a properties
62  * list elements are separated by the platform's newline string unless its
63  * <span class="src">delim</span> parameter has been set. A PropertiesList is the
64  * standard AntX bean for {@linkplain GenericParameters} or
65  * <span class="src">Properties</span>.
66  * <p>
67  * <b>Example Usage:</b><pre>
68  * &lt;<b>properties</b> id="javadoc.options"&gt;
69  * &lt;property name="visibility" value="package"/&gt;
70  * &lt;property name="maintitle" value="My API Documentation"/&gt;
71  * &lt;property name="copyleft" value="(c) 2004 Me, Myself, and I."/&gt;
72  * ...
73  * &lt;/properties&gt;
74  * ...
75  * &lt;macrodef name="apidocs"&gt;
76  * &lt;attribute name="args"/&gt;
77  * &lt;sequential&gt;
78  * &lt;javadoc
79  * access="${$prop:@{args}->visibility}"
80  * windowtitle="${$prop:@{args}->maintitle}"
81  * .../&gt;
82  * ...
83  * &lt;apidocs args="javadoc.options"/&gt;
84  * </pre>
85  *
86  * @since JWare/AntX 0.5
87  * @author ssmc, &copy;2004-2005 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
88  * @version 0.5
89  * @.safety single
90  * @.group api,helper
91  **/
92
93 public final class PropertiesList extends GenericParameters
94     implements ListFriendly, FlexSourceSupport, FixtureComponent, AntLibFriendly
95 {
96     private static final String JavaDoc IAM_= AntX.fixture+"PropertiesList:";
97
98
99     /** Default delimiter used by all property lists. **/
100     public static final String JavaDoc DEFAULT_DELIMITER = Strings.NL;
101
102
103     /**
104      * Initializes a new empty properties collection bean.
105      **/
106     public PropertiesList()
107     {
108     }
109
110
111
112     /**
113      * Initializes a new empty properties collection bean
114      * associated with project.
115      * @param project this object's enclosing project
116      **/
117     public PropertiesList(Project project)
118     {
119         setProject(project);
120     }
121
122
123
124     /**
125      * Capture our identifier for feedback since types don't
126      * always get correct location information.
127      * @param id our identifier (via build script)
128      **/
129     public void setId(String JavaDoc id)
130     {
131         m_Id= id;
132     }
133
134
135
136     /**
137      * Tries to return an unique identifier for this list.
138      **/
139     public String JavaDoc getId()
140     {
141         return m_Id;
142     }
143
144
145
146     /**
147      * Sets a custom delimiter for this properties list. This
148      * delimiter will be used by all stringification(TM)
149      * methods.
150      * @param delimiter new delimiter (non-null)
151      **/
152     public void setDelim(String JavaDoc delimiter)
153     {
154         AntX.require_(delimiter!=null,IAM_,"setDelim- nonzro delim");
155         m_delim = delimiter;
156     }
157
158
159
160     /**
161      * Returns the delimiter this list will use for all
162      * stringification(TM). Never returns <i>null</i>.
163      **/
164     public String JavaDoc getDelim()
165     {
166         return m_delim;
167     }
168
169
170
171     /**
172      * From another properties-like object, add all unique contents
173      * (no overwriting of locally defined items). The referenced
174      * thing must be an object that we can translate into a standard
175      * <span class="src">Properties</span> object.
176      * @param other reference to other properties item (non-null)
177      * @throws BuildException if reference is malformed or
178      * referred-to thing is not convertible to a Properties.
179      **/
180     public void addConfiguredProperties(ReferenceHandle other)
181     {
182         AntX.require_(other!=null,IAM_,"addProps- nonzro handle");
183         Reference r = other.getRefId();
184         if (r==null || r.getRefId()==null || r.getRefId().equals(m_Id)) {
185             String JavaDoc error = Iteration.uistrs().get
186                 ("task.bad.nested.item","properties","Invalid 'refid'");
187             log(error,Project.MSG_ERR);
188             throw new BuildException(error);
189         }
190         boolean continu = true;
191         if (other.getHaltIfMissingFlag()==Boolean.FALSE) {
192             Object JavaDoc referredTo = getProject().getReference(r.getRefId());
193             if (referredTo==null) {
194                 continu = false;
195             }
196         }
197         if (continu) {
198             Properties JavaDoc otherP = FixtureExaminer.
199                 getReferencedProperties(getProject(),r.getRefId(),null);
200             Iterator JavaDoc itr = otherP.entrySet().iterator();
201             while (itr.hasNext()) {
202                 Map.Entry JavaDoc kv = (Map.Entry JavaDoc)itr.next();
203                 String JavaDoc key = (String JavaDoc)kv.getKey();
204                 if (get(key)==null) {
205                     put(key, (String JavaDoc)kv.getValue());
206                 }
207             }
208         }
209     }
210
211
212
213     /**
214      * Returns an iterator for all stringified key-value pairs
215      * in this list. Each item is a single string of form:
216      * <i>key</i>=<i>value</i> where <i>value</i> can be the
217      * empty string.
218      * @param theProject [optional] the context project (can be
219      * <i>null</i>)
220      * @see #getDelim
221      */
222     public Iterator JavaDoc readonlyStringIterator(Project theProject)
223     {
224         Map JavaDoc items = copyOfParameterObjects();
225         List JavaDoc kvpairs = AntXFixture.newList(items.size());
226         Iterator JavaDoc itr = items.values().iterator();
227         while (itr.hasNext()) {
228             InnerNameValuePair e = (InnerNameValuePair)itr.next();
229             String JavaDoc v = e.getValue(theProject,true);
230             if (v==null) {
231                 kvpairs.add(""+e.getName());
232             } else {
233                 kvpairs.add(""+e.getName()+"="+v);
234             }
235         }
236         return kvpairs.iterator();
237     }
238
239
240
241     /**
242      * Returns the string-form appropriate for this object.
243      * @param theProject [optional] the context project (can be
244      * <i>null</i>)
245      **/
246     public String JavaDoc stringFrom(Project theProject)
247     {
248         StringBuffer JavaDoc sb = AntXFixture.newLargeStringBuffer();
249         final String JavaDoc theDelimiter = getDelim();
250
251         int N=0;
252         Iterator JavaDoc itr= readonlyStringIterator(theProject);
253
254         while (itr.hasNext()) {
255             if (N>0) {
256                 sb.append(theDelimiter);
257             }
258             sb.append(itr.next().toString());
259             N++;
260         }
261         itr=null;
262         return sb.substring(0);
263     }
264
265
266
267     /**
268      * Adds the contents of the given resource file to this list.
269      * The resource file must contain a standard Properties-formatted set
270      * of key-value pairs. This method acts as a no-op if the no such
271      * resource exists.
272      * @param rn (subpath) name of resoure (non-null)
273      * @throws BuildException if unable to read resoure once opened
274      **/
275     public void setResource(String JavaDoc rn)
276     {
277         AntX.require_(rn!=null,IAM_,"setRez- nonzro name");
278
279         InputStream JavaDoc is = LocalTk.getSystemResourceAsStream(rn, getProject());
280         if (is!=null) {
281             try {
282                 Properties JavaDoc values = new Properties JavaDoc();
283                 values.load(is);
284                 mergeOther(values);
285             } catch(IOException JavaDoc iox) {
286                 String JavaDoc error = Iteration.uistrs().get("task.bad.configfile",
287                     "resource("+rn+")", iox.getMessage());
288                 log(error,Project.MSG_ERR);
289                 throw new BuildException(error,iox);
290             }
291         } else {
292             String JavaDoc warning = Iteration.uistrs().get("task.nostream.from.rez", rn);
293             log(warning,Project.MSG_WARN);
294         }
295     }
296
297
298
299     /**
300      * Adds the contents of the named Properties file to this list.
301      * The contents of the file are <em>merged</em> with
302      * this lists current contents, unconditionally replacing any
303      * pre-existing items of same names. This method does nothing if
304      * the named file does not exist.
305      * @param filepath absolute path or project-relative path (non-null)
306      * @throws BuildException if unable to read existing file for any reason.
307      **/
308     public void setFile(String JavaDoc filepath)
309     {
310         AntX.require_(filepath!=null,IAM_,"setFile- nonzro name");
311
312         File JavaDoc f = getProject().resolveFile(filepath);
313         if (f.canRead()) {
314             try {
315                 URL JavaDoc url = AntXFixture.fileUtils().getFileURL(f);
316                 Properties JavaDoc values = InputFileLoader.loadProperties(url,null);
317                 mergeOther(values);
318             } catch(IOException JavaDoc ioX) {
319                 String JavaDoc error = Iteration.uistrs().get("task.bad.configfile",
320                     filepath, ioX.getMessage());
321                 log(error,Project.MSG_ERR);
322                 throw new BuildException(error,ioX);
323             }
324         } else {
325             String JavaDoc warning = Iteration.uistrs().get("task.err.filenotfound", filepath);
326             log(warning, Project.MSG_WARN);
327         }
328     }
329
330
331
332     /**
333      * Adds the contents of the named Properties URL to this list.
334      * The contents of the resource are <em>merged</em> with
335      * this lists current contents, unconditionally replacing any
336      * pre-existing items of same names.
337      * @param urlstring location of Properties file (non-null)
338      * @throws BuildException if unable to load resource for any reason.
339      **/
340     public void setURL(String JavaDoc urlstring)
341     {
342         AntX.require_(urlstring!=null,IAM_,"setURL- nonzro URL");
343         
344         try {
345             URL JavaDoc url = new URL JavaDoc(urlstring);
346             Properties JavaDoc values = InputFileLoader.loadProperties(url,null);
347             mergeOther(values);
348         } catch(IOException JavaDoc ioX) {
349             String JavaDoc error = Iteration.uistrs().get("task.bad.configfile",
350                 "URL("+urlstring+")", ioX.getMessage());
351             log(error,Project.MSG_ERR);
352             throw new BuildException(error,ioX);
353         }
354     }
355
356
357     private String JavaDoc m_Id = "n/d";
358     private String JavaDoc m_delim = DEFAULT_DELIMITER;
359 }
360
361
362 /* end-of-PropertiesList.java */
Popular Tags