1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
<!--
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>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
<title>Java Task</title>
</head>
<body>
<h2><a name="java">Java</a></h2>
<h3>Description</h3>
<p>Executes a Java class within the running (Apache Ant) VM or forks another VM if
specified.</p>
<p>
If odd things go wrong when you run this task, set fork="true" to use a new
JVM.
<p>As of Ant 1.6.3, you can interact with a forked VM, as well as
sending input to it via the <code>input</code> and <code>inputstring</code>
attributes.</p>
<h4><a name="background">Running Ant as a background process on
Unix(-like) systems</a></h4>
<p>If you run Ant as a background process (like <code>ant &</code>)
and use the <code><java></code> task with <code>spawn</code>
set to <code>false</code> and <code>fork</code>
to <code>true</code>, you must provide explicit input to the forked
process or Ant will be suspended because it tries to read from the
standard input.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">classname</td>
<td valign="top">the Java class to execute.</td>
<td align="center" valign="top">Either <tt>jar</tt> or <tt>classname</tt></td>
</tr>
<tr>
<td valign="top">jar</td>
<td valign="top">the location of the jar file to execute (must have a
Main-Class entry in the manifest). Fork must be set to true if this option is selected.
See notes below for more details.
</td>
<td align="center" valign="top">Either <tt>jar</tt> or <tt>classname</tt></td>
</tr>
<tr>
<td valign="top">args</td>
<td valign="top">the arguments for the class that is
executed. <b>deprecated, use nested <code><arg></code>
elements instead.</b></td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">classpath</td>
<td valign="top">the classpath to use.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">classpathref</td>
<td valign="top">the classpath to use, given as <a
href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">fork</td>
<td valign="top">if enabled triggers the class execution in another VM
(disabled by default)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">spawn</td>
<td valign="top">if enabled allows to start a process which will outlive ant.<br>
Requires fork=true, and not compatible
with timeout, input, output, error, result attributes.<br>
(disabled by default)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">jvm</td>
<td valign="top">the command used to invoke the Java Virtual Machine,
default is 'java'. The command is resolved by java.lang.Runtime.exec().
Ignored if fork is disabled.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">jvmargs</td>
<td valign="top">the arguments to pass to the forked VM (ignored
if fork is disabled). <b>deprecated, use nested
<code><jvmarg></code> elements instead.</b></td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">maxmemory</td>
<td valign="top">Max amount of memory to allocate to the forked VM
(ignored if fork is disabled)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">failonerror</td>
<td valign="top">Stop the buildprocess if the command exits with a
returncode other than 0. Default is "false" (see <a href="#failonerror">note</a>)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">resultproperty</td>
<td valign="top">The name of a property in which the return code of the
command should be stored. Only of interest if failonerror=false
and if fork=true.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">dir</td>
<td valign="top">The directory to invoke the VM in. (ignored if
fork is disabled)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">output</td>
<td valign="top">Name of a file to which to write the output. If the error stream
is not also redirected to a file or property, it will appear in this output.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">error</td>
<td valign="top">The file to which the standard error of the command should be
redirected. </td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">logError</td>
<td valign="top">This attribute is used when you wish to see error output in Ant's
log and you are redirecting output to a file/property. The error
output will not be included in the output file/property. If you
redirect error with the "error" or "errorProperty"
attributes, this will have no effect.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">append</td>
<td valign="top">Whether output and error files should be appended to or overwritten.
Defaults to false.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">outputproperty</td>
<td valign="top">The name of a property in which the output of the
command should be stored. Unless the error stream is redirected to a separate
file or stream, this property will include the error output.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">errorproperty</td>
<td valign="top">The name of a property in which the standard error of the
command should be stored.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">input</td>
<td valign="top">A file from which the executed command's standard input
is taken. This attribute is mutually exclusive with the
inputstring attribute</td>
<td align="center" valign="top">No; default is to take standard input from console
(unless <code>spawn="true"</code>)</td>
</tr>
<tr>
<td valign="top">inputstring</td>
<td valign="top">A string which serves as the input stream for the
executed command. This attribute is mutually exclusive with the
input attribute.</td>
<td align="center" valign="top">No; default is to take standard input from console
(unless <code>spawn="true"</code>)</td>
</tr>
<tr>
<td valign="top">newenvironment</td>
<td valign="top">Do not propagate old environment when new
environment variables are specified. Default is "false"
(ignored if fork is disabled).</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">timeout</td>
<td valign="top">Stop the command if it doesn't finish within the
specified time (given in milliseconds). <strong>It is highly
recommended to use this feature only if fork is enabled.</strong></td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">clonevm</td>
<td valign="top">If set to true, then all system properties
and the bootclasspath of the forked Java Virtual Machine will be
the same as those of the Java VM running Ant. Default is
"false" (ignored if fork is disabled).
<em>since Ant 1.7</em></td>
<td align="center" valign="top">No</td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>arg and jvmarg</h4>
<p>Use nested <code><arg></code> and <code><jvmarg></code>
elements to specify arguments for the Java class and the forked VM respectively.
See <a href="../using.html#arg">Command line arguments</a>.</p>
<h4>sysproperty</h4>
<p>Use nested <code><sysproperty></code>
elements to specify system properties required by the class.
These properties will be made available to the VM during the execution
of the class (either ANT's VM or the forked VM). The attributes
for this element are the same as for <a href="exec.html#env">environment
variables</a>.</p>
<h4>syspropertyset</h4>
<p>You can specify a set of properties to be used as system properties
with <a href="../Types/propertyset.html">syspropertyset</a>s.</p>
<p><em>since Ant 1.6</em>.</p>
<h4>classpath</h4>
<p><code>Java</code>'s <i>classpath</i> attribute is a <a
href="../using.html#path">PATH like structure</a> and can also be set via a nested
<i>classpath</i> element.</p>
<h4>bootclasspath</h4>
<p>The location of bootstrap class files can be specified using this
<a href="../using.html#path">PATH like structure</a> - will be ignored
if <i>fork</i> is not <code>true</code> or the target VM doesn't
support it (i.e. Java 1.1).</p>
<p><em>since Ant 1.6</em>.</p>
<h4>env</h4>
<p>It is possible to specify environment variables to pass to the
forked VM via nested <i>env</i> elements. See the description in the
section about <a href="exec.html#env">exec</a></p>
<p>Settings will be ignored if fork is disabled.</p>
<h4>permissions</h4>
<p>Security permissions can be revoked and granted during the execution of the
class via a nested <i>permissions</i> element. For more information please
see <a href="../Types/permissions.html">permissions</a></p>
<p>When the permission RuntimePermission exitVM has not been granted (or has
been revoked) the System.exit() call will be intercepted
and treated like indicated in <i>failonerror</i>.</p>
<p>Note:<br>
If you do not specify permissions,
a set of default permissions will be added to your Java invocation to make
sure that the ant run will continue or terminated as indicated by
<i>failonerror</i>. All permissions not granted per default will be
checked by whatever security manager was already in place. exitVM will be
disallowed.
</p>
<p>Settings will be ignored if fork is enabled.</p>
<p><em>since Ant 1.6</em>.</p>
<h4>assertions</h4>
<p>You can control enablement of Java 1.4 assertions with an
<a href="../Types/assertions.html"><tt><assertions></tt></a>
subelement.</p>
<p>Assertion statements are currently ignored in non-forked mode.</p>
<p><em>since Ant 1.6.</em></p>
<a name="redirector"><h4>redirector</h4></a>
<i><b>Since Ant 1.6.2</b></i>
<p>A nested <a href="../Types/redirector.html">I/O Redirector</a>
can be specified. In general, the attributes of the redirector behave
as the corresponding attributes available at the task level. The most
notable peculiarity stems from the retention of the <code><java></code>
attributes for backwards compatibility. Any file mapping is done
using a <CODE>null</CODE> sourcefile; therefore not all
<a href="../Types/mapper.html">Mapper</a> types will return
results. When no results are returned, redirection specifications
will fall back to the task level attributes. In practice this means that
defaults can be specified for input, output, and error output files.
</p>
<a name="failonerror"><h3>Errors and return codes</h3></a>
By default the return code of a <code><java></code> is ignored.
Alternatively, you can set <code>resultproperty</code> to the name
of a property and have it assigned to the result code (barring immutability,
of course).
When you set <code>failonerror="true"</code>, the only possible value for
<code>resultproperty</code> is 0. Any non-zero response is treated as an
error and would mean the build exits.
<p> Similarly, if <code>failonerror="false"</code> and <code>fork="false"</code>
, then <code><java></code> <b>must</b> return 0 otherwise the build will
exit, as the class was run by the build JVM.</p>
<h3>JAR file execution</h3>
<p>The parameter of the <tt>jar</tt> attribute is of type <tt>File</tt>;
that is, the parameter is resolved to an absolute file relative to the
base directory of the project, <i>not</i> the directory in which the Java
task is run. If you need to locate a JAR file relative to the directory
the task will be run in, you need to explicitly create the full path
to the JAR file.</p>
<p>When using the <tt>jar</tt> attribute, all classpath settings are
ignored according to <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/java.html">Oracle's
specification</a>.
<h3>Examples</h3>
<pre>
<java classname="test.Main">
<arg value="-h"/>
<classpath>
<pathelement location="dist/test.jar"/>
<pathelement path="${java.class.path}"/>
</classpath>
</java>
</pre>
Run a class in this JVM with a new jar on the classpath
<pre>
<java jar="dist/test.jar"
fork="true"
failonerror="true"
maxmemory="128m"
>
<arg value="-h"/>
<classpath>
<pathelement location="dist/test.jar"/>
<pathelement path="${java.class.path}"/>
</classpath>
</java>
</pre>
Run the JAR test.jar in this project's dist/lib directory.
using the manifest supplied entry point, forking (as required),
and with a maximum memory of 128MB. Any non zero return code breaks the build.
<pre>
<java
dir="${exec.dir}"
jar="${exec.dir}/dist/test.jar"
fork="true"
failonerror="true"
maxmemory="128m"
>
<arg value="-h"/>
<classpath>
<pathelement location="dist/test.jar"/>
<pathelement path="${java.class.path}"/>
</classpath>
</java>
</pre>
Run the JAR dist/test.jar relative to the directory
<tt>${exec.dir}</tt>, this being the same directory into which the JVM
is to start up.
<pre> <java classname="test.Main"/></pre>
Runs a given class with the current classpath.
<pre>
<java classname="test.Main"
fork="yes" >
<sysproperty key="DEBUG" value="true"/>
<arg value="-h"/>
<jvmarg value="-Xrunhprof:cpu=samples,file=log.txt,depth=3"/>
</java>
</pre>
Add system properties and JVM-properties to the JVM as in
<code>java ="-Xrunhprof:cpu=samples,file=log.txt,depth=3 -DDEBUG=true test.Main</code>
<pre> <java classname="ShowJavaVersion" classpath="."
jvm="path-to-java14-home/bin/java" fork="true"
taskname="java1.4" >
</pre>
Use a given Java implementation (another the one Ant is currently using) to run the class.
For documentation in the log <code>taskname</code> is used to change the <code>[java]</code>
log-prefix to <code>[java1.4]</code>.
<p><strong>Note</strong>: you can not specify the (highly deprecated) MSJVM, "jview.exe" as the
JVM, as it takes different parameters for other JVMs,
That JVM can be started from <code><exec></code> if required.</p>
</body>
</html>
|
