You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by gi...@apache.org on 2018/02/28 07:01:28 UTC
[13/47] ant git commit: Use HTML 5(-ish), fix links
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/Types/selectors-program.html
----------------------------------------------------------------------
diff --git a/manual/Types/selectors-program.html b/manual/Types/selectors-program.html
index 55698fc..2e471ea 100644
--- a/manual/Types/selectors-program.html
+++ b/manual/Types/selectors-program.html
@@ -28,138 +28,116 @@
<p>Want to define your own selectors? It's easy!</p>
- <p>First, pick the type of selector that you want to define. There
- are three types, and a recipe for each one follows. Chances are
- you'll want to work with the first one, Custom Selectors.</p>
+ <p>First, pick the type of selector that you want to define. There are three types, and a
+ recipe for each one follows. Chances are you'll want to work with the first one, Custom
+ Selectors.</p>
<ol>
<li>Custom Selectors
- <p>This is the category that Apache Ant provides specifically for you to
- define your own Selectors. Anywhere you want to use your selector
- you use the <code><custom></code> element and specify
- the class name of your selector within it. See the
- <a href="selectors.html#customselect">Custom Selectors</a>
- section of the Selector page for details. The
- <code><custom></code> element can be used anywhere
- the core selectors can be used. It can be contained within
- <a href="selectors.html#selectcontainers">Selector Containers</a>,
- for example.</p>
+ <p>This is the category that Apache Ant provides specifically for you to define your own
+ Selectors. Anywhere you want to use your selector you use
+ the <code><custom></code> element and specify the class name of your selector
+ within it. See the <a href="selectors.html#customselect">Custom Selectors</a> section of
+ the Selector page for details. The <code><custom></code> element can be used
+ anywhere the core selectors can be used. It can be contained
+ within <a href="selectors.html#selectcontainers">Selector Containers</a>, for
+ 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>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>
<li>Core Selectors
- <p>These are the selectors used by Ant itself. To implement one of
- these, you will have to alter some of the classes contained within
- Ant.</p>
+ <p>These are the selectors used by Ant itself. To implement one of these, you will have
+ to alter some of the classes contained within Ant.</p>
<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 true
- or false 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 setError(String errmsg) 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
+ <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><p>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 appropriate.</p>
+ 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
+ appropriate.</li>
</ul>
<li>Selector Containers
- <p>Got an idea for a new Selector Container? Creating a new one is
- no problem:</p>
+ <p>Got an idea for a new Selector Container? Creating a new one is no problem:</p>
<ul>
- <li><p>Create a new class that implements
- <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>.
- </p>
- <li><p>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.</p>
- <li><p>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>.
- </p>
+ <li>Create a new class that
+ implements <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>
</ul>
</ol>
<h3>Testing Selectors</h3>
- <p>For a robust component (and selectors are (Project)Components) tests are
- necessary. For testing Tasks we use JUnit TestCases - more specific
- <tt>org.apache.tools.ant.BuildFileRule extends org.junit.rules.ExternalResource</tt>.
- 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 <tt>BaseExtendSelector</tt> its features have to be tested also (e.g. setError()).
- </p>
-
- <p>That's why we have a test rule for doing our selector tests:
- <tt>org.apache.tools.ant.types.selectors.BaseSelectorRule</tt>.</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 the src/etc/testcases/types/selectors.xml. BaseSelectorRule
- then gives us helper methods for handling multiple selections. </p>
-
- <p>Because the term "testcase" or "testenvironment" are so often used, this
- special testenvironment got a new name: <i>bed</i>. The setup and cleanup of
- the bed is all handled by the BaseSelectorRule so any test only has to handle
- the actual test scenarios</p>
+ <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>
+
+ <p>That's why we have a test rule for doing our selector
+ tests: <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
+ the <samp>src/etc/testcases/types/selectors.xml</samp>. BaseSelectorRule then gives us
+ helper methods for handling multiple selections.</p>
+
+ <p>Because the term "testcase" or "testenvironment" are so often used, this special
+ testenvironment got a new name: <em>bed</em>. The setup and cleanup of the bed is all
+ handled by the BaseSelectorRule so any test only has to handle the actual test scenarios</p>
<p>A usual test scenario is:</p>
<ol>
@@ -169,7 +147,8 @@
<li>verify the work</li>
</ol>
- <p>An example test would be:</p><pre>
+ <p>An example test would be:</p>
+ <pre>
package org.apache.tools.ant.types.selectors;
public class MySelectorTest {
@@ -190,48 +169,43 @@ public class MySelectorTest {
// do the tests
assertEquals("FTTTTTTTT", selectorRule.selectionString(s));
}
-}
- </pre>
- As an example of an error JUnit could log<pre>
- [junit] FAILED
- [junit] Error for files: <font color=blue>.;copy.filterset.filtered;tar/gz/asf-logo.gif.tar.gz</font>
- [junit] expected:<<font color=blue>FTTTFTTTF...</font>> but was:<TTTTTTTTT...>
- [junit] junit.framework.ComparisonFailure: Error for files: .;copy.filterset.filtered;tar/gz/asf-logo.gif.tar.gz
- [junit] expected:<FTTTFTTTF...> but was:<TTTTTTTTT...>
- [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 <tt>getInstance()</tt>
- method. But that isn't used here. The used <tt>getSelector()</tt> 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 (<tt>getProject()</tt>), for example
+}</pre>
+ <p>As an example of an error JUnit could log</p>
+ <pre>
+[junit] FAILED
+[junit] Error for files: <span style="color:blue">.;copy.filterset.filtered;tar/gz/asf-logo.gif.tar.gz</span>
+[junit] expected:<<span style="color:blue">FTTTFTTTF...</span>> but was:<TTTTTTTTT...>
+[junit] junit.framework.ComparisonFailure: Error for files: .;copy.filterset.filtered;tar/gz/asf-logo.gif.tar.gz
+[junit] expected:<FTTTFTTTF...> but was:<TTTTTTTTT...>
+[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>
<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 <tt>DataType</tt> and therefore a <tt>ProjectComponent</tt>. <br>
- That means that you have access to the project object and its logging capability.
- <tt>ProjectComponent</tt> itself provides <i>log</i> methods which will do the
- access to the project instance. Logging is therefore done simply with:</p>
- <pre>
- log( "message" );
- </pre>
- or
- <pre>
- log( "message" , loglevel );
- </pre>
- where the <tt>loglevel</tt> is one of the values
+ 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
+ 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> org.apache.tools.ant.Project.MSG_ERR </li>
- <li> org.apache.tools.ant.Project.MSG_WARN </li>
- <li> org.apache.tools.ant.Project.MSG_INFO (= default) </li>
- <li> org.apache.tools.ant.Project.MSG_VERBOSE </li>
- <li> org.apache.tools.ant.Project.MSG_DEBUG </li>
+ <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>
</ul>
</body>