AntSession


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  import java.net.URL  ;
24  import org.apache.tools.ant.module.run.LoggerTrampoline;
25  import org.openide.windows.OutputListener;
26  
27  /**
28   * Represents one Ant build session, possibly consisting of multiple targets,
29   * subprojects, and so on.
30   * A session may be shared by several {@link AntLogger}s.
31   * @author Jesse Glick
32   * @since org.apache.tools.ant.module/3 3.12
33   */
34  public final class AntSession {
35  
36      static {
37          LoggerTrampoline.ANT_SESSION_CREATOR = new LoggerTrampoline.Creator() {
38              public AntSession makeAntSession(LoggerTrampoline.AntSessionImpl impl) {
39                  return new AntSession(impl);
40              }
41              public AntEvent makeAntEvent(LoggerTrampoline.AntEventImpl impl) {
42                  throw new AssertionError  ();
43              }
44              public TaskStructure makeTaskStructure(LoggerTrampoline.TaskStructureImpl impl) {
45                  throw new AssertionError  ();
46              }
47          };
48      }
49      
50      private final LoggerTrampoline.AntSessionImpl impl;
51      private AntSession(LoggerTrampoline.AntSessionImpl impl) {
52          this.impl = impl;
53      }
54      
55      /**
56       * Get the Ant script originally invoked.
57       * Note that due to subproject support some events may come from other scripts.
58       * @return the Ant script which was run to start with
59       */
60      public File   getOriginatingScript() {
61          return impl.getOriginatingScript();
62      }
63      
64      /**
65       * Get the Ant targets originally run.
66       * @return a list of one or more targets (but may be empty during {@link AntLogger#buildInitializationFailed})
67       */
68      public String  [] getOriginatingTargets() {
69          return impl.getOriginatingTargets();
70      }
71      
72      /**
73       * Get optional data stored by the logger in this session.
74       * @param logger the logger which wishes to retrieve data
75       * @return any optional data, or null initially
76       */
77      public Object   getCustomData(AntLogger logger) {
78          return impl.getCustomData(logger);
79      }
80      
81      /**
82       * Store custom data associated with this session.
83       * May be used by the logger to keep some information that will persist
84       * for the lifetime of the session.
85       * @param logger the logger which wishes to store data
86       * @param data some custom data to retain
87       */
88      public void putCustomData(AntLogger logger, Object   data) {
89          impl.putCustomData(logger, data);
90      }
91      
92      /**
93       * Print a line of text to the Ant output.
94       * @param message a message to print (newline will be appended automatically)
95       * @param err true to send to the error stream, false for regular output
96       * @param listener an output listener suitable for hyperlinks, or null for a plain print
97       * @see #createStandardHyperlink
98       */
99      public void println(String   message, boolean err, OutputListener listener) {
100         impl.println(message, err, listener);
101     }
102     
103     /**
104      * Deliver a message logged event to all matching loggers.
105      * <p>
106      * Loggers will receive {@link AntLogger#messageLogged} with an event
107      * similar to the original event except for the message and log level;
108      * also the exception will always be null and the event will initially
109      * be unconsumed.
110      * </p>
111      * <p>
112      * This call blocks until all loggers have processed the nested event.
113      * Note that this logger may also receive the event so it must be reentrant.
114      * </p>
115      * <p class="nonnormative">
116      * Loggers are discouraged from using this facility merely to create hyperlinks
117      * for which the target is known. Use {@link #println} instead. This method
118      * is primarily intended for use from the standard logger to deliver stack
119      * trace lines to other loggers which may be able to hyperlink them.
120      * </p>
121      * @param originalEvent the original event received by the calling logger
122      * @param message a message to log (see {@link AntEvent#getMessage})
123      * @param level the level to log it at (see {@link AntEvent#getLogLevel})
124      */
125     public void deliverMessageLogged(AntEvent originalEvent, String   message, int level) {
126         impl.deliverMessageLogged(originalEvent, message, level);
127     }
128     
129     /**
130      * Marks an exception as having been processed by a logger.
131      * <p>
132      * A single build-halting exception can traverse any number of Ant events
133      * as it progresses outwards, typically from the failing task to the failing
134      * target (possibly several times due to subprojects) and finally to the build failure.
135      * </p>
136      * <p class="nonnormative">
137      * Consuming the exception permits a logger to indicate to other loggers that it
138      * has already handled the problem in an appropriate manner. Since the standard
139      * logger may print an exception (possibly with stack trace) that is part of
140      * a {@link AntLogger#buildFinished} event, loggers which deal with the exception
141      * in some other way should consume it before returning from the callback.
142      * </p>
143      * @param t an exception to mark as consumed
144      * @throws IllegalStateException if it was already consumed
145      */
146     public void consumeException(Throwable   t) throws IllegalStateException   {
147         impl.consumeException(t);
148     }
149     
150     /**
151      * Tests whether a given exception has already been consumed by some logger.
152      * <p>
153      * Note that if an exception is consumed, any exception with that exception
154      * as its {@link Throwable#getCause} (possibly recursively) is also considered
155      * consumed. This is useful because Ant's <code>ProjectHelper.addLocationToBuildException</code>
156      * will annotate <code>BuildException</code>s with location information by constructing
157      * wrapper exceptions.
158      * </p>
159      * @param t an exception
160      * @return true if it (or a nested exception) has already been consumed by {@link #consumeException}
161      */
162     public boolean isExceptionConsumed(Throwable   t) {
163         return impl.isExceptionConsumed(t);
164     }
165 
166     /**
167      * Get the (user-requested) verbosity level for this session.
168      * Generally only messages logged at this or lesser level (higher priority) should be displayed.
169      * @return the verbosity, e.g. {@link AntEvent#LOG_INFO}
170      */
171     public int getVerbosity() {
172         return impl.getVerbosity();
173     }
174     
175     /**
176      * Get a display name used for the session as a whole.
177      * @return a user-presentable display name appropriate for session-scope messaging
178      */
179     public String   getDisplayName() {
180         return impl.getDisplayName();
181     }
182     
183     /**
184      * Convenience method to create a standard hyperlink implementation.
185      * The GUI of the hyperlink will be oriented toward error messages and
186      * may involve editor annotations.
187      * Line and column numbers start at 1.
188      * @param file a file to link to (may or may not exist, but hyperlink will not work if it does not)
189      * @param message a message to use e.g. for the status bar when clicking on the hyperlink,
190      *                or for annotation tool tips
191      * @param line1 the starting line number, or -1 if there is no associated line number
192      * @param column1 the starting column number, or -1 if there is no associated column number
193      *                (must be -1 if line1 is -1)
194      * @param line2 the ending line number, or -1 for a single-line link
195      *              (must be -1 if line1 is -1)
196      * @param column2 the ending column number, or -1 if not applicable
197      *                (must be -1 if either line2 or column1 is -1)
198      * @return a standard hyperlink suitable for {@link #println}
199      */
200     public OutputListener createStandardHyperlink(URL   file, String   message, int line1, int column1, int line2, int column2) {
201         return impl.createStandardHyperlink(file, message, line1, column1, line2, column2);
202     }
203     
204     @Override  
205     public String   toString() {
206         return impl.toString();
207     }
208     
209 }
210
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags