KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > tools > ant > module > spi > AntLogger


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */

19
20 package org.apache.tools.ant.module.spi;
21
22 import java.io.File JavaDoc;
23
24 /**
25  * A pluggable logger that can listen to {@link AntEvent}s during
26  * one or more {@link AntSession}s.
27  * <p>
28  * There can be several loggers active on a given session,
29  * so {@link AntEvent#consume} may be used to cooperate.
30  * Implementations may be registered to default {@link org.openide.util.Lookup}.
31  * Loggers are notified of events in the order of their registration in lookup.
32  * </p>
33  * <p>
34  * A logger will always first be asked if it is interested in a given session;
35  * if it declines, it will receive no further events for that session.
36  * Otherwise it will normally receive {@link #buildStarted}; then some combination of
37  * target, task, and message logged events; then {@link #buildFinished}.
38  * (Or it may receive just {@link #buildInitializationFailed}.)
39  * A logger may <em>not</em> assume that target and task events are properly
40  * nested in any way, due to Ant's <code>&lt;parallel&gt;</code> task and
41  * other complexities such as <code>&lt;import&gt;</code> handling. Events may
42  * also be delivered from the originating script or any subscripts, again with
43  * no guaranteed nesting behavior. A logger may not assume that it will not
44  * receive any events after {@link #buildFinished}.
45  * </p>
46  * <p>
47  * Various mask methods permit loggers to declare themselves uninterested in
48  * some kinds of events. Such events will not be delivered to them. Loggers should
49  * declare themselves interested only in events they will actually use in some way,
50  * to permit the Ant engine to minimize the number of events delivered. Note that
51  * loggers which do not declare themselves interested in the given session will
52  * not receive {@link #buildStarted}, {@link #buildFinished}, or
53  * {@link #buildInitializationFailed} at all, and loggers not additionally interested
54  * in all scripts will not receive {@link #buildInitializationFailed}.
55  * </p>
56  * <p>
57  * A logger should not keep any state as a rule; this would be a memory leak, and
58  * also a logger may be called from multiple threads with different sessions.
59  * Use {@link AntSession#getCustomData} and {@link AntSession#putCustomData} instead.
60  * Loggers may not make calls to the session, event, or task structure objects outside
61  * the dynamic scope of an event callback.
62  * </p>
63  * <p>
64  * This is an abstract class so that new event types or masks may be added in the future.
65  * To prevent possible conflicts, implementors are forbidden to define other methods
66  * which take a single parameter of type {@link AntEvent} or which have a name beginning
67  * with the string <code>interested</code>.
68  * </p>
69  * <div class="nonnormative">
70  * <p>
71  * The Ant module registers one logger at position 100 in META-INF/services lookup
72  * which may or may not handle any events which have not already been consumed
73  * (marking them consumed itself) and will typically process message logged events
74  * by printing them to the output somehow, using hyperlinks for common file error
75  * patterns such as <samp>/path/to/File.java:34: some message</samp>. It may also
76  * handle sequences of messages logged within a task in the format
77  * </p>
78  * <pre>&nbsp;/path/to/File.java:34: you cannot throw a bogus exception here
79  * &nbsp; throw new Exception("bogus!");
80  * &nbsp; ^</pre>
81  * <p>
82  * by linking to the column number indicated by the caret (<samp>^</samp>).
83  * </p>
84  * </div>
85  * @author Jesse Glick
86  * @see <a HREF="http://www.netbeans.org/issues/show_bug.cgi?id=42525">Issue #42525</a>
87  * @since org.apache.tools.ant.module/3 3.12
88  */

