Java Tutorial Blog

Apache ANT Listeners and Loggers

//  by 

This article explains in brief about two features of ANT which are used to monitor the build process: Listeners and Loggers. In the previous articles on ANT we saw that ANT has logging feature(logging using external log4j). If the logger is not specified then ANT uses the DefaultLogger. Along with logger, Ant also has a log message handling category known as a listener. At a low level a logger is in fact a listener with a little difference.

  • Logger has the ability to write to log output device, such as a console or a file supplied by the “-logfile” command line argument.
  • Another difference is ANT build file can have multiple listeners but only one logger.
  • The logger is something which ANT connects to the System.out and System.err streams

The article briefly explains about loggers, listeners and built-in loggers/listeners.

Books:

Apache-Ant-Logo-java

Ant Listeners

A build life has events, which alerts the listener.These events are:

  • Build started
  • Build finished
  • Target started
  • Target finished
  • Task started
  • Task finished
  • Message logged

As these events trigger some action in listener, they are used for various recording and maintenance operation. New listeners may be registered on the command line through the -listener argument.

Ant Loggers

A logger is built on top of a listener, extends the capabilities of listeners and logs information about the build. You use a logger whenever you run ANT, whether or not you specify one. If a logger is not specified in ANT, then you are using the DefaultLogger. Loggers have following features:

  1. Loggers receive a handle to the standard output and error print streams and hence log information to the console or to a specified file(command for specifying file -logfile).
  2. Loggers are aware of logging level (-quiet, -verbose, -debug)
  3. Loggers are aware of Emacs-mode

Built-in Listeners/Loggers

In addition to the DefaultLogger, Ant comes with following standard loggers and listeners:

  • DefaultLogger
  • NoBannerLogger
  • MailLogger
  • AnsiColorLogger
  • XmlLogger
  • Log4jListener
  • TimestampedLogger
  • BigProjectLogger
  • ProfileLogger

Here’s a brief overview of what each one does:
(Note:The source file and build file used in all the examples below shown are from previous article(Tutorial of java programming with Apache Ant) )

DefaultLogger

DefaultLogger is used implicitly by ANT unless overridden to use some other logger.Though the logging is not so impressive, but it does its job well. Use the following command-line option to override this logger:
ant -logger org.apache.tools.ant.DefaultLogger

Output

C:\>ant -logger org.apache.tools.ant.DefaultLogger
Buildfile: build.xml
clean:
   [delete] Deleting directory C:\build
compile:
    [mkdir] Created dir: C:\build\classes
    [javac] Compiling 1 source file to C:\build\classes
jar:
    [mkdir] Created dir: C:\build\jar
      [jar] Building jar: C:\build\jar\WelcomeToJavaBeat.jar
run:
     [java] 0 [main] INFO net.javaBeat.WelcomeToJavaBeat  - Welcome To JavaBeat
main:
BUILD SUCCESSFUL

NoBannerLogger

The NoBannerLogger is very similar to the DefaultLogger, except it omits output from targets that don’t log anything. When you run Ant, the console is printed as follows:
Each target’s name prints at the left-most column, followed by a colon, and then the name of corresponding task is printed in brackets. This occurs even if there is no useful output from any of the tasks.Here at such scenarios NoBannerLogger can be used to suppress output of empty target output.

Use the following command-line switch to use NoBannerLogger:
ant -logger org.apache.tools.ant.NoBannerLogger

Output

C:\>ant -logger org.apache.tools.ant.NoBannerLogger
Buildfile: build.xml
clean:
   [delete] Deleting directory C:\build
compile:
    [mkdir] Created dir: C:\build\classes
    [javac] Compiling 1 source file to C:\build\classes
jar:
    [mkdir] Created dir: C:\build\jar
      [jar] Building jar: C:\build\jar\WelcomeToJavaBeat.jar
run:
     [java] 0 [main] INFO net.javaBeat.WelcomeToJavaBeat  - Welcome To JavaBeat
BUILD SUCCESSFUL

Here you see that the logger has omitted the main target.

MailLogger

This logger extends the DefaultLogger, such that it captures all the output logged through DefaultLogger,then send a success or failure messages to unique email lists. A group of properties must be set for MailLogger to do its job. These properties can be passed into Ant from the command line using the standard Java -D syntax or statements in your init target or,by specifying a properties file.
The properties are:

  • MailLogger.mailhost-Mail server to use.Defaults to “localhost”.
  • MailLogger.port -SMTP Port for the Mail server.Defaults to “25”.
  • MailLogger.user-user name for SMTP auth.This field is required, if SMTP auth is required on your SMTP server the email message will be then sent using Mime and requires JavaMail
  • MailLogger.password-password for SMTP auth.This field is required, if SMTP auth is required on your SMTP server the email message will be then sent using Mime and requires JavaMail.
  • MailLogger.ssl-on or true if ssl is needed.This feature requires JavaMail.
  • MailLogger.from-You have to set this to a good “from” address
  • MailLogger.replyto-You have to set this to a “replyto” address(es),comma-seperated.
  • MailLogger.failure.notify-Whether to send an e-mail on build failure; defaults to true
  • MailLogger.success.notify-Whether to send an e-mail on build success; defaults to true
  • MailLogger.failure.to-A comma-separated list of e-mail addresses to send to on build failure
  • MailLogger.success.to-A comma-separated list of e-mail addresses to send to on build success
  • MailLogger.failure.subject-The subject of the e-mail on build failure; defaults to “Build Failure”
  • MailLogger.success.subject-The subject of the e-mail on build success; defaults to “Build Success”
  • MailLogger.failure.body-The fixed body of the e-mail on build failure;default is to send full log output
  • MailLogger.success.body-The fixed body of the e-mail on build success;default is to send full log output
  • MailLogger.mimeType-MIME-type of the message being sent;defaults to text/plain
  • MailLogger.charset-character set of message being sent.
  • MailLogger.starttls.enable-on or true if STARTTLS should be supported (requires JavaMail);deafults to “false”
  • MailLogger.properties.file-The name of a properties file that contains properties for the logger and which overrides other values.

Use the following command-line option to use this logger:
ant -logger org.apache.tools.ant.listener.MailLogger

AnsiColorLogger

AnsiColorLogger can produce color output(standard ANT output) by prefixing and suffixing ANSI color code escape sequences to it.It extends the DefaultLogger features.You can specify certain ANSI color sequences for different types of messages based on severity. In other words, info messages are a different color than errors. There are lots of codes that you can use to specify which colors you want. Consult the Ant documentation for the full list.

AnsiColorLogger is designed to work on terminals that support ANSI color codes. It works on XTerm, ETerm, Win9x Console (with ANSI.SYS loaded.), etc.

NOTE: It doesn’t work on WinNT and successors, even when a COMMAND.COM console loaded with ANSI.SYS is used.
The recognized keys and their default values are shown below:

 AnsiColorLogger.ERROR_COLOR=2;31
 AnsiColorLogger.WARNING_COLOR=2;35
 AnsiColorLogger.INFO_COLOR=2;36
 AnsiColorLogger.VERBOSE_COLOR=2;32
 AnsiColorLogger.DEBUG_COLOR=2;34

Each key takes as value a color combination defined as Attribute;Foreground;Background.In the above example, background value has not been used.

Command line option to use this logger:
ant -logger org.apache.tools.ant.listener.AnsiColorLogger

Log4jListener

Log4jListener passes events to Log4j for highly customizable logging. Log4j JAR need to be installed and a ‘log4j.xml’ configuration file configured for this listener to work.Each build event is passed to Log4j, using the full classname of the generator of each build event as the Log4j category:

  • build started / build finished – org.apache.tools.ant.Project
  • target started / target finished – org.apache.tools.ant.Target
  • task started / task finished – the fully qualified classname of the task
  • message logged – the classname of one of the above, so if a task logs a message, its classname is the Log4j category used, and so on.

All the start events are logged as INFO-level messages; finish events are sent as INFO if they succeed, and ERROR otherwise. Message events are logged according to their Ant logging level, mapping directly to a corresponding Log4j level.

Example:
log4j.xml file:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
   <appender name="fileAppender" class="org.apache.log4j.FileAppender">
   	<param name="Threshold" value="INFO" />
          <param name="File" value="build.log" />
          <param name="Append" value="true" />
          <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%t %-5p %c{2} - %m%n"/>
          </layout>
     </appender>

  <root>
    <priority value ="debug" />
    <appender-ref ref="fileAppender" />
  </root>
</log4j:configuration>

Place Log4j JAR in your Ant classpath.Set the following attributes:
set ANT_OPTS=-Dlog4j.debug -Dlog4j.configuration=file:///c:/lib/log4j.xml
To use this listener, use the command:
ant -listener org.apache.tools.ant.listener.Log4jListener

Output in build.log file:

  INFO Project : Build started.
  INFO Target : Target "clean" started.
  INFO Delete : Deleting directory C:\build
  INFO Target : Target "clean" finished.
  INFO Target : Target "compile" started.
  INFO Mkdir : Created dir: C:\build\classes
  INFO Javac : C:\build.xml:21: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
  INFO Javac : Compiling 1 source file to C:\build\classes
  INFO Target : Target "compile" finished.
  INFO Target : Target "jar" started.
  INFO Mkdir : Created dir: C:\build\jar
  INFO Jar : Building jar: C:\build\jar\WelcomeToJavaBeat.jar
  INFO Target : Target "jar" finished.
  INFO Target : Target "run" started.
  INFO Java : 0 [main] INFO net.javaBeat.WelcomeToJavaBeat  - Welcome To JavaBeat
  INFO Target : Target "run" finished.
  INFO Target : Target "main" started.
  INFO Target : Target "main" finished.
  INFO Project : Build finished.

XmlLogger

XmlLogger logs all the build information to an XML file. This logger behaves differently depending on whether it is invoked as a listener or a logger.This logger writes to XML file named log.xml, or the value of the XmlLogger.file (set in your init target, at the command line with -D, or in a properties file) property if present, when used as a listener. In logger mode, all output goes to the console or to the file specified in -logfile of command-line option.
You can set a property called ant.XmlLogger.stylesheet to point to the XSLT stylesheet. If you don’t specify a style sheet, the XML file will point to one called log.xsl by default in the current directory(ANT_HOME/etc). If you don’t want stylesheet support built into your XML file, set this property to an empty string “”.
Whether XmlLogger is used as a listener or logger, the output is generated only on build completion, as it buffers the information in order to provide timing information for task, targets, and the project.

Command lines for starting Ant with the XmlLogger in both listener and logger modes are:
ant -listener org.apache.tools.ant.XmlLogger
The output is logged in log.xml

ant -logger org.apache.tools.ant.XmlLogger -logfile output.xml
The output is logged in output.xml

TimestampedLogger
TimestampedLogger includes the build completion time at the final success/failure.It extends the fetaures of DefaultLogger.

To use this listener, use the command:
ant -logger org.apache.tools.ant.listener.TimestampedLogger
Output:

C:\>ant -logger org.apache.tools.ant.listener.TimestampedLogger
Buildfile: C:\build.xml
clean:
    [delete] Deleting directory C:\build
compile:
     [mkdir] Created dir: C:\build\classes
     [javac] C:\build.xml:21: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
     [javac] Compiling 1 source file to C:\build\classes
 jar:
     [mkdir] Created dir: C:\build\jar
       [jar] Building jar: C:\build\jar\WelcomeToJavaBeat.jar
 run:
      [java] 0 [main] INFO net.javaBeat.WelcomeToJavaBeat  - Welcome To JavaBeat

 main:

BUILD SUCCESSFUL - at 1/30/13 12:53 PM

BigProjectLogger
BigProjectLogger is used in big projects which build complex systems,especialy those run with continuous integration tools and use subant.

  • When entering a child project, prints its name and directory
  • When exiting a child project, prints its name
  • Includes the name of the project when printing a target
  • Omits logging the names of all targets that have no direct task output
  • Includes the build finished timestamp of the TimeStamp logger

This is useful when using to build a large project from many smaller projects;the output shows which particular project is building.

To use this listener, use the command:
ant -logger org.apache.tools.ant.listener.BigProjectLogger
Output:

C:\>ant -logger org.apache.tools.ant.listener.BigProjectLogger
Buildfile: C:\build.xml

======================================================================
Entering project
In C:\
======================================================================

WelcomeToJavaBeat.clean:
   [delete] Deleting directory C:\build

WelcomeToJavaBeat.compile:
    [mkdir] Created dir: C:\build\classes
    [javac] C:\build.xml:21: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
    [javac] Compiling 1 source file to C:\build\classes

WelcomeToJavaBeat.jar:
    [mkdir] Created dir: C:\build\jar
      [jar] Building jar: C:\build\jar\WelcomeToJavaBeat.jar

