| 1 |
////////////////////////////////////////// |
| 2 |
|
| 3 |
Licensed to the Apache Software Foundation (ASF) under one |
| 4 |
or more contributor license agreements. See the NOTICE file |
| 5 |
distributed with this work for additional information |
| 6 |
regarding copyright ownership. The ASF licenses this file |
| 7 |
to you under the Apache License, Version 2.0 (the |
| 8 |
"License"); you may not use this file except in compliance |
| 9 |
with the License. You may obtain a copy of the License at |
| 10 |
|
| 11 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 12 |
|
| 13 |
Unless required by applicable law or agreed to in writing, |
| 14 |
software distributed under the License is distributed on an |
| 15 |
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 16 |
KIND, either express or implied. See the License for the |
| 17 |
specific language governing permissions and limitations |
| 18 |
under the License. |
| 19 |
|
| 20 |
////////////////////////////////////////// |
| 21 |
|
| 22 |
= The <groovy> Ant Task |
| 23 |
|
| 24 |
Executes a series of Groovy statements from http://ant.apache.org/[Apache Ant]. |
| 25 |
Statements can either be read in from a text file using the `src` attribute or from between the enclosing Groovy tags. |
| 26 |
|
| 27 |
== Required taskdef |
| 28 |
|
| 29 |
Assuming `groovy-all-VERSION.jar` is in `my.classpath` you will need to declare this task in the `build.xml` prior to using it: |
| 30 |
|
| 31 |
[source,xml] |
| 32 |
---- |
| 33 |
<taskdef name="groovy" |
| 34 |
classname="org.codehaus.groovy.ant.Groovy" |
| 35 |
classpathref="my.classpath"/> |
| 36 |
<groovy> |
| 37 |
---- |
| 38 |
|
| 39 |
== <groovy> attributes |
| 40 |
|
| 41 |
[cols="<1,<2,<1",options="header,footer"] |
| 42 |
|============================================ |
| 43 |
|Attribute|Description|Required |
| 44 |
|src|File containing Groovy statements. The directory containing the file is added to the classpath.| Yes, unless statements enclosed within tags |
| 45 |
|classpath|The classpath to use.|No |
| 46 |
|classpathref|The classpath to use, given as reference to a PATH defined elsewhere.|No |
| 47 |
|output|Set the output file; defaults to the Ant log.|No |
| 48 |
|fork|If enabled the script will be executed in another JVM (disabled by default).|No |
| 49 |
|scriptBaseClass|The name of the base class for scripts.|No |
| 50 |
|indy|If enabled the script will be executed with `invokedynamic` (disabled by default).|No |
| 51 |
|============================================ |
| 52 |
|
| 53 |
== Parameters specified as nested elements |
| 54 |
=== <classpath> |
| 55 |
|
| 56 |
Groovy's classpath attribute is a PATH like structure and can also be set via a nested classpath element. |
| 57 |
|
| 58 |
=== <arg> |
| 59 |
|
| 60 |
Arguments can be set via one or more nested <arg> elements using the standard Ant http://ant.apache.org/manual/using.html#arg[command line conventions]. |
| 61 |
|
| 62 |
== Available bindings |
| 63 |
|
| 64 |
A number of bindings are in scope for use within your Groovy statements. |
| 65 |
|
| 66 |
[cols="<1,<5",options="header,footer"] |
| 67 |
|============================================ |
| 68 |
|Name|Description |
| 69 |
|ant|an instance of `AntBuilder` that knows about the current ant project |
| 70 |
|project|the current ant project |
| 71 |
|properties|a `Map` of ant properties |
| 72 |
|target|the owning target that invoked this groovy script |
| 73 |
|task|the wrapping task, can access anything needed in `org.apache.tools.ant.Task` |
| 74 |
|args|command line arguments, if any |
| 75 |
|============================================ |
| 76 |
|
| 77 |
== Examples |
| 78 |
|
| 79 |
Hello world, version 1: |
| 80 |
|
| 81 |
[source,xml] |
| 82 |
--------------------------------------------------------------------------------- |
| 83 |
<groovy> |
| 84 |
println "Hello World" |
| 85 |
</groovy> |
| 86 |
--------------------------------------------------------------------------------- |
| 87 |
|
| 88 |
Hello world, version 2: |
| 89 |
|
| 90 |
[source,xml] |
| 91 |
--------------------------------------------------------------------------------- |
| 92 |
<groovy> |
| 93 |
ant.echo "Hello World" |
| 94 |
</groovy> |
| 95 |
--------------------------------------------------------------------------------- |
| 96 |
|
| 97 |
List all xml files in the current directory: |
| 98 |
|
| 99 |
[source,xml] |
| 100 |
--------------------------------------------------------------------------------- |
| 101 |
<groovy> |
| 102 |
xmlfiles = new File(".").listFiles().findAll{ it =~ "\.xml$" } |
| 103 |
xmlfiles.sort().each { println it.toString() } |
| 104 |
</groovy> |
| 105 |
--------------------------------------------------------------------------------- |
| 106 |
|
| 107 |
List all xml files within a jar: |
| 108 |
|
| 109 |
[source,xml] |
| 110 |
--------------------------------------------------------------------------------- |
| 111 |
<zipfileset id="found" src="foobar.jar" |
| 112 |
includes="**/*.xml"/> |
| 113 |
<groovy> |
| 114 |
project.references.found.each { |
| 115 |
println it.name |
| 116 |
} |
| 117 |
</groovy> |
| 118 |
--------------------------------------------------------------------------------- |
| 119 |
|
| 120 |
Run a script: |
| 121 |
|
| 122 |
[source,xml] |
| 123 |
--------------------------------------------------------------------------------- |
| 124 |
<groovy src="/some/directory/some/file.groovy"> |
| 125 |
<classpath> |
| 126 |
<pathelement location="/my/groovy/classes/directory"/> |
| 127 |
</classpath> |
| 128 |
</groovy> |
| 129 |
--------------------------------------------------------------------------------- |
| 130 |
|
| 131 |
Find all `Builder` classes having an `org.*` package within a directory of jars: |
| 132 |
|
| 133 |
[source,xml] |
| 134 |
--------------------------------------------------------------------------------- |
| 135 |
<property name="local.target" value="C:/Projects/GroovyExamples"/> |
| 136 |
<groovy> |
| 137 |
import java.util.jar.JarFile |
| 138 |
def classes = [] |
| 139 |
def resourceNamePattern = /org\/.*\/.*Builder.class/ |
| 140 |
def jarNamePattern = /.*(beta|commons).*jar$/ |
| 141 |
|
| 142 |
def libdir = new File("${properties['local.target']}/lib") |
| 143 |
libdir.listFiles().grep(~jarNamePattern).each { candidate -> |
| 144 |
new JarFile(candidate).entries().each { entry -> |
| 145 |
if (entry.name ==~ resourceNamePattern) classes += entry.name |
| 146 |
} |
| 147 |
} |
| 148 |
properties["builder-classes"] = classes.join(' ') |
| 149 |
</groovy> |
| 150 |
<echo message='${builder-classes}'/> |
| 151 |
--------------------------------------------------------------------------------- |
| 152 |
|
| 153 |
Which might result in something like: |
| 154 |
[source] |
| 155 |
--------------------------------------------------------------------------------- |
| 156 |
org/apache/commons/cli/PatternOptionBuilder.class org/apache/commons/cli/OptionBuilder.class org/codehaus/groovy/tools/groovydoc/GroovyRootDocBuilder.class org/custommonkey/xmlunit/HTMLDocumentBuilder.class org/custommonkey/xmlunit/TolerantSaxDocumentBuilder.class |
| 157 |
--------------------------------------------------------------------------------- |
| 158 |
|
| 159 |
FileScanner version of above (with a slight variation on collecting the names): |
| 160 |
|
| 161 |
[source,xml] |
| 162 |
--------------------------------------------------------------------------------- |
| 163 |
<groovy> |
| 164 |
import java.util.jar.JarFile |
| 165 |
def resourceNamePattern = /org\/.*\/.*Builder.class/ |
| 166 |
def candidates = ant.fileScanner { |
| 167 |
fileset(dir: '${local.target}/lib') { |
| 168 |
include(name: '*beta*.jar') |
| 169 |
include(name: '*commons*.jar') |
| 170 |
} |
| 171 |
} |
| 172 |
def classes = candidates.collect { |
| 173 |
new JarFile(it).entries().collect { it.name }.findAll { |
| 174 |
it ==~ resourceNamePattern |
| 175 |
} |
| 176 |
}.flatten() |
| 177 |
properties["builder-classes"] = classes.join(' ') |
| 178 |
</groovy> |
| 179 |
--------------------------------------------------------------------------------- |
| 180 |
|
| 181 |
Calling out to a web service from your Ant script: |
| 182 |
|
| 183 |
[source,xml] |
| 184 |
--------------------------------------------------------------------------------- |
| 185 |
<?xml version="1.0" encoding="UTF-8"?> |
| 186 |
<project name="SOAP example" default="main" basedir="."> |
| 187 |
<property environment="env"/> |
| 188 |
<property name="celsius" value="0"/> |
| 189 |
<target name="main"> |
| 190 |
<taskdef name="groovy" classname="org.codehaus.groovy.ant.Groovy"> |
| 191 |
<classpath> |
| 192 |
<fileset dir="${env.GROOVY_HOME}" includes="embeddable/groovy-all-*.jar,lib/ivy*.jar"/> |
| 193 |
</classpath> |
| 194 |
</taskdef> |
| 195 |
<groovy> |
| 196 |
@Grab('org.codehaus.groovy.modules:groovyws:0.5.1') |
| 197 |
import groovyx.net.ws.WSClient |
| 198 |
def url = 'http://www.w3schools.com/webservices/tempconvert.asmx?WSDL' |
| 199 |
def proxy = new WSClient(url, this.class.classLoader) |
| 200 |
proxy.initialize() |
| 201 |
ant.echo "I'm freezing at ${properties.celsius} degrees Celsius" |
| 202 |
properties.result = proxy.CelsiusToFahrenheit(properties.celsius) |
| 203 |
</groovy> |
| 204 |
<antcall target="results"/> |
| 205 |
</target> |
| 206 |
<target name="results"> |
| 207 |
<echo message="I'm freezing at ${result} degrees Fahrenheit"/> |
| 208 |
</target> |
| 209 |
</project> |
| 210 |
--------------------------------------------------------------------------------- |
| 211 |
|
| 212 |
Which will output the following (along with some informational messages): |
| 213 |
|
| 214 |
[source] |
| 215 |
--------------------------------------------------------------------------------- |
| 216 |
main: |
| 217 |
... |
| 218 |
[echo] I'm freezing at 0 degrees Celsius |
| 219 |
results: |
| 220 |
[echo] I'm freezing at 32 degrees Fahrenheit |
| 221 |
|
| 222 |
BUILD SUCCESSFUL |
| 223 |
--------------------------------------------------------------------------------- |
| 224 |
|
| 225 |
Setting arguments: |
| 226 |
|
| 227 |
[source,xml] |
| 228 |
--------------------------------------------------------------------------------- |
| 229 |
<target name="run"> |
| 230 |
<groovy> |
| 231 |
<arg line="1 2 3"/> |
| 232 |
<arg value="4 5"/> |
| 233 |
println args.size() |
| 234 |
println args[2] |
| 235 |
args.each{ ant.echo(message:it) } |
| 236 |
</groovy> |
| 237 |
</target> |
| 238 |
--------------------------------------------------------------------------------- |
| 239 |
|
| 240 |
Output: |
| 241 |
|
| 242 |
[source] |
| 243 |
--------------------------------------------------------------------------------- |
| 244 |
Buildfile: build.xml |
| 245 |
|
| 246 |
run: |
| 247 |
[groovy] 4 |
| 248 |
[groovy] 3 |
| 249 |
[echo] 1 |
| 250 |
[echo] 2 |
| 251 |
[echo] 3 |
| 252 |
[echo] 4 5 |
| 253 |
|
| 254 |
BUILD SUCCESSFUL |
| 255 |
--------------------------------------------------------------------------------- |