Java > Open Source Codes > com > idaremedia > antx > flowcontrol > wrap > IfErrorTask


1 /**
2  * $Id: IfErrorTask.java 180 2007-03-15 12:56:38Z ssmc $
3  * Copyright 2002-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 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.flowcontrol.wrap;
30
31 import org.apache.tools.ant.BuildException;
32 import org.apache.tools.ant.Project;
33
34 import com.idaremedia.antx.AntX;
35 import com.idaremedia.antx.ErrorSnapshot;
36 import com.idaremedia.antx.ExportedProperties;
37 import com.idaremedia.antx.FixtureExaminer;
38 import com.idaremedia.antx.apis.BuildAssertionException;
39 import com.idaremedia.antx.ownhelpers.LocalTk;
40 import com.idaremedia.antx.parameters.PropertySource;
41 import com.idaremedia.antx.starters.StrictInnerTaskSet;
42 import com.idaremedia.antx.starters.Quiet;
43
44 /**
45  * Set of tasks to be executed iff an build exception is detected by a protected taskset.
46  * Must be nested within a {@linkplain TolerantTaskSet TolerantTaskSet} like a
47  * ProtectedTaskSet.
48  * <p>
49  * If you specify an error substitution (see the <span class="src">convertto</span>
50  * option), this task will store the <em>converted</em> error to any snapshots and/or
51  * project references. The original error will be stored as the new error's causing
52  * throwable.
53  *
54  * @since JWare/AntX 0.1
55  * @author ssmc, &copy;2002-2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
56  * @version 0.5
57  * @.safety n/a
58  * @see TolerantTaskSet
59  **/
60
61 public final class IfErrorTask extends StrictInnerTaskSet implements Quiet
62 {
63     /**
64      * Creates a new iferror handler in a protected taskset.
65      **/
66     public IfErrorTask()
67     {
68         super(AntX.flow+"protect");
69     }
70
71
72     /**
73      * Sets the name of property updated with either a predefined
74      * {@linkplain #setFailValue value} or the thrown exception's
75      * message.
76      * @see #setFailValue
77      **/
78     public void setFailProperty(String property)
79     {
80         require_(property!=null,"setFailProp- nonzro propnam");
81         m_failProperty = property;
82     }
83
84
85     /**
86      * Returns name of the property to be updated iff a build
87      * exception is detected by this task's enclosing protected
88      * taskset. Returns <i>null</i> if never set.
89      **/
90     public final String getFailProperty()
91     {
92         return m_failProperty;
93     }
94
95
96     /**
97      * Sets the name of an exported property updated with either
98      * a predefined {@linkplain #setFailValue value} or the
99      * thrown exception's message.
100      * @see #setFailValue
101      * @since JWare/AntX 0.2
102      **/
103     public void setFailVariable(String variable)
104     {
105         require_(variable!=null,"setFailVar- nonzro varnam");
106         m_failVar = variable;
107     }
108
109
110     /**
111      * Returns name of the exported property to be updated iff a build
112      * exception is detected by this task's enclosing protected
113      * taskset. Returns <i>null</i> if never set.
114      **/
115     public final String getFailVariable()
116     {
117         return m_failVar;
118     }
119
120
121     /**
122      * Sets the value used to set the failure property if a
123      * build exception is detected. By default, if requested,
124      * the fail property is set to the exception's message.
125      **/
126     public void setFailValue(String value)
127     {
128         require_(value!=null,"setfailV- nonzro valu");
129         m_failValue = value;
130     }
131
132
133     /**
134      * Returns the explicit value to which the failure property
135      * is set in event of detected build exception. Returns
136      * <i>null</i> if never set.
137      **/
138     public final String getFailValue()
139     {
140         return m_failValue;
141     }
142
143
144     /**
145      * Sets the name of an {@linkplain ErrorSnapshot ErrorSnapshot}
146      * reference to be created iff a build exception is detected. This
147      * name should not refer to an existing project reference.
148      * @param reference name of <em>new</em> reference
149      **/
150     public void setCaptureSnapshotRefId(String reference)
151     {
152         m_failSnapshotRefId= reference;
153     }
154
155
156     /**
157      * Returns the name of a <em>new</em> ErrorSnapshot reference
158      * to be created iff a build exception is detected.
159      **/
160     public final String getCaptureSnapshotRefId()
161     {
162         return m_failSnapshotRefId;
163     }
164
165
166     /**
167      * Alias for {@linkplain #setCaptureSnapshotRefId setCaptureSnapshotRefId}
168      * that is typically used from build xml (easier element name).
169      **/
170     public final void setCaptureSnapshot(String newRefId)
171     {
172         setCaptureSnapshotRefId(newRefId);
173     }
174
175
176     /**
177      * Set the name of an BuildException reference to be created iff
178      * a build exception is detected. This name should not refer to
179      * an existing reference (overwritten).
180      **/
181     public void setCaptureThrownRefId(String reference)
182     {
183         m_failThrownRefId = reference;
184     }
185
186
187     /**
188      * Alias for {@linkplain #setCaptureThrownRefId setCaptureThrownRefId}
189      * that is typically used from build xml (easier element name).
190      **/
191     public final void setCaptureThrown(String thrownRefId)
192     {
193         setCaptureThrownRefId(thrownRefId);
194     }
195
196
197     /**
198      * Returns the name of the <em>new</em> BuildException reference
199      * to be created iff a build exception is detected.
200      **/
201     public final String getCaptureThrownRefId()
202     {
203         return m_failThrownRefId;
204     }
205
206
207     /**
208      * Sets a comma-delimited list of properties to be captured with
209      * an error snapshot if an exception is detected. If the given
210      * namesList is either one of the symbolic property domain names
211      * like "<span class="src">script</span>" or "<span class="src">jre</span>"
212      * all of the matching domain's properties are included in the
213      * snapshot.
214      * @param namesList comma-delimited list of names
215      * @see #setCaptureSnapshotRefId
216      **/
217     public void setCapturePropertyNames(String namesList)
218     {
219         require_(namesList!=null,"setCapturPs- nonzro list");
220         m_propertyNames= namesList;
221     }
222
223
224     /**
225      * Returns comma-delimited list of properties to be captured
226      * with an error snapshot in the event of a detected build
227      * exception. Will return <i>null</i> if never set.
228      **/
229     public final String getCapturePropertyNames()
230     {
231         return m_propertyNames;
232     }
233
234
235     /**
236      * Alias to {@linkplain #setCapturePropertyNames setCapturePropertyNames}
237      * that is typically used from build xml (easier element name).
238      **/
239     public final void setCaptureProperties(String namesList)
240     {
241         setCapturePropertyNames(namesList);
242     }
243
244
245
246     /**
247      * Tells this handler to convert the captured error to something
248      * else on script's behalf.
249      * @param what "new", "assert" or custom exception class name
250      * @since JWare/AntX 0.4
251      **/
252     public void setConvertTo(String what)
253     {
254         require_(what!=null,"setCvtTo- nonzro target");
255         m_convertTo= what;
256     }
257
258
259
260     /**
261      * Tells this handler to be quiet when it captures an error. Will
262      * prevent informative message from being written to log.
263      * @param quiet <i>true</i> if be quiet.
264      * @since JWare/AntX 0.5
265      **/
266     public final void setQuiet(boolean quiet)
267     {
268         m_tellCaught = quiet ? Boolean.FALSE : Boolean.TRUE;
269     }
270
271
272
273     /**
274      * Returns this handler's script-supplied quiet flag. Will return
275      * <i>null</i> if never set explicitly.
276      * @since JWare/AntX 0.5
277      **/
278     public final Boolean getQuietFlag()
279     {
280         return m_tellCaught;
281     }
282
283
284     /**
285      * Called by enclosing block to prepare this task for execution
286      * because of a detected build exception, rtX. By default captures
287      * any requested error snapshots and sets up failure properties.
288      * @return the incoming exception or, if requested, a substitute.
289      **/
290     final RuntimeException throwOccured(RuntimeException rtX)
291     {
292         final Project P= getProject();
293         TolerantTaskSet wrt= (TolerantTaskSet)getEnclosingTask();
294
295         if (tellCaught()) {
296             int loglevel = Project.MSG_ERR;
297             if (!wrt.isHaltIfError()) {
298                 loglevel = Project.MSG_INFO;
299             }
300             log(uistrs().get("flow.caught.failure",
301                              wrt.getOwningTarget().getName(), rtX.getMessage()),
302                 loglevel);
303         }
304
305         String what= getFailValue();
306         if (what==null) {
307             what= rtX.getMessage();
308         }
309
310         if (getFailProperty()!=null) {
311             P.setNewProperty(getFailProperty(), what);
312         }
313         if (getFailVariable()!=null) {
314             ExportedProperties.set(getFailVariable(), what);
315         }
316
317         rtX = getPreferredX(rtX);
318
319         if (getCaptureThrownRefId()!=null) {
320             String refid= getCaptureThrownRefId();
321
322             if (P.getReference(refid)!=null) {
323                 log(uistrs().get("task.warn.refid.exists",refid),Project.MSG_WARN);
324             }
325             P.addReference(refid,rtX);
326         }
327
328         if (getCaptureSnapshotRefId()!=null) {
329             String refid = getCaptureSnapshotRefId();
330
331             if (P.getReference(refid)!=null) {
332                 log(uistrs().get("task.warn.refid.exists",refid),Project.MSG_WARN);
333             }
334
335             ErrorSnapshot es= new ErrorSnapshot(wrt, rtX);
336             es.setName(refid);
337
338             String nl= getCapturePropertyNames();
339             if (nl!=null) {
340                 PropertySource domain = PropertySource.from(nl);
341                 if (domain!=null) {
342                     es.captureProperties
343                         (FixtureExaminer.copyOfProperties(domain,P));
344                 } else {
345                     es.captureProperties(nl);
346                 }
347             }
348             P.addReference(refid,es);
349         }
350
351         return rtX;
352     }
353
354
355
356     /**
357      * Replace the actual exception with a script requested
358      * substitution if necessary. Will return the original if no
359      * substitution requested or unable to create new exception.
360      * @param rtX the causing exception (non-null)
361      * @return script-requesed replacement or same if no such request
362      * @since JWare/AntX 0.4
363      **/
364     private RuntimeException getPreferredX(RuntimeException rtX)
365     {
366         if (m_convertTo!=null) {
367             if ("new".equals(m_convertTo)) {
368                 rtX = new BuildException(rtX.getMessage(),rtX,getLocation());
369             }
370             else
371             if ("assert".equals(m_convertTo)) {
372                 if (!(rtX instanceof BuildAssertionException)) {
373                     rtX = (RuntimeException )LocalTk.replaceError
374                                 (rtX, getLocation(), BuildAssertionException.class);
375                 }
376             }
377             else {
378                 rtX = (RuntimeException )LocalTk.replaceError
379                                 (rtX, getLocation(), m_convertTo);
380             }
381         }
382         return rtX;
383     }
384
385
386
387     private boolean tellCaught()
388     {
389         return m_tellCaught==null || m_tellCaught==Boolean.TRUE;
390     }
391
392
393     private String m_failProperty, m_failVar;
394     private String m_failValue;
395     private String m_failSnapshotRefId, m_failThrownRefId;
396     private String m_propertyNames;
397     private String m_convertTo;
398     private Boolean m_tellCaught;//NB: null=>YES!
399 }
400
401 /* end-of-IfErrorTask.java */
402

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags