KickJava   Java API By Example, From Geeks To Geeks.

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


1 /**
2  * $Id: StrictAntLib.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.starters;
30
31 import java.util.Iterator JavaDoc;
32 import java.util.List JavaDoc;
33
34 import org.apache.tools.ant.BuildException;
35 import org.apache.tools.ant.Location;
36 import org.apache.tools.ant.Project;
37 import org.apache.tools.ant.Task;
38 import org.apache.tools.ant.UnknownElement;
39 import org.apache.tools.ant.taskdefs.Antlib;
40 import org.apache.tools.ant.taskdefs.AntlibDefinition;
41
42 import com.idaremedia.antx.AntX;
43 import com.idaremedia.antx.AntXFixture;
44 import com.idaremedia.antx.helpers.TaskHandle;
45 import com.idaremedia.antx.helpers.Tk;
46 import com.idaremedia.antx.ownhelpers.TaskExaminer;
47
48 /**
49  * Starting implementation for an AntX-based Antlib that restricts its contents in some
50  * way. For example, an AntXtras ACM definition file will limit its contents to a single
51  * <span class="src">&lt;macrodef&gt;</span>. The filtering process this task uses to
52  * limit its contents is like that used by the AntX {@linkplain TaskSet} class.
53  *
54  * @since JWare/AntX 0.5
55  * @author ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
56  * @version 0.5
57  * @.safety single
58  * @.group impl,infra
59  **/
60
61 public abstract class StrictAntLib extends Antlib implements StrictOuterTask
62 {
63     /**
64      * Initializes a new strict antlib instance.
65      * @since JWare/AntX 0.5
66      */
67     protected StrictAntLib()
68     {
69         super();
70         Iam_ = AntX.fixture+"AntLib:";
71     }
72
73
74
75     /**
76      * Initializes a new labeled strict antlib instance.
77      * @param iam CV-label (non-null)
78      * @since JWare/AntX 0.5
79      */
80     protected StrictAntLib(String JavaDoc iam)
81     {
82         super();
83         Iam_= Tk.cvlabelFrom(iam);
84     }
85
86
87
88     /**
89      * Initializes the default URI for all definitions loaded by
90      * this library.
91      * @param uri the XML-NS URI identifier
92      **/
93     public void setURI(String JavaDoc uri)
94     {
95         super.setURI(uri);
96         m_uriLocal = uri;
97     }
98
99
100
101     /**
102      * Returns the default URI used for this library's definition
103      * items. Will return <i>null</i> if never set explicitly.
104      */
105     public final String JavaDoc getDefaultItemURI()
106     {
107         return m_uriLocal;
108     }
109
110
111
112     /**
113      * Initializes the default classloader of all definitions
114      * loaded by this library.
115      * @param cl the class loader
116      */
117     public void setClassLoader(ClassLoader JavaDoc cl)
118     {
119         super.setClassLoader(cl);
120         m_clLocal = cl;
121     }
122
123
124
125     /**
126      * Returns the default class loader used for this library's
127      * definition items. Will return <i>null</i> if never set.
128      */
129     public final ClassLoader JavaDoc getDefaultItemClassLoader()
130     {
131         if (m_clLocal==null) {
132             m_clLocal= Antlib.class.getClassLoader();
133         }
134         return m_clLocal;
135     }
136
137
138
139     /**
140      * Adds another library definition task to this library if
141      * allowed. Definition is performed when this library executed.
142      * @param task task to be added (non-null)
143      * @throws BuildException if task cannot be included in library
144      * @since JWare/AntX 0.5
145      **/
146     public void addTask(Task task)
147     {
148         TaskHandle taskH = new TaskHandle(task);
149
150         if (includeTask(taskH)) {
151             getTasksList().add(taskH.getTask());
152         } else {
153             String JavaDoc ermsg = AntX.uistrs().get("taskset.nested.task.disallowed",
154                                     task.getTaskName(), this.getTaskName());
155             log(ermsg, Project.MSG_ERR);
156             throw new BuildException(ermsg,getLocation());
157         }
158     }
159
160
161
162     /**
163      * Returns this library's list of nested definitions. Each element
164      * is list has been verified by {@linkplain #includeTask includeTask}.
165      * @since JWare/AntX 0.5
166      **/
167     protected final List JavaDoc getTasksList()
168     {
169         return m_nestedTasks;
170     }
171
172
173
174     /**
175      * Returns <i>true</i> if task inside handle is allowed to nest
176      * within this library. By default returns <i>true</i> if the task
177      * is an instance of the <span class="src">AntlibDefinition</span>.
178      * This method can also switch the task to be included in this
179      * library by updating the incoming handle. Warning: the task should
180      * never be set to <i>null</i> if this method returns <i>true</i>.
181      * @param taskH the task to be nested (as handle)
182      * @since JWare/AntX 0.5
183      * @see #checkTaskCount checkTaskCount
184      * @see #checkTaskType checkTaskType
185      **/
186     protected boolean includeTask(TaskHandle taskH)
187     {
188         boolean ok= checkTaskCount(taskH);
189         if (ok) {
190             Class JavaDoc c = TaskExaminer.trueClass(taskH.getTask());
191             ok = checkTaskType(c,taskH);
192         }
193         return ok;
194     }
195
196
197
198     /**
199      * Template method that should verify whether another task can be
200      * added to this library. Called by {@linkplain #includeTask includeTask}.
201      * Many strict library limit the number of elements that can be
202      * defined per library file.
203      * @param taskH the task to be nested (as handle)
204      * @return <i>false</i> if another task cannot be added
205      **/
206     protected boolean checkTaskCount(TaskHandle taskH)
207     {
208         return true;
209     }
210
211
212
213     /**
214      * Template method that should verify whether a task of a particular
215      * type can be added to this library.
216      * @param c the true class of the task under test (non-null)
217      * @param taskH the task to be nested (as handle)
218      * @return <i>false</i> if task of named type cannot be added
219      **/
220     protected boolean checkTaskType(Class JavaDoc c, TaskHandle taskH)
221     {
222         return c!=null && AntlibDefinition.class.isAssignableFrom(c);
223     }
224
225
226
227     /**
228      * Verifies we're in a live project (created from build process).
229      * @throws IllegalStateException if not in project
230      **/
231     protected final void verifyInProject_(String JavaDoc calr)
232     {
233         if (getProject()==null) {
234             String JavaDoc ermsg = AntX.uistrs().get("cv.verifyInP",Iam_,calr);
235             log(ermsg, Project.MSG_ERR);
236             throw new IllegalStateException JavaDoc(ermsg);
237         }
238     }
239
240
241
242     /**
243      * Ensures this library can proceed with task installation. By
244      * default just checks to make sure our project reference has
245      * been defined. Subclasses will often check to make sure at least
246      * one library item has been defined.
247      * @param calr calling scope's identifier (non-null)
248      **/
249     protected void verifyCanExecute_(String JavaDoc calr)
250     {
251         verifyInProject_(calr);
252     }
253
254
255
256     /**
257      * Executes a single nested library task. The incoming library
258      * task must be already configured (not a placeholder) and
259      * initialized.
260      * @param nestedTask the library task (non-null)
261      **/
262     protected void performLibraryTask(Task nestedTask)
263     {
264         AntlibDefinition libTask = (AntlibDefinition)nestedTask;
265         libTask.setURI(getDefaultItemURI());
266         libTask.setAntlibClassLoader(getDefaultItemClassLoader());
267         libTask.execute();//@.impl Use execute and *not* perform!
268 }
269
270
271
272     /**
273      * Method called before this antlib performs its nested
274      * library tasks. Does nothing by default.
275      **/
276     protected void aboutToInstall()
277     {
278         //nothing
279 }
280     
281
282
283     /**
284      * Method called after this antlib has tried to perform
285      * its nested tasks. The incoming uncaught exception reference
286      * will be non-null if this task aborted prematurely due to
287      * an unhandled exception; otherwise, it is <i>null</i>. Does
288      * nothing by default.
289      * @param uncaught [optional] reason for termination
290      **/
291     protected void installCompleted(RuntimeException JavaDoc uncaught)
292     {
293         //nothing
294 }
295
296
297
298     /**
299      * Performs each of this library's nested elements. Does nothing
300      * if this library is empty. Implemented as a template method with
301      * several predefined hook methods for subclasses.
302      * @see #aboutToInstall
303      * @see #performLibraryTask performLibraryTask(&#8230;)
304      * @see #installCompleted installCompleted(&#8230;)
305      * @.pattern GoF.TemplateMethod
306      **/
307     public void execute()
308     {
309         verifyCanExecute_("exec");
310         
311         List JavaDoc tl = getTasksList();
312         
313         RuntimeException JavaDoc failure=null;
314         aboutToInstall();
315         try {
316             if (!tl.isEmpty()) {
317                 Location libLocation = getLocation();
318
319                 for (Iterator JavaDoc itr= tl.iterator();itr.hasNext();) {
320                     Task libitem = (Task)itr.next();
321                     setLocation(libitem.getLocation());
322
323                     if (libitem instanceof UnknownElement) {
324                         UnknownElement ue= (UnknownElement)libitem;
325                         ue.maybeConfigure();
326                         libitem = ue.getTask();
327                     }
328                     if (libitem!=null) {
329                         performLibraryTask(libitem);
330                     }
331                 }
332
333                 setLocation(libLocation);
334             }
335         } catch(RuntimeException JavaDoc rtX) {
336             failure = rtX;
337             throw rtX;
338         } finally {
339             installCompleted(failure);
340         }
341     }
342
343
344     protected final String JavaDoc Iam_;
345     private List JavaDoc m_nestedTasks= AntXFixture.newList(10);
346     private String JavaDoc m_uriLocal;
347     private ClassLoader JavaDoc m_clLocal;
348 }
349
350
351 /* end-of-StrictAntLib.java */
Popular Tags