89 public abstract class AntLogger {
90     
91     /** No-op constructor for implementors. */
92     protected AntLogger() {}
93     
94     /**
95      * Special constant indicating the logger is not interested in receiving
96      * any target events.
97      * @see #interestedInTargets
98      */

99     public static final String JavaDoc[] NO_TARGETS = {};
100     
101     /**
102      * Special constant indicating the logger is interested in receiving
103      * all target events.
104      * @see #interestedInTargets
105      */

106     public static final String JavaDoc[] ALL_TARGETS = {};
107     
108     /**
109      * Special constant indicating the logger is not interested in receiving
110      * any task events.
111      * @see #interestedInTasks
112      */

113     public static final String JavaDoc[] NO_TASKS = {};
114     
115     /**
116      * Special constant indicating the logger is interested in receiving
117      * all task events.
118      * @see #interestedInTasks
119      */

120     public static final String JavaDoc[] ALL_TASKS = {};
121     
122     /**
123      * Fired only if the build could not even be started.
124      * {@link AntEvent#getException} will be non-null.
125      * The default implementation does nothing.
126      * @param event the associated event object
127      */

128     public void buildInitializationFailed(AntEvent event) {}
129     
130     /**
131      * Fired once when a build is started.
132      * The default implementation does nothing.
133      * @param event the associated event object
134      */

135     public void buildStarted(AntEvent event) {}
136     
137     /**
138      * Fired once when a build is finished.
139      * The default implementation does nothing.
140      * @param event the associated event object
141      * @see AntEvent#getException
142      */

143     public void buildFinished(AntEvent event) {}
144     
145     /**
146      * Fired when a target is started.
147      * It is <em>not</em> guaranteed that {@link AntEvent#getTargetName}
148      * will be non-null (as can happen in some circumstances with
149      * <code>&lt;import&gt;</code>, for example).
150      * The default implementation does nothing.
151      * @param event the associated event object
152      */

153     public void targetStarted(AntEvent event) {}
154     
155     /**
156      * Fired when a target is finished.
157      * It is <em>not</em> guaranteed that {@link AntEvent#getTargetName}
158      * will be non-null.
159      * The default implementation does nothing.
160      * @param event the associated event object
161      */

162     public void targetFinished(AntEvent event) {}
163     
164     /**
165      * Fired when a task is started.
166      * It is <em>not</em> guaranteed that {@link AntEvent#getTaskName} or
167      * {@link AntEvent#getTaskStructure} will be non-null, though they will
168      * usually be defined.
169      * {@link AntEvent#getTargetName} might also be null.
170      * The default implementation does nothing.
171      * @param event the associated event object
172      */

173     public void taskStarted(AntEvent event) {}
174     
175     /**
176      * Fired when a task is finished.
177      * It is <em>not</em> guaranteed that {@link AntEvent#getTaskName} or
178      * {@link AntEvent#getTaskStructure} will be non-null.
179      * {@link AntEvent#getTargetName} might also be null.
180      * The default implementation does nothing.
181      * @param event the associated event object
182      */

183     public void taskFinished(AntEvent event) {}
184
185     /**
186      * Fired when a message is logged.
187      * The task and target fields may or may not be defined.
188      * The default implementation does nothing.
189      * @param event the associated event object
190      */

191     public void messageLogged(AntEvent event) {}
192
193     /**
194      * Mark whether this logger is interested in a given Ant session.
195      * @param session a session which is about to be start
196      * @return true to receive events about it; by default, false
197      */

198     public boolean interestedInSession(AntSession session) {
199         return false;
200     }
201     
202     /**
203      * Mark whether this logger is interested in any Ant script.
204      * If true, no events will be masked due to the script location.
205      * Note that a few events have no defined script and so will only
206      * be delivered to loggers interested in all scripts; typically this
207      * applies to debugging messages when a project is just being configured.
208      * @param session the relevant session
209      * @return true to receive events for all scripts; by default, false
210      */

211     public boolean interestedInAllScripts(AntSession session) {
212         return false;
213     }
214     
215     /**
216      * Mark whether this logger is interested in a given Ant script.
217      * Called only if {@link #interestedInAllScripts} is false.
218      * Only events with a defined script according to {@link AntEvent#getScriptLocation}
219      * which this logger is interested in will be delivered.
220      * Note that a few events have no defined script and so will only
221      * be delivered to loggers interested in all scripts; typically this
222      * applies to debugging messages when a project is just being configured.
223      * Note also that a single session can involve many different scripts.
224      * @param script a particular build script
225      * @param session the relevant session
226      * @return true to receive events sent from this script; by default, false
227      */

228     public boolean interestedInScript(File JavaDoc script, AntSession session) {
229         return false;
230     }
231
232     /**
233      * Mark which kinds of targets this logger is interested in.
234      * This applies to both target start and finish events, as well as any other
235      * events for which {@link AntEvent#getTargetName} is not null, such as task
236      * start and finish events, and message log events.
237      * If {@link #NO_TARGETS}, no events with specific targets will be sent to it.
238      * If a specific list, only events with defined target names included in the list
239      * will be sent to it.
240      * If {@link #ALL_TARGETS}, all events not otherwise excluded will be sent to it.
241      * @param session the relevant session
242      * @return a nonempty (and non-null) list of target names; by default, {@link #NO_TARGETS}
243      */

244     public String JavaDoc[] interestedInTargets(AntSession session) {
245         return NO_TARGETS;
246     }
247     
248     /**
249      * Mark which kinds of tasks this logger is interested in.
250      * This applies to both task start and finish events, as well as any other
251      * events for which {@link AntEvent#getTaskName} is not null, such as
252      * message log events.
253      * If {@link #NO_TASKS}, no events with specific tasks will be sent to it.
254      * If a specific list, only events with defined task names included in the list
255      * will be sent to it.
256      * If {@link #ALL_TASKS}, all events not otherwise excluded will be sent to it.
257      * @param session the relevant session
258      * @return a nonempty (and non-null) list of task names; by default, {@link #NO_TASKS}
259      */

260     public String JavaDoc[] interestedInTasks(AntSession session) {
261         return NO_TASKS;
262     }
263     
264     /**
265      * Mark which kinds of message log events this logger is interested in.
266      * This applies only to message log events and no others.
267      * Only events with log levels included in the returned list will be delivered.
268      * @param session the relevant session
269      * @return a list of levels such as {@link AntEvent#LOG_INFO}; by default, an empty list
270      * @see AntSession#getVerbosity
271      */

272     public int[] interestedInLogLevels(AntSession session) {
273         return new int[0];
274     }
275     
276 }
277
Popular Tags