http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/filterchain.html ---------------------------------------------------------------------- diff --git a/manual/Types/filterchain.html b/manual/Types/filterchain.html index cf5b090..f5266e5 100644 --- a/manual/Types/filterchain.html +++ b/manual/Types/filterchain.html @@ -27,7 +27,7 @@ that contained the string <q>blee</q> from the first 10 lines of a text file <samp>foo</samp> (<em>you wouldn't want to filter a binary file</em>) to a file <samp>bar</samp>, you would do something like:</p> -<pre>cat foo|head -n10|grep blee > bar</pre> +<pre class="input">cat foo|head -n10|grep blee > bar</pre> <p>Apache Ant was not flexible enough. There was no way for the <code><copy></code> task to do something similar. If you wanted the <code><copy></code> task to get the first 10 lines, you would have had to create special attributes:</p> @@ -42,8 +42,8 @@ and plug them in.</p> <p>The solution was to refactor data transformation oriented tasks to support FilterChains. A FilterChain is a group of ordered FilterReaders. Users can define their own FilterReaders by just -extending the <code>java.io.FilterReader</code> class. Such custom FilterReaders can be easily -plugged in as nested elements of <code><filterchain></code> by +extending the <code class="code">java.io.FilterReader</code> class. Such custom FilterReaders can +be easily plugged in as nested elements of <code><filterchain></code> by using <code><filterreader></code> elements.</p> <p>Example:</p> <pre> @@ -119,8 +119,9 @@ elements are defined in the build file using this. Please note that built in fi also be defined using this syntax.</p> <p>A FilterReader element must be supplied with a class name as an attribute value. The class -resolved by this name must extend <code>java.io.FilterReader</code>. If the custom filter reader -needs to be parameterized, it must implement <code>org.apache.tools.type.Parameterizable</code>.</p> +resolved by this name must extend <code class="code">java.io.FilterReader</code>. If the custom +filter reader needs to be parameterized, it must +implement <code class="code">org.apache.tools.type.Parameterizable</code>.</p> <table class="attr"> <tr> @@ -206,8 +207,8 @@ is substituted with the property's actual value.</p> <h4>Example</h4> -<p>This results in the property <code>modifiedmessage</code> holding the value "All these -moments will be lost in time, like teardrops in the rain"</p> +<p>This results in the property <code>modifiedmessage</code> holding the value <q>All these moments +will be lost in time, like teardrops in the rain</q></p> <pre> <echo message="All these moments will be lost in time, like teardrops in the ${weather}" file="loadfile1.tmp"/> @@ -955,8 +956,8 @@ extracted)</p> <p><em>Since Ant 1.8.0</em></p> <p>The sort filter reads all lines and sorts them. The sort order can be reversed and it is -possible to specify a custom implementation of the <code>java.util.Comparator</code> interface -to get even more control.</p> +possible to specify a custom implementation of the <code class="code">java.util.Comparator</code> +interface to get even more control.</p> <table class="attr"> <tr> @@ -972,8 +973,8 @@ to get even more control.</p> </tr> <tr> <td>comparator</td> - <td>Class name of a class that implements <code>java.util.Comparator</code> for Strings. - This class will be used to determine the sort order of lines.</td> + <td>Class name of a class that implements <code class="code">java.util.Comparator</code> for + Strings. This class will be used to determine the sort order of lines.</td> <td>No</td> </tr> </table> @@ -1023,12 +1024,12 @@ them into <samp>build</samp> location. <p> Sort all files <samp>*.txt</samp> from <samp>src</samp> location using as sorting -criterium <code>EvenFirstCmp</code> class, that sorts the file lines putting even lines first -then odd lines for example. The modified files are copied into <samp>build</samp> -location. The <code>EvenFirstCmp</code>, has to an instanciable class -via <code>Class.newInstance()</code>, therefore in case of inner class has to -be <em>static</em>. It also has to implement <code>java.util.Comparator</code> interface, for -example: +criterium <code class="code">EvenFirstCmp</code> class, that sorts the file lines putting even lines +first then odd lines for example. The modified files are copied into <samp>build</samp> +location. The <code class="code">EvenFirstCmp</code> has to an instanciable class +via <code class="code">Class.newInstance()</code>, therefore in case of inner class has to +be <em>static</em>. It also has to implement <code class="code">java.util.Comparator</code> +interface, for example: </p> <pre> @@ -1166,9 +1167,9 @@ this on very large input.</p> </tokenfilter></pre> <h4 id="stringtokenizer">StringTokenizer</h4> -<p>This tokenizer is based on <code>java.util.StringTokenizer</code>. It splits up the input -into strings separated by white space, or by a specified list of delimiting characters. If the -stream starts with delimiter characters, the first token will be the empty string (unless +<p>This tokenizer is based on <code class="code">java.util.StringTokenizer</code>. It splits up the +input into strings separated by white space, or by a specified list of delimiting characters. If +the stream starts with delimiter characters, the first token will be the empty string (unless the <var>delimsaretokens</var> attribute is used).</p> <table class="attr"> @@ -1430,8 +1431,7 @@ the <a href="../Tasks/native2ascii.html">native2ascii</a> task.</p> </tr> <tr> <td>reverse</td> - <td>Reverse the sense of the conversion, - i.e. convert from ASCII to native.</td> + <td>Reverse the sense of the conversion, i.e. convert from ASCII to native.</td> <td>No</td> </tr> </table> @@ -1456,9 +1456,10 @@ See the <a href="../Tasks/script.html">Script</a> task for an explanation of scr dependencies. </p> <p> -The script is provided with an object <samp>self</samp> that has <code>getToken()</code> -and <code>setToken(String)</code> methods. The <code>getToken()</code> method returns the current -token. The <code>setToken(String)</code> method replaces the current token. +The script is provided with an object <samp class="code">self</samp> that +has <code class="code">getToken()</code> and <code class="code">setToken(String)</code> methods. +The <code class="code">getToken()</code> method returns the current +token. The <code class="code">setToken(String)</code> method replaces the current token. </p> <p> This filter may be used directly within a <code>filterchain</code>. @@ -1538,8 +1539,8 @@ the <a href="../Tasks/script.html">script</a> task on how to use this element. <h4 id="custom">Custom tokenizers and string filters</h4> <p>Custom string filters and tokenizers may be plugged in by extending the -interfaces <code>org.apache.tools.ant.filters.TokenFilter.Filter</code> -and <code>org.apache.tools.ant.util.Tokenizer</code> respectly.</p> +interfaces <code class="code">org.apache.tools.ant.filters.TokenFilter.Filter</code> +and <code class="code">org.apache.tools.ant.util.Tokenizer</code> respectly.</p> <p>They are defined in the build file using <code><typedef/></code>. For example, a string filter that capitalizes words may be declared as:</p>
http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/mapper.html ---------------------------------------------------------------------- diff --git a/manual/Types/mapper.html b/manual/Types/mapper.html index a4e014b..bf8a10a 100644 --- a/manual/Types/mapper.html +++ b/manual/Types/mapper.html @@ -32,9 +32,10 @@ may want to specify the target files, either to help Apache Ant or to get an ext functionality.</p> <p>While source files are usually specified as <a href="fileset.html">fileset</a>s, you don't specify target files directly—instead, you tell Ant how to find the target file(s) for one -source file. An instance of <code>org.apache.tools.ant.util.FileNameMapper</code> is responsible for -this. It constructs target file names based on rules that can be parameterized with <var>from</var> -and <var>to</var> attributes—the exact meaning of which is implementation-dependent.</p> +source file. An instance of <code class="code">org.apache.tools.ant.util.FileNameMapper</code> is +responsible for this. It constructs target file names based on rules that can be parameterized +with <var>from</var> and <var>to</var> attributes—the exact meaning of which is +implementation-dependent.</p> <p>These instances are defined in <code><mapper></code> elements with the following attributes:</p> <table class="attr"> @@ -88,16 +89,16 @@ is, a <a href="../using.html#path">path</a>-like structure.</p> <p><em>Since Ant 1.7.0</em>, nested File Mappers can be supplied via either <code><mapper></code> elements or <a href="../Tasks/typedef.html"><code><typedef></code></a>'d implementations -of <code>org.apache.tools.ant.util.FileNameMapper</code>. If nested File Mappers are specified by -either means, the mapper will be implicitly configured as a <a href="#composite-mapper">composite -mapper</a>.</p> +of <code class="code">org.apache.tools.ant.util.FileNameMapper</code>. If nested File Mappers are +specified by either means, the mapper will be implicitly configured as +a <a href="#composite-mapper">composite mapper</a>.</p> <h3>The built-in mapper types</h3> <p>All built-in mappers are case-sensitive.</p> <p><em>Since Ant 1.7.0</em>, each of the built-in mapper implementation types is directly accessible using a specific tagname. This makes it possible for filename mappers to support attributes in -addition to the generally available <var>to</var> and <var>from</var>.<br/> The <code><mapper -type|classname="..."></code> usage form remains valid for reasons of backward -compatibility.</p> +addition to the generally available <var>to</var> and <var>from</var>.<br/> +The <code><mapper <var>type</var>|<var>classname</var>="..."></code> usage form +remains valid for reasons of backward compatibility.</p> <!-- --> <!-- Identity Mapper --> @@ -330,10 +331,10 @@ case).</p> <p>Note that you need to escape a dollar-sign (<q>$</q>) with another dollar-sign in Ant.</p> <p>The regexp mapper needs a supporting library and an implementation -of <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that hides the specifics of the -library. <em>Since Ant 1.8.0</em>, Java 1.4 or later is required, so the implementation based on -the <code>java.util.regex</code> package is always be available. You can still use the now retired -Jakarta ORO or Jakarta Regex instead if your provide the corresponding jar in +of <code class="code">org.apache.tools.ant.util.regexp.RegexpMatcher</code> that hides the specifics +of the library. <em>Since Ant 1.8.0</em>, Java 1.4 or later is required, so the implementation based +on the <code class="code">java.util.regex</code> package is always be available. You can still use +the now retired Jakarta ORO or Jakarta Regex instead if your provide the corresponding jar in your <code>CLASSPATH</code>.</p> <p>For information about using <a href="https://savannah.gnu.org/projects/gnu-regexp/"; @@ -344,17 +345,17 @@ target="_top">your mileage may vary</a> with different regexp engines.</p> <p>If you want to use one of the <a href="../install.html#librarydependencies">regular expression libraries</a> other than <code>java.util.regex</code> you need to also use the -corresponding <code>ant-[apache-oro, apache-regexp].jar</code> from the Ant release you are using. +corresponding <samp>ant-[apache-oro, apache-regexp].jar</samp> from the Ant release you are using. Make sure that both will be loaded from the same classpath, that is either put them into your <code>CLASSPATH</code>, <samp>ANT_HOME/lib</samp> directory or a nested <code><classpath></code> element of the mapper—you cannot -have <code>ant-[apache-oro, apache-regexp].jar</code> in <samp>ANT_HOME/lib</samp> and the library +have <samp>ant-[apache-oro, apache-regexp].jar</samp> in <samp>ANT_HOME/lib</samp> and the library in a nested <code><classpath></code>.</p> <p>Ant will choose the regular expression library based on the following algorithm:</p> <ul> <li>If the system property <code>ant.regexp.matcherimpl</code> has been set, it is taken as the name -of the class implementing <code>org.apache.tools.ant.util.regexp.RegexpMatcher</code> that should be -used.</li> +of the class implementing <code class="code">org.apache.tools.ant.util.regexp.RegexpMatcher</code> +that should be used.</li> <li>If it has not been set, uses the JDK 1.4 classes.</li> </ul> @@ -590,7 +591,7 @@ mappers; prior to Ant 1.8.0 the order has been undefined.</p> <td><code>foo.bar.A</code></td> </tr> </table> -<p>The composite mapper has no corresponding <code><mapper <var>type</var>></code> +<p>The composite mapper has no corresponding <code><mapper></code> <var>type</var> attribute.</p> <!-- --> @@ -633,7 +634,7 @@ operation. The <var>to</var> and <var>from</var> attributes are ignored.</p> <td><code>new/path/B.java2</code></td> </tr> </table> -<p>The chained mapper has no corresponding <code><mapper <var>type</var>></code> +<p>The chained mapper has no corresponding <code><mapper></code> <var>type</var> attribute.</p> <!-- --> @@ -678,9 +679,7 @@ file name.</p> </tr> </table> - <p>The filtermapper has no corresponding - <code><mapper <var>type</var>></code> attribute. - </p> +<p>The filtermapper has no corresponding <code><mapper></code> <var>type</var> attribute.</p> <!-- --> <!-- Script Mapper --> @@ -742,8 +741,7 @@ dependencies.</p> </tr> </table> <p>This filename mapper can take a nested <classpath> element. See -the <a href="../Tasks/script.html">script</a> task on how to use this element. -</p> +the <a href="../Tasks/script.html">script</a> task on how to use this element.</p> <h5>Example</h5> <pre> @@ -793,7 +791,7 @@ every source file, with the list of mapped names reset after every invocation.</ </tr> </table> -<p>The scriptmapper has no corresponding <code><mapper <var>type</var>></code> attribute.</p> +<p>The scriptmapper has no corresponding <code><mapper></code> <var>type</var> attribute.</p> <h4 id="firstmatch-mapper">firstmatchmapper</h4> <p><em>Since Ant 1.8.0</em></p> @@ -822,7 +820,7 @@ collects the results of all matching children.</p> </tr> </table> -<p>The firstmatchmapper has no corresponding <code><mapper <var>type</var>></code> +<p>The firstmatchmapper has no corresponding <code><mapper></code> <var>type</var> attribute.</p> <h4 id="cutdirs-mapper">cutdirsmapper</h4> @@ -843,7 +841,7 @@ attribute.</p> </tr> </table> -<p>The cutdirsmapper has no corresponding <code><mapper <var>type</var>></code> attribute.</p> +<p>The cutdirsmapper has no corresponding <code><mapper></code> <var>type</var> attribute.</p> <table class="attr"> <tr> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/namespace.html ---------------------------------------------------------------------- diff --git a/manual/Types/namespace.html b/manual/Types/namespace.html index d6711be..a9ece1c 100644 --- a/manual/Types/namespace.html +++ b/manual/Types/namespace.html @@ -184,17 +184,17 @@ <h3>Mixing Elements from Different Namespaces</h3> <p> - Now comes the difficult part: elements from different namespaces can be woven together - under certain circumstances. This has a lot to do with the Ant - 1.6 <a href="../develop.html#nestedtype">add type introspection rules</a>: Ant types and - tasks are now free to accept arbitrary named types as nested elements, as long as the - concrete type implements the interface expected by the task/type. The most obvious example - for this is the <code><condition></code> task, which supports various nested - conditions, all of which extend the interface <code>Condition</code>. To integrate a - custom condition in Ant, you can now simply <code><typedef></code> the condition, - and then use it anywhere nested conditions are allowed (assuming the containing element - has a generic <code>add(Condition)</code> or <code>addConfigured(Condition)</code> - method): + Now comes the difficult part: elements from different namespaces can be woven together under + certain circumstances. This has a lot to do with the Ant + 1.6 <a href="../develop.html#nestedtype">add type introspection rules</a>: Ant types and tasks + are now free to accept arbitrary named types as nested elements, as long as the concrete type + implements the interface expected by the task/type. The most obvious example for this is + the <code><condition></code> task, which supports various nested conditions, all of + which extend the interface <code class="code">Condition</code>. To integrate a custom + condition in Ant, you can now simply <code><typedef></code> the condition, and then use + it anywhere nested conditions are allowed (assuming the containing element has a + generic <code class="code">add(Condition)</code> + or <code class="code">addConfigured(Condition)</code> method): </p> <pre> <typedef resource="org/example/conditions.properties" uri="<a href="http://example.org/conditions";>http://example.org/conditions</a>"/> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/permissions.html ---------------------------------------------------------------------- diff --git a/manual/Types/permissions.html b/manual/Types/permissions.html index 1032d37..4986f3f 100644 --- a/manual/Types/permissions.html +++ b/manual/Types/permissions.html @@ -134,9 +134,9 @@ are revoked. If the <var>actions</var> are left empty all actions match, and ar <grant class="java.util.PropertyPermission" name="user.home" action="read,write"/> </permissions> </pre> -<p>Grants the base set of permissions with the addition of a <code>SocketPermission</code> to -connect to <samp>foo.bar.com</samp> and the permission to read and write -the <code>user.home</code> system property.</p> +<p>Grants the base set of permissions with the addition of +a <code class="code">SocketPermission</code> to connect to <samp>foo.bar.com</samp> and the +permission to read and write the <code>user.home</code> system property.</p> </body> </html> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/regexp.html ---------------------------------------------------------------------- diff --git a/manual/Types/regexp.html b/manual/Types/regexp.html index 48d3870..88bd69b 100644 --- a/manual/Types/regexp.html +++ b/manual/Types/regexp.html @@ -57,12 +57,12 @@ dependencies</a> concerning the supporting libraries.</p> <p>The property <code>ant.regexp.regexpimpl</code> governs which regular expression implementation will be chosen. Possible values for this property are:</p> <ul> -<li><code>org.apache.tools.ant.util.regexp.Jdk14RegexpRegexp</code></li> -<li><code>org.apache.tools.ant.util.regexp.JakartaOroRegexp</code></li> -<li><code>org.apache.tools.ant.util.regexp.JakartaRegexpRegexp</code></li> +<li><code class="code">org.apache.tools.ant.util.regexp.Jdk14RegexpRegexp</code></li> +<li><code class="code">org.apache.tools.ant.util.regexp.JakartaOroRegexp</code></li> +<li><code class="code">org.apache.tools.ant.util.regexp.JakartaRegexpRegexp</code></li> </ul> <p>It can also be another implementation of the -interface <code>org.apache.tools.ant.util.regexp.Regexp</code>. +interface <code class="code">org.apache.tools.ant.util.regexp.Regexp</code>. If <code>ant.regexp.regexpimpl</code> is not defined, Ant uses Jdk14Regexp as this is always available.</p> <p> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/resources.html ---------------------------------------------------------------------- diff --git a/manual/Types/resources.html b/manual/Types/resources.html index 62277cc..f78d6ce 100644 --- a/manual/Types/resources.html +++ b/manual/Types/resources.html @@ -1015,11 +1015,11 @@ collection.</p> <p>A single resource collection is required.</p> <h4 id="tokens">tokens</h4> -<p>Includes the <a href="#string">string</a> tokens gathered from a nested resource -collection. Uses the same tokenizers supported by +<p>Includes the <a href="#string">string</a> tokens gathered from a nested resource collection. Uses +the same tokenizers supported by the <a href="filterchain.html#tokenfilter">TokenFilter</a>. Imaginative use of this resource -collection can implement equivalents for such Unix functions as <code>sort</code>, <code>grep --c</code>, <code>wc</code> and <code>wc -l</code>.</p> +collection can implement equivalents for such Unix functions as <kbd>sort</kbd>, <kbd>grep +-c</kbd>, <kbd>wc</kbd> and <kbd>wc -l</kbd>.</p> <table class="attr"> <tr> <th>Attribute</th> @@ -1056,7 +1056,7 @@ collection can implement equivalents for such Unix functions as <code>sort</code </sort> </union> </concat></pre> -<p>Implements Unix <code>sort -u</code> against resource collection <q>input</q>.</p> +<p>Implements Unix <kbd>sort -u</kbd> against resource collection <q>input</q>.</p> <h4 id="setlogic">Set operations</h4> <p>The following resource collections implement set operations:</p> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/selectors-program.html ---------------------------------------------------------------------- diff --git a/manual/Types/selectors-program.html b/manual/Types/selectors-program.html index 6f415ed..55c3c9a 100644 --- a/manual/Types/selectors-program.html +++ b/manual/Types/selectors-program.html @@ -45,15 +45,15 @@ example.</p> <p>To create a new Custom Selector, you have to create a class that - implements <code>org.apache.tools.ant.types.selectors.ExtendFileSelector</code>. The - easiest way to do that is through the convenience base - class <code>org.apache.tools.ant.types.selectors.BaseExtendSelector</code>, which - provides all of the methods for supporting <code><param></code> tags. First, - override the <code>isSelected()</code> method, and optionally - the <code>verifySettings()</code> method. If your custom selector requires parameters to - be set, you can also override the <code>setParameters()</code> method and interpret the - parameters that are passed in any way you like. Several of the core selectors - demonstrate how to do that because they can also be used as custom selectors.</p> + implements <code class="code">org.apache.tools.ant.types.selectors.ExtendFileSelector</code>. + The easiest way to do that is through the convenience base + class <code class="code">org.apache.tools.ant.types.selectors.BaseExtendSelector</code>, + which provides all of the methods for supporting <code><param></code> tags. First, + override the <code class="code">isSelected()</code> method, and optionally + the <code class="code">verifySettings()</code> method. If your custom selector requires + parameters to be set, you can also override the <code class="code">setParameters()</code> + method and interpret the parameters that are passed in any way you like. Several of the core + selectors demonstrate how to do that because they can also be used as custom selectors.</p> <li>Core Selectors @@ -62,37 +62,40 @@ <ul> <li><p>First, create a class that - implements <code>org.apache.tools.ant.types.selectors.FileSelector</code>. You can - either choose to implement all methods yourself from scratch, or you can - extend <code>org.apache.tools.ant.types.selectors.BaseSelector</code> instead, a - convenience class that provides reasonable default behaviour for many methods.</p> - - <p>There is only one method required. <code>public boolean isSelected(File basedir, - String filename, File file)</code> is the real purpose of the whole exercise. It - returns <q>true</q> or <q>false</q> depending on whether the given file should be - selected from the list or not.</p> - - <p>If you are using <code>org.apache.tools.ant.types.selectors.BaseSelector</code> - there are also some predefined behaviours you can take advantage of. Any time you - encounter a problem when setting attributes or adding tags, you can - call <code>setError(String errmsg)</code> and the class will know that there is a - problem. Then, at the top of your <code>isSelected()</code> method - call <code>validate()</code> and a BuildException will be thrown with the contents - of your error message. The <code>validate()</code> method also gives you a last - chance to check your settings for consistency because it - calls <code>verifySettings()</code>. Override this method and - call <code>setError()</code> within it if you detect any problems in how your - selector is set up.</p> - - <p>You may also want to override <code>toString()</code>.</p></li> - - <li>Put an <code>add</code> method for your selector - in <code>org.apache.tools.ant.types.selectors.SelectorContainer</code>. This is an - interface, so you will also have to add an implementation for the method in the - classes which implement it, - namely <code>org.apache.tools.ant.types.AbstractFileSet</code>, <code>org.apache.tools.ant.taskdefs.MatchingTask</code> - and <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>. Once - it is in there, it will be available everywhere that core selectors are + implements <code class="code">org.apache.tools.ant.types.selectors.FileSelector</code>. + You can either choose to implement all methods yourself from scratch, or you can + extend <code class="code">org.apache.tools.ant.types.selectors.BaseSelector</code> + instead, a convenience class that provides reasonable default behaviour for many + methods.</p> + + <p>There is only one method required. <code class="code">public boolean isSelected(File + basedir, String filename, File file)</code> is the real purpose of the whole + exercise. It returns <q>true</q> or <q>false</q> depending on whether the given file + should be selected from the list or not.</p> + + <p>If you are + using <code class="code">org.apache.tools.ant.types.selectors.BaseSelector</code> there + are also some predefined behaviours you can take advantage of. Any time you encounter a + problem when setting attributes or adding tags, you can + call <code class="code">setError(String errmsg)</code> and the class will know that + there is a problem. Then, at the top of your <code class="code">isSelected()</code> + method call <code class="code">validate()</code> and a <code>BuildException</code> will + be thrown with the contents of your error + message. The <code class="code">validate()</code> method also gives you a last chance to + check your settings for consistency because it + calls <code class="code">verifySettings()</code>. Override this method and + call <code class="code">setError()</code> within it if you detect any problems in how + your selector is set up.</p> + + <p>You may also want to override <code class="code">toString()</code>.</p></li> + + <li>Put an <code class="code">add()</code> method for your selector + in <code class="code">org.apache.tools.ant.types.selectors.SelectorContainer</code>. + This is an interface, so you will also have to add an implementation for the method in + the classes which implement it, + namely <code class="code">org.apache.tools.ant.types.AbstractFileSet</code>, <code class="code">org.apache.tools.ant.taskdefs.MatchingTask</code> + and <code class="code">org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>. + Once it is in there, it will be available everywhere that core selectors are appropriate.</li> </ul> @@ -100,18 +103,18 @@ <p>Got an idea for a new Selector Container? Creating a new one is no problem:</p> <ul> <li>Create a new class that - implements <code>org.apache.tools.ant.types.selectors.SelectorContainer</code>. + implements <code class="code">org.apache.tools.ant.types.selectors.SelectorContainer</code>. This will ensure that your new Container can access any new selectors that come along. Again, there is a convenience class available for you - called <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>.</li> - <li>Implement the <code>public boolean isSelected(String filename, File file)</code> - method to do the right thing. Chances are you'll want to iterate over the selectors - under you, so use <code>selectorElements()</code> to get an iterator that will do - that.</li> - <li>Again, put an <code>add</code> method for your container - in <code>org.apache.tools.ant.types.selectors.SelectorContainer</code> and its - implementations <code>org.apache.tools.ant.types.AbstractFileSet</code> - and <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>.</li> + called <code class="code">org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>.</li> + <li>Implement the <code class="code">public boolean isSelected(String filename, File + file)</code> method to do the right thing. Chances are you'll want to iterate over the + selectors under you, so use <code class="code">selectorElements()</code> to get an + iterator that will do that.</li> + <li>Again, put an <code class="code">add()</code> method for your container + in <code class="code">org.apache.tools.ant.types.selectors.SelectorContainer</code> and + its implementations <code class="code">org.apache.tools.ant.types.AbstractFileSet</code> + and <code class="code">org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>.</li> </ul> </ol> @@ -119,16 +122,16 @@ <p>For a robust component (and selectors are (Project)Components) tests are necessary. For testing Tasks we use JUnit Tests and Rules—more - specific <code>org.apache.tools.ant.BuildFileRule extends - org.junit.rules.ExternalResource</code>. Some of its features like configure the (test) - project by reading its buildfile and execute targets we need for selector tests - also. Therefore we use that BuildFileRule. But testing selectors requires some more work: - having a set of files, instantiate and configure the selector, check the selection work and - more. Because we usually extend <code>BaseExtendSelector</code> its features have to be - tested also (e.g. <code>setError()</code>).</p> + specific <code class="code">org.apache.tools.ant.BuildFileRule extends + org.junit.rules.ExternalResource</code>. Some of its features like configure the (test) project + by reading its buildfile and execute targets we need for selector tests also. Therefore we use + that BuildFileRule. But testing selectors requires some more work: having a set of files, + instantiate and configure the selector, check the selection work and more. Because we usually + extend <code class="code">BaseExtendSelector</code> its features have to be tested also + (e.g. <code class="code">setError()</code>).</p> <p>That's why we have a test rule for doing our selector - tests: <code>org.apache.tools.ant.types.selectors.BaseSelectorRule</code>.</p> + tests: <code class="code">org.apache.tools.ant.types.selectors.BaseSelectorRule</code>.</p> <p>This class extends ExternalResource and therefore can included in the set of Ant's unit tests. It holds an instance of preconfigured BuildFileRule. Configuration is done by parsing @@ -180,32 +183,32 @@ public class MySelectorTest { [junit] at junit.framework.Assert.assertEquals(Assert.java:81) [junit] at org.apache.tools.ant.types.selectors.BaseSelectorTest.performTest(BaseSelectorTest.java:194)</pre> - <p>Described above the test class should provide a <code>getInstance()</code> method. But - that isn't used here. The used <code>getSelector()</code> method is implemented in the base - class and gives an instance of an Ant Project to the selector. This is usually done inside - normal build file runs, but not inside this special environment, so this method gives the - selector the ability to use its own Project object (<code>getProject()</code>), for example - for logging.</p> + <p>Described above the test class should provide a <code class="code">getInstance()</code> + method. But that isn't used here. The used <code class="code">getSelector()</code> method is + implemented in the base class and gives an instance of an Ant Project to the selector. This is + usually done inside normal build file runs, but not inside this special environment, so this + method gives the selector the ability to use its own Project object + (<code class="code">getProject()</code>), for example for logging.</p> <h3>Logging</h3> - <p>During development and maybe later you sometimes need the output of information. - Therefore Logging is needed. Because the selector extends BaseExtendSelector or directly - BaseSelector it is an Ant <code>DataType</code> and therefore - a <code>ProjectComponent</code>.<br/> That means that you have access to the project object - and its logging capability. <code>ProjectComponent</code> itself - provides <code>log()</code> methods which will do the access to the project + <p>During development and maybe later you sometimes need the output of information. Therefore + Logging is needed. Because the selector extends BaseExtendSelector or directly BaseSelector it + is an Ant <code class="code">DataType</code> and therefore + a <code class="code">ProjectComponent</code>.<br/> That means that you have access to the + project object and its logging capability. <code class="code">ProjectComponent</code> itself + provides <code class="code">log()</code> methods which will do the access to the project instance. Logging is therefore done simply with:</p> <pre>log("message");</pre> <p>or</p> <pre>log("message", loglevel);</pre> <p>where the <code>loglevel</code> is one of the values</p> <ul> - <li><code>org.apache.tools.ant.Project.MSG_ERR</code></li> - <li><code>org.apache.tools.ant.Project.MSG_WARN</code></li> - <li><code>org.apache.tools.ant.Project.MSG_INFO</code> (default)</li> - <li><code>org.apache.tools.ant.Project.MSG_VERBOSE</code></li> - <li><code>org.apache.tools.ant.Project.MSG_DEBUG</code></li> + <li><code class="code">org.apache.tools.ant.Project.MSG_ERR</code></li> + <li><code class="code">org.apache.tools.ant.Project.MSG_WARN</code></li> + <li><code class="code">org.apache.tools.ant.Project.MSG_INFO</code> (default)</li> + <li><code class="code">org.apache.tools.ant.Project.MSG_VERBOSE</code></li> + <li><code class="code">org.apache.tools.ant.Project.MSG_DEBUG</code></li> </ul> </body> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/selectors.html ---------------------------------------------------------------------- diff --git a/manual/Types/selectors.html b/manual/Types/selectors.html index 2c59d59..f8a2631 100644 --- a/manual/Types/selectors.html +++ b/manual/Types/selectors.html @@ -34,10 +34,10 @@ any target by using the <code><selector></code> tag and then using it as a reference.</p> <p>Different selectors have different attributes. Some selectors can contain other selectors, - and these are called <a href="#selectcontainers"><code>Selector Containers</code></a>. There is - also a category of selectors that allow user-defined extensions, - called <a href="#customselect"><code>Custom Selectors</code></a>. The ones built in to Apache - Ant are called <a href="#coreselect"><code>Core Selectors</code></a>.</p> + and these are called <a href="#selectcontainers"><q>Selector Containers</q></a>. There is also + a category of selectors that allow user-defined extensions, + called <a href="#customselect"><q>Custom Selectors</q></a>. The ones built in to Apache Ant are + called <a href="#coreselect"><q>Core Selectors</q></a>.</p> <h3 id="coreselect">Core Selectors</h3> @@ -877,36 +877,36 @@ <h4 id="readable">Readable Selector</h4> <p>The <code><readable></code> selector selects only files that are readable. Ant only - invokes <code>java.io.File#canRead</code> so if a file is unreadable but JVM cannot detect this - state, this selector will still select the file.</p> + invokes <code class="code">java.io.File#canRead</code> so if a file is unreadable but JVM cannot + detect this state, this selector will still select the file.</p> <h4 id="writable">Writable Selector</h4> <p>The <code><writable></code> selector selects only files that are writable. Ant only - invokes <code>java.io.File#canWrite</code> so if a file is nonwritable but JVM cannot detect - this state, this selector will still select the file.</p> + invokes <code class="code">java.io.File#canWrite</code> so if a file is nonwritable but JVM + cannot detect this state, this selector will still select the file.</p> <h4 id="executable">Executable Selector</h4> <p>The <code><executable></code> selector selects only files that are executable. Ant - only invokes <code>java.nio.file.Files#isExecutable</code> so if a file is not executable but - JVM cannot detect this state, this selector will still select the file.</p> + only invokes <code class="code">java.nio.file.Files#isExecutable</code> so if a file is not + executable but JVM cannot detect this state, this selector will still select the file.</p> <p><em>Since Ant 1.10.0</em></p> <h4 id="symlink">Symlink Selector</h4> <p>The <code><symlink></code> selector selects only files that are symbolic links. Ant - only invokes <code>java.nio.file.Files#isSymbolicLink</code> so if a file is a symbolic link but - JVM cannot detect this state, this selector will not select the file.</p> + only invokes <code class="code">java.nio.file.Files#isSymbolicLink</code> so if a file is a + symbolic link but JVM cannot detect this state, this selector will not select the file.</p> <p><em>Since Ant 1.10.0</em></p> <h4 id="ownedBy">OwnedBy Selector</h4> <p>The <code><ownedBy></code> selector selects only files that are owned by the given - user. Ant only invokes <code>java.nio.file.Files#getOwner</code> so if a file system doesn't - support the operation this selector will not select the file.</p> + user. Ant only invokes <code class="code">java.nio.file.Files#getOwner</code> so if a file + system doesn't support the operation this selector will not select the file.</p> <p><em>Since Ant 1.10.0</em></p> @@ -1312,9 +1312,9 @@ <p>First, you have to write your selector class in Java. The only requirement it must meet in order to be a selector is that it implements - the <code>org.apache.tools.ant.types.selectors.FileSelector</code> interface, which contains a - single method. See <a href="selectors-program.html">Programming Selectors in Ant</a> for more - information.</p> + the <code class="code">org.apache.tools.ant.types.selectors.FileSelector</code> interface, which + contains a single method. See <a href="selectors-program.html">Programming Selectors in Ant</a> + for more information.</p> <p>Once that is written, you include it in your build file by using the <code><custom></code> tag.</p> @@ -1328,7 +1328,7 @@ <tr> <td>classname</td> <td>The name of your class that - implements <code>org.apache.tools.ant.types.selectors.FileSelector</code>. + implements <code class="code">org.apache.tools.ant.types.selectors.FileSelector</code>. </td> <td>Yes</td> </tr> @@ -1362,15 +1362,15 @@ <ul> <li><a href="#containsselect">Contains Selector</a> with - classname <code>org.apache.tools.ant.types.selectors.ContainsSelector</code> + classname <code class="code">org.apache.tools.ant.types.selectors.ContainsSelector</code> <li><a href="#dateselect">Date Selector</a> with - classname <code>org.apache.tools.ant.types.selectors.DateSelector</code> + classname <code class="code">org.apache.tools.ant.types.selectors.DateSelector</code> <li><a href="#depthselect">Depth Selector</a> with - classname <code>org.apache.tools.ant.types.selectors.DepthSelector</code> + classname <code class="code">org.apache.tools.ant.types.selectors.DepthSelector</code> <li><a href="#filenameselect">Filename Selector</a> with - classname <code>org.apache.tools.ant.types.selectors.FilenameSelector</code> + classname <code class="code">org.apache.tools.ant.types.selectors.FilenameSelector</code> <li><a href="#sizeselect">Size Selector</a> with - classname <code>org.apache.tools.ant.types.selectors.SizeSelector</code> + classname <code class="code">org.apache.tools.ant.types.selectors.SizeSelector</code> </ul> <p>Here is the example from the Depth Selector section rewritten to use the selector http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/Types/xmlcatalog.html ---------------------------------------------------------------------- diff --git a/manual/Types/xmlcatalog.html b/manual/Types/xmlcatalog.html index 371ec07..edc27fa 100644 --- a/manual/Types/xmlcatalog.html +++ b/manual/Types/xmlcatalog.html @@ -38,8 +38,9 @@ Dependencies</a> for more information.</p> <p>This data type provides a catalog of resource locations based on the <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html"; target="_top">OASIS XML Catalog standard</a>. The catalog entries are used both for Entity -resolution and URI resolution, in accordance with the <code>org.xml.sax.EntityResolver</code> -and <code>javax.xml.transform.URIResolver</code> interfaces as defined in +resolution and URI resolution, in accordance with +the <code class="code">org.xml.sax.EntityResolver</code> +and <code class="code">javax.xml.transform.URIResolver</code> interfaces as defined in the <a href="https://download.oracle.com/otn-pub/jcp/jaxp-1_6-mrel3-spec/JAXP1_6-FinalSpec.pdf"; target="_top">Java API for XML Processing (JAXP) Specification</a>.</p> <p>For example, in a <code>web.xml</code> file, the DTD is referenced as:</p> @@ -193,21 +194,18 @@ warning will be logged.</p> <p>Set up an XMLCatalog with a single DTD referenced locally in a user's home directory:</p> <pre> <xmlcatalog> - <dtd - publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" - location="/home/dion/downloads/docbook/docbookx.dtd"/> + <dtd publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" + location="/home/dion/downloads/docbook/docbookx.dtd"/> </xmlcatalog></pre> <p>Set up an XMLCatalog with a multiple DTDs to be found either in the filesystem (relative to the Ant project <var>basedir</var>) or in the classpath: </p> <pre> <xmlcatalog id="commonDTDs"> - <dtd - publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" - location="docbook/docbookx.dtd"/> - <dtd - publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" - location="web-app_2_2.dtd"/> + <dtd publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" + location="docbook/docbookx.dtd"/> + <dtd publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" + location="web-app_2_2.dtd"/> </xmlcatalog></pre> <p>Set up an XMLCatalog with a combination of DTDs and entities as well as a nested XMLCatalog @@ -215,21 +213,17 @@ and external catalog files in both formats:</p> <pre> <xmlcatalog id="allcatalogs"> - <dtd - publicId="-//ArielPartners//DTD XML Article V1.0//EN" - location="com/arielpartners/knowledgebase/dtd/article.dtd"/> - <entity - publicId="LargeLogo" - location="com/arielpartners/images/ariel-logo-large.gif"/> + <dtd publicId="-//ArielPartners//DTD XML Article V1.0//EN" + location="com/arielpartners/knowledgebase/dtd/article.dtd"/> + <entity publicId="LargeLogo" + location="com/arielpartners/images/ariel-logo-large.gif"/> <xmlcatalog refid="commonDTDs"/> <catalogpath> <pathelement location="/etc/sgml/catalog"/> - <fileset - dir="/anetwork/drive" - includes="**/catalog"/> - <fileset - dir="/my/catalogs" - includes="**/catalog.xml"/> + <fileset dir="/anetwork/drive" + includes="**/catalog"/> + <fileset dir="/my/catalogs" + includes="**/catalog.xml"/> </catalogpath> </xmlcatalog> </xmlcatalog></pre> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/argumentprocessor.html ---------------------------------------------------------------------- diff --git a/manual/argumentprocessor.html b/manual/argumentprocessor.html index 848ffe8..0d8c2c2 100644 --- a/manual/argumentprocessor.html +++ b/manual/argumentprocessor.html @@ -28,48 +28,42 @@ <h2 id="definition">What is an ArgumentProcessor?</h2> <p> -An <code>ArgumentProcessor</code> is a parser of command line argument which is -then call before and after the build file is being parsed. Third party -libraries may then be able to have custom argument line argument which modify -Ant behaviour. +An <code class="code">ArgumentProcessor</code> is a parser of command line argument which is then +call before and after the build file is being parsed. Third party libraries may then be able to have +custom argument line argument which modify Ant behaviour. </p> <p> -An <code>ArgumentProcessor</code> is called each time Ant parse an unknown -argument, an <code>ArgumentProcessor</code> doesn't take precedence over Ant to -parse already supported options. It is then recommended to third -party <code>ArgumentProcessor</code> implementation to chose specific 'enough' -argument name, avoiding for instance one letter arguments. +An <code class="code">ArgumentProcessor</code> is called each time Ant parse an unknown argument, +an <code class="code">ArgumentProcessor</code> doesn't take precedence over Ant to parse already +supported options. It is then recommended to third party <code class="code">ArgumentProcessor</code> +implementation to chose specific 'enough' argument name, avoiding for instance one letter arguments. </p> <p> -It is also called at the different phases so different behaviour can be -implemented. It is called just after every arguments are parsed, just -before the project is being configured (the build file being parsed), -and just after. Some of the methods to be implemented return a boolean: -if <q>true</q> is returned, Ant will terminate immediately, without -error. +It is also called at the different phases so different behaviour can be implemented. It is called +just after every arguments are parsed, just before the project is being configured (the build file +being parsed), and just after. Some of the methods to be implemented return a boolean: +if <q>true</q> is returned, Ant will terminate immediately, without error. </p> <p> -Being called during all these phases, an <code>ArgumentProcessor</code> -can just print some specific system properties and quit -(like <code>-diagnose</code>), or print some specific properties of a -project after being parsed and quit (like <code>-projectHelp</code>), -or just set some custom properties on the project and let it run. +Being called during all these phases, an <code class="code">ArgumentProcessor</code> can just print +some specific system properties and quit (like <kbd>-diagnose</kbd>), or print some specific +properties of a project after being parsed and quit (like <kbd>-projectHelp</kbd>), or just set some +custom properties on the project and let it run. </p> <h2 id="repository">How to register it's own ArgumentProcessor</h2> -<p>First, the <code>ArgumentProcessor</code> must be an implementation of -<code>org.apache.tools.ant.ArgumentProcessor</code>. +<p>First, the <code class="code">ArgumentProcessor</code> must be an implementation +of <code class="code">org.apache.tools.ant.ArgumentProcessor</code>. </p> <p>Then to declare it: create a -file <samp>META-INF/services/org.apache.tools.ant.ArgumentProcessor</samp> -which contains only one line the fully qualified name of the class of the -implementation. This file together with the implementation class need then to -be found in Ant's classpath. +file <samp>META-INF/services/org.apache.tools.ant.ArgumentProcessor</samp> which contains only one +line the fully qualified name of the class of the implementation. This file together with the +implementation class need then to be found in Ant's classpath. </p> </body> </html> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/cover.html ---------------------------------------------------------------------- diff --git a/manual/cover.html b/manual/cover.html index 8ba4d6f..bbadd5b 100644 --- a/manual/cover.html +++ b/manual/cover.html @@ -26,7 +26,7 @@ <h1 class="center"><img src="images/ant_logo_large.gif" width="190" height="120"></h1> <h1 class="center">Apache Ant™ 1.10.3 Manual</h1> <p>This is the manual for version 1.10.3 of <a href="https://ant.apache.org/"; target="_top">Apache Ant</a>. If your - version of Ant (as verified with <code>ant -version</code>) is older or newer than this version then this is not the + version of Ant (as verified with <kbd>ant -version</kbd>) is older or newer than this version then this is not the correct manual set. Please use the documentation appropriate to your current version. Also, if you are using a version older than the most recent release, we recommend an upgrade to fix bugs as well as provide new functionality.</p> http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/develop.html ---------------------------------------------------------------------- diff --git a/manual/develop.html b/manual/develop.html index 254e1f8..6806ced 100644 --- a/manual/develop.html +++ b/manual/develop.html @@ -28,25 +28,25 @@ <h2 id="writingowntask">Writing Your Own Task</h2> <p>It is very easy to write your own task:</p> <ol> - <li>Create a Java class that extends <code>org.apache.tools.ant.Task</code> + <li>Create a Java class that extends <code class="code">org.apache.tools.ant.Task</code> or <a href="base_task_classes.html">another class</a> that was designed to be extended.</li> <li id="footnote-1-back">For each attribute, write a <em>setter</em> method. The setter method must be a <code>public void</code> method that takes a single argument. The name of the method must begin with <code>set</code>, followed by the attribute name, with the first character of - the name in uppercase, and the rest in lowercase<a href="#footnote-1"><sup>*</sup></a>. That - is, to support an attribute named <code>file</code> you create a method <code>setFile</code>. - Depending on the type of the argument, Ant will perform some conversions for you, - see <a href="#set-magic">below</a>.</li> + the name in uppercase, and the rest in lowercase<a href="#footnote-1">*</a>. That + is, to support an attribute named <code>file</code> you create a + method <code class="code">setFile</code>. Depending on the type of the argument, Ant will + perform some conversions for you, see <a href="#set-magic">below</a>.</li> <li>If your task shall contain other tasks as nested elements (like <a href="Tasks/parallel.html"><code>parallel</code></a>), your class must implement the - interface <code>org.apache.tools.ant.TaskContainer</code>. If you do so, your task can not - support any other nested elements. See <a href="#taskcontainer">below</a>.</li> + interface <code class="code">org.apache.tools.ant.TaskContainer</code>. If you do so, your task + can not support any other nested elements. See <a href="#taskcontainer">below</a>.</li> <li>If the task should support character data (text nested between the start and end tags), write - a <code>public void addText(String)</code> method. Note that Ant does <strong>not</strong> - expand properties on the text it passes to the task.</li> + a <code class="code">public void addText(String)</code> method. Note that Ant + does <strong>not</strong> expand properties on the text it passes to the task.</li> <li>For each nested element, write a <em>create</em>, <em>add</em> or <em>addConfigured</em> method. A create method must be a <code>public</code> method that takes no arguments and returns @@ -57,7 +57,7 @@ (<code>addConfigured</code>), followed by the element name. For a more complete discussion see <a href="#nested-elements">below</a>.</li> - <li>Write a <code>public void execute</code> method, with no arguments, that throws + <li>Write a <code class="code">public void execute()</code> method, with no arguments, that throws a <code>BuildException</code>. This method implements the task itself.</li> </ol> @@ -68,13 +68,14 @@ one doesn't really matter to Ant, using all lower case is a good convention, tho <h3>The Life-cycle of a Task</h3> <ol> <li>The xml element that contains the tag corresponding to the task gets converted to - an <code>UnknownElement</code> at parse time. This <code>UnknownElement</code> gets placed in a - list within a target object, or recursively within another <code>UnknownElement</code>. + an <code class="code">UnknownElement</code> at parse time. + This <code class="code">UnknownElement</code> gets placed in a list within a target object, or + recursively within another <code class="code">UnknownElement</code>. </li> - <li>When the target is executed, each <code>UnknownElement</code> is invoked using - an <code>perform()</code> method. This instantiates the task. This means that tasks only gets - instantiated at run time. + <li>When the target is executed, each <code class="code">UnknownElement</code> is invoked using + an <code class="code">perform()</code> method. This instantiates the task. This means that tasks + only gets instantiated at run time. </li> <li>The task gets references to its project and location inside the buildfile via its @@ -86,29 +87,29 @@ one doesn't really matter to Ant, using all lower case is a good convention, tho <li>The task gets a reference to the target it belongs to via its inherited <code>target</code> variable.</li> - <li><code>init()</code> is called at run time.</li> + <li><code class="code">init()</code> is called at run time.</li> <li>All child elements of the XML element corresponding to this task are created via this - task's <code>createXXX()</code> methods or instantiated and added to this task via - its <code>addXXX()</code> methods, at run time. Child elements corresponding - to <code>addConfiguredXXX()</code> are created at this point but the - actual <code>addConfigured</code> method is not called.</li> + task's <code class="code">createXXX()</code> methods or instantiated and added to this task via + its <code class="code">addXXX()</code> methods, at run time. Child elements corresponding + to <code class="code">addConfiguredXXX()</code> are created at this point but the + actual <em>addConfigured</em> method is not called.</li> - <li>All attributes of this task get set via their corresponding <code>setXXX</code> methods, at - runtime.</li> + <li>All attributes of this task get set via their corresponding <code class="code">setXXX()</code> + methods, at runtime.</li> <li>The content character data sections inside the XML element corresponding to this task is added - to the task via its <code>addText</code> method, at runtime.</li> + to the task via its <code class="code">addText()</code> method, at runtime.</li> - <li>All attributes of all child elements get set via their corresponding <code>setXXX</code> - methods, at runtime.</li> + <li>All attributes of all child elements get set via their + corresponding <code class="code">setXXX()</code> methods, at runtime.</li> <li>If child elements of the XML element corresponding to this task have been created - for <code>addConfiguredXXX()</code> methods, those methods get invoked now.</li> + for <code class="code">addConfiguredXXX()</code> methods, those methods get invoked now.</li> - <li id="execute"><code>execute()</code> is called at runtime. If <q>target1</q> - and <q>target2</q> both depend on <q>target3</q>, then running <code>'ant target1 - target2'</code> will run all tasks in <q>target3</q> twice.</li> + <li id="execute"><code class="code">execute()</code> is called at runtime. If <q>target1</q> + and <q>target2</q> both depend on <q>target3</q>, then running <kbd>ant target1 target2</kbd> + will run all tasks in <q>target3</q> twice.</li> </ol> <h3 id="set-magic">Conversions Ant will perform for attributes</h3> @@ -120,93 +121,98 @@ string containing a single property reference. These will be assigned directly v matching type. Since it requires some beyond-the-basics intervention to enable this behavior, it may be a good idea to flag attributes intended to permit this usage paradigm.</p> -<p>The most common way to write an attribute setter is to use a <code>java.lang.String</code> -argument. In this case Ant will pass the literal value (after property expansion) to your task. -But there is more! If the argument of you setter method is</p> +<p>The most common way to write an attribute setter is to use +a <code class="code">java.lang.String</code> argument. In this case Ant will pass the literal value +(after property expansion) to your task. But there is more! If the argument of you setter method +is</p> <ul> - <li><code>boolean</code>, your method will be passed the value <code>true</code> if the value - specified in the build file is one of <code>true</code>, <code>yes</code>, or <code>on</code> - and <code>false</code> otherwise.</li> + <li><code>boolean</code>, your method will be passed the value <q>true</q> if the value specified + in the build file is one of <q>true</q>, <q>yes</q>, or <q>on</q> and <q>false</q> + otherwise.</li> - <li><code>char</code> or <code>java.lang.Character</code>, your method will be passed the first - character of the value specified in the build file.</li> + <li><code>char</code> or <code class="code">java.lang.Character</code>, your method will be passed + the first character of the value specified in the build file.</li> - <li>any other primitive type (<code>int</code>, <code>short</code> and so on), Ant will convert - the value of the attribute into this type, thus making sure that you'll never receive input that - is not a number for that attribute.</li> + <li>any other primitive type (<code class="code">int</code>, <code class="code">short</code> and + so on), Ant will convert the value of the attribute into this type, thus making sure that you'll + never receive input that is not a number for that attribute.</li> - <li><code>java.io.File</code>, Ant will first determine whether the value given in the build file - represents an absolute path name. If not, Ant will interpret the value as a path name relative - to the project's basedir.</li> + <li><code class="code">java.io.File</code>, Ant will first determine whether the value given in + the build file represents an absolute path name. If not, Ant will interpret the value as a path + name relative to the project's <var>basedir</var>.</li> - <li><code>org.apache.tools.ant.types.Resource</code>, Ant will resolve the string as - a <code>java.io.File</code> as above, then pass in as - a <code>org.apache.tools.ant.types.resources.FileResource</code>. <em>Since Ant 1.8</em></li> + <li><code class="code">org.apache.tools.ant.types.Resource</code>, Ant will resolve the string as + a <code class="code">java.io.File</code> as above, then pass in as + a <code class="code">org.apache.tools.ant.types.resources.FileResource</code>. <em>Since Ant + 1.8</em></li> - <li><code>org.apache.tools.ant.types.Path</code>, Ant will tokenize the value specified in the - build file, accepting <q>:</q> and <q>;</q> as path separators. Relative path names will be - interpreted as relative to the project's <var>basedir</var>.</li> + <li><code class="code">org.apache.tools.ant.types.Path</code>, Ant will tokenize the value + specified in the build file, accepting <q>:</q> and <q>;</q> as path separators. Relative path + names will be interpreted as relative to the project's <var>basedir</var>.</li> - <li><code>java.lang.Class</code>, Ant will interpret the value given in the build file as a Java - class name and load the named class from the system class loader.</li> + <li><code class="code">java.lang.Class</code>, Ant will interpret the value given in the build + file as a Java class name and load the named class from the system class loader.</li> - <li>any other type that has a constructor with a single <code>String</code> argument, Ant will use - this constructor to create a new instance from the value given in the build file.</li> + <li>any other type that has a constructor with a single <code class="code">String</code> argument, + Ant will use this constructor to create a new instance from the value given in the build + file.</li> - <li>A subclass of <code>org.apache.tools.ant.types.EnumeratedAttribute</code>, Ant will invoke - this classes <code>setValue</code> method. Use this if your task should support enumerated - attributes (attributes with values that must be part of a predefined set of values). - See <code>org/apache/tools/ant/taskdefs/FixCRLF.java</code> and the - inner <code>AddAsisRemove</code> class used in <code>setCr</code> for an example.</li> + <li>A subclass of <code class="code">org.apache.tools.ant.types.EnumeratedAttribute</code>, Ant + will invoke this class's <code class="code">setValue</code> method. Use this if your task + should support enumerated attributes (attributes with values that must be part of a predefined + set of values). See <code>org/apache/tools/ant/taskdefs/FixCRLF.java</code> and the + inner <code class="code">AddAsisRemove</code> class used in <code class="code">setCr</code> for + an example.</li> <li>A (Java 5) enumeration, Ant will call the setter with the enum constant matching the value - given in the build file. This is easier than using <code>EnumeratedAttribute</code> and can - result in cleaner code, but of course your task will not run on JDK 1.4 or earlier. Note that - any override of <code>toString()</code> in the enumeration is ignored; the build file must use - the declared name (see <code>Enum.getName()</code>). You may wish to use lowercase enum constant - names, in contrast to usual Java style, to look better in build files. <em>Since Ant - 1.7.0</em></li> + given in the build file. This is easier than using <code class="code">EnumeratedAttribute</code> + and can result in cleaner code, but of course your task will not run on JDK 1.4 or earlier. Note + that any override of <code class="code">toString()</code> in the enumeration is ignored; the + build file must use the declared name (see <code>Enum.getName()</code>). You may wish to use + lowercase enum constant names, in contrast to usual Java style, to look better in build + files. <em>Since Ant 1.7.0</em></li> </ul> <p>What happens if more than one setter method is present for a given attribute? A method taking -a <code>String</code> argument will always lose against the more specific methods. If there are -still more setters Ant could chose from, only one of them will be called, but we don't know which, -this depends on the implementation of your Java virtual machine.</p> +a <code class="code">String</code> argument will always lose against the more specific methods. If +there are still more setters Ant could chose from, only one of them will be called, but we don't +know which, this depends on the implementation of your Java virtual machine.</p> <h3 id="nested-elements">Supporting nested elements</h3> <p>Let's assume your task shall support nested elements with the name <code>inner</code>. First of all, you need a class that represents this nested element. Often you simply want to use one of -Ant's classes like <code>org.apache.tools.ant.types.FileSet</code> to support +Ant's classes like <code class="code">org.apache.tools.ant.types.FileSet</code> to support nested <code>fileset</code> elements.</p> <p>Attributes of the nested elements or nested child elements of them will be handled using the same -mechanism used for tasks (i.e. setter methods for attributes, addText for nested text and -create/add/addConfigured methods for child elements).</p> +mechanism used for tasks (i.e. <em>setter</em> methods for +attributes, <code class="code">addText()</code> for nested text +and <em>create</em>/<em>add</em>/<em>addConfigured</em> methods for child elements).</p> -<p>Now you have a class <code>NestedElement</code> that is supposed to be used for your +<p>Now you have a class <code class="code">NestedElement</code> that is supposed to be used for your nested <code><inner></code> elements, you have three options:</p> <ol> - <li><code>public NestedElement createInner()</code></li> - <li><code>public void addInner(NestedElement anInner)</code></li> - <li><code>public void addConfiguredInner(NestedElement anInner)</code></li> + <li><code class="code">public NestedElement createInner()</code></li> + <li><code class="code">public void addInner(NestedElement anInner)</code></li> + <li><code class="code">public void addConfiguredInner(NestedElement anInner)</code></li> </ol> <p>What is the difference?</p> -<p>Option 1 makes the task create the instance of <code>NestedElement</code>, there are no -restrictions on the type. For the options 2 and 3, Ant has to create an instance -of <code>NestedInner</code> before it can pass it to the task, this means, <code>NestedInner</code> -must have a <code>public</code> no-arg constructor or a <code>public</code> one-arg constructor -taking a <code>Project</code> class as a parameter. This is the only difference between options 1 -and 2.</p> +<p>Option 1 makes the task create the instance of <code class="code">NestedElement</code>, there are +no restrictions on the type. For the options 2 and 3, Ant has to create an instance +of <code class="code">NestedInner</code> before it can pass it to the task, this +means, <code class="code">NestedInner</code> must have a <code>public</code> no-arg constructor or +a <code>public</code> one-arg constructor taking a <code class="code">Project</code> class as a +parameter. This is the only difference between options 1 and 2.</p> <p>The difference between 2 and 3 is what Ant has done to the object before it passes it to the -method. <code>addInner</code> will receive an object directly after the constructor has been -called, while <code>addConfiguredInner</code> gets the object <em>after</em> the attributes and -nested children for this new object have been handled.</p> +method. <code class="code">addInner()</code> will receive an object directly after the constructor +has been called, while <code class="code">addConfiguredInner()</code> gets the object <em>after</em> +the attributes and nested children for this new object have been handled.</p> <p>What happens if you use more than one of the options? Only one of the methods will be called, but we don't know which, this depends on the implementation of your JVM.</p> @@ -215,12 +221,13 @@ but we don't know which, this depends on the implementation of your JVM.</p> <p>If your task needs to nest an arbitrary type that has been defined using <code><typedef></code> you have two options.</p> <ol> - <li><code>public void add(Type type)</code></li> - <li><code>public void addConfigured(Type type)</code></li> + <li><code class="code">public void add(Type type)</code></li> + <li><code class="code">public void addConfigured(Type type)</code></li> </ol> <p>The difference between 1 and 2 is the same as between 2 and 3 in the previous section.</p> <p>For example suppose one wanted to handle objects object of -type <code>org.apache.tools.ant.taskdefs.condition.Condition</code>, one may have a class:</p> +type <code class="code">org.apache.tools.ant.taskdefs.condition.Condition</code>, one may have a +class:</p> <pre> public class MyTask extends Task { private List conditions = new ArrayList(); @@ -270,8 +277,8 @@ public class Sample { } }</pre> <p>This class defines a number of static classes that -implement/extend <code>Path</code>, <code>MyFileSelector</code> and <code>MyInterface</code>. These -may be defined and used as follows:</p> +implement/extend <code class="code">Path</code>, <code class="code">MyFileSelector</code> +and <code class="code">MyInterface</code>. These may be defined and used as follows:</p> <pre> <typedef name="myfileselector" classname="Sample$MyFileSelector" classpath="classes" loaderref="classes"/> @@ -292,17 +299,19 @@ may be defined and used as follows:</p> <h3 id="taskcontainer">TaskContainer</h3> -<p>The <code>TaskContainer</code> consists of a single method, <code>addTask</code> that basically -is the same as an <a href="#nested-elements">add method</a> for nested elements. The task instances -will be configured (their attributes and nested elements have been handled) when your -task's <code>execute</code> method gets invoked, but not before that.</p> +<p>The <code class="code">TaskContainer</code> consists of a single +method, <code class="code">addTask</code> that basically is the same as +an <a href="#nested-elements">add method</a> for nested elements. The task instances will be +configured (their attributes and nested elements have been handled) when your +task's <code class="code">execute</code> method gets invoked, but not before that.</p> -<p>When we <a href="#execute">said</a> <code>execute</code> would be called, we lied ;-). In fact, -Ant will call the <code>perform</code> method in <code>org.apache.tools.ant.Task</code>, which in -turn calls <code>execute</code>. This method makes sure that <a href="#buildevents">Build +<p>When we <a href="#execute">said</a> <code class="code">execute</code> would be called, we lied +;-). In fact, Ant will call the <code class="code">perform</code> method +in <code class="code">org.apache.tools.ant.Task</code>, which in turn +calls <code class="code">execute</code>. This method makes sure that <a href="#buildevents">Build Events</a> will be triggered. If you execute the task instances nested into your task, you should -also invoke <code>perform</code> on these instances instead of -<code>execute</code>.</p> +also invoke <code class="code">perform</code> on these instances instead +of <code class="code">execute</code>.</p> <h3>Example</h3> <p>Let's write our own task, which prints a message on the <code>System.out</code> stream. The task @@ -378,17 +387,19 @@ just been compiled.</p> </project></pre> <p>Another way to add a task (more permanently) is to add the task name and implementing class name -to the <samp>default.properties</samp> file in the <code>org.apache.tools.ant.taskdefs</code> -package. Then you can use it as if it were a built-in task.</p> +to the <samp>default.properties</samp> file in +the <code class="code">org.apache.tools.ant.taskdefs</code> package. Then you can use it as if it +were a built-in task.</p> <hr/> <h2 id="buildevents">Build Events</h2> <p>Ant is capable of generating build events as it performs the tasks necessary to build a project. Listeners can be attached to Ant to receive these events. This capability could be used, for example, to connect Ant to a GUI or to integrate Ant with an IDE.</p> -<p>To use build events you need to create an ant <code>Project</code> object. You can then call -the <code>addBuildListener</code> method to add your listener to the project. Your listener must -implement the <code>org.apache.tools.antBuildListener</code> interface. The listener will receive +<p>To use build events you need to create an ant <code class="code">Project</code> object. You can +then call the <code class="code">addBuildListener</code> method to add your listener to the +project. Your listener must implement +the <code class="code">org.apache.tools.antBuildListener</code> interface. The listener will receive BuildEvents for the following events</p> <ul> <li>Build started</li> @@ -405,40 +416,43 @@ via <a href="Tasks/ant.html"><code><ant></code></a> or <a href="Tasks/subant.html"><code><subant></code></a> or uses <a href="Tasks/antcall.html"><code><antcall></code></a>, you are creating a new Ant "project" that will send target and task level events of its own but never sends build -started/finished events. <em>Since Ant 1.6.2</em>, BuildListener interface has an extension named -SubBuildListener that will receive two new events for</p> +started/finished events. <em>Since Ant 1.6.2</em>, <code class="code">BuildListener</code> interface +has an extension named <code class="code">SubBuildListener</code> that will receive two new events +for</p> <ul> <li>SubBuild started</li> <li>SubBuild finished</li> </ul> <p>If you are interested in those events, all you need to do is to implement the new interface -instead of BuildListener (and register the listener, of course).</p> +instead of <code class="code">BuildListener</code> (and register the listener, of course).</p> -<p>If you wish to attach a listener from the command line you may use the <code>-listener</code> +<p>If you wish to attach a listener from the command line you may use the <kbd>-listener</kbd> option. For example:</p> -<pre>ant -listener org.apache.tools.ant.XmlLogger</pre> +<pre class="input">ant -listener org.apache.tools.ant.XmlLogger</pre> <p>will run Ant with a listener that generates an XML representation of the build progress. This listener is included with Ant, as is the default listener, which generates the logging to standard output.</p> -<p><strong>Note</strong>: A listener must not access <code>System.out</code> -and <code>System.err</code> directly since output on these streams is redirected by Ant's core to -the build event system. Accessing these streams can cause an infinite loop in Ant. Depending on the -version of Ant, this will either cause the build to terminate or the JVM to run out of Stack -space. A logger, also, may not access <code>System.out</code> and <code>System.err</code> -directly. It must use the streams with which it has been configured.</p> +<p><strong>Note</strong>: A listener must not access <code class="code">System.out</code> +and <code class="code">System.err</code> directly since output on these streams is redirected by +Ant's core to the build event system. Accessing these streams can cause an infinite loop in +Ant. Depending on the version of Ant, this will either cause the build to terminate or the JVM to +run out of Stack space. A logger, also, may not access <code class="code">System.out</code> +and <code class="code">System.err</code> directly. It must use the streams with which it has been +configured.</p> -<p><strong>Note</strong>: All methods of a BuildListener except for the "Build Started" and "Build -Finished" events may occur on several threads simultaneously—for example while Ant is -executing a <code><parallel></code> task.</p> +<p><strong>Note</strong>: All methods of a <code class="code">BuildListener</code> except for the +"Build Started" and "Build Finished" events may occur on several threads simultaneously—for +example while Ant is executing a <code><parallel></code> task.</p> <h3>Example</h3> -<p>Writing an adapter to your favourite log library is very easy. Just implement the BuildListener -interface, instantiate your logger and delegate the message to that instance.</p> +<p>Writing an adapter to your favourite log library is very easy. Just implement +the <code class="code">BuildListener</code> interface, instantiate your logger and delegate the +message to that instance.</p> <p>When starting your build provide your adapter class and the log library to the build classpath -and activate your logger via <code>-listener</code> option as described above.</p> +and activate your logger via <kbd>-listener</kbd> option as described above.</p> <pre> public class MyLogAdapter implements BuildListener { http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/feedback.html ---------------------------------------------------------------------- diff --git a/manual/feedback.html b/manual/feedback.html index 2ac985e..2c958a2 100644 --- a/manual/feedback.html +++ b/manual/feedback.html @@ -25,7 +25,7 @@ <body> <h1 id="feedback">Feedback and Troubleshooting</h1> -<p>If things do not work, especially simple things like <code>ant -version</code>, then something is +<p>If things do not work, especially simple things like <kbd>ant -version</kbd>, then something is wrong with your configuration. Before filing bug reports and emailing all the Apache Ant mailing lists</p> <ol> @@ -42,7 +42,7 @@ being picked up by accident.</li> <li>If a task failing to run is from <samp>optional.jar</samp> in <samp>ANT_HOME/lib</samp>? Are there any libraries which it depends on missing?</li> - <li>If a task doesn't do what you expect, run <code>ant -verbose</code> or <code>ant -debug</code> + <li>If a task doesn't do what you expect, run <kbd>ant -verbose</kbd> or <kbd>ant -debug</kbd> to see what is happening</li> </ol> <p>If you can't fix your problem, start with the <a href="https://ant.apache.org/mail.html"; http://git-wip-us.apache.org/repos/asf/ant/blob/14dfef58/manual/inputhandler.html ---------------------------------------------------------------------- diff --git a/manual/inputhandler.html b/manual/inputhandler.html index 6b366e0..1c48d5d 100644 --- a/manual/inputhandler.html +++ b/manual/inputhandler.html @@ -26,89 +26,77 @@ <h2>Overview</h2> -<p>When a task wants to prompt a user for input, it doesn't simply -read the input from the console as this would make it impossible to -embed Apache Ant in an IDE. Instead it asks an implementation of the -<code>org.apache.tools.ant.input.InputHandler</code> interface to -prompt the user and hand the user input back to the task.</p> - -<p>To do this, the task creates an <code>InputRequest</code> object -and passes it to the <code>InputHandler</code>. Such an -<code>InputRequest</code> may know whether a given user input is valid -and the <code>InputHandler</code> is supposed to reject all invalid -input.</p> - -<p>Exactly one <code>InputHandler</code> instance is associated with -every Ant process, users can specify the implementation using the -<code>-inputhandler</code> command line switch.</p> +<p>When a task wants to prompt a user for input, it doesn't simply read the input from the console +as this would make it impossible to embed Apache Ant in an IDE. Instead it asks an implementation +of the <code class="code">org.apache.tools.ant.input.InputHandler</code> interface to prompt the +user and hand the user input back to the task.</p> + +<p>To do this, the task creates an <code class="code">InputRequest</code> object and passes it to +the <code class="code">InputHandler</code>. Such an <code class="code">InputRequest</code> may know +whether a given user input is valid and the <code class="code">InputHandler</code> is supposed to +reject all invalid input.</p> + +<p>Exactly one <code class="code">InputHandler</code> instance is associated with every Ant process, +users can specify the implementation using the <kbd>-inputhandler</kbd> command line switch.</p> <h2>InputHandler</h2> -<p>The <code>InputHandler</code> interface contains exactly one -method</p> +<p>The <code class="code">InputHandler</code> interface contains exactly one method</p> <pre> void handleInput(InputRequest request) - throws org.apache.tools.ant.BuildException;</pre> + throws org.apache.tools.ant.BuildException;</pre> -<p>with some pre- and postconditions. The main postcondition is that -this method must not return unless the <code>request</code> considers -the user input valid; it is allowed to throw an exception in this -situation.</p> +<p>with some pre- and postconditions. The main postcondition is that this method must not return +unless the <code>request</code> considers the user input valid; it is allowed to throw an exception +in this situation.</p> <p>Ant comes with three built-in implementations of this interface:</p> <h3 id="defaulthandler">DefaultInputHandler</h3> -<p>This is the implementation you get, when you don't use -the <code>-inputhandler</code> command line switch at all. This -implementation will print the prompt encapsulated in -the <code>request</code> object to Ant's logging system and -re-prompt for input until the user enters something that is considered -valid input by the <code>request</code> object. Input will be read -from the console and the user will need to press the Return key.</p> +<p>This is the implementation you get, when you don't use the <kbd>-inputhandler</kbd> command line +switch at all. This implementation will print the prompt encapsulated in the <code>request</code> +object to Ant's logging system and re-prompt for input until the user enters something that is +considered valid input by the <code>request</code> object. Input will be read from the console and +the user will need to press the Return key.</p> <h3>PropertyFileInputHandler</h3> -<p>This implementation is useful if you want to run unattended build -processes. It reads all input from a properties file and makes the -build fail if it cannot find valid input in this file. The name of -the properties file must be specified in the Java system +<p>This implementation is useful if you want to run unattended build processes. It reads all input +from a properties file and makes the build fail if it cannot find valid input in this file. The +name of the properties file must be specified in the Java system property <code>ant.input.properties</code>.</p> -<p>The prompt encapsulated in a <code>request</code> will be used as -the key when looking up the input inside the properties file. If no -input can be found, the input is considered invalid and an exception -will be thrown.</p> +<p>The prompt encapsulated in a <code>request</code> will be used as the key when looking up the +input inside the properties file. If no input can be found, the input is considered invalid and an +exception will be thrown.</p> -<p><strong>Note</strong> that <code>ant.input.properties</code> must -be a Java system property, not an Ant property. I.e. you cannot -define it as a simple parameter to <code>ant</code>, but you can +<p><strong>Note</strong> that <code>ant.input.properties</code> must be a Java system property, not +an Ant property. I.e. you cannot define it as a simple parameter to <kbd>ant</kbd>, but you can define it inside the <code>ANT_OPTS</code> environment variable.</p> <h3>GreedyInputHandler</h3> <p><em>Since Ant 1.7</em></p> -<p>Like the default implementation, this InputHandler reads from standard -input. However, it consumes <em>all</em> available input. This behavior is -useful for sending Ant input via an OS pipe.</p> +<p>Like the default implementation, this InputHandler reads from standard input. However, it +consumes <em>all</em> available input. This behavior is useful for sending Ant input via an OS +pipe.</p> <h3>SecureInputHandler</h3> <p><em>Since Ant 1.7.1</em></p> -<p>This InputHandler calls <code>System.console().readPassword()</code>, -available since Java 6. On earlier platforms it falls back to the -behavior of DefaultInputHandler.</p> +<p>This InputHandler calls <code class="code">System.console().readPassword()</code>, available +since Java 6. On earlier platforms it falls back to the behavior +of <code class="code">DefaultInputHandler</code>.</p> <h2>InputRequest</h2> -<p>Instances of <code>org.apache.tools.ant.input.InputRequest</code> -encapsulate the information necessary to ask a user for input and -validate this input.</p> +<p>Instances of <code class="code">org.apache.tools.ant.input.InputRequest</code> encapsulate the +information necessary to ask a user for input and validate this input.</p> -<p>The instances of <code>InputRequest</code> itself will accept any -input, but subclasses may use stricter -validations. <code>org.apache.tools.ant.input.MultipleChoiceInputRequest</code> -should be used if the user input must be part of a predefined set of -choices.</p> +<p>The instances of <code class="code">InputRequest</code> itself will accept any input, but +subclasses may use stricter +validations. <code class="code">org.apache.tools.ant.input.MultipleChoiceInputRequest</code> should +be used if the user input must be part of a predefined set of choices.</p> </body> </html>
