KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > capture > CaptureLogsTask


1 /**
2  * $Id: CaptureLogsTask.java 180 2007-03-15 12:56:38Z ssmc $
3  * Copyright 2002-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.capture;
30
31 import org.apache.tools.ant.BuildEvent;
32 import org.apache.tools.ant.BuildListener;
33 import org.apache.tools.ant.Project;
34
35 import com.idaremedia.antx.AntX;
36 import com.idaremedia.antx.NoiseLevel;
37 import com.idaremedia.antx.apis.ProblemHandler;
38 import com.idaremedia.antx.helpers.Strings;
39 import com.idaremedia.antx.ownhelpers.LocalTk;
40 import com.idaremedia.antx.starters.BuildListenerSkeleton;
41 import com.idaremedia.antx.starters.TaskSet;
42
43 /**
44  * Diagnostics helper task that records all the Ant messages logged by its nested tasks.
45  * Particularly useful to test scripts when combined with the &lt;assertlogged&gt;
46  * evaluation task.
47  * <p>
48  * <b>Example Usage:</b><pre>
49  * &lt;capturelogs&gt;
50  * &lt;echo level="warning" message="((A warning))"/&gt;
51  * &lt;assertlogged value="((A warning))"/&gt;
52  * &lt;echo level="verbose" message="((Verbose message))"/&gt;
53  * &lt;assertlogged value="((Verbose message))" occurances="0"/&gt;
54  * &lt;assertlogged important="no" value="((Verbose message))" occurances="1"/&gt;
55  * &lt;assertlogged important="no"&gt;
56  * &lt;string value="((A warning))"/&gt;
57  * &lt;string value="((Verbose message))"/&gt;
58  * &lt;/assertlogged&gt;
59  * &lt;/capturelogs&gt;
60  * </pre>
61  *
62  * @since JWare/AntX 0.2
63  * @author ssmc, &copy;2002-2005 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
64  * @version 0.5
65  * @.safety guarded (for log writes/reads after fully configured)
66  * @.group impl,helper
67  * @see AssertLoggedTask
68  * @see CopyLoggedTask
69  **/
70
71 public class CaptureLogsTask extends TaskSet implements LogsRecorder
72 {
73     /**
74      * Initializes a new CaptureLogsTask instance.
75      **/
76     public CaptureLogsTask()
77     {
78         super(AntX.capture+"CaptureLogsTask:");
79     }
80
81
82     /**
83      * Initializes a new CV-labeled CaptureLogsTask instance.
84      * @param iam CV-label (non-null)
85      **/
86     public CaptureLogsTask(String JavaDoc iam)
87     {
88         super(iam);
89     }
90
91
92
93     /**
94      * Sets the context's important noise level threshold. Messages
95      * logged at or lower than the important threshold are captured
96      * in this task's <i>{@linkplain #getImportantBuffer high priority}</i>
97      * buffer as well as the regular <i>{@linkplain #getAllBuffer all}</i>
98      * buffer. Usually the important threshold is set at INFO or lower
99      * (WARNING, ERROR, FATAL). Defaults to capturing messages at the
100      * the AntX default noise level (INFO) or lower to the high priority
101      * buffer. Setting to <i>null</i> will reset this task to use the
102      * default.
103      * @param threshold the important noise level threshold (inclusive)
104      * @.safety single
105      **/
106     public void setImportantFrom(NoiseLevel threshold)
107     {
108         if (threshold==NoiseLevel.FATAL) {
109             threshold = NoiseLevel.ERROR;//Pin since never logged here!
110 }
111         m_importantThreshold= threshold;
112     }
113
114
115
116     /**
117      * Returns this recorder's important noise level threshold.
118      * Returns the {@linkplain NoiseLevel#getDefault AntX default} if
119      * never explicitly defined or reset.
120      **/
121     public NoiseLevel getImportantThreshold()
122     {
123         NoiseLevel nl= m_importantThreshold;
124         return (nl!=null) ? nl : NoiseLevel.getDefault(getProject());
125     }
126
127
128
129     /**
130      * Returns <i>true</i> if this task would consider the given
131      * noise level important.
132      * @param nl noise level (non-null)
133      **/
134     public final boolean isImportant(NoiseLevel nl)
135     {
136         require_(nl!=null,"isImportnt- nonzro NL");
137         if (NoiseLevel.isAsBadAs(nl,getImportantThreshold())) {
138             return true;
139         }
140         return false;
141     }
142
143
144
145     /**
146      * Tells this task whether captured messages should be separated
147      * with a platform-specific newline sequence.
148      * @param splitEm <i>true</i> to separate messages entries
149      * @since JWare/AntX 0.3
150      **/
151     public void setSplitEntries(boolean splitEm)
152     {
153         m_splitMsgs = splitEm;
154     }
155
156
157     /**
158      * Returns <i>true</i> if this task will insert a platform-specific
159      * newline sequence between each captured message. Is off by default.
160      * @since JWare/AntX 0.3
161      **/
162     public final boolean willSplitEntries()
163     {
164         return m_splitMsgs;
165     }
166
167
168
169     /**
170      * Tells this task to include a message's source if possible.
171      * A source label is not included by default.
172      * @since JWare/AntX 0.4
173      **/
174     public void setIncludeSource(boolean includeEm)
175     {
176         m_addMsgSource = includeEm;
177     }
178
179
180     /**
181      * Returns <i>true</i> if this task will include source
182      * information (like task or target name) for each captured
183      * message. Is off by default.
184      * @since JWare/AntX 0.4
185      **/
186     public final boolean willIncludeSource()
187     {
188         return m_addMsgSource;
189     }
190
191
192
193     /**
194      * Returns a <em>copy</em> of current high priority buffer's
195      * contents. The messages captured to this buffer are determined
196      * by this task's importance threshold.
197      * @see #setImportantFrom
198      **/
199     public String JavaDoc copyOfImportantLogs()
200     {
201         return getImportantBuffer().substring(0);
202     }
203
204
205
206     /**
207      * Returns a <em>copy</em> of all contents captured by this
208      * task so far. The returned string contains all levels of messages
209      * from DEBUG to FATAL since this task was executed or last reset.
210      * @see #copyOfImportantLogs
211      **/
212     public String JavaDoc copyOfAllLogs()
213     {
214         return getAllBuffer().substring(0);
215     }
216
217
218
219     /**
220      * Resets this task's logs as iff no event ever recorded.
221      **/
222     public void clearLogs()
223     {
224         resetBuffers();
225     }
226
227
228
229     /**
230      * Returns this task's high priority messages buffer. Never
231      * returns <i>null</i>.
232      * @see #setImportantFrom
233      **/
234     protected final StringBuffer JavaDoc getImportantBuffer()
235     {
236         return m_boobooBuffer;
237     }
238
239
240
241     /**
242      * Returns this task's all messages buffer. Never returns
243      * <i>null</i>.
244      **/
245     protected final StringBuffer JavaDoc getAllBuffer()
246     {
247         return m_allBuffer;
248     }
249
250
251
252     /**
253      * Clears contents of all of this task's capture buffer.
254      **/
255     protected final void resetBuffers()
256     {
257         getAllBuffer().delete(0,getAllBuffer().length());
258         getImportantBuffer().delete(0,getImportantBuffer().length());
259     }
260
261
262
263     /**
264      * Starts capturing logged messages to this task's buffers.
265      **/
266     protected void performNestedTasks()
267     {
268         Project P = getProject();
269         try {
270             verify_(!m_isInstalled,"perform- not installed");
271             verify_(!P.getBuildListeners().contains(getBuildListener()),"perform- not installed");
272             P.addBuildListener(getBuildListener());
273             m_isInstalled = true;
274             CapturedLogs.installRecorder(this,m_errHandler);
275             performTheTasksList();
276         } finally {
277             if (m_isInstalled) {
278                 m_isInstalled = false;
279                 P.removeBuildListener(getBuildListener());
280                 CapturedLogs.unwindRecorder(m_errHandler);
281             }
282             resetBuffers();
283         }
284     }
285
286
287
288     /**
289      * Returns the Ant BuildListener implementation for this task.
290      **/
291     protected final BuildListener getBuildListener()
292     {
293         return m_buildListener;
294     }
295
296
297
298     private volatile boolean m_isInstalled;
299     private NoiseLevel m_importantThreshold;//NB:determined live
300 private boolean m_splitMsgs;//NB:nope
301 private boolean m_addMsgSource;//NB:nope
302 private final Recorder m_buildListener = new Recorder();
303     private final StringBuffer JavaDoc m_allBuffer = new StringBuffer JavaDoc(320);
304     private final StringBuffer JavaDoc m_boobooBuffer = new StringBuffer JavaDoc(150);
305     private final ProblemHandler m_errHandler= new ProblemHandler() {
306             public void problem(Object JavaDoc nugget, int nl) {
307                 CaptureLogsTask.this.log(String.valueOf(nugget),nl);
308             }
309         };
310
311
312     /**
313      * Helper that captures all logged messages to enclosing
314      * CaptureLogTask's buffers.
315      * @since JWare/AntX 0.2
316      * @author ssmc, &copy;2002-2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
317      * @version 0.5
318      **/
319     private class Recorder extends BuildListenerSkeleton {
320         /**
321          * Captures logged information to enclosing task's buffers. Implementation
322          * Note: We depend on (current) fact that more important noise level indices
323          * are lower that less important ones. If this ever changes we must update
324          * this code (ssmc).
325          **/
326         public void messageLogged(BuildEvent e) {
327             String JavaDoc msg = e.getMessage();
328             if (willIncludeSource()) {
329                 msg = LocalTk.purtyEventMsg(e);
330             }
331             addMsg(getAllBuffer(),msg);
332             if (NoiseLevel.isAsBadAs(e.getPriority(),getImportantThreshold())) {
333                 addMsg(getImportantBuffer(),msg);
334             }
335         }
336         /** Ensures messages written with trailing newline if needed. **/
337         private void addMsg(StringBuffer JavaDoc sb, String JavaDoc msg)
338         {
339             sb.append(msg);
340             if (willSplitEntries()) {
341                 sb.append(Strings.NL);
342             }
343         }
344     }
345 }
346
347 /* end-of-CaptureLogsTask.java */
348
Popular Tags