[guide] <issue>

The <issue> task lets you broadcast generic checkpoints from within your Ant scripts that others can listen for and react to. While many of the SAM components already issue checkpoints as part of their implementations, the <issue> task lets you bring this simple hook mechanism to non-SAM elements like your own Ant macrodefs. The <issue> task also supplements the builtin Ant <import> functionality because it lets clients enhance your implementations from the inside, not just at the beginning or at the end like import target overloading does. For an <issue> to be of any value, you must install a <reactiondef> that matches its identifier on the target run harness; see the Examples section for how to do this.

The <issue> task differs from the <announce> task in that it is not tied explicitly to artifact generation; it just lets you notify any interested parties that you have reached a particular point in your processing. Also, <issue> differs from the standard AntX <checkpoint> task because you notify Ant-based listeners from it, not log system listeners like those based on Apache’s log4j.

Parameters

Nested Element: <property>^[0..*]

The <property> element defines a property to overlay when issuing the checkpoint. Any callback scripts will see the property as a readonly command property. Use the <property> element to passthru local context to any listeners.

Examples

1) The following snippet is part of an initialization target that issues several internal checkpoints to facilitate extension via SAM callbacks. If this target where defined as part of an imported project, the client build script could install callbacks that are automatically triggered whenever the init target was executed.

    [ Imported build file ]
    <project name="common"...>
        <target name="boot" unless="boot.disabled">
            <tstamp/>
            <issue checkpoint="boot"/>

            <property name="audience" value="dev"/>
            <property file="${audience}.properties"/>
            <issue checkpoint="boot-audience"/>
            …
            <property name="boot.disabled" value="yes"/>
        </target>
        …
    </project>

    [ Importing build file ]
    <project name="client"...>
        <import file="common.xml"/>

        <add-reactiondefs>
            <reactionfor checkpoint="boot-audience" call="target:init"/>
        </add-reactiondefs>

        <target name="init">
            …
        </target>
    </project>

2) The following snippet demonstrates how target-based reactions to issued checkpoints still function with the standard Ant import target overloading mechanisms. In the preceding example, the client’s init target is called after the boot target has determined the audience the project is being built for. If this client script is itself imported into another client scritp clientclient, and the init method overloaded by the new project; that target will be called when the checkpoint is issued. Note that the AntX flow-control <callinline> makes calling the original parent target of the same name trivial.

    [ Imported build file ]
    <project name="client"...>
        …[see preceding example]
    </project>

    [ Importing build file ]
    <project name="clientclient"...>
        <import file="client.xml"/>

        <target name="init">
            …[my pre-init enhancements]
            <callinline super="client"/>
            …[my post-init enhancements]
        </target>
    </project>

3) The following snippet demonstrates how issue can be used to implement general application-specific callbacks. Instead of using the generic checkpoint scheme, this script defines its own trackernote: scheme with messages broadcast to any listeners on the Trackers run harness. In our snippet, the purgeissue macro will be called whenever a Jira or Bugzilla issue is processed through ARMs like mkjiramark.

    [ Imported build file ]
    <project name="common"...>
        <macrodef name="mkjiramark">
           <attribute name="issueno"/>
           …
           <sequential>
              …
              <issue trackernote="jira" on="Trackers">
                 <property name="trackerid" value="@{issueno}"/>
              </issue>
              …
           </sequential>
    </macrodef>

    [ Importing build file ]
    <project name="client"...>
        <import file="common.xml"/>

        <managesams action="install-runharness">
           <harness name="Trackers"/>
        </managesams>

        <add-reactiondefs>
            <reactionfor trackernotelike="jira|bugzilla" call="macro:purgeissue"/>
        </add-reactiondefs>

        <macrodef name="purgeissue" uri="jware.sams.reaction">
            <attribute name="trackerid"/>
            <sequential>
               <quietdelete file="${pending.dir}/@{trackerid}.xml"/>
               <assign reference="issues.count" op="++"/>
            </sequential>
        </macrodef>
    </project>

Related Topics

• The IssueCheckpointTask Java class implements <issue>.
• The <announce> task lets you announce mini-artifacts or other useful byproducts explicitly.