KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > ErrorSnapshot


1 /**
2  * $Id: ErrorSnapshot.java 186 2007-03-16 13:42:35Z 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 of the License, or (at your option) any later
9  * 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;
30
31 import java.util.Hashtable JavaDoc;
32 import java.util.Iterator JavaDoc;
33 import java.util.List JavaDoc;
34 import java.util.Map JavaDoc;
35 import java.util.Properties JavaDoc;
36
37 import org.apache.tools.ant.BuildException;
38 import org.apache.tools.ant.Location;
39 import org.apache.tools.ant.Project;
40 import org.apache.tools.ant.Task;
41 import org.apache.tools.ant.types.PropertySet;
42
43 import com.idaremedia.antx.apis.FlexStringFriendly;
44 import com.idaremedia.antx.apis.Nameable;
45 import com.idaremedia.antx.helpers.Strings;
46 import com.idaremedia.antx.helpers.Tk;
47
48 /**
49  * Struct class that keeps the environment and information about a thrown build exception.
50  * Works with the AntX build-feedback modules and protected tasksets.
51  *
52  * @since JWare/AntX 0.1
53  * @author ssmc, &copy;2002-2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
54  * @version 0.5
55  * @.safety guarded
56  * @.group impl,helper
57  * @.stereo struct
58  **/
59
60 public final class ErrorSnapshot extends AssertableProjectComponent
61     implements Cloneable JavaDoc, Nameable, FlexStringFriendly
62 {
63     /**
64      * Do common task-based initialization.
65      **/
66     private void init(Task source)
67     {
68         require_(source!=null,"ctor- nonzro task");
69         setProject(source.getProject());
70         m_taskName = source.getTaskName();
71         m_targetName = source.getOwningTarget().getName();
72         setLocation(source.getLocation());
73         m_Id = "ErrorSnapshot@"+System.identityHashCode(this);
74     }
75
76
77     /**
78      * Creates a new standalone error snapshot.
79      * @since JWare/AntX 0.4
80      **/
81     public ErrorSnapshot()
82     {
83         super(AntX.flow+"protect");
84     }
85
86
87     /**
88      * Creates a new error snapshot.
89      * @param source task creating snapshot (non-null)
90      **/
91     public ErrorSnapshot(Task source)
92     {
93         super(AntX.flow+"protect");
94         init(source);
95     }
96
97
98     /**
99      * Creates a new error snapshot of thrown exception.
100      **/
101     public ErrorSnapshot(Task source, Exception JavaDoc thrown)
102     {
103         super(AntX.flow+"protect");
104         init(source);
105         setThrown(thrown);
106     }
107
108
109     /**
110      * Returns this snapshot's identifying name. Will return
111      * this object's system identifier if never set. Never
112      * returns <i>null</i>.
113      **/
114     public String JavaDoc getName()
115     {
116         return m_Id;
117     }
118
119
120     /**
121      * Sets this snapshot's name explicitly. Usually done by
122      * at construction. Cannot be set <i>null</i>.
123      **/
124     public void setName(String JavaDoc name)
125     {
126         if (name!=null) {
127             m_Id = name;
128         }
129     }
130
131
132     /**
133      * Returns name of the task that created this snapshot.
134      * Returns the empty string if this snapshot created standalone.
135      **/
136     public String JavaDoc getTaskName()
137     {
138         return m_taskName;
139     }
140
141
142     /**
143      * Changes the name of task associated with this snapshot.
144      * Useful if snapshot rendered by one task on behalf of another.
145      **/
146     public void setEffectiveTaskName(String JavaDoc taskName)
147     {
148         require_(taskName!=null,"setTskNam- nonzro nam");
149         m_taskName = taskName;
150     }
151
152
153     /**
154      * Returns name of the owning target of the task that
155      * created this snapshot. Returns empty string if this snapshot
156      * created standalone.
157      **/
158     public String JavaDoc getTargetName()
159     {
160         return m_targetName;
161     }
162
163
164     /**
165      * Changes the name of target associated with this snapshot.
166      * Useful if snapshot rendered by one target on behalf of another.
167      **/
168     public void setEffectiveTargetName(String JavaDoc targetName)
169     {
170         require_(targetName!=null,"setTrgtNam- nonzro nam");
171         m_targetName = targetName;
172     }
173
174
175     /**
176      * Sets this snapshot's <i>causing</i> exception.
177      * @param thrown the thrown exception (non-null)
178      **/
179     public synchronized void setThrown(Exception JavaDoc thrown)
180     {
181         m_thrown = thrown;
182         if (getLocation()==null && (thrown instanceof BuildException)) {
183             setLocation(((BuildException)thrown).getLocation());
184         }
185     }
186
187
188     /**
189      * Sets this snapshot's <i>causing</i> exception and updates
190      * its location to match the exception's.
191      * @param thrown the thrown exception (non-null)
192      * @param updateLoc <i>true</i> if snapshot's location should
193      * be sync'ed
194      **/
195     public synchronized void setThrown(Exception JavaDoc thrown,
196                                        boolean updateLoc)
197     {
198         m_thrown = thrown;
199         if (updateLoc && (thrown instanceof BuildException)) {
200             setLocation(((BuildException)thrown).getLocation());
201         }
202     }
203
204
205     /**
206      * Returns this snapshot's exception. Can return <i>null</i> if
207      * never defined.
208      **/
209     public Exception JavaDoc getThrown()
210     {
211         return m_thrown;
212     }
213
214
215     /**
216      * Sets this snapshot task's location.
217      **/
218     public void setLocation(Location location)
219     {
220         m_location = location;
221     }
222
223
224     /**
225      * Returns this snapshot task's location. Never returns
226      * <i>null</i> but can return unknown location.
227      **/
228     public Location getLocation()
229     {
230         return m_location;
231     }
232
233
234     /**
235      * Associates a local source comment with this snapshot.
236      **/
237     public void setComment(String JavaDoc comment)
238     {
239         m_comment = (comment==null) ? "" : comment;
240     }
241
242
243     /**
244      * Returns this snapshot's comment string. Will return
245      * empty string if never set.
246      **/
247     public final String JavaDoc getComment()
248     {
249         return m_comment;
250     }
251
252
253     /**
254      * Adds a set of properties en-masse to this snapshot.
255      * @param ps the property set to be added (as-is)
256      * @since JWare/AntX 0.4
257      **/
258     public final void addConfiguredPropertySet(PropertySet ps)
259     {
260         require_(ps!=null,"addPropSet- nonzro propset");
261         try {
262             Properties JavaDoc p= ps.getProperties();
263             synchronized(this) {
264                 if (m_env==null) {
265                     m_env = p;
266                 } else {
267                     getEnv().putAll(p);
268                     p.clear();
269                 }
270             }
271             p=null;
272         } catch(RuntimeException JavaDoc rtX) {
273             log(uistrs().get("task.bad.propset",rtX.getMessage()),
274                 Project.MSG_ERR);
275         }
276     }
277
278
279     /**
280      * Returns this snapshot's captured properties. Never
281      * returns <i>null</i>.
282      **/
283     protected synchronized Hashtable JavaDoc getEnv()
284     {
285         if (m_env==null) {
286             m_env = new Hashtable JavaDoc(31,0.8f);
287         }
288         return m_env;
289     }
290
291
292     /**
293      * Adds a captured property to this snapshot.
294      * @param name property's name (non-null)
295      * @param value property's value (non-null)
296      **/
297     public void setProperty(String JavaDoc name, String JavaDoc value)
298     {
299         if (value==null) {
300             value=Strings.NULL;
301         }
302         getEnv().put(name,value);
303     }
304
305
306     /**
307      * Saves a project property to this snapshot.
308      * @param name the project property to be captured (non-null)
309      **/
310     public void captureProperty(String JavaDoc name)
311     {
312         String JavaDoc value = getProject().getProperty(name);
313         if (value==null) {
314             value= Strings.NULL;
315         }
316         getEnv().put(name,value);
317     }
318
319
320     /**
321      * Saves a set of project properties to this snapshot.
322      * @param namesList comma-delimited list of property names (non-null)
323      **/
324     public void captureProperties(String JavaDoc namesList)
325     {
326         List JavaDoc keys = Tk.splitList(namesList,",");
327         for (int i=0,N=keys.size();i<N;i++) {
328             captureProperty((String JavaDoc)keys.get(i));
329         }
330     }
331
332
333
334     /**
335      * Saves a script-supplied set of properties to this
336      * snapshot. This method is a adaption point for saving
337      * custom property sets to a snapshot. Call must protect
338      * incoming properties against concurrent modification.
339      * @since JWare/AntX 0.4
340      **/
341     public void captureProperties(Map JavaDoc properties)
342     {
343         getEnv().putAll(properties);
344     }
345
346
347     /**
348      * Assumes a set of project properties as this snapshot's
349      * base set.
350      * @param fullP the full set of properties (user|all)
351      **/
352     private void assumeProperties(Hashtable JavaDoc fullP)
353     {
354         if (m_env==null) {
355             m_env= fullP;
356         } else {
357             Hashtable JavaDoc byhand= m_env;
358             m_env= fullP;
359             m_env.putAll(byhand);//mine wins if is existin key
360 }
361     }
362
363
364     /**
365      * Saves all user properties to this snapshot.
366      **/
367     public synchronized void captureUserProperties()// *cough*
368 {
369         assumeProperties(getProject().getUserProperties());
370     }
371
372
373     /**
374      * Saves all project properties to this snapshot.
375      **/
376     public synchronized void captureAllProperties()// *cough*
377 {
378         assumeProperties(getProject().getProperties());
379     }
380
381
382     /**
383      * Returns new copy of this snapshot's current set of
384      * properties.
385      **/
386     public synchronized Properties JavaDoc copyOfProperties()
387     {
388         Hashtable JavaDoc myP = getEnv();
389         synchronized(myP) {
390             if (myP instanceof Properties JavaDoc) {
391                 return (Properties JavaDoc)myP.clone();
392             }
393             Properties JavaDoc copiedP= new Properties JavaDoc();
394             if (!myP.isEmpty()) {
395                 Iterator JavaDoc itr= myP.entrySet().iterator();
396                 while (itr.hasNext()) {
397                     Map.Entry JavaDoc mE= (Map.Entry JavaDoc)itr.next();
398                     copiedP.setProperty(mE.getKey().toString(),
399                                         mE.getValue().toString());
400                 }
401             }
402             return copiedP;
403         }
404     }
405
406
407     /**
408      * Creates a clone of this snapshot (used if as a reference I
409      * am inherited and passed to another independent project).
410      **/
411     public synchronized Object JavaDoc clone()
412     {
413         try {
414             ErrorSnapshot copy= (ErrorSnapshot)super.clone();
415             copy.m_env = copyOfProperties();//ok even if Properties
416 return copy;
417         } catch(CloneNotSupportedException JavaDoc clnx) {
418             throw new InternalError JavaDoc(uistrs().get(AntX.CLONE_BROKEN_MSGID));
419         }
420     }
421
422
423     /**
424      * Creates a passably readable string of this ErrorSnapshot.
425      * Used by String.valueOf(&#46;&#46;&#46;) when application-specific
426      * transformation not provided.
427      **/
428     public String JavaDoc toString()
429     {
430         String JavaDoc comment = getComment();
431
432         if (getThrown()!=null) {
433             String JavaDoc what = getThrown().getMessage();
434             return (comment!=null) ? (comment+" CAUSE: '"+what+"'") : what;
435
436         } else if (comment!=null && comment.length()>0) {
437             return comment;
438
439         } else if (getLocation()!=null) {
440             return getLocation().toString();
441         }
442
443         return uistrs().get("snapshot.fallback.msg",
444                             getTargetName(),getTaskName());
445     }
446
447
448     /**
449      * Returns the underlying exception's message if present. Otherwise
450      * returns this snapshot's comment.
451      **/
452     public String JavaDoc stringFrom(Project p)
453     {
454         if (getThrown()!=null) {
455             return getThrown().getMessage();
456         }
457         return getComment();
458     }
459
460
461     private String JavaDoc m_Id;
462     private String JavaDoc m_targetName="", m_taskName="";
463     private Location m_location=Location.UNKNOWN_LOCATION;
464     private Hashtable JavaDoc m_env;
465     private String JavaDoc m_comment="";
466     private Exception JavaDoc m_thrown;
467 }
468
469 /* end-of-ErrorSnapshot.java */
470
Popular Tags