source: other-projects/trunk/gs3-release-maker/apache-ant-1.6.5/docs/manual/CoreTypes/selectors-program.html@ 14627

Last change on this file since 14627 was 14627, checked in by oranfry, 17 years ago

initial import of the gs3-release-maker
File size: 11.4 KB
Line 
1<html>
2 <head>
3 <meta http-equiv="Content-Language" content="en-us">
4 <title>Programming Selectors in Ant</title>
5<link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
6 </head>
7
8 <body>
9 <h2>Programming your own Selectors</h2>
10
11 <h3>Selector Programming API</h3>
12
13 <p>Want to define your own selectors? It's easy!</p>
14
15 <p>First, pick the type of selector that you want to define. There
16 are three types, and a recipe for each one follows. Chances are
17 you'll want to work with the first one, Custom Selectors.</p>
18
19 <ol>
20 <li>Custom Selectors
21
22 <p>This is the category that Ant provides specifically for you to
23 define your own Selectors. Anywhere you want to use your selector
24 you use the <code>&lt;custom&gt;</code> element and specify
25 the class name of your selector within it. See the
26 <a href="selectors.html#customselect">Custom Selectors</a>
27 section of the Selector page for details. The
28 <code>&lt;custom&gt;</code> element can be used anywhere
29 the core selectors can be used. It can be contained within
30 <a href="selectors.html#selectcontainers">Selector Containers</a>,
31 for example.</p>
32
33 <p>To create a new Custom Selector, you have to create a class that
34 implements
35 <code>org.apache.tools.ant.types.selectors.ExtendFileSelector</code>.
36 The easiest way to do that is through the convenience base class
37 <code>org.apache.tools.ant.types.selectors.BaseExtendSelector</code>,
38 which provides all of the methods for supporting
39 <code>&lt;param&gt;</code> tags. First, override the
40 <code>isSelected()</code> method, and optionally the
41 <code>verifySettings()</code> method. If your custom
42 selector requires parameters to be set, you can also override
43 the <code>setParameters()</code> method and interpret the
44 parameters that are passed in any way you like. Several of the
45 core selectors demonstrate how to do that because they can
46 also be used as custom selectors.</p>
47
48 <li>Core Selectors
49
50 <p>These are the selectors used by Ant itself. To implement one of
51 these, you will have to alter some of the classes contained within
52 Ant.</p>
53
54 <ul>
55 <li><p>First, create a class that implements
56 <code>org.apache.tools.ant.types.selectors.FileSelector</code>.
57 You can either choose to implement all methods yourself from
58 scratch, or you can extend
59 <code>org.apache.tools.ant.types.selectors.BaseSelector</code>
60 instead, a convenience class that provides reasonable default
61 behaviour for many methods.</p>
62
63 <p>There is only one method required.
64 <code>public boolean isSelected(File basedir, String filename,
65 File file)</code>
66 is the real purpose of the whole exercise. It returns true
67 or false depending on whether the given file should be
68 selected from the list or not.</p>
69
70 <p>If you are using
71 <code>org.apache.tools.ant.types.selectors.BaseSelector</code>
72 there are also some predefined behaviours you can take advantage
73 of. Any time you encounter a problem when setting attributes or
74 adding tags, you can call setError(String errmsg) and the class
75 will know that there is a problem. Then, at the top of your
76 <code>isSelected()</code> method call <code>validate()</code> and
77 a BuildException will be thrown with the contents of your error
78 message. The <code>validate()</code> method also gives you a
79 last chance to check your settings for consistency because it
80 calls <code>verifySettings()</code>. Override this method and
81 call <code>setError()</code> within it if you detect any
82 problems in how your selector is set up.</p>
83
84 <p>You may also want to override <code>toString()</code>.</p>
85
86 <li><p>Put an <code>add</code> method for your selector in
87 <code>org.apache.tools.ant.types.selectors.SelectorContainer</code>.
88 This is an interface, so you will also have to add an implementation
89 for the method in the classes which implement it, namely
90 <code>org.apache.tools.ant.types.AbstractFileSet</code>,
91 <code>org.apache.tools.ant.taskdefs.MatchingTask</code> and
92 <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>.
93 Once it is in there, it will be available everywhere that core
94 selectors are appropriate.</p>
95 </ul>
96
97 <li>Selector Containers
98 <p>Got an idea for a new Selector Container? Creating a new one is
99 no problem:</p>
100 <ul>
101 <li><p>Create a new class that implements
102 <code>org.apache.tools.ant.types.selectors.SelectorContainer</code>.
103 This will ensure that your new
104 Container can access any new selectors that come along. Again, there
105 is a convenience class available for you called
106 <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>.
107 </p>
108 <li><p>Implement the
109 <code>public boolean isSelected(String filename, File file)</code>
110 method to do the right thing. Chances are you'll want to iterate
111 over the selectors under you, so use
112 <code>selectorElements()</code> to get an iterator that will do
113 that.</p>
114 <li><p>Again, put an <code>add</code> method for your container in
115 <code>org.apache.tools.ant.types.selectors.SelectorContainer</code>
116 and its implementations
117 <code>org.apache.tools.ant.types.AbstractFileSet</code> and
118 <code>org.apache.tools.ant.types.selectors.BaseSelectorContainer</code>.
119 </p>
120 </ul>
121 </ol>
122
123 <h3>Testing Selectors</h3>
124
125 <p>For a robust component (and selectors are (Project)ComponentŽs) tests are
126 necessary. For testing Tasks we use JUnit TestCases - more specific
127 <tt>org.apache.tools.ant.BuildFileTest extends junit.framework.TestCase</tt>.
128 Some of its features like configure the (test) project by reading its buildfile and
129 execute targets we need for selector tests also. Therefore we use that BuildFileTest.
130 But testing selectors requires some more work: having a set of files, instantiate
131 and configure the selector, check the selection work and more. Because we usually
132 extend <tt>BaseExtendSelector</tt> its features have to be tested also (e.g. setError()).
133 </p>
134
135 <p>ThatŽs why we have a base class for doing our selector tests:
136 <tt>org.apache.tools.ant.types.selectors.BaseSelectorTest</tt>.</p>
137
138 <p>This class extends TestCase and therefore can included in the set of AntŽs
139 unit tests. It holds an instance of preconfigured BuildFileTest. Configuration
140 is done by parsing the src/etc/testcases/types/selectors.xml. BaseSelectorTest
141 then gives us helper methods for handling multiple selections. </p>
142
143 <p>Because the term "testcase" or "testenvironment" are so often used, this
144 special testenvironment got a new name: <i>bed</i>. Like you initialize the
145 test environment by calling setUp() and cleaning by calling tearDown() (<i>or like
146 to make your bed before go sleeping</i>) you have to do that work with your
147 <i>bed</i> by calling <tt>makeBed()</tt> respecitive <tt>cleanupBed()</tt>.</p>
148
149 <p>A usual test scenario is<ol>
150 <li>make the bed</li>
151 <li>instantiate the selector</li>
152 <li>configure the selector</li>
153 <li>let the selector do some work</li>
154 <li>verify the work</li>
155 <li>clean the bed</li>
156 </ol>
157 </p>
158
159 <p>For common way of instantiation you have to override the <tt>getInstance()</tt>
160 simply by returning a new object of your selector. For easier "selection and verification work"
161 BaseSelectorTest provides the method <tt>performTests()</tt> which
162 iterates over all files (and directories) in the String array <tt>filenames</tt>
163 and checks whether the given selector returns the expected result. If an error
164 occured (especially the selector does not return the expected result) the test
165 fails and the failing filenames are logged.</p>
166
167 <p>An example test would be:<pre>
168package org.apache.tools.ant.types.selectors;
169
170public class MySelectorTest extends BaseSelectorTest {
171
172 public MySelectorTest(String name) {
173 super(name);
174 }
175
176 public BaseSelector getInstance() {
177 return new MySelector();
178 }
179
180 public void testCase1() {
181 try {
182 // initialize test environment 'bed'
183 makeBed();
184
185 // Configure the selector
186 MySelector s = (MySelector)getSelector();
187 s.addParam("key1", "value1");
188 s.addParam("key2", "value2");
189 s.setXX(true);
190 s.setYY("a value");
191
192 // do the tests
193 performTests(s, "FTTTTTTTTTTT"); // First is not selected - rest is
194
195 } finally {
196 // cleanup the environment
197 cleanupBed();
198 }
199 }
200}
201 </pre>
202 As an example of an error JUnit could log<pre>
203 [junit] FAILED
204 [junit] Error for files: <font color=blue>.;copy.filterset.filtered;tar/gz/asf-logo.gif.tar.gz</font>
205 [junit] expected:&lt;<font color=blue>FTTTFTTTF...</font>&gt; but was:&lt;TTTTTTTTT...&gt;
206 [junit] junit.framework.ComparisonFailure: Error for files: .;copy.filterset.filtered;tar/gz/asf-logo.gif.tar.gz
207 [junit] expected:&lt;FTTTFTTTF...&gt; but was:&lt;TTTTTTTTT...&gt;
208 [junit] at junit.framework.Assert.assertEquals(Assert.java:81)
209 [junit] at org.apache.tools.ant.types.selectors.BaseSelectorTest.performTest(BaseSelectorTest.java:194)
210 </pre></p>
211
212 <p>Described above the test class should provide a <tt>getInstance()</tt>
213 method. But that isnŽt used here. The used <tt>getSelector()</tt> method is
214 implemented in the base class and gives an instance of an Ant Project to
215 the selector. This is usually done inside normal build file runs, but not
216 inside this special environment, so this method gives the selector the
217 ability to use its own Project object (<tt>getProject()</tt>), for example
218 for logging.</p>
219
220
221 <h3>Logging</h3>
222
223 <p>During development and maybe later you sometimes need the output of information.
224 Therefore Logging is needed. Because the selector extends BaseExtendSelector or directly
225 BaseSelector it is an Ant <tt>DataType</tt> and therefore a <tt>ProjectComponent</tt>. <br>
226 That means that you have access to the project object and its logging capability.
227 <tt>ProjectComponent</tt> itself provides <i>log</i> methods which will do the
228 access to the project instance. Logging is therefore done simply with:
229 <pre>
230 log( "message" );
231 </pre>
232 or
233 <pre>
234 log( "message" , loglevel );
235 </pre>
236 where the <tt>loglevel</tt> is one of the values <ul>
237 <li> org.apache.tools.ant.Project.MSG_ERR </li>
238 <li> org.apache.tools.ant.Project.MSG_WARN </li>
239 <li> org.apache.tools.ant.Project.MSG_INFO (= default) </li>
240 <li> org.apache.tools.ant.Project.MSG_VERBOSE </li>
241 <li> org.apache.tools.ant.Project.MSG_DEBUG </li>
242 </ul>
243 </p>
244
245 <hr>
246 <p align="center">Copyright &copy; 2002-2004 The Apache Software
247 Foundation. All rights Reserved.</p>
248 </body>
249
250</html>
Note: See TracBrowser for help on using the repository browser.