The JWare/AntX build-feedback package that contains several tasks for using the Apache Jakarta Log4J logging system from within Ant. The primary classes are EmitTask (defined as <emit>), EmitConfigureTask (defined as <emitconfigure>), and EmitConfigurationType (defined as <emitconfiguration>).

In its simpliest form the EmitTask can be considered a custom <echo> replacement. EmitTask allows an executing build to send scoped, complex messages to an external logging system without having to create a custom build listener. A build manager can use any Log4J viewing system to track a build's progress (there are a few free Log4j viewing systems). And because it it based on the MsgTask, EmitTask includes all the message customization features of that task as well.

On its own the EmitTask is pretty handy. However, the EmitConfigureTask adds a level of build-process support to remove some of the administration and maintenance issues associated with specifying lots of options with every <emit> call. The <emitconfigure> task lets you setup defaults for any enclosed emit tasks (including those triggered from antcall's to other targets and/or those triggered from ant calls to sub-builds). The only runtime requirement is that the affected tasks remain within the same Java Virtual Machine and thread-of-execution as the <emitconfigure> task. Here is an example:

    <emitconfigure defaultNoiseLevel="${build.noiselevel}" defaultFrom="builds.nightly.AntX">
       <antcall target="checkout-tag-sources"/>
       <antcall target="compile"/>
       <antcall target="compile-optional-bits"/>
       <antcall target="acceptance-tests"/>
       <antcall target="docs"/>
       <antcall target="build-distrib"/>
       <antcall target="broadcast-distrib-ready"/>
    </emitconfigure>
The EmitConfigurationType completes the trio. The <emitconfiguration> type allows you to specify a set of default configuration information that an embedded <emitconfigure> can reference; for example:
    <emitconfiguration id="build.logging.defaults">
        <from="build.nightly.AntX"/>
        <noiselevel="verbose"/>
        <emitterFactory="mycompany.builds.AntLogEmitter"/>
    </emitconfiguration>
    ...
    <emitconfigure defaultsRefid="build.logging.defaults"...>
        ...

Emitting ErrorSnapshots

Depending on the options given to an <emit> task, the feedback system will generate either a simple string message or a custom object called an ErrorSnapshot. JWare/AntX has provided a custom Log4J ObjectRenderer to ensure these snapshot objects are translated properly for any Log4J Appender (basis of any Log4J viewing system). Note this custom renderer isn't absolutely necessary, the ErrorSnapshot instances will produce a useable string on their own as expected by the default object renderer. However custom information like captured properties and task or target information will not be included. Below are some configuration lines to include in two log4j configuration file-types to map ErrorSnapshots to the custom object renderer:
  For a 'log4j.properties' file:
    log4j.renderer.com.idaremedia.antx.ErrorSnapshot=\
             com.idaremedia.antx.feedback.ErrorSnapshotRenderer

  For a 'log4j.xml' file:
    <renderer renderedClass="com.idaremedia.antx.ErrorSnapshot"
             renderingClass="com.idaremedia.antx.feedback.ErrorSnapshotRenderer">

The error-snapshot support of the <emit> task is often used in conjunction with a protected series of tasks (see JWare/AntX's build-flowcontrol package). If/when a build failure occurs, the emit task ensures that context information and specific fault information is passed on to the diagnostics system. The <protect>/<iferror> tasks provide a mechanism for creating error snapshots; the feedback system provides a mechanism for reporting them. Below is a example demonstrating how these tasks work together:

    <protect haltiferror="false">
        <iferror capturesnapshot="javadoc.err">
            <emit level="error" msgid="msg.javadoc.problem" 
                  thrown="javadoc.err" properties="all"/>
        </iferror>
        ...
        <javadoc ... />
    </protect>

Using Other Logging Systems

By default the feedback package classes work with the Log4J logging system, but it takes just three steps to customize the feedback tasks to use other logging systems like the J2SE 1.4's logging system or IBM's LogKit. First, a custom implementation of DiagnosticsEmitter and DiagnosticsEmitterFactory interfaces must be created for the new logging system. Next, these new classes must be placed in Ant's classpath before the <emitconfigure> task is used. (See the Ant documentation on how to include optional task jars in its runtime.) Finally, the emitterfactory option of the <emitconfigure> task is used to direct the task to use the new custom factory. Any <emit> tasks enclosed within a so-configured <emitconfigure> block will broadcast to the new logging system.

Examples

Some examples of feedback tasks are shown below. Assume that EmitTask is defined by either the <emit> or the <checkpoint> task declarations.
  Using EmitTask:
    <emit msgid="precompile-checks-done" echo="yes"/>
    <emit level="debug" properties="all" message="Hi" echo="no"/>
    <emit from="${feedback.compile}" message="Past precompile checks" echo="yes"/>
    <emit level="fatal" thrown="${err.last}" msgid="build.failed" properties="all"/>
    <emit message="javac.options" properties="javac.debug,javac.depend" level="verbose"/>
    <emit timestamp="on" echo="off" properties="none"/>
    <emit from="${feedback.distrib}.web" msgid="checkpoint.upload.finished"/>
    <emit from="${grp.compiling}.apis" task="javac[templates]" msgid="banner.compiling"/>
    <emit snapshot="build.error" level="fatal"/>

  Using EmitConfigureTask:
    <emitconfigure defaultNoiseLevel="info" emitterfactory="my.logging.EmitterFactory">
       <emit msgid="msg.compile.start"/>
       ...
    </emitconfigure>

    <emitconfigure />

The JWare/AntX feedback package has been verified against Log4J versions 1.2.6. Several GUI-based appenders (LogFactor5 and ChainSaw) have been tested and work fine. Please report any incompatibilities with standard Log4J distributions to the JWare/AntX developers.

[More Learning Materials]   [Documentation Problems]
( Updated: Dec 14 2003, 07:06 PM, -0500 )