| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <html> |
| <head> |
| <script type="text/javascript">var xookiConfig = {level: 1};</script> |
| <script type="text/javascript" src="../xooki/xooki.js"></script> |
| </head> |
| <body> |
| <textarea id="xooki-source"> |
| <b>Tag:</b> triggers |
| <span class="since">since 1.4</span> |
| |
| <span class="tagdoc" id="ivysettings.triggers">Defines a list of triggers to activate on some Ivy events.</span> |
| |
| A trigger is an action which is performed whenever a particular event occurs. |
| Ivy supports 3 type of triggers out of the box: |
| <ul> |
| <li>ant-call</li> calls a target in the same build as the original one whenever a particular event occurs. |
| <li>ant-build</li> calls an ant build which may be in another ant build script. |
| <li>log</li> echo a message, usually in a file |
| </ul> |
| |
| If you want to use a different trigger, you can <a href="../extend.html">implement your own</a>. |
| |
| The following events are available in Ivy: |
| <table class="ivy-children"> |
| <thead> |
| <tr><th>Name</th><th>Attributes</th><th>Description</th></tr> |
| </thead> |
| <tbody> |
| <tr><td>pre-resolve</td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the module for which the dependencies will be resolved |
| <li>module</li>the name of the module for which the dependencies will be resolved |
| <li>revision</li>the revision of the module for which the dependencies will be resolved |
| <li>conf</li>comma separated list of configurations which will be resolved |
| </ul> |
| </td> |
| <td>Fired at the beginning of the resolve process, before module dependencies and transitive dependencies are resolved.</td> |
| </tr> |
| <tr><td>pre-resolve-dependency</td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the dependency resolved |
| <li>module</li>the name of the dependency resolved |
| <li>req-revision</li>the requested revision for the dependency <span class="since">since 2.0</span> (provided for consistency with post-resolve-dependency) |
| <li>req-revision-default</li>the default requested revision constraint for the dependency <span class="since">since 2.0</span> |
| <li>req-revision-dynamic</li>the requested revision dynamic constraint for the dependency <span class="since">since 2.0</span> |
| <li>revision</li>the requested revision for the dependency |
| <li>resolver</li>the name of the resolver used to resolve the dependency |
| </ul> |
| </td> |
| <td>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.</td> |
| </tr> |
| <tr><td>post-resolve-dependency</td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the dependency resolved |
| <li>module</li>the name of the dependency resolved |
| <li>req-revision</li>the requested revision for the dependency <span class="since">since 2.0</span> |
| <li>req-revision-default</li>the default requested revision constraint for the dependency <span class="since">since 2.0</span> |
| <li>req-revision-dynamic</li>the requested revision dynamic constraint for the dependency <span class="since">since 2.0</span> |
| <li>revision</li>the revision of the dependency resolved, or the requested revision if the resolution was not successful |
| <li>resolved</li>true if the resolution was successful, false otherwise |
| <li>duration</li>the time elapsed to resolve the dependency (in ms) <span class="since">since 2.0</span> |
| <li>resolver</li>the name of the resolver used to resolve the dependency |
| <li>any extra attribute</li>all extra attributes found on the info tag of the resolved dependency are available <span class="since">since 2.0</span> |
| </ul> |
| </td> |
| <td>Fired after each dependency is resolved</td> |
| </tr> |
| <tr><td>post-resolve</td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the module for which the dependencies have been resolved |
| <li>module</li>the name of the module for which the dependencies have been resolved |
| <li>revision</li>the revision of the module for which the dependencies have been resolved |
| <li>conf</li>comma separated list of configurations resolved |
| <li>resolve-id</li>the identifier of the resolution process <span class="since">since 2.0</span> |
| <li>nb-dependencies</li>total number of dependencies, including transitive and evicted ones <span class="since">since 2.0</span> |
| <li>nb-artifacts</li>total number of artifacts resolved, excluding metadata artifacts <span class="since">since 2.0</span> |
| <li>resolve-duration</li>the time (in ms) elapsed to resolve dependencies, before dowloading artifacts <span class="since">since 2.0</span> |
| <li>download-duration</li>the time (in ms) elapsed to download all artifacts, excluding metadata artifacts downloaded during the first phase of the resolution process <span class="since">since 2.0</span> |
| <li>download-size</li>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 <span class="since">since 2.0</span> |
| </ul> |
| </td> |
| <td>Fired at the end of the resolve process, when all module dependencies have been resolved</td> |
| </tr> |
| <tr><td>pre-download-artifact</td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the artifact which is about to be downloaded |
| <li>module</li>the name of the module of the artifact which is about to be downloaded |
| <li>revision</li>the revision of the the artifact which is about to be downloaded |
| <li>artifact</li>the name of the the artifact which is about to be downloaded |
| <li>type</li>the type of the the artifact which is about to be downloaded |
| <li>ext</li>the extension of the the artifact which is about to be downloaded |
| <li>metadata</li>true if the artifact to be downloaded is a metadata artifact, false for published artifacts <span class="since">since 2.0</span> |
| <li>resolver</li>the name of the resolver used to download the artifact |
| <li>origin</li>the origin location from which it will be downloaded |
| <li>local</li>true if it's a local artifact, false otherwise |
| </ul> |
| </td> |
| <td>Fired before an artifact is downloaded from a repository to the cache</td> |
| </tr> |
| <tr><td>post-download-artifact</td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the artifact which was just downloaded |
| <li>module</li>the name of the module of the artifact which was just downloaded |
| <li>revision</li>the revision of the the artifact which was just downloaded |
| <li>artifact</li>the name of the the artifact which was just downloaded |
| <li>type</li>the type of the the artifact which was just downloaded |
| <li>ext</li>the extension of the the artifact which was just downloaded |
| <li>metadata</li>true if the downloaded artifact is a metadata artifact, false for published artifacts <span class="since">since 2.0</span> |
| <li>resolver</li>the name of the resolver used to download the artifact |
| <li>origin</li>the origin location from which it was downloaded |
| <li>local</li>true if it's a local artifact, false otherwise |
| <li>size</li>the size in bytes of the downloaded artifact |
| <li>duration</li>the time elapsed to download the artifact (in ms) <span class="since">since 2.0</span> |
| <li>file</li>the file to which it has been downloaded |
| </ul> |
| </td> |
| <td>Fired after an artifact has been downloaded from a repository to the cache</td> |
| </tr> |
| <tr><td>pre-retrieve <br/><span class="since">since 2.0</span></td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the module for which the dependencies will be retrieved |
| <li>module</li>the name of the module for which the dependencies will be retrieved |
| <li>revision</li>the revision of the module for which the dependencies will be retrieved |
| <li>conf</li>comma separated list of configurations which will be retrieved |
| <li>symlink</li>true if Ivy will use symbolic links instead of copies on supported platforms, false otherwise |
| <li>sync</li>true if the retrieve process will be performed in sync mode, false otherwise |
| </ul> |
| </td> |
| <td>Fired at the beginning of the retrieve process.</td> |
| </tr> |
| <tr><td>post-retrieve <br/><span class="since">since 2.0</span></td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the module for which the dependencies have been retrieved |
| <li>module</li>the name of the module for which the dependencies will be retrieved |
| <li>revision</li>the revision of the module for which the dependencies have been retrieved |
| <li>conf</li>comma separated list of configurations which have been retrieved |
| <li>symlink</li>true if Ivy used symbolic links instead of copies on supported platforms, false otherwise |
| <li>sync</li>true if the retrieve process has been performed in sync mode, false otherwise |
| <li>duration</li>the time elapsed in ms during the retrieve process |
| <li>size</li>the total size of artifacts which have actually been copied (or symlinked) |
| <li>nbCopied</li>the number of artifacts copied or symlinked |
| <li>nbUptodate</li>the number of artifacts which were already present and up to date at the destination location |
| </ul> |
| </td> |
| <td>Fired at the end of the retrieve process.</td> |
| </tr> |
| <tr><td>pre-retrieve-artifact <br/><span class="since">since 2.1</span></td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the artifact which is about to be retrieved |
| <li>module</li>the name of the module of the artifact which is about to be retrieved |
| <li>revision</li>the revision of the the artifact which is about to be retrieved |
| <li>artifact</li>the name of the the artifact which is about to be retrieved |
| <li>type</li>the type of the the artifact which is about to be retrieved |
| <li>ext</li>the extension of the the artifact which is about to be retrieved |
| <li>metadata</li>true if the retrieved artifact is a metadata artifact, false for published artifacts |
| <li>size</li>the size in bytes of the retrieved artifact |
| <li>from</li>the absolute path from which it will be retrieved (usually a location in cache) |
| <li>to</li>the absolute path to which it will be retrieved |
| </ul> |
| </td> |
| <td>Fired before an artifact is retrieved from the cache to a local location</td> |
| </tr> |
| <tr><td>post-retrieve-artifact <br/><span class="since">since 2.1</span></td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the artifact which has just been retrieved |
| <li>module</li>the name of the module of the artifact which has just been retrieved |
| <li>revision</li>the revision of the the artifact which has just been retrieved |
| <li>artifact</li>the name of the the artifact which has just been retrieved |
| <li>type</li>the type of the the artifact which has just been retrieved |
| <li>ext</li>the extension of the the artifact which has just been retrieved |
| <li>metadata</li>true if the retrieved artifact is a metadata artifact, false for published artifacts |
| <li>size</li>the size in bytes of the retrieved artifact |
| <li>from</li>the absolute path from which it has just been retrieved (usually a location in cache) |
| <li>to</li>the absolute path to which it has just been retrieved |
| </ul> |
| </td> |
| <td>Fired after an artifact is retrieved from the cache to a local location</td> |
| </tr> |
| <tr><td>pre-publish-artifact <br/><span class="since">since 2.0</span></td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the artifact which is about to be published |
| <li>module</li>the name of the module of the artifact which is about to be published |
| <li>revision</li>the revision of the the artifact which is about to be published |
| <li>artifact</li>the name of the the artifact which is about to be published |
| <li>type</li>the type of the the artifact which is about to be published |
| <li>ext</li>the extension of the the artifact which is about to be published |
| <li>resolver</li>the name of the resolver into which the artifact is about to be published |
| <li>file</li>the absolute path of the source file for the artifact |
| <li>overwrite</li>"true" if the new data will overwrite existing artifacts, "false" otherwise |
| </ul> |
| </td> |
| <td>Fired before an artifact is published into a repository</td> |
| </tr> |
| <tr><td>post-publish-artifact <br/><span class="since">since 2.0</span></td> |
| <td> |
| <ul> |
| <li>organisation</li>the organisation of the artifact that was published |
| <li>module</li>the name of the module of the artifact that was published |
| <li>revision</li>the revision of the the artifact that was published |
| <li>artifact</li>the name of the the artifact that was published |
| <li>type</li>the type of the the artifact that was published |
| <li>ext</li>the extension of the the artifact that was published |
| <li>resolver</li>the name of the resolver into which the artifact was published |
| <li>file</li>the absolute path of the source file for the artifact |
| <li>overwrite</li>"true" if the new data overwrote existing artifacts, "false" otherwise |
| <li>status</li>"successful" if the artifact published successfully; "failed" if the artifact failed to publish, or if the status is unknown |
| </ul> |
| </td> |
| <td>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.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| |
| 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). |
| |
| <h1>Child elements</h1> |
| <table class="ivy-children"> |
| <thead> |
| <tr><th class="ivy-chld">Element</th><th class="ivy-chld-desc">Description</th><th class="ivy-chld-card">Cardinality</th></tr> |
| </thead> |
| <tbody> |
| <tr><td>any trigger</td><td>adds a trigger to the list of registered triggers</td> |
| <td>1..n</td></tr> |
| </tbody> |
| </table> |
| |
| <h1>Built-in Triggers</h1> |
| Ivy comes with 3 built-in triggers: |
| |
| <table class="ivy-attributes"> |
| <thead> |
| <tr><th>Name</th><th>Description</th></tr> |
| </thead> |
| <tbody> |
| <tr><td>ant-build</td><td>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.</td></tr> |
| <tr><td>ant-call</td><td>Calls a target in the current ant build.</td></tr> |
| <tr><td>log</td><td>Logs a message on the console or in a log file.</td></tr> |
| </tbody> |
| </table> |
| |
| |
| <h1><a name="common">Common attributes</a></h1> |
| 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 |
| |
| <table class="ivy-attributes"> |
| <thead> |
| <tr><th class="ivy-att">Attribute</th><th class="ivy-att-desc">Description</th><th class="ivy-att-req">Required</th></tr> |
| </thead> |
| <tbody> |
| <tr><td>name</td><td>the name of the trigger for identification purpose only</td> |
| <td>Yes</td> |
| </tr> |
| <tr><td>event</td><td>the name of the event on which the trigger should be performed</td> |
| <td>Yes</td> |
| </tr> |
| <tr><td>filter</td><td>a filter expression used to restrict when the trigger should be performed</td> |
| <td>No, defaults to no filter</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h1>Examples</h1> |
| <code type="xml"> |
| <triggers> |
| <ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish" |
| event="pre-resolve-dependency" filter="revision=latest.integration"/> |
| </triggers> |
| </code> |
| 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. |
| <hr/> |
| <code type="xml"> |
| <triggers> |
| <ant-build antfile="${ivy.settings.dir}/[module]/build.xml" target="publish" |
| event="pre-resolve-dependency" filter="revision=latest.integration" |
| onlyonce="false" /> |
| </triggers> |
| </code> |
| Same as before, but this time the builds will be triggered as many time as the dependency is resolved, instead of only once. |
| <hr/> |
| <code type="xml"> |
| <triggers> |
| <ant-call target="unzip" prefix="dep" |
| event="post-download-artifact" filter="type=zip AND status=successful"/> |
| </triggers> |
| </code> |
| 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: |
| <code type="xml"> |
| <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> |
| </code> |
| <hr/> |
| <code type="xml"> |
| <triggers> |
| <log file="ivy.log" |
| message='downloaded "${origin}" to "${file}" (${duration}ms - ${size}B)' |
| event="post-download-artifact" filter="status=successful"/> |
| </triggers> |
| </code> |
| 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.</textarea> |
| <script type="text/javascript">xooki.postProcess();</script> |
| </body> |
| </html> |