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  ;
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  [] 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  [] 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  [] 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  [] 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   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  [] 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  [] 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags