KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > construct > ItemConstructorTask


1 /**
2  * $Id: ItemConstructorTask.java 180 2007-03-15 12:56:38Z ssmc $
3  * Copyright 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.construct;
30
31 import java.util.Map JavaDoc;
32
33 import org.apache.tools.ant.BuildException;
34 import org.apache.tools.ant.Project;
35 import org.apache.tools.ant.Task;
36 import org.apache.tools.ant.TaskContainer;
37 import org.apache.tools.ant.UnknownElement;
38
39 import com.idaremedia.antx.AssertableTask;
40 import com.idaremedia.antx.FixtureExaminer;
41 import com.idaremedia.antx.apis.Nameable;
42 import com.idaremedia.antx.ownhelpers.UEContainerProxy;
43 import com.idaremedia.antx.parameters.FeedbackLevel;
44
45
46 /**
47  * Fixture configuration instruction that creates a new Ant item and installs it as
48  * a top-level project reference. Unless told otherwise, a constructor will overwrite
49  * an existing reference with its nested object's definition.
50  *
51  * @since JWare/AntX 0.5
52  * @author ssmc, &copy;2005 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
53  * @version 0.5
54  * @.safety single
55  * @.group impl,helper
56  **/
57
58 public abstract class ItemConstructorTask extends AssertableTask
59     implements Nameable, TaskContainer
60 {
61     /**
62      * Initializes a new item constructor instance.
63      **/
64     protected ItemConstructorTask(String JavaDoc iam)
65     {
66         super(iam);
67     }
68
69
70 // ---------------------------------------------------------------------------------------
71 // Script-facing Parameters:
72 // ---------------------------------------------------------------------------------------
73
74     /**
75      * Set the target reference's identifier (non-null)
76      * @param dstRefId reference id to install item under (non-null)
77      * @see #setHaltIfExists setHaltIfExists(&#8230;)
78      **/
79     public void setName(String JavaDoc dstRefId)
80     {
81         require_(dstRefId!=null, "setName- nonzro refid");
82         m_toRefId = dstRefId;
83     }
84
85
86
87
88     /**
89      * Returns the (new) target reference's identifer.
90      * Returns <i>null</i> if never set and source never
91      * set.
92      **/
93     public final String JavaDoc getName()
94     {
95         return m_toRefId;
96     }
97
98
99
100     /**
101      * Sets if this task will generate a build error if the
102      * destination reference id already exists within its project.
103      * Trumps the 'overwrite' option.
104      * @param halt <i>true</i> to throw build exception
105      * @see #setName setName
106      * @see #setOverwrite setOverwrite
107      **/
108     public void setHaltIfExists(boolean halt)
109     {
110         m_haltIfExists = halt;
111     }
112
113
114
115     /**
116      * Returns <i>true</i> if this task will generate a build error
117      * if the destination reference id already exists within its
118      * project. Defaults <i>false</i> (supports overwrites).
119      **/
120     public final boolean isHaltIfExists()
121     {
122         return m_haltIfExists;
123     }
124
125
126
127     /**
128      * Sets if this task will overwrite an existing reference.
129      * This option is ignored if the 'haltiferror' option
130      * is turned on.
131      * @see #setHaltIfExists
132      * @param allowOverwrite <i>true</i> if can overwrite old reference
133      **/
134     public void setOverwrite(boolean allowOverwrite)
135     {
136         m_allowOverwrite = allowOverwrite;
137     }
138
139
140
141     /**
142      * Returns <i>true</i> if this task will overwrite an existing
143      * reference. Defaults <i>true</i>. Ignored if 'haltiferror'
144      * option is turned on.
145      **/
146     public final boolean willAllowOverwrite()
147     {
148         return m_allowOverwrite;
149     }
150
151
152
153     /**
154      * Tells this task how much non-diagnostic feedback to generate.
155      * Really only has "loud" vs. "quiet-ish" interpretation. If
156      * set quiet, this task will not issue a warning if it overwrites
157      * an existing reference.
158      * @param level feedback level (non-null)
159      **/
160     public void setFeedback(String JavaDoc level)
161     {
162         require_(level!=null,"setFeedback- nonzro level");
163         FeedbackLevel fbl = FeedbackLevel.from(level);
164         if (fbl==null) {
165             String JavaDoc e = getAntXMsg("task.illegal.param.value",
166                            getTaskName(), level, "feedback");
167             log(e, Project.MSG_ERR);
168             throw new BuildException(e, getLocation());
169         }
170         m_fbLevel = fbl;
171     }
172
173
174
175     /**
176      * Returns this task's assigned feedback level. Will return
177      * <i>null</i> by default.
178      **/
179     public final FeedbackLevel getFeedbackLevel()
180     {
181         return m_fbLevel;
182     }
183
184
185 // ---------------------------------------------------------------------------------------
186 // Script-facing Nested Elements:
187 // ---------------------------------------------------------------------------------------
188
189
190     /**
191      * Stashes the named UE proxy for subsequent installation.
192      * @param task the unknown element task proxy (non-null)
193      **/
194     public void addTask(Task task)
195     {
196         require_(task instanceof UnknownElement, "addTask- is UE proxy");
197         UnknownElement ue = (UnknownElement)task;
198         if (m_itemUE!=null) {
199             String JavaDoc ermsg = uistrs().get("taskset.only.one.specialtask",
200                                         ue.getQName(), m_itemQName);
201             log(ermsg,Project.MSG_ERR);
202             throw new BuildException(ermsg,getLocation());
203         }
204         m_itemQName = ue.getQName();
205         m_itemUE = new UEContainerProxy(ue);
206     }
207
208
209 // ---------------------------------------------------------------------------------------
210 // Execution:
211 // ---------------------------------------------------------------------------------------
212
213
214     /**
215      * Installs the nested item declaration as a top-level reference
216      * in this task's parent project.
217      * @throws BuildException if verification fails.
218      */
219     public void execute()
220     {
221         verifyCanExecute_("exec");
222         
223         String JavaDoc refid = getName();
224         final Project P = getProject();
225         boolean quiet = FeedbackLevel.isQuietish(m_fbLevel,true,true);
226
227         Object JavaDoc there = FixtureExaminer.trueReference(P,refid);
228         if (there==FixtureExaminer.PENDING_REFERENCE) {
229             quiet = true;
230             there = null;
231         }
232
233         Map JavaDoc refs = P.getReferences();
234         if (there!=null) {
235             String JavaDoc msg = uistrs().get("task.warn.refid.exists",refid);
236             if (isHaltIfExists()) {
237                 log(msg,Project.MSG_ERR);
238                 throw new BuildException(msg,getLocation());
239             }
240             if (!willAllowOverwrite()) {
241                 if (!quiet) {
242                     log(msg,Project.MSG_VERBOSE);
243                 }
244                 m_itemUE = null;
245                 return;
246             }
247             if (!quiet) {
248                 log(msg,Project.MSG_WARN);
249             }
250         }
251
252         Object JavaDoc actual = beforeInstall(m_itemUE);
253         verify_(actual!=null,"exec- nonzro item");
254
255         if (quiet) {
256             refs.put(refid,actual);
257         } else {
258             P.addReference(refid,actual);
259         }
260
261         m_itemUE = null;
262     }
263
264
265
266     /**
267      * Verifies that this task has at least its source reference
268      * identifier set.
269      * @throws BuildException if missing any required bits.
270      **/
271     public void verifyIsDefined()
272     {
273         if (getName()==null) {
274             String JavaDoc ermsg = uistrs().get("task.needs.this.attr",
275                 getTaskName(),"name");
276             log(ermsg,Project.MSG_ERR);
277             throw new BuildException(ermsg,getLocation());
278         }
279         if (m_itemUE==null) {
280             String JavaDoc ermsg = uistrs().get("task.needs.oneof.these.nested",
281                 getTaskName(),"<any ant component>");
282             log(ermsg,Project.MSG_ERR);
283             throw new BuildException(ermsg,getLocation());
284         }
285     }
286
287
288
289     /**
290      * Verifies this task is completely defined with a target refid
291      * and definition sub-element.
292      * @throws BuildException if not in project or not defined properly.
293      **/
294     protected void verifyCanExecute_(String JavaDoc calr)
295     {
296         verifyInProject_(calr);
297         verifyIsDefined();
298     }
299
300
301
302     /**
303      * Called just before the new item's proxy is inserted into the
304      * project's reference table. Subclasses can perform the item (if
305      * it is a task) or do further adjustments. The returned object
306      * can be proxy or the underlying real object; it cannot be <i>null</i>.
307      * @param ue wrapper for the item to be installed (non-null)
308      * @return the object to be installed (cannot be <i>null</i>)
309      **/
310     protected Object JavaDoc beforeInstall(UEContainerProxy ue)
311     {
312         return ue;
313     }
314
315
316     private String JavaDoc m_toRefId;
317     private boolean m_haltIfExists;//NB:false allow overwrites!
318 private boolean m_allowOverwrite=true;//NB:true allow overwrites!
319 private FeedbackLevel m_fbLevel=FeedbackLevel.NORMAL;//NB:=>overwrite noise
320 private UEContainerProxy m_itemUE;
321     private String JavaDoc m_itemQName;
322 }
323
324 /* end-of-ItemConstructorTask.java */
Popular Tags