KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > starters > StringItemListHandle


1 /**
2  * $Id: StringItemListHandle.java 186 2007-03-16 13:42:35Z ssmc $
3  * Copyright 2003-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 as published by the
8  * Free Software Foundation; either version 2.1 of the License, or (at your option) any
9  * 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 (GNU Lesser General Public License) 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 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.starters;
30
31 import java.util.Iterator JavaDoc;
32
33 import org.apache.tools.ant.BuildException;
34 import org.apache.tools.ant.Project;
35 import org.apache.tools.ant.types.Reference;
36
37 import com.idaremedia.antx.AntX;
38 import com.idaremedia.antx.AssertableProjectComponent;
39 import com.idaremedia.antx.apis.FlexStringFriendly;
40 import com.idaremedia.antx.helpers.Strings;
41 import com.idaremedia.antx.ownhelpers.LocalTk;
42
43 /**
44  * Helper that can refer to any {@linkplain StringItemList} implementatation instance.
45  * Useful when an task or type implementation is only interested in itemlists in a
46  * generic sense and needs to define a bean-friendly typed parameter setter. Instead of
47  * using a specific itemlist subclass, the task can define their setter in terms of a
48  * StringItemListHandle.
49  * <p>
50  * <b>Examples:</b><pre>
51  * --Given Two KindsOf ItemLists--
52  * &lt;<b>strings</b> id="ignoredfiles" prefix="*."&gt;
53  * &lt;string value="last"&gt;
54  * &lt;string value="jar"&gt;
55  * &lt;string value="gz"&gt;
56  * &lt;string value="tgz"&gt;
57  * &lt;/strings&gt;
58  * &lt;<b>urls</b> id="ftpservers"&gt;
59  * &lt;url value="ftp://ftp.apache.org/"/&gt;
60  * &lt;url value="ftp://ftp.eclipse.org/"/&gt;
61  * &lt;/urls&gt;
62  *
63  * --MkFileTask uses a StringItemListHandle to handle both list types as &lt;lines&gt;--
64  *
65  * &lt;<b>newfile</b> path="${work}/lib/.cvsignore"&gt;
66  * &lt;line value="classes"/&gt;
67  * &lt;lines listref="ignoredfiles"/&gt;
68  * &lt;/newfile&gt;
69  *
70  * &lt;<b>newfile</b> path="${tempdir}/ftp.in" persist="no"&gt;
71  * &lt;lines listref="ftpservers"/&gt;
72  * &lt;/newfile&gt;
73  * </pre>
74  *
75  * @since JWare/AntX 0.3
76  * @author ssmc, &copy;2003-2005 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
77  * @version 0.5
78  * @.safety guarded (once fully configured)
79  * @.group api,helper
80  **/
81
82 public class StringItemListHandle extends AssertableProjectComponent
83     implements Cloneable JavaDoc, ListFriendly
84 {
85     /**
86      * Initializes a new StringItemList handle instance.
87      * @see #setListRef setListRef()
88      **/
89     public StringItemListHandle()
90     {
91         super(AntX.starters+"ItemListHandle:");
92     }
93
94
95
96     /**
97      * Initializes a StringItemList handle with list reference.
98      * @param ref the existing reference to an item list (non-null)
99      * @see #setListRef setListRef()
100      **/
101     public StringItemListHandle(Reference ref)
102     {
103         super(AntX.starters+"ItemListHandle:");
104         require_(ref!=null && ref.getRefId()!=null,"ctor- nonzro refId");
105         setListRef(LocalTk.referenceFor(ref));
106     }
107
108
109
110     /**
111      * Returns a clone of this itemlist handle. Clones the underlying
112      * reference-- not the refered-to itemlist.
113      **/
114     public final Object JavaDoc clone()
115     {
116         try {
117             StringItemListHandle cloned = (StringItemListHandle)super.clone();
118             if (m_listReference!=null) {
119                 cloned.m_listReference =
120                     LocalTk.referenceFor(m_listReference.getRefId(),getProject());
121             }
122             return cloned;
123         } catch(CloneNotSupportedException JavaDoc clnx) {
124             throw new Error JavaDoc(uistrs().get(AntX.CLONE_BROKEN_MSGID));
125         }
126     }
127
128
129
130     /**
131      * Initializes this handle's refered-to itemlist.
132      * @param r the reference (non-null)
133      **/
134     public final void setListRef(Reference r)
135     {
136         require_(r!=null,"setRef- nonzro ref");
137         m_listReference = r;
138     }
139
140
141
142     /**
143      * Returns this handle's current itemlist reference. Can return
144      * <i>null</i> if never set.
145      **/
146     public final Reference getListRef()
147     {
148         return m_listReference;
149     }
150
151
152
153     /**
154      * Tells this itemlist handle whether to return raw unprocessed
155      * strings of the target list. Defaults "no".
156      * @param raw <i>true</i> if unprocessed strings (by default).
157      * @since JWare/AntX 0.5
158      **/
159     public final void setRaw(Boolean JavaDoc raw)
160     {
161         if (StringItemList.RAW.equals(raw)) {
162             m_how = StringItemList.RAW;
163         } else {
164             m_how = StringItemList.PROCESSED;
165         }
166     }
167
168
169
170     /**
171      * Returns the string itemlist to which this handle is referring.
172      * @param theProject [optionll] project from which the reference is
173      * read. If <i>null</i> this handle uses its own enclosing
174      * project.
175      * @throws BuildException if this handle undefined, the reference
176      * doesn't exist, or the refered-to-thing is not a string
177      * itemlist.
178      **/
179     public final StringItemList getList(Project theProject)
180     {
181         String JavaDoc error = null;
182
183         if (getListRef()==null) {
184             error = uistrs().get("type.needs.this.attr",
185                                  getUsedForName(),"listref");
186             log(error,Project.MSG_ERR);
187             throw new BuildException(error);
188         }
189
190         if (theProject==null) {
191             theProject= getProject();
192             verify_(theProject!=null,"getRefObj- hav project");
193         }
194
195         String JavaDoc refid = getListRef().getRefId();
196         Object JavaDoc o = theProject.getReference(refid);
197
198         if (o==null) {
199             error = uistrs().get("task.missing.refid", refid);
200         }
201         else if (!StringItemList.class.isAssignableFrom(o.getClass())) {
202             error = uistrs().get("task.bad.refid", refid,
203                                  StringItemList.class.getName(),
204                                  o.getClass().getName());
205         }
206         if (error!=null) {
207             log(error,Project.MSG_ERR);
208             throw new BuildException(error);
209         }
210         return (StringItemList)o;
211     }
212
213
214
215     /**
216      * Convenience to return a string iterator for a <em>snapshot</em>
217      * of the referred-to itemlist.
218      * @see StringItemList#readonlyStringIterator(Project)
219      * readonlyStringIterator(Project)
220      * @see #setRaw setRaw(boolean)
221      **/
222     public final Iterator JavaDoc readonlyStringIterator(Project theProject)
223     {
224         return getList(theProject).readonlyStringIterator(theProject,m_how);
225     }
226
227
228
229     /**
230      * Returns <i>true</i> if this handle is undefined or its targetted
231      * list item is empty.
232      **/
233     public final boolean isEmpty()
234     {
235         if (getListRef()==null) {
236             return true;
237         }
238         verifyInProject_("isEmpty");
239         StringItemList list = getList(getProject());
240         return list.isEmpty();
241     }
242
243
244
245
246     /**
247      * Returns the number of items in this list's targetted list item.
248      * Will return zero if this handle has no list.
249      **/
250     public final int size()
251     {
252         if (getListRef()==null) {
253             return 0;
254         }
255         verifyInProject_("isEmpty");
256         return getList(getProject()).size();
257     }
258
259
260
261     /**
262      * Helper that returns a newline-delimited list of an itemlist's
263      * stringified form. Returns the empty string if the list is
264      * <i>null</i>.
265      * @param il the itemlist to be converted
266      * @param P [optional] project from which properties resolved.
267      **/
268     public static final String JavaDoc byLineStringFrom(StringItemList il, Project P)
269     {
270         if (il==null) {
271             return "";
272         }
273         int i=0;
274         StringBuffer JavaDoc sb = new StringBuffer JavaDoc(100);
275         Iterator JavaDoc itr= il.readonlyStringIterator(P);
276         while (itr.hasNext()) {
277             if (i>0) {
278                 sb.append(Strings.NL);
279             }
280             sb.append(itr.next());
281             i++;
282         }
283         return sb.substring(0);
284     }
285
286
287
288     /**
289      * Returns a newline-delimited list of this handle's underlying
290      * itemlist. Returns the empty string if this handle has no
291      * defined itemlist reference.
292      * @param P [optional] project from which reference read.
293      * @see #byLineStringFrom(StringItemList,Project)
294      * byLineStringFrom(StringItemList,Project)
295      **/
296     public final String JavaDoc byLineStringFrom(Project P)
297     {
298         if (getListRef()==null) {
299             return "";
300         }
301         return byLineStringFrom(getList(P), P);
302     }
303
304
305
306     /**
307      * Returns a flex-string friendly value of this handle's refered-to
308      * itemlist. If the underlying itemlist implements the
309      * FlexStringFriendly interface, it's method is used directly;
310      * otherwise, this method returns a newline-delimined list of
311      * the underlying itemlist's strings.
312      * @see #byLineStringFrom(Project)
313      * @param P [optional] project from which reference read.
314      **/
315     public String JavaDoc stringFrom(Project P)
316     {
317         if (getListRef()==null) {
318             return "";
319         }
320         StringItemList il = getList(P);
321         if (il instanceof FlexStringFriendly) {
322             return ((FlexStringFriendly)il).stringFrom(P);
323         }
324         return byLineStringFrom(il,P);
325     }
326
327
328
329     /**
330      * Returns the underlying itemlist's string form. Uses this
331      * object's enclosing project as source of reference.
332      **/
333     public String JavaDoc toString()
334     {
335         if (getListRef()==null) {
336             return "";
337         }
338         verifyInProject_("toString");
339         return getList(getProject()).toString();
340     }
341
342
343
344     /**
345      * Returns this handle's used-as field name. Defaults to
346      * "items" if never defined. Never returns <i>null</i>.
347      **/
348     public final String JavaDoc getUsedForName()
349     {
350         return m_typicalName;
351     }
352
353
354
355     /**
356      * Customizes this handle's used-as field name. Used in error
357      * messages.
358      **/
359     public final void setUsedForName(String JavaDoc name)
360     {
361         require_(name!=null,"setUsedForNam- nonzro nam");
362         m_typicalName = name;
363     }
364
365
366     private Reference m_listReference;
367     private String JavaDoc m_typicalName= "items";
368     private Boolean JavaDoc m_how = StringItemList.PROCESSED;
369 }
370
371 /* end-of-StringItemListHandle.java */
372
Popular Tags