WelcomeToJavaBeat.run:
     [java] 0 [main] INFO net.javaBeat.WelcomeToJavaBeat  - Welcome To JavaBeat

======================================================================
Exiting project "WelcomeToJavaBeat"
======================================================================

BUILD SUCCESSFUL - at 1/30/13 12:54 PM
Total time: 2 seconds

ProfileLogger
The ProfileLogger is a default logger which adds start time,end time and durations for each task and target.The output contains a timestamp when entering the build, target or task and a timestamp and the needed time when exiting.

To use this listener, use the command:
ant -logger org.apache.tools.ant.listener.ProfileLogger

Output

C:\>ant -logger org.apache.tools.ant.listener.ProfileLogger
Buildfile: C:\build.xml
property: started Wed Jan 30 12:55:11 IST 2013
property: finished Wed Jan 30 12:55:12 IST 2013 (360ms)
property: started Wed Jan 30 12:55:12 IST 2013
property: finished Wed Jan 30 12:55:12 IST 2013 (0ms)
property: started Wed Jan 30 12:55:12 IST 2013
property: finished Wed Jan 30 12:55:12 IST 2013 (0ms)
property: started Wed Jan 30 12:55:12 IST 2013
property: finished Wed Jan 30 12:55:12 IST 2013 (0ms)
property: started Wed Jan 30 12:55:12 IST 2013
property: finished Wed Jan 30 12:55:12 IST 2013 (0ms)
property: started Wed Jan 30 12:55:12 IST 2013
property: finished Wed Jan 30 12:55:12 IST 2013 (0ms)
path: started Wed Jan 30 12:55:12 IST 2013
path: finished Wed Jan 30 12:55:12 IST 2013 (62ms)
Target clean: started Wed Jan 30 12:55:12 IST 2013
delete: started Wed Jan 30 12:55:12 IST 2013
  [delete] Deleting directory C:\build
delete: finished Wed Jan 30 12:55:12 IST 2013 (31ms)
Target clean: finished Wed Jan 30 12:55:12 IST 2013 (31ms)
Target compile: started Wed Jan 30 12:55:12 IST 2013
mkdir: started Wed Jan 30 12:55:12 IST 2013
    [mkdir] Created dir: C:\build\classes
mkdir: finished Wed Jan 30 12:55:12 IST 2013 (47ms)
javac: started Wed Jan 30 12:55:12 IST 2013
    [javac] C:\build.xml:21: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
    [javac] Compiling 1 source file to C:\build\classes
javac: finished Wed Jan 30 12:55:13 IST 2013 (782ms)
Target compile: finished Wed Jan 30 12:55:13 IST 2013 (829ms)
Target jar: started Wed Jan 30 12:55:13 IST 2013
mkdir: started Wed Jan 30 12:55:13 IST 2013
    [mkdir] Created dir: C:\build\jar
mkdir: finished Wed Jan 30 12:55:13 IST 2013 (0ms)
jar: started Wed Jan 30 12:55:13 IST 2013
      [jar] Building jar: C:\build\jar\WelcomeToJavaBeat.jar
jar: finished Wed Jan 30 12:55:13 IST 2013 (78ms)
Target jar: finished Wed Jan 30 12:55:13 IST 2013 (93ms)
Target run: started Wed Jan 30 12:55:13 IST 2013
java: started Wed Jan 30 12:55:13 IST 2013
     [java] 0 [main] INFO net.javaBeat.WelcomeToJavaBeat  - Welcome To JavaBeat
java: finished Wed Jan 30 12:55:14 IST 2013 (844ms)
Target run: finished Wed Jan 30 12:55:14 IST 2013 (859ms)
Target main: started Wed Jan 30 12:55:14 IST 2013
Target main: finished Wed Jan 30 12:55:14 IST 2013 (0ms)
BUILD SUCCESSFUL

Summary

Books:

To summarize,we saw the difference between loggers and listerners.Each built-in logger and listerner is expalined in brief with a simple example.For any further queries please leave your comments.

About Manisha Patil

Manisha S Patil, currently residing at Pune India. She is currently working as freelance writer for websites. She had earlier worked at Caritor Bangalore, TCS Bangalore and Sungard Pune. She has 5 years of experience in Java/J2EE technologies.