Debian Codegraph @

subprojects/groovy-ant/src/spec/doc/groovy-ant-task.adoc

raw
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 ---------------------------------------------------------------------------------