triggers

Tag: triggers
since 1.4 Defines a list of triggers to activate on some Ivy events. A trigger is an action which is performed whenever a particular event occurs.
Ivy supports 3 type of triggers out of the box:

ant-call
ant-build
log

If you want to use a different trigger, you can implement your own.

The following events are available in Ivy:

Name	Attributes	Description
pre-resolve	organisation the organisation of the module for which the dependencies will be resolved module the name of the module for which the dependencies will be resolved revision the revision of the module for which the dependencies will be resolved conf comma separated list of configurations which will be resolved	Fired at the beginning of the resolve process, before module dependencies and transitive dependencies are resolved.
pre-resolve-dependency	organisation the organisation of the dependency resolved module the name of the dependency resolved req-revision the requested revision for the dependency since 2.0 (provided for consistency with post-resolve-dependency) req-revision-default the default requested revision constraint for the dependency since 2.0 req-revision-dynamic the requested revision dynamic constraint for the dependency since 2.0 revision the requested revision for the dependency resolver the name of the resolver used to resolve the dependency	Fired before each dependency is resolved. In this case resolved means resolving the actual revision if the requested revision is a version constraint and not a static version, and downloading all necessary metadata information.
post-resolve-dependency	organisation the organisation of the dependency resolved module the name of the dependency resolved req-revision the requested revision for the dependency since 2.0 req-revision-default the default requested revision constraint for the dependency since 2.0 req-revision-dynamic the requested revision dynamic constraint for the dependency since 2.0 revision the revision of the dependency resolved, or the requested revision if the resolution was not successful resolved true if the resolution was successful, false otherwise duration the time elapsed to resolve the dependency (in ms) since 2.0 resolver the name of the resolver used to resolve the dependency any extra attribute all extra attributes found on the info tag of the resolved dependency are available since 2.0	Fired after each dependency is resolved
post-resolve	organisation the organisation of the module for which the dependencies have been resolved module the name of the module for which the dependencies have been resolved revision the revision of the module for which the dependencies have been resolved conf comma separated list of configurations resolved resolve-id the identifier of the resolution process since 2.0 nb-dependencies total number of dependencies, including transitive and evicted ones since 2.0 nb-artifacts total number of artifacts resolved, excluding metadata artifacts since 2.0 resolve-duration the time (in ms) elapsed to resolve dependencies, before dowloading artifacts since 2.0 download-duration the time (in ms) elapsed to download all artifacts, excluding metadata artifacts downloaded during the first phase of the resolution process since 2.0 download-size the total size (in bytes) of all downloaded artifacts, excluding metadata artifacts. Only artifacts actually downloaded (not in cache or used from their original location) are considered since 2.0	Fired at the end of the resolve process, when all module dependencies have been resolved
pre-download-artifact	organisation the organisation of the artifact which is about to be downloaded module the name of the module of the artifact which is about to be downloaded revision the revision of the the artifact which is about to be downloaded artifact the name of the the artifact which is about to be downloaded type the type of the the artifact which is about to be downloaded ext the extension of the the artifact which is about to be downloaded metadata true if the artifact to be downloaded is a metadata artifact, false for published artifacts since 2.0 resolver the name of the resolver used to download the artifact origin the origin location from which it will be downloaded local true if it's a local artifact, false otherwise	Fired before an artifact is downloaded from a repository to the cache
post-download-artifact	organisation the organisation of the artifact which was just downloaded module the name of the module of the artifact which was just downloaded revision the revision of the the artifact which was just downloaded artifact the name of the the artifact which was just downloaded type the type of the the artifact which was just downloaded ext the extension of the the artifact which was just downloaded metadata true if the downloaded artifact is a metadata artifact, false for published artifacts since 2.0 resolver the name of the resolver used to download the artifact origin the origin location from which it was downloaded local true if it's a local artifact, false otherwise size the size in bytes of the downloaded artifact duration the time elapsed to download the artifact (in ms) since 2.0 file the file to which it has been downloaded	Fired after an artifact has been downloaded from a repository to the cache
pre-retrieve since 2.0	organisation the organisation of the module for which the dependencies will be retrieved module the name of the module for which the dependencies will be retrieved revision the revision of the module for which the dependencies will be retrieved conf comma separated list of configurations which will be retrieved symlink true if Ivy will use symbolic links instead of copies on supported platforms, false otherwise sync true if the retrieve process will be performed in sync mode, false otherwise	Fired at the beginning of the retrieve process.
post-retrieve since 2.0	organisation the organisation of the module for which the dependencies have been retrieved module the name of the module for which the dependencies will be retrieved revision the revision of the module for which the dependencies have been retrieved conf comma separated list of configurations which have been retrieved symlink true if Ivy used symbolic links instead of copies on supported platforms, false otherwise sync true if the retrieve process has been performed in sync mode, false otherwise duration the time elapsed in ms during the retrieve process size the total size of artifacts which have actually been copied (or symlinked) nbCopied the number of artifacts copied or symlinked nbUptodate the number of artifacts which were already present and up to date at the destination location	Fired at the end of the retrieve process.
pre-retrieve-artifact since 2.1	organisation the organisation of the artifact which is about to be retrieved module the name of the module of the artifact which is about to be retrieved revision the revision of the the artifact which is about to be retrieved artifact the name of the the artifact which is about to be retrieved type the type of the the artifact which is about to be retrieved ext the extension of the the artifact which is about to be retrieved metadata true if the retrieved artifact is a metadata artifact, false for published artifacts size the size in bytes of the retrieved artifact from the absolute path from which it will be retrieved (usually a location in cache) to the absolute path to which it will be retrieved	Fired before an artifact is retrieved from the cache to a local location
post-retrieve-artifact since 2.1	organisation the organisation of the artifact which has just been retrieved module the name of the module of the artifact which has just been retrieved revision the revision of the the artifact which has just been retrieved artifact the name of the the artifact which has just been retrieved type the type of the the artifact which has just been retrieved ext the extension of the the artifact which has just been retrieved metadata true if the retrieved artifact is a metadata artifact, false for published artifacts size the size in bytes of the retrieved artifact from the absolute path from which it has just been retrieved (usually a location in cache) to the absolute path to which it has just been retrieved	Fired after an artifact is retrieved from the cache to a local location
pre-publish-artifact since 2.0	organisation the organisation of the artifact which is about to be published module the name of the module of the artifact which is about to be published revision the revision of the the artifact which is about to be published artifact the name of the the artifact which is about to be published type the type of the the artifact which is about to be published ext the extension of the the artifact which is about to be published resolver the name of the resolver into which the artifact is about to be published file the absolute path of the source file for the artifact overwrite "true" if the new data will overwrite existing artifacts, "false" otherwise	Fired before an artifact is published into a repository
post-publish-artifact since 2.0	organisation the organisation of the artifact that was published module the name of the module of the artifact that was published revision the revision of the the artifact that was published artifact the name of the the artifact that was published type the type of the the artifact that was published ext the extension of the the artifact that was published resolver the name of the resolver into which the artifact was published file the absolute path of the source file for the artifact overwrite "true" if the new data overwrote existing artifacts, "false" otherwise status "successful" if the artifact published successfully; "failed" if the artifact failed to publish, or if the status is unknown	Fired after an artifact is published into a repository. Note that this event is fired whether or not the publication succeeded. The "status" property can be checked to verify success.

The child tag used for the dependency resolver must be equal to a name of a trigger type (either built-in or added with the typedef tag).

Child elements

Element	Description	Cardinality
any trigger	adds a trigger to the list of registered triggers	1..n

Built-in Triggers

Ivy comes with 3 built-in triggers:

Name	Description
ant-build	Triggers an ant build. Note that by default the ant build is triggered only once per build file, the property onlyonce can be set to false to change this.
ant-call	Calls a target in the current ant build.
log	Logs a message on the console or in a log file.

Common attributes

All triggers share some common attributes detailed here.

Among these attributes, you will find how to select when the trigger should be performed. You have to provide an event name, which is simple, but you can also use a filter expression. The syntax for this expression is very simple and limited:
you can use the = operator to compare an attribute (left operande) with a value (right operande).
you can use AND OR NOT as boolean operators
you cannot use parenthesis to change the precedence

Attribute	Description	Required
name	the name of the trigger for identification purpose only	Yes
event	the name of the event on which the trigger should be performed	Yes
filter	a filter expression used to restrict when the trigger should be performed	No, defaults to no filter

Examples

<triggers>
    <ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish"
           event="pre-resolve-dependency" filter="revision=latest.integration"/>
</triggers>

Triggers an ant build of the ant file ${ivy.settings.dir}/[module]/build.xml (where [module] is replaced by the name of the dependency resolved) with the target "publish", just before resolving a dependency with a latest.integration revision.
Note that by default the ant build is triggered only once per build file. See below to see how to trigger the build more than once.

<triggers>
    <ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish"
           event="pre-resolve-dependency" filter="revision=latest.integration"
           onlyonce="false" />
</triggers>

Same as before, but this time the builds will be triggered as many time as the dependency is resolved, instead of only once.

<triggers>
    <ant-call target="unzip" prefix="dep"
          event="post-download-artifact" filter="type=zip AND status=successful"/>
</triggers>

Triggers an ant call of the target unzip just after downloading a zip artifact, prefixing all parameters to the target with 'dep'.
Here is how the target can look like:

<target name="unzip">
     <echo>
        unzipping artifact: 
        organisation=${dep.organisation} 
        module=${dep.module} 
        revision=${dep.revision}
        artifact=${dep.artifact}
        type=${dep.type}
        ext=${dep.ext}
        origin=${dep.origin}
        local=${dep.local}
        size=${dep.size}
        file=${dep.file}
     </echo>
     <mkdir dir="${basedir}/out"/>
     <unzip src="${dep.file}" dest="${basedir}/out"/>
</target>

<triggers>
    <log file="ivy.log" 
          message='downloaded "${origin}" to "${file}" (${duration}ms - ${size}B)'
          event="post-download-artifact" filter="status=successful"/>
</triggers>

Logs any successful artifact download, with information on the source and destination, and details on download size and duration.

The file attribute is optional, the log trigger will output messages to console if it isn't provided.

Copyright © 2011 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache Ivy, Apache Ant, Ivy, Ant, Apache, the Apache Ivy logo, the Apache Ant logo and the Apache feather logo are trademarks of The Apache Software Foundation.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.

Apache Ivy™

triggers

Child elements

Built-in Triggers

Common attributes

Examples