← Back to branch summary

~ubuntu-branches/ubuntu/quantal/netbeans/quantal

« back to all changes in this revision

Viewing changes to ant/arch/arch-ant-main.xml

  • Committer: Bazaar Package Importer
  • Author(s): Marek Slama
  • Date: 2008-01-29 14:11:22 UTC
  • Revision ID: james.westby@ubuntu.com-20080129141122-fnzjbo11ntghxfu7
Tags: upstream-6.0.1
Import upstream version 6.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
ant/arch/arch-ant-main.xml
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!--
 
3
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 
4
 
 
5
Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 
6
 
 
7
 
 
8
The contents of this file are subject to the terms of either the GNU
 
9
General Public License Version 2 only ("GPL") or the Common
 
10
Development and Distribution License("CDDL") (collectively, the
 
11
"License"). You may not use this file except in compliance with the
 
12
License. You can obtain a copy of the License at
 
13
http://www.netbeans.org/cddl-gplv2.html
 
14
or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
 
15
specific language governing permissions and limitations under the
 
16
License.  When distributing the software, include this License Header
 
17
Notice in each file and include the License file at
 
18
nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this
 
19
particular file as subject to the "Classpath" exception as provided
 
20
by Sun in the GPL Version 2 section of the License file that
 
21
accompanied this code. If applicable, add the following below the
 
22
License Header, with the fields enclosed by brackets [] replaced by
 
23
your own identifying information:
 
24
"Portions Copyrighted [year] [name of copyright owner]"
 
25
 
 
26
Contributor(s):
 
27
 
 
28
The Original Software is NetBeans. The Initial Developer of the Original
 
29
Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
 
30
Microsystems, Inc. All Rights Reserved.
 
31
 
 
32
If you wish your version of this file to be governed by only the CDDL
 
33
or only the GPL Version 2, indicate your decision by adding
 
34
"[Contributor] elects to include this software in this distribution
 
35
under the [CDDL or GPL Version 2] license." If you do not indicate a
 
36
single choice of license, a recipient has the option to distribute
 
37
your version of this file under either the CDDL, the GPL Version 2 or
 
38
to extend the choice of license to its licensees as provided above.
 
39
However, if you add GPL Version 2 code and therefore, elected the GPL
 
40
Version 2 license, then the option applies only if the new code is
 
41
made subject to such option by the copyright holder.
 
42
-->
 
43
<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
 
44
    <!ENTITY api-questions SYSTEM "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
 
45
]>
 
46
 
 
47
<api-answers
 
48
  question-version="1.27"
 
49
  author="jglick@netbeans.org"
 
50
>
 
51
 
 
52
  &api-questions;
 
53
 
 
54
 
 
55
<!--
 
56
        <question id="arch-overall" when="init">
 
57
            Describe the overall architecture.
 
58
            <hint>
 
59
            What will be API for
 
60
            <a href="http://openide.netbeans.org/tutorial/api-design.html#design.apiandspi">
 
61
                clients and what support API</a>? 
 
62
            What parts will be pluggable?
 
63
            How will plug-ins be registered? Please use <code>&lt;api type="export"/&gt;</code>
 
64
            to describe your general APIs.
 
65
            If possible please provide 
 
66
            simple diagrams. 
 
67
            </hint>
 
68
        </question>
 
69
-->
 
70
    <answer id="arch-overall">
 
71
        <p>
 
72
            The main uses of the Ant integration module are self-contained and do
 
73
            not interact directly with other modules: the user selects a target
 
74
            in an Ant script and runs it. Nonetheless, there are a few
 
75
            significant ways other modules can interact with this module:
 
76
        </p>
 
77
        <ol>
 
78
            <li>
 
79
                <api group="java" name="AntLogger" type="export" category="stable" url="@TOP@/org/apache/tools/ant/module/spi/AntLogger.html">
 
80
                    <p>
 
81
                        Permits customization of the way Ant output is displayed.
 
82
                    </p>
 
83
                </api>
 
84
            </li>
 
85
            <li>
 
86
                <api group="java.io.File" name="register-defs" type="export" category="stable" url="@TOP@/org/apache/tools/ant/module/spi/package-summary.html#register-defs">
 
87
                    <p>
 
88
                    Registering custom Ant task and type definitions (when these
 
89
                    can be run inside the NetBeans JVM only). Typically used to
 
90
                    add special tasks which somehow script the IDE, such as
 
91
                    connecting the JPDA debugger to a process launched by Ant.
 
92
                    </p>
 
93
                </api>
 
94
            </li>
 
95
            <li>
 
96
                <api group="java" name="AutomaticExtraClasspathProvider" type="export" category="stable" url="@TOP@/org/apache/tools/ant/module/spi/AutomaticExtraClasspathProvider.html">
 
97
                    <p>
 
98
                        Permits additions to the default Ant classpath.
 
99
                    </p>
 
100
                </api>
 
101
            </li>
 
102
            <li>
 
103
                <api group="java" name="IntrospectedInfo" type="export" category="stable" url="@TOP@/org/apache/tools/ant/module/api/IntrospectedInfo.html">
 
104
                    <p>
 
105
                    Examining cached and introspected data about which tasks and
 
106
                    types are known to be defined in the user's Ant scripts, and
 
107
                    what their design-time structure is. Used by XML code
 
108
                    completion, for example.
 
109
                    </p>
 
110
                </api>
 
111
            </li>
 
112
            <li>
 
113
                <api group="java" name="AntTargetExecutor" type="export" category="stable" url="@TOP@/org/apache/tools/ant/module/api/AntTargetExecutor.html">
 
114
                    <p>
 
115
                    Running named targets in specified Ant scripts. Can be used
 
116
                    by modules which provide a different UI for initiating Ant
 
117
                    execution. <code>ActionUtils</code> provides a more convenient
 
118
                    wrapper around this functionality.
 
119
                    </p>
 
120
                </api>
 
121
            </li>
 
122
        </ol>
 
123
    </answer>
 
124
 
 
125
 
 
126
 
 
127
<!--
 
128
        <question id="arch-quality" when="init">
 
129
            How the <a href="http://www.netbeans.org/community/guidelines/q-evangelism.html">quality</a>
 
130
            of your code will be tested and 
 
131
            how future regressions are going to be prevented?
 
132
            <hint>
 
133
            What kind of testing
 
134
            you want to use? What/how much area of functionality
 
135
            should be covered by the tests? 
 
136
            </hint>
 
137
        </question>
 
138
-->
 
139
    <answer id="arch-quality">
 
140
        <p>
 
141
            Currently a fair amount of the module is covered by functional tests.
 
142
            There are some unit tests, especially for newer code.
 
143
        </p>
 
144
    </answer>
 
145
 
 
146
 
 
147
 
 
148
<!--
 
149
        <question id="arch-time" when="init">
 
150
            What are the time estimates of the work?
 
151
            <hint>
 
152
            Please express your estimates of how long the design, implementation,
 
153
            stabilization are likely to last. How many people will be needed to
 
154
            implement this and what is the expected milestone the work should be 
 
155
            ready.
 
156
            </hint>
 
157
        </question>
 
158
-->
 
159
    <answer id="arch-time">
 
160
        <p>
 
161
            N/A; already implemented.
 
162
        </p>
 
163
    </answer>
 
164
 
 
165
 
 
166
 
 
167
<!--
 
168
        <question id="arch-usecases" when="init">
 
169
            Describe the main <a href="http://openide.netbeans.org/tutorial/api-design.html#usecase">
 
170
            use cases</a> of the new API. Who will use it at
 
171
            what circumstances and what will be the typical code to write
 
172
            to use the module.
 
173
        </question>
 
174
-->
 
175
    <answer id="arch-usecases">
 
176
        <p>
 
177
            The principal use cases for the API are covered in the overall API architecture.
 
178
        </p>
 
179
    </answer>
 
180
 
 
181
 
 
182
 
 
183
<!--
 
184
        <question id="arch-what" when="init">
 
185
            What is this project good for?
 
186
            <hint>
 
187
            Please provide here a few lines describing the project, 
 
188
            what problem it should solve, provide links to documentation, 
 
189
            specifications, etc.
 
190
            </hint>
 
191
        </question>
 
192
-->
 
193
    <answer id="arch-what">
 
194
        <p>
 
195
            The Ant integration module recognizes Ant build scripts, facilitates
 
196
            editing them as text or structurally, lets the user run targets or
 
197
            create shortcuts to them, etc.
 
198
        </p>
 
199
    </answer>
 
200
 
 
201
 
 
202
 
 
203
<!--
 
204
        <question id="compat-i18n" when="impl">
 
205
            Is your module correctly internationalized?
 
206
            <hint>
 
207
            Correct internationalization means that it obeys instructions 
 
208
            at <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/i18n-branding.html">
 
209
            NetBeans I18N pages</a>.
 
210
            </hint>
 
211
        </question>
 
212
-->
 
213
    <answer id="compat-i18n">
 
214
        <p>
 
215
            Visible strings directly represented by the module are
 
216
            internationalized. However Ant itself is not, and so messages coming
 
217
            from Ant will appear only in English.
 
218
        </p>
 
219
    </answer>
 
220
 
 
221
 
 
222
 
 
223
<!--
 
224
        <question id="compat-standards" when="init">
 
225
            Does the module implement or define any standards? Is the 
 
226
            implementation exact or does it deviate somehow?
 
227
        </question>
 
228
-->
 
229
    <answer id="compat-standards">
 
230
        <p>
 
231
            Insofar as Ant can be considered a standard, it implements the
 
232
            standard behavior of running an Ant script. The implementation should
 
233
            behave quite similarly to what the normal Ant command-line usage does
 
234
            (since it delegates to the Ant library internally and only replaces
 
235
            the command-line wrapper with an IDE wrapper). Since the Ant project
 
236
            does not publish a formal specification of how Ant should behave,
 
237
            there is no objective criterion for judging the fidelity.
 
238
        </p>
 
239
        <p>
 
240
            Likely areas of difference between command-line and IDE usage:
 
241
            obscure class loader scenarios (since the IDE must load Ant in a
 
242
            special class loader, whereas the command-line tool may do it
 
243
            differently); system properties set in the IDE but not on the command
 
244
            line; etc. Generally, well-written scripts and tasks are not affected
 
245
            by these differences, but occasionally problems arise (they are
 
246
            treated as bugs).
 
247
        </p>
 
248
    </answer>
 
249
 
 
250
 
 
251
 
 
252
<!--
 
253
        <question id="compat-version" when="impl">
 
254
            Can your module coexist with earlier and future
 
255
            versions of itself? Can you correctly read all old settings? Will future
 
256
            versions be able to read your current settings? Can you read
 
257
            or politely ignore settings stored by a future version?
 
258
            
 
259
            <hint>
 
260
            Very helpful for reading settings is to store version number
 
261
            there, so future versions can decide whether how to read/convert
 
262
            the settings and older versions can ignore the new ones.
 
263
            </hint>
 
264
        </question>
 
265
-->
 
266
    <answer id="compat-version">
 
267
        <p>
 
268
            Loading older settings is generally supported for compatibility.
 
269
        </p>
 
270
    </answer>
 
271
 
 
272
 
 
273
 
 
274
<!--
 
275
        <question id="dep-jre" when="final">
 
276
            Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
 
277
            <hint>
 
278
            It is expected that if your module runs on 1.x that it will run 
 
279
            on 1.x+1 if no, state that please. Also describe here cases where
 
280
            you run different code on different versions of JRE and why.
 
281
            </hint>
 
282
        </question>
 
283
-->
 
284
    <answer id="dep-jre">
 
285
        <p>
 
286
            JRE 1.5 is required.
 
287
        </p>
 
288
    </answer>
 
289
 
 
290
 
 
291
 
 
292
<!--
 
293
        <question id="dep-jrejdk" when="final">
 
294
            Do you require the JDK or is the JRE enough?
 
295
        </question>
 
296
-->
 
297
    <answer id="dep-jrejdk">
 
298
        <p>
 
299
            The module itself requires only the JRE, but Ant requires the JDK in
 
300
            order to do anything useful such as compile Java classes.
 
301
        </p>
 
302
    </answer>
 
303
 
 
304
 
 
305
 
 
306
<!--
 
307
        <question id="dep-nb" when="init">
 
308
            What other NetBeans projects and modules does this one depend on?
 
309
            <hint>
 
310
            If you want, describe such projects as imported API using
 
311
            the <code>&lt;api name="identification" type="import or export" category="stable" url="where is the description" /&gt;</code>
 
312
            </hint>
 
313
        </question>
 
314
-->
 
315
    <answer id="dep-nb">
 
316
          <defaultanswer generate='none'/>
 
317
        <ul>
 
318
            <li>
 
319
                <p>
 
320
                    <api name="FilesystemsAPI" type="import" category="stable" url="@org-openide-filesystems@/" group="java"/> and
 
321
                    <api name="DatasystemsAPI" type="import" category="stable" url="@org-openide-loaders@/" group="java"/>
 
322
                    for dealing with files including Ant scripts.
 
323
                </p>
 
324
            </li>
 
325
            <li>
 
326
                <p>
 
327
                    <api name="NodesAPI" type="import" category="stable" url="@org-openide-nodes@/" group="java"/>,
 
328
                    <api name="ActionsAPI" type="import" category="stable" url="@org-openide-actions@/" group="java"/>,
 
329
                    <api name="WindowSystemAPI" type="import" category="stable" url="@org-openide-windows@/" group="java"/>,
 
330
                    <api name="OptionsAPI" type="import" category="stable" url="@org-openide-options@/" group="java"/>,
 
331
                    <api name="EditorAPI" type="import" category="stable" url="@org-openide-text@/" group="java"/>,
 
332
                    etc. for providing the various GUI components of the module.
 
333
                </p>
 
334
            </li>
 
335
            <li>
 
336
                <api name="ModulesAPI" type="import" category="stable" url="@org-openide-modules@/" group="java">
 
337
                    for finding enabled modules to possibly load custom definitions from.
 
338
                </api>
 
339
            </li>
 
340
            <li>
 
341
                <api name="ExecutionAPI" type="import" category="stable" url="@org-openide-execution@/" group="java">
 
342
                    for running scripts in the execution engine.
 
343
                </api>
 
344
            </li>
 
345
            <li>
 
346
                <api name="InputOutputAPI" type="import" category="stable" url="@org-openide-io@/" group="java">
 
347
                    for displaying output from Ant in the Output Window.
 
348
                </api>
 
349
            </li>
 
350
            <li>
 
351
                <api name="JavaSupportAPIs" type="import" category="stable" url="@org-netbeans-api-java@/" group="java">
 
352
                    for getting an appropriate class loader from a given source file.
 
353
                </api>
 
354
            </li>
 
355
        </ul>
 
356
    </answer>
 
357
 
 
358
 
 
359
 
 
360
<!--
 
361
        <question id="dep-non-nb" when="init">
 
362
            What other projects outside NetBeans does this one depend on?
 
363
            
 
364
            <hint>
 
365
            Some non-NetBeans projects are packaged as NetBeans modules
 
366
            (see <a href="http://libs.netbeans.org/">libraries</a>) and
 
367
            it is preferred to use this approach when more modules may
 
368
            depend on such third-party library.
 
369
            </hint>
 
370
        </question>
 
371
-->
 
372
    <answer id="dep-non-nb">
 
373
        <ol>
 
374
            <li>
 
375
                <api group="java" name="Ant" type="import" category="third" url="http://ant.apache.org/">
 
376
                    Ant itself, of course.
 
377
                    1.5.3+ is required, 1.7.0 recommended (and currently bundled); some features may be limited to newer versions.
 
378
                </api>
 
379
            </li>
 
380
        </ol>
 
381
    </answer>
 
382
 
 
383
 
 
384
 
 
385
<!--
 
386
        <question id="dep-platform" when="init">
 
387
            On which platforms does your module run? Does it run in the same
 
388
            way on each?
 
389
            <hint>
 
390
            If your module is using JNI or deals with special differences of
 
391
            OSes like filesystems, etc. please describe here what they are.
 
392
            </hint>
 
393
        </question>
 
394
-->
 
395
    <answer id="dep-platform">
 
396
        <p>
 
397
            Should be as platform-independent as Ant itself is. Ant uses some
 
398
            platform-specific tricks to normalize pathnames, launch
 
399
            platform-dependent tools, etc., but the user is shielded from the
 
400
            details wherever possible.
 
401
        </p>
 
402
    </answer>
 
403
 
 
404
 
 
405
 
 
406
    <answer id="deploy-dependencies">
 
407
        Nothing.
 
408
    </answer>
 
409
 
 
410
 
 
411
 
 
412
<!--
 
413
        <question id="deploy-jar" when="impl">
 
414
            Do you deploy just module JAR file(s) or other files as well?
 
415
            <hint>
 
416
            If your module consists of just one module JAR file, just confirm that.
 
417
            If it uses more than one JAR, describe where they are located, how
 
418
            they refer to each other. 
 
419
            If it consist of module JAR(s) and other files, please describe
 
420
            what is their purpose, why other files are necessary. Please 
 
421
            make sure that installation/uninstallation leaves the system 
 
422
            in state as it was before installation.
 
423
            </hint>
 
424
        </question>
 
425
-->
 
426
    <answer id="deploy-jar">
 
427
        <p>
 
428
            The module itself is contained in a regular module JAR. The bundled
 
429
            Ant installation is contained in <code>ant/lib/*.jar</code> in the
 
430
            NetBeans installation. (It is necessary for the Ant libraries to be
 
431
            loaded explicitly and not be accessible directly from the module.)
 
432
            There is also a bridge JAR <code>ant/nblib/bridge.jar</code> which
 
433
            communicates between Ant itself and the module.
 
434
        </p>
 
435
    </answer>
 
436
 
 
437
 
 
438
 
 
439
<!--
 
440
        <question id="deploy-nbm" when="impl">
 
441
            Can you deploy an NBM via the Update Center?
 
442
            <hint>
 
443
            If not why?
 
444
            </hint>
 
445
        </question>
 
446
-->
 
447
    <answer id="deploy-nbm">
 
448
        <p>
 
449
            Yes.
 
450
        </p>
 
451
    </answer>
 
452
 
 
453
 
 
454
 
 
455
<!--
 
456
        <question id="deploy-packages" when="init">
 
457
            Are packages of your module made inaccessible by not declaring them
 
458
            public?
 
459
            
 
460
            <hint>
 
461
            NetBeans module system allows restriction of access rights to
 
462
            public classes of your module from other modules. This prevents
 
463
            unwanted dependencies of others on your code and should be used
 
464
            whenever possible (<a href="http://www.netbeans.org/download/javadoc/OpenAPIs/org/openide/doc-files/upgrade.html#3.4-public-packages">
 
465
            public packages
 
466
            </a>). If you do not restrict access to your classes you are
 
467
            making it too easy for other people to misuse your implementation
 
468
            details, that is why you should have good reason for not 
 
469
            restricting package access.
 
470
            </hint>
 
471
        </question>
 
472
-->
 
473
    <answer id="deploy-packages">
 
474
        <p>
 
475
            Yes, only official packages are exported.
 
476
        </p>
 
477
    </answer>
 
478
 
 
479
 
 
480
 
 
481
<!--
 
482
        <question id="deploy-shared" when="final">
 
483
            Do you need to be installed in the shared location only, or in the user directory only,
 
484
            or can your module be installed anywhere?
 
485
            <hint>
 
486
            Installation location shall not matter, if it does explain why.
 
487
            Consider also whether <code>InstalledFileLocator</code> can help.
 
488
            </hint>
 
489
        </question>
 
490
-->
 
491
    <answer id="deploy-shared">
 
492
        <p>
 
493
            Should not matter where. <code>InstalledFileLocator</code> is used.
 
494
        </p>
 
495
    </answer>
 
496
 
 
497
 
 
498
 
 
499
<!--
 
500
        <question id="exec-classloader" when="impl">
 
501
            Does your code create its own class loader(s)?
 
502
            <hint>
 
503
            A bit unusual. Please explain why and what for.
 
504
            </hint>
 
505
        </question>
 
506
-->
 
507
    <answer id="exec-classloader">
 
508
        <p>
 
509
            Yes, several class loaders are created:
 
510
        </p>
 
511
        <ol>
 
512
            <li>
 
513
                <p>
 
514
                    Ant itself is loaded from a class loader containing just
 
515
                    <code>ant/lib/*.jar</code> (or generally from
 
516
                    <code>lib/*.jar</code> in a user-specified Ant installation
 
517
                    directory), plus any user-specified additional classpath
 
518
                    entries and entries from <code>AutomaticExtraClasspathProvider</code>.
 
519
                </p>
 
520
                <p>
 
521
                    <code>InstalledFileLocator</code> is used to find
 
522
                    <code>ant/lib/ant.jar</code> and the default Ant installation
 
523
                    is taken to be the parent directory of the containing directory
 
524
                    of this (e.g. <code>ide5/ant/</code>).
 
525
                </p>
 
526
                <p>
 
527
                    If any files <code>ant/patches/*.jar</code> exist, they are
 
528
                    loaded at the front of the classpath, to permit an IDE distribution
 
529
                    to bundle a version of Ant with patches (e.g. for #47708).
 
530
                </p>
 
531
            </li>
 
532
            <li>
 
533
                <p>
 
534
                    <code>ant/nblib/bridge.jar</code> is loaded from a class
 
535
                    loader delegating to both the main Ant loader, and the Ant
 
536
                    module's class loader.
 
537
                </p>
 
538
            </li>
 
539
            <li>
 
540
                <p>
 
541
                    Each module with a custom definition JAR in
 
542
                    <code>ant/nblib/*.jar</code> gets a class loader delegating
 
543
                    to both the main Ant loader, and that module's class loader.
 
544
                </p>
 
545
            </li>
 
546
        </ol>
 
547
    </answer>
 
548
 
 
549
 
 
550
 
 
551
<!--
 
552
        <question id="exec-component" when="impl">
 
553
            Is execution of your code influenced by any (string) property
 
554
            of any of your components?
 
555
            
 
556
            <hint>
 
557
            Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
 
558
            or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
 
559
            a behavior of some code. This of course forms an interface that should
 
560
            be documented. Also if one depends on some interface that an object
 
561
            implements (<code>component instanceof Runnable</code>) that forms an
 
562
            API as well.
 
563
            </hint>
 
564
        </question>
 
565
-->
 
566
    <answer id="exec-component">
 
567
        <p>
 
568
            No.
 
569
        </p>
 
570
    </answer>
 
571
 
 
572
 
 
573
 
 
574
<!--
 
575
        <question id="exec-introspection" when="impl">
 
576
            Does your module use any kind of runtime type information (<code>instanceof</code>,
 
577
            work with <code>java.lang.Class</code>, etc.)?
 
578
            <hint>
 
579
            Check for cases when you have an object of type A and you also
 
580
            expect it to (possibly) be of type B and do some special action. That
 
581
            should be documented. The same applies on operations in meta-level
 
582
            (Class.isInstance(...), Class.isAssignableFrom(...), etc.).
 
583
            </hint>
 
584
        </question>
 
585
-->
 
586
    <answer id="exec-introspection">
 
587
        <p>
 
588
            Yes, internally (not at the API level). Loading and introspecting
 
589
            task classes, loading Ant itself, checking for different Ant
 
590
            versions, etc. all require some use of reflection.
 
591
        </p>
 
592
    </answer>
 
593
 
 
594
 
 
595
 
 
596
<!--
 
597
        <question id="exec-privateaccess" when="final">
 
598
            Are you aware of any other parts of the system calling some of 
 
599
            your methods by reflection?
 
600
            <hint>
 
601
            If so, describe the "contract" as an API. Likely private or friend one, but
 
602
            still API and consider rewrite of it.
 
603
            </hint>
 
604
        </question>
 
605
-->
 
606
    <answer id="exec-privateaccess">
 
607
        <p>
 
608
            No.
 
609
        </p>
 
610
    </answer>
 
611
 
 
612
 
 
613
 
 
614
<!--
 
615
        <question id="exec-process" when="impl">
 
616
            Do you execute an external process from your module? How do you ensure
 
617
            that the result is the same on different platforms? Do you parse output?
 
618
            Do you depend on result code?
 
619
            <hint>
 
620
            If you feed an input, parse the output please declare that as an API.
 
621
            </hint>
 
622
        </question>
 
623
-->
 
624
    <answer id="exec-process">
 
625
        <p>
 
626
            Of course, Ant is run (as a VM-internal process). Ant itself handles
 
627
            platform issues for the most part. Output is sent by Ant directly to
 
628
            NetBeans-specific <code>AntLogger</code>s.
 
629
        </p>
 
630
    </answer>
 
631
 
 
632
 
 
633
 
 
634
<!--
 
635
        <question id="exec-property" when="impl">
 
636
            Is execution of your code influenced by any environment or
 
637
            Java system (<code>System.getProperty</code>) property?
 
638
            
 
639
            <hint>
 
640
            If there is a property that can change the behavior of your 
 
641
            code, somebody will likely use it. You should describe what it does 
 
642
            and the <a href="http://openide.netbeans.org/tutorial/api-design.html#life">stability category</a>
 
643
            of this API. You may use
 
644
            <pre>
 
645
                &lt;api type="export" group="property" name="id" category="private" url="http://..."&gt;
 
646
                    description of the property, where it is used, what it influence, etc.
 
647
                &lt;/api&gt;            
 
648
            </pre>
 
649
            </hint>
 
650
        </question>
 
651
-->
 
652
    <answer id="exec-property">
 
653
        <p>
 
654
            Generally not except for <a
 
655
            href="http://ant.apache.org/manual/running.html#sysprops">properties
 
656
            interpreted by Ant itself</a>.
 
657
        </p>
 
658
    </answer>
 
659
 
 
660
 
 
661
 
 
662
<!--
 
663
        <question id="exec-reflection" when="impl">
 
664
            Does your code use Java Reflection to execute other code?
 
665
            <hint>
 
666
            This usually indicates a missing or insufficient API in the other
 
667
            part of the system. If the other side is not aware of your dependency
 
668
            this contract can be easily broken.
 
669
            </hint>
 
670
        </question>
 
671
-->
 
672
    <answer id="exec-reflection">
 
673
        <p>
 
674
            Yes, see <a href="#answer-exec-introspection">introspection</a> for details.
 
675
        </p>
 
676
    </answer>
 
677
 
 
678
 
 
679
 
 
680
<!--
 
681
        <question id="exec-threading" when="impl">
 
682
            What threading models, if any, does your module adhere to?
 
683
            <hint>
 
684
                If your module calls foreign APIs which have a specific threading model,
 
685
                indicate how you comply with the requirements for multithreaded access
 
686
                (synchronization, mutexes, etc.) applicable to those APIs.
 
687
                If your module defines any APIs, or has complex internal structures
 
688
                that might be used from multiple threads, declare how you protect
 
689
                data against concurrent access, race conditions, deadlocks, etc.,
 
690
                and whether such rules are enforced by runtime warnings, errors, assertions, etc.
 
691
                Examples: a class might be non-thread-safe (like Java Collections); might
 
692
                be fully thread-safe (internal locking); might require access through a mutex
 
693
                (and may or may not automatically acquire that mutex on behalf of a client method);
 
694
                might be able to run only in the event queue; etc.
 
695
                Also describe when any events are fired: synchronously, asynchronously, etc.
 
696
                Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations">Threading Recommendations</a> (in progress)
 
697
            </hint>
 
698
        </question>
 
699
-->
 
700
    <answer id="exec-threading">
 
701
        <p>
 
702
            <code>IntrospectedInfo</code> should be thread-safe and fires changes
 
703
            asynchronously. Other API-visible classes are generally thread-safe
 
704
            unless otherwise noted. Internal classes follow natural Datasystems,
 
705
            Nodes, etc. threading models. Running an Ant target uses the
 
706
            execution engine, which spawns a fresh thread.
 
707
            <code>AntLogger</code>s are stateless and must be reentrant for multiple threads;
 
708
            <code>AntSession</code>s and so on are thread-safe.
 
709
        </p>
 
710
    </answer>
 
711
 
 
712
 
 
713
 
 
714
<!--
 
715
        <question id="format-clipboard" when="impl">
 
716
            Which data flavors (if any) does your code read from or insert to
 
717
            the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
 
718
            
 
719
            <hint>
 
720
            Often Node's deal with clipboard by usage of <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
 
721
            Check your code for overriding these methods.
 
722
            </hint>
 
723
        </question>
 
724
-->
 
725
    <answer id="format-clipboard">
 
726
        <p>
 
727
            None.
 
728
        </p>
 
729
    </answer>
 
730
 
 
731
 
 
732
 
 
733
<!--
 
734
        <question id="format-dnd" when="impl">
 
735
            Which protocols (if any) does your code understand during Drag &amp; Drop?
 
736
            <hint>
 
737
            Often Node's deal with clipboard by usage of <code>Node.drag, Node.getDropType</code>. 
 
738
            Check your code for overriding these methods. Btw. if they are not overridden, they
 
739
            by default delegate to <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
 
740
            </hint>
 
741
        </question>
 
742
-->
 
743
    <answer id="format-dnd">
 
744
        <p>
 
745
            None.
 
746
        </p>
 
747
    </answer>
 
748
 
 
749
 
 
750
 
 
751
<!--
 
752
        <question id="format-types" when="impl">
 
753
            Which protocols and file formats (if any) does your module read or write on disk,
 
754
            or transmit or receive over the network?
 
755
        </question>
 
756
-->
 
757
    <answer id="format-types">
 
758
        <p>
 
759
            Reads Ant scripts, of course. Also understands Ant 1.6's
 
760
            <code>antlib.xml</code> syntax in custom task/type definition JARs.
 
761
        </p>
 
762
    </answer>
 
763
 
 
764
 
 
765
 
 
766
<!--
 
767
        <question id="lookup-lookup" when="init">
 
768
            Does your module use <code>org.openide.util.Lookup</code>
 
769
            or any similar technology to find any components to communicate with? Which ones?
 
770
            
 
771
            <hint>
 
772
            Please describe the interfaces you are searching for, where 
 
773
            are defined, whether you are searching for just one or more of them,
 
774
            if the order is important, etc. Also classify the stability of such
 
775
            API contract.
 
776
            </hint>
 
777
        </question>
 
778
-->
 
779
    <answer id="lookup-lookup">
 
780
        <p>
 
781
            Uses various <code>getDefault</code> methods on standard helper
 
782
            classes. Looks for all <code>ModuleInfo</code> instances in default
 
783
            lookup to know in which enabled modules to search for custom
 
784
            definitions.
 
785
            Looks for instances of <code>AutomaticExtraClasspathProvider</code>
 
786
            and <code>AntLogger</code> in default lookup.
 
787
        </p>
 
788
    </answer>
 
789
 
 
790
 
 
791
 
 
792
<!--
 
793
        <question id="lookup-register" when="final">
 
794
            Do you register anything into lookup for other code to find?
 
795
            <hint>
 
796
            Do you register using layer file or using <code>META-INF/services</code>?
 
797
            Who is supposed to find your component?
 
798
            </hint>
 
799
        </question>
 
800
-->
 
801
    <answer id="lookup-register">
 
802
        <p>
 
803
            Just a MIME resolver.
 
804
            Also a default <code>AntLogger</code> is registered.
 
805
        </p>
 
806
    </answer>
 
807
 
 
808
 
 
809
 
 
810
<!--
 
811
        <question id="lookup-remove" when="final">
 
812
            Do you remove entries of other modules from lookup?
 
813
            <hint>
 
814
            Why? Of course, that is possible, but it can be dangerous. Is the module
 
815
            your are masking resource from aware of what you are doing?
 
816
            </hint>
 
817
        </question>
 
818
-->
 
819
    <answer id="lookup-remove">
 
820
        <p>
 
821
            No.
 
822
        </p>
 
823
    </answer>
 
824
 
 
825
 
 
826
 
 
827
<!--
 
828
        <question id="perf-exit" when="final">
 
829
            Does your module run any code on exit?
 
830
        </question>
 
831
-->
 
832
    <answer id="perf-exit">
 
833
        <p>
 
834
            Cleans up stray editor annotations.
 
835
        </p>
 
836
    </answer>
 
837
 
 
838
 
 
839
 
 
840
<!--
 
841
        <question id="perf-huge_dialogs" when="final">
 
842
            Does your module contain any dialogs or wizards with a large number of
 
843
            GUI controls such as combo boxes, lists, trees, or text areas?
 
844
        </question>
 
845
-->
 
846
    <answer id="perf-huge_dialogs">
 
847
        <p>
 
848
            The Ant Shortcut Wizard contains several panels. Otherwise all
 
849
            dialogs are pretty small.
 
850
        </p>
 
851
    </answer>
 
852
 
 
853
 
 
854
 
 
855
<!--
 
856
        <question id="perf-limit" when="init">
 
857
            Are there any hard-coded or practical limits in the number or size of
 
858
            elements your code can handle?
 
859
        </question>
 
860
-->
 
861
    <answer id="perf-limit">
 
862
        <p>
 
863
            None known.
 
864
        </p>
 
865
    </answer>
 
866
 
 
867
 
 
868
 
 
869
<!--
 
870
        <question id="perf-mem" when="final">
 
871
            How much memory does your component consume? Estimate
 
872
            with a relation to the number of windows, etc.
 
873
        </question>
 
874
-->
 
875
    <answer id="perf-mem">
 
876
        <p>
 
877
            The main question is how much memory a build consumes as it runs. Can
 
878
            be substantial - will easily keep a default 96Mb heap filled - but
 
879
            does not appear to leak. Ant itself mostly uses memory linearly (i.e.
 
880
            allocates and soon releases it), except for deeply nested build
 
881
            scripts. Tasks which are likely to consume a lot of heap (e.g.
 
882
            Javadoc) are typically run as external processes by default.
 
883
        </p>
 
884
    </answer>
 
885
 
 
886
 
 
887
 
 
888
<!--
 
889
        <question id="perf-menus" when="final">
 
890
            Does your module use dynamically updated context menus, or
 
891
            context-sensitive actions with complicated enablement logic?
 
892
        </question>
 
893
-->
 
894
    <answer id="perf-menus">
 
895
        <p>
 
896
            The <b>Run&nbsp;Target...</b> context menu on a build script is
 
897
            calculated from the script's targets.
 
898
        </p>
 
899
        <p>
 
900
            Menu items which are Ant shortcuts are enabled or not according to
 
901
            whether the script is well-formed.
 
902
        </p>
 
903
    </answer>
 
904
 
 
905
 
 
906
 
 
907
<!--
 
908
        <question id="perf-progress" when="final">
 
909
            Does your module execute any long-running tasks?
 
910
            
 
911
            <hint>Long running tasks should never block 
 
912
            AWT thread as it badly hurts the UI
 
913
            <a href="http://performance.netbeans.org/responsiveness/issues.html">
 
914
            responsiveness</a>.
 
915
            Tasks like connecting over
 
916
            network, computing huge amount of data, compilation
 
917
            be done asynchronously (for example
 
918
            using <code>RequestProcessor</code>), definitively it should 
 
919
            not block AWT thread.
 
920
            </hint>
 
921
        </question>
 
922
-->
 
923
    <answer id="perf-progress">
 
924
        <p>
 
925
            Running Ant processes are put in the execution engine but not displayed by it.
 
926
        </p>
 
927
        <p>
 
928
            Loading introspected info for the Ant installation is a
 
929
            once-per-session hit of perhaps half a second. This would typically
 
930
            occur when first running an Ant script, or first getting code
 
931
            completion, etc.
 
932
        </p>
 
933
    </answer>
 
934
 
 
935
 
 
936
 
 
937
<!--
 
938
        <question id="perf-scale" when="init">
 
939
            Which external criteria influence the performance of your
 
940
            program (size of file in editor, number of files in menu, 
 
941
            in source directory, etc.) and how well your code scales?
 
942
            <hint>
 
943
            Please include some estimates, there are other more detailed 
 
944
            questions to answer in later phases of implementation. 
 
945
            </hint>
 
946
        </question>
 
947
-->
 
948
    <answer id="perf-scale">
 
949
        <p>
 
950
            Most interesting criteria relate to performance of Ant itself, which
 
951
            seems fine.
 
952
        </p>
 
953
        <p>
 
954
            Adding an extra module with custom task definitions add a small
 
955
            overhead (10msec?) to launching an Ant script. The time is largely
 
956
            spent in Ant itself so is difficult to optimize out.
 
957
        </p>
 
958
        <p>
 
959
            Adding new <code>AntLogger</code>s will slow down Ant output a little
 
960
            bit, but it seems not significantly compared to typical overhead of
 
961
            Ant tasks themselves.
 
962
        </p>
 
963
    </answer>
 
964
 
 
965
 
 
966
 
 
967
<!--
 
968
        <question id="perf-spi" when="init">
 
969
            How the performance of the plugged in code will be enforced?
 
970
            <hint>
 
971
            If you allow foreign code to be plugged into your own module, how
 
972
            do you enforce, that it will behave correctly and fast and will not
 
973
            negatively influence the performance of your own module?
 
974
            </hint>
 
975
        </question>
 
976
-->
 
977
    <answer id="perf-spi">
 
978
        <p>
 
979
            Nothing special is done in this regard for most SPIs.
 
980
            <code>AntLogger</code> has a number of mask methods which permit the
 
981
            Ant module to exclude some loggers from consideration for delivery
 
982
            of a given event.
 
983
        </p>
 
984
    </answer>
 
985
 
 
986
 
 
987
 
 
988
<!--
 
989
        <question id="perf-startup" when="final">
 
990
            Does your module run any code on startup?
 
991
        </question>
 
992
-->
 
993
    <answer id="perf-startup">
 
994
        <p>
 
995
            No.
 
996
        </p>
 
997
    </answer>
 
998
 
 
999
 
 
1000
 
 
1001
<!--
 
1002
        <question id="perf-wakeup" when="final">
 
1003
            Does any piece of your code wake up periodically and do something
 
1004
            even when the system is otherwise idle (no user interaction)?
 
1005
        </question>
 
1006
-->
 
1007
    <answer id="perf-wakeup">
 
1008
        <p>
 
1009
            No.
 
1010
        </p>
 
1011
    </answer>
 
1012
 
 
1013
 
 
1014
 
 
1015
<!--
 
1016
        <question id="resources-file" when="final">
 
1017
            Does your module use <code>java.io.File</code> directly?
 
1018
            
 
1019
            <hint>
 
1020
            NetBeans provide a logical wrapper over plain files called 
 
1021
            <code>org.openide.filesystems.FileObject</code> that
 
1022
            provides uniform access to such resources and is the preferred
 
1023
            way that should be used. But of course there can be situations when
 
1024
            this is not suitable.
 
1025
            </hint>
 
1026
        </question>
 
1027
-->
 
1028
    <answer id="resources-file">
 
1029
        <p>
 
1030
            <code>java.io.File</code> is used by Ant itself, so the module uses
 
1031
            it too when appropriate. The Filesystems API is used where ability to
 
1032
            execute a script is irrelevant; or where the ability to refresh file
 
1033
            objects is needed.
 
1034
        </p>
 
1035
    </answer>
 
1036
 
 
1037
 
 
1038
 
 
1039
<!--
 
1040
        <question id="resources-layer" when="final">
 
1041
            Does your module provide own layer? Does it create any files or
 
1042
            folders in it? What it is trying to communicate by that and with which 
 
1043
            components?
 
1044
            
 
1045
            <hint>
 
1046
            NetBeans allows automatic and declarative installation of resources 
 
1047
            by module layers. Module register files into appropriate places
 
1048
            and other components use that information to perform their task
 
1049
            (build menu, toolbar, window layout, list of templates, set of
 
1050
            options, etc.). 
 
1051
            </hint>
 
1052
        </question>
 
1053
-->
 
1054
    <answer id="resources-layer">
 
1055
        <p>
 
1056
            Yes; the layer includes templates, editor annotation
 
1057
            definitions, etc.
 
1058
        </p>
 
1059
    </answer>
 
1060
 
 
1061
 
 
1062
 
 
1063
<!--
 
1064
        <question id="resources-mask" when="final">
 
1065
            Does your module mask/hide/override any resources provided by other modules in
 
1066
            their layers?
 
1067
            
 
1068
            <hint>
 
1069
            If you mask a file provided by another module, you probably depend
 
1070
            on that and do not want the other module to (for example) change
 
1071
            the file's name. That module shall thus make that file available as an API
 
1072
            of some stability category.
 
1073
            </hint>
 
1074
        </question>
 
1075
-->
 
1076
    <answer id="resources-mask">
 
1077
        <p>
 
1078
            No.
 
1079
        </p>
 
1080
    </answer>
 
1081
 
 
1082
 
 
1083
 
 
1084
<!--
 
1085
        <question id="resources-read" when="final">
 
1086
            Does your module read any resources from layers? For what purpose?
 
1087
            
 
1088
            <hint>
 
1089
            As this is some kind of intermodule dependency, it is a kind of API.
 
1090
            Please describe it and classify according to 
 
1091
            <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
 
1092
            common stability categories</a>.
 
1093
            </hint>
 
1094
        </question>
 
1095
-->
 
1096
    <answer id="resources-read">
 
1097
        <api category="devel" group="layer" name="layer-actions" type="export">
 
1098
            <p>
 
1099
                Context menu actions are read from the layer folder
 
1100
                <code>Loaders/text/x-ant+xml/Actions</code>.
 
1101
            </p>
 
1102
        </api>
 
1103
    </answer>
 
1104
 
 
1105
<!--
 
1106
        <question id="security-grant" when="final">
 
1107
            Does your code grant addition rights to some code?
 
1108
            <hint>Avoid using a classloder that adds some extra
 
1109
            permissions to loaded code unless realy necessary.
 
1110
            Also note that your API implementation
 
1111
            can also expose unneeded permissions to enemy code by
 
1112
            AccessController.doPrilileged() calls.</hint>
 
1113
        </question>
 
1114
-->
 
1115
    <answer id="security-grant">
 
1116
        <p>
 
1117
            Yes, running Ant creates several class loaders to which all permissions
 
1118
            are granted. A wide variety of permissions are needed by various tasks.
 
1119
        </p>
 
1120
    </answer>
 
1121
 
 
1122
 
 
1123
 
 
1124
<!--
 
1125
        <question id="security-policy" when="final">
 
1126
            Does your functionality require standard policy file modification?
 
1127
            <hint>Your code may pass control to third party code not
 
1128
            coming from trusted domain. It covers code downloaded over
 
1129
            network or code coming from libraries that are not bundled
 
1130
            with NetBeans. Which permissions it needs to grant to which domain?</hint>
 
1131
        </question>
 
1132
-->
 
1133
    <answer id="security-policy">
 
1134
        <p>
 
1135
            No policy file modifications needed. All permissions granted.
 
1136
        </p>
 
1137
    </answer>
 
1138
 
 
1139
<!--
 
1140
        <question id="exec-ant-tasks" when="impl">
 
1141
            Do you define or register any ant tasks that other can use?
 
1142
            
 
1143
            <hint>
 
1144
            If you provide an ant task that users can use, you need to be very
 
1145
            careful about its syntax and behaviour, as it most likely forms an
 
1146
                  API for end users and as there is a lot of end users, their reaction
 
1147
            when such API gets broken can be pretty strong.
 
1148
            </hint>
 
1149
        </question>
 
1150
-->
 
1151
    <answer id="exec-ant-tasks">
 
1152
        <p>
 
1153
            No.
 
1154
        </p>
 
1155
    </answer>
 
1156
 
 
1157
 
 
1158
 
 
1159
 
 
1160
<!--
 
1161
        <question id="arch-where" when="init">
 
1162
            Where one can find sources for your module?
 
1163
            <hint>
 
1164
                Please provide link to the CVS web client at
 
1165
                http://www.netbeans.org/download/source_browse.html
 
1166
                or just use tag defaultanswer generate='here'
 
1167
            </hint>
 
1168
        </question>
 
1169
-->
 
1170
    <answer id="arch-where">
 
1171
        <defaultanswer generate='here' />
 
1172
    </answer>
 
1173
 
 
1174
</api-answers>