Section 12.3. Creating Custom Listeners

12.3. Creating Custom Listeners

Ant tracks build events, such as when tasks start and finish, and you can catch those events with a listener. Listeners implement the org.apache.tools.antBuildListener interface and will receive BuildEvents for these events:

• Build started

• Build finished

• Target started

• Target finished

• Task started

• Task finished

• Message logged

To add a listener in code, you can create an ant Project object and then call its addBuildListener( ) method to add a listener to the project. You can attach a listener to a build from the command line as in this example:

ant -listener org.apache.tools.ant.XmlLogger

which runs Ant with a listener that generates an XML version of the build progress.

Listeners and loggers must not access System.out and System.err because output on these streams is redirected by Ant's core to the build event system. In other words, accessing these streams may cause an infinite loop.

To implement the listener interface, you implement methods such as buildStarted( ), buildFinished( ), targetStarted( ), and so on. In SoundListener.java, shown in Example 12-16, the listener code uses the org.apache.tools.ant.taskdefs.optional.sound.AntSoundPlayer class to play a sound when the build is finished. The addBuildSuccessfulSound(java.io.File file, int loops, java.lang.Long duration) method is used to add a sound to play for build success, and addBuildFailed-Sound(java.io.File fileFail, int loopsFail, java.lang.Long duration) to add a sound indicating build failure. In the listener's buildFinished( ) method, the sound player's buildFinished( ) method is called to play the sound.

If you run this example, substitute your own local filenames for file1.wav and file2.wav in SoundListener.java. The AntSoundPlayer can play sound files in .wav and .aiff format.

Example 12-16. A new listener (ch12/listener/SoundListener.java)

import java.io.File; import org.apache.tools.ant.BuildEvent; import org.apache.tools.ant.BuildListener; import org.apache.tools.ant.taskdefs.optional.sound.AntSoundPlayer; public class SoundListener implements BuildListener {     AntSoundPlayer soundplayer = new AntSoundPlayer( );     public SoundListener( )     {         soundplayer.addBuildSuccessfulSound(new File("file1.wav"), 1,              new Long(500));         soundplayer.addBuildFailedSound(new File("file2.wav"), 1, new Long(500));     }     public void buildStarted(BuildEvent event) {}     public void buildFinished(BuildEvent event)      {         soundplayer.buildFinished(event);     }     public void targetStarted(BuildEvent event) {}     public void targetFinished(BuildEvent event) {}     public void taskStarted(BuildEvent event) {}     public void taskFinished(BuildEvent event) {}          public void messageLogged(BuildEvent event) {} }

To build this listener, include ant-jmf.jar in the classpath to pick up AntSoundPlayer. Here's the file this example builds, Project.java:

public class Project  {     public void execute( )      {         System.out.println("No worries.");     } }

Here's the build file. Nothing special.

<?xml version="1.0"?> <project basedir="." default="main">     <property name="src" value="src"/>     <property name="output" value="output"/>     <target name="main" depends="jar">         <taskdef name="project" classname="Project" classpath="Project.jar"/>         <project/>     </target>     <target name="compile">         <mkdir dir="${output}"/>         <javac srcdir="${src}" destdir="${output}"/>     </target>     <target name="jar" depends="compile">         <jar destfile="Project.jar" basedir="${output}"/>     </target> </project>

To attach the listener to the build, run Ant this way:

%ant -listener SoundListener

If the build finishes successfully, you'll hear the sound you've added for a build; otherwise, you'll hear the sound you've set for failure.

Want to know what task or target fired a build event? Use the BuildEvent object's getTask( ) or getTarget( ) methods, in which a BuildEvent object is passed to each listener method.