[guide] <announce>

The <announce> task lets you issue artifact location announcements for useful build by-products generated as part of your build or test iteration but not declared through a formal SAM artifact definition. Other SAM listener components like reactions can use these manual announcements to trigger more processing or to feed build status logs. From a listener’s perspective, a manual announcement is no different from an artifactdef generated announcement which means the same constraints apply to macrodef-based reactions with regards to its namespace (jware.sams.reaction) and its attribute list (an artifactlocation attribute is required).

Parameters

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

The <property> element lets you associate a custom property with the announced artifact’s context. A listener can use context properties in its processing and cached announcements include these properties as part of the definition.

Examples

1) The following snippet shows a macrodef prepare-javasources that creates a local merged directory of java source files. When the merge operation is complete, it announces the availability of the source tree (identified as javasources#workspace) to any listeners (like those installed by “init-listeners”). Note that the client script’s reaction macrodef is linked to the required jware.sams.reaction namespace. SAMS expects all of its reaction methods that rely on macrodefs to be in this namespace. Also, the announcement automatically creates an artifactlocation parameter that is passed to the macrodef and an artifact.cacheflag property that is overlaid in the project space. The artifactlocation attribute contains the value of the artifact’s location— this is different from the artifactlocation passed to an ARM (which contains the name of the variable to update with the location value).

    [ Imported build file ]
    <macrodef name="prepare-javasources">
       <attribute name="packages">
       <attribute name="in" default="${workspace.dir}"/>
       <sequential>
          <assert isnotwhitespace="@{packages}" malformed="reject"
                  msg="CVS package list is not empty"/>
          <mkdir dir="@{in}/sources/java"/>
          <foreach i="package" list="@{packages}" mode="local">
             <cvs package="${package}" dest="${pristine.dir}" failonerror="yes"/>
             <echo message="${ITID_STAMP}" file="${pristine.dir}/${package}/.codate"/>
             <copy todir="${workspace.dir}/sources/java">
                <fileset dir="${pristine.dir}/${package}/sources/java">
                   <exclude name="**/.*/"/>
                </fileset>
                <filterset refid="javasources.copyfilters"/>
             </copy>
          </foreach>
          <announce cache="yes" artifact="javasources#workspace"
                    location="${$ospath:@(workspace.dir)/sources/java/}">
             <property name="components" value="@{packages}"/>
          </announce>
       </sequential>
    </macrodef>

    [ Importing build file ]
    <target name="init-listeners">
       <add-reactiondefs>
          <reactionfor artifact="javasources#workspace">
             <method use="macro:zip-javasources"/>
          </reactionfor>
          …
       </add-reactiondefs>
    </target>

    <macrodef name="zip-javasources" uri="jware.sams.reaction">
       <attribute name="artifactlocation"/>
       <sequential>
           <assign var="zip-javasources.comment"
               value="Java Sources: ${BASE_STAMP}; Components: ${components}"/>
           <zip destfile="${outputs.dir}/java-sources.zip" whenempty="fail"
                comment="${$var:zip-javasources.comment}">
              <zipfileset dir="@{artifactlocation}" prefix="java" casesensitive="no">
                <exclude name="**/devnote*"/>
              </zipfileset>
           </zip>
           <announce cache="${artifact.cacheflag}"
                     artifact="javasources#archive"
                     location="${$ospath:@(outputs.dir)/java-sources.zip}">
              <property name="comment" value"${$var:zip-javasources.comment}"/>
           </announce>
           <unassign var="zip-javasources.comment"/>
      </sequential>
    </macrodef>

Related Topics

• The AnnounceArtifactTask Java class implements <announce>.
• The <issue> task lets you broadcast generic checkpoints from within your Ant scripts.