source: release-kits/lirk3/bin/ant-installer/web/manual/manual/CoreTasks/java.html@ 14982

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

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