source: release-kits/lirk3/resources/gs3-release-maker/apache-ant-1.6.5/docs/manual/OptionalTasks/script.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 9.1 KB
Line 
1<html>
2
3<head>
4<meta http-equiv="Content-Language" content="en-us"></meta>
5<title>Script Task</title>
6<link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
7</head>
8
9<body>
10
11<h2><a name="script">Script</a></h2>
12<h3>Description</h3>
13<p>Execute a script in a
14 <a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a> supported language.</p>
15<p><b>Note:</b> This task depends on external libraries not included in the Ant distribution.
16See <a href="../install.html#librarydependencies">Library Dependencies</a> for more information.</p>
17<p>All items (tasks, targets, etc) of the running project are
18accessible from the script, using either their <code>name</code> or
19<code>id</code> attributes (as long as their names are considered
20valid Java identifiers, that is).
21The name "project" is a pre-defined reference to the Project, which can be
22used instead of the project name. The name "self" is a pre-defined reference to the actual
23<code>&lt;script&gt;</code>-Task instance.<br/>From these objects you have access to the Ant Java API, see the
24<a href="../api/index.html">JavaDoc</a> (especially for
25<a href="../api/org/apache/tools/ant/Project.html">Project</a> and
26<a href="../api/org/apache/tools/ant/taskdefs/optional/Script.html">Script</a>) for more information.</p>
27<p>If you are using JavaScript a good resource is <a target="_blank" href="http://www.mozilla.org/rhino/doc.html">
28http://www.mozilla.org/rhino/doc.html</a> as we are using their JavaScript interpreter.</p>
29<p>Scripts can do almost anything a task written in Java could do.</p>
30<p>Rhino provides a special construct - the <i>JavaAdapter</i>. With that you can
31create an object which implements several interfaces, extends classes and for which you
32can overwrite methods. Because this is an undocumented feature (yet), here is the link
33to an explanation: <a href="http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&newwindow=1&frame=right&th=610d2db45c0756bd&seekm=391EEC3C.5236D929%40yahoo.com#link2">
34Groups@Google: "Rhino, enum.js, JavaAdapter?"</a> by Norris Boyd in the newsgroup
35<i>netscape.public.mozilla.jseng</i>.</p>
36
37
38
39<h3>Parameters</h3>
40<table border="1" cellpadding="2" cellspacing="0">
41 <tr>
42 <td valign="top"><b>Attribute</b></td>
43 <td valign="top"><b>Description</b></td>
44 <td align="center" valign="top"><b>Required</b></td>
45 </tr>
46 <tr>
47 <td valign="top">language</td>
48 <td valign="top">The programming language the script is written in.
49 Must be a supported Apache BSF language</td>
50 <td valign="top" align="center">Yes</td>
51 </tr>
52 <tr>
53 <td valign="top">src</td>
54 <td valign="top">The location of the script as a file, if not inline</td>
55 <td valign="top" align="center">No</td>
56 </tr>
57</table>
58<h3>Examples</h3>
59The following snippet shows use of five different languages:
60 <blockquote><pre>
61 &lt;property name="message" value="Hello world"/&gt;
62
63 &lt;script language="groovy"&gt;
64 println("message is " + message)
65 &lt;/script&gt;
66
67 &lt;script language="beanshell"&gt;
68 System.out.println("message is " + message);
69 &lt;/script&gt;
70
71 &lt;script language="judoscript"&gt;
72 println 'message is ', message
73 &lt;/script&gt;
74
75 &lt;script language="ruby"&gt;
76 print 'message is ', $message, "\n"
77 &lt;/script&gt;
78
79 &lt;script language="jython"&gt;
80print "message is %s" % message
81 &lt;/script&gt;
82</pre>
83 </blockquote>
84 <p>
85 Note that for the <i>jython</i> example, the script contents <b>must</b>
86 start on the first column.
87 </p>
88 <p>
89 The following script shows a little more complicated jruby example:
90 </p>
91 <blockquote><pre>
92&lt;script language="ruby"&gt;
93 xmlfiles = Dir.new(".").entries.delete_if { |i| ! (i =~ /\.xml$/) }
94 xmlfiles.sort.each { |i| $self.log(i) }
95&lt;/script&gt;
96</pre>
97 </blockquote>
98 <p>
99 The same example in groovy is:
100 </p>
101 <blockquote><pre>
102&lt;script language="groovy"&gt;
103 xmlfiles = new java.io.File(".").listFiles().findAll{ it =~ "\.xml$"}
104 xmlfiles.sort().each { self.log(it.toString())}
105&lt;/script&gt;
106</pre>
107 </blockquote>
108 <p>
109 The following script uses javascript to create a number of
110 echo tasks and execute them.
111 </p>
112<blockquote><pre>
113&lt;project name=&quot;squares&quot; default=&quot;main&quot; basedir=&quot;.&quot;&gt;
114
115 &lt;target name=&quot;main&quot;&gt;
116
117 &lt;script language=&quot;javascript&quot;&gt; &lt;![CDATA[
118
119 for (i=1; i&lt;=10; i++) {
120 echo = squares.createTask(&quot;echo&quot;);
121 echo.setMessage(i*i);
122 echo.perform();
123 }
124
125 ]]&gt; &lt;/script&gt;
126
127 &lt;/target&gt;
128
129&lt;/project&gt;
130</pre></blockquote>
131<p>generates</p>
132<blockquote><pre>
133main:
1341
1354
1369
13716
13825
13936
14049
14164
14281
143100
144
145BUILD SUCCESSFUL
146</pre></blockquote>
147<p>Another example, using <a href="../using.html#references">references by id</a>
148and two different scripting languages:</p>
149<blockquote><pre>
150&lt;project name=&quot;testscript&quot; default=&quot;main&quot;&gt;
151 &lt;target name=&quot;sub&quot;&gt;
152 &lt;echo id=&quot;theEcho&quot;/&gt;
153 &lt;/target&gt;
154
155 &lt;target name=&quot;sub1&quot;&gt;
156 &lt;script language=&quot;netrexx&quot;&gt;&lt;![CDATA[
157 theEcho.setMessage(&quot;In sub1&quot;)
158 sub.execute
159 ]]&gt;&lt;/script&gt;
160 &lt;/target&gt;
161
162 &lt;target name=&quot;sub2&quot;&gt;
163 &lt;script language=&quot;javascript&quot;&gt;&lt;![CDATA[
164 theEcho.setMessage(&quot;In sub2&quot;);
165 sub.execute();
166 ]]&gt;&lt;/script&gt;
167 &lt;/target&gt;
168
169 &lt;target name=&quot;main&quot; depends=&quot;sub1,sub2&quot;/&gt;
170&lt;/project&gt;
171</pre></blockquote>
172<p>generates</p>
173<blockquote><pre>
174sub1:
175In sub1
176
177sub2:
178In sub2
179
180main:
181
182BUILD SUCCESSFUL
183</pre></blockquote>
184
185<p>Now a more complex example using the Java API and the Ant API. The goal is to list the
186filesizes of all files a <code>&lt;fileset/&gt;</code> caught.</p>
187<blockquote><pre>
188
189&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
190&lt;project name="<font color=blue>MyProject</font>" basedir="." default="main"&gt;
191
192 &lt;property name="fs.dir" value="src"/&gt;
193 &lt;property name="fs.includes" value="**/*.txt"/&gt;
194 &lt;property name="fs.excludes" value="**/*.tmp"/&gt;
195
196 &lt;target name="main"&gt;
197 &lt;script language="javascript"&gt; &lt;![CDATA[
198
199 // import statements
200 <font color=blue>// importPackage(java.io)</font>;
201 <font color=blue>importClass(java.io.File)</font>;
202
203 // Access to Ant-Properties by their names
204 dir = <font color=blue>project</font>.getProperty("fs.dir");
205 includes = <font color=blue>MyProject</font>.getProperty("fs.includes");
206 excludes = <font color=blue>self.getProject()</font> .<font color=blue>getProperty("fs.excludes")</font>;
207
208 // Create a &lt;fileset dir="" includes=""/&gt;
209 fs = project.<font color=blue>createDataType("fileset")</font>;
210 fs.setDir( new File(dir) );
211 <font color=blue>fs.setIncludes(includes)</font>;
212 fs.setExcludes(excludes);
213
214 // Get the files (array) of that fileset
215 ds = fs.getDirectoryScanner(project);
216 srcFiles = ds.getIncludedFiles();
217
218 // iterate over that array
219 for (i=0; i&lt;srcFiles.length; i++) {
220
221 // get the values via Java API
222 var basedir = fs.getDir(project);
223 var filename = srcFiles[i];
224 var file = <font color=blue>new File(basedir, filename)</font>;
225 var size = file.length();
226
227 // create and use a Task via Ant API
228 echo = MyProject.<font color=blue>createTask("echo")</font>;
229 echo.setMessage(filename + ": " + size + " byte");
230 echo.<font color=blue>perform()</font>;
231 }
232 ]]&gt;&lt;/script&gt;
233 &lt;/target&gt;
234&lt;/project&gt;
235</pre></blockquote>
236<p>We want to use the Java API. Because we don't want always typing the package signature
237we do an import. Rhino knows two different methods for import statements: one for packages
238and one for a single class. By default only the <i>java</i> packages are available, so
239<i>java.lang.System</i> can be directly imported with <code>importClass/importPackage</code>.
240For other packages you have to prefix the full classified name with <i>Packages</i>.
241For example Ant's <i>FileUtils</i> class can be imported with
242<code>importClass(<b>Packages</b>.org.apache.tools.ant.util.FileUtils)</code>
243<br>
244The <code>&lt;script&gt;</code> task populates the Project instance under
245the name <i>project</i>, so we can use that reference. Another way is to use its given name
246or getting its reference from the task itself.<br>
247The Project provides methods for accessing and setting properties, creating DataTypes and
248Tasks and much more.<br>
249After creating a FileSet object we initialize that by calling its set-methods. Then we can
250use that object like a normal Ant task (<code>&lt;copy&gt;</code> for example).<br>
251For getting the size of a file we instantiate a <code>java.io.File</code>. So we are using
252normal Java API here.<br>
253Finally we use the <code>&lt;echo&gt;</code> task for producing the output. The task is not executed by
254its execute() method, because the perform() method (implemented in Task itself) does the
255appropriate logging before and after invoking execute().
256</p>
257
258
259<hr>
260<p align="center">Copyright &copy; 2000-2004 The Apache Software Foundation. All rights
261Reserved.</p>
262
263</body>
264</html>
Note: See TracBrowser for help on using the repository browser.