|
|
|
|
The Ant integration module recognizes Ant build scripts, facilitates editing them as text or structurally, lets the user run targets or create shortcuts to them, etc.
Question (arch-overall): Describe the overall architecture. Answer:The main uses of the Ant integration module are self-contained and do not interact directly with other modules: the user selects a target in an Ant script and runs it. Nonetheless, there are a few significant ways other modules can interact with this module:
Permits customization of the way Ant output is displayed.
Registering custom Ant task and type definitions (when these can be run inside the NetBeans JVM only). Typically used to add special tasks which somehow script the IDE, such as connecting the JPDA debugger to a process launched by Ant.
Permits additions to the default Ant classpath.
Examining cached and introspected data about which tasks and types are known to be defined in the user's Ant scripts, and what their design-time structure is. Used by XML code completion, for example.
Running named targets in specified Ant scripts. Can be used
by modules which provide a different UI for initiating Ant
execution. ActionUtils provides a more convenient
wrapper around this functionality.
The principal use cases for the API are covered in the overall API architecture.
Question (arch-time): What are the time estimates of the work? Answer:N/A; already implemented.
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented? Answer:Currently a fair amount of the module is covered by functional tests. There are some unit tests, especially for newer code.
Question (arch-where): Where one can find sources for your module? Answer:
The sources for the module are in the Apache Git repositories or in the GitHub repositories.
These modules are required in project.xml:
Should be as platform-independent as Ant itself is. Ant uses some platform-specific tricks to normalize pathnames, launch platform-dependent tools, etc., but the user is shielded from the details wherever possible.
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)? Answer:JRE 1.5 is required.
Question (dep-jrejdk): Do you require the JDK or is the JRE enough? Answer:The module itself requires only the JRE, but Ant requires the JDK in order to do anything useful such as compile Java classes.
The module itself is contained in a regular module JAR. The bundled
Ant installation is contained in ant/lib/*.jar in the
NetBeans installation. (It is necessary for the Ant libraries to be
loaded explicitly and not be accessible directly from the module.)
There is also a bridge JAR ant/nblib/bridge.jar which
communicates between Ant itself and the module.
Yes.
Question (deploy-shared): Do you need to be installed in the shared location only, or in the user directory only, or can your module be installed anywhere? Answer:
Should not matter where. InstalledFileLocator is used.
Yes, only official packages are exported.
Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one, in addition to or instead of the normal module dependency declaration (e.g. tokens to require)? Answer: Nothing.Visible strings directly represented by the module are internationalized. However Ant itself is not, and so messages coming from Ant will appear only in English.
Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow? Answer:Insofar as Ant can be considered a standard, it implements the standard behavior of running an Ant script. The implementation should behave quite similarly to what the normal Ant command-line usage does (since it delegates to the Ant library internally and only replaces the command-line wrapper with an IDE wrapper). Since the Ant project does not publish a formal specification of how Ant should behave, there is no objective criterion for judging the fidelity.
Likely areas of difference between command-line and IDE usage: obscure class loader scenarios (since the IDE must load Ant in a special class loader, whereas the command-line tool may do it differently); system properties set in the IDE but not on the command line; etc. Generally, well-written scripts and tasks are not affected by these differences, but occasionally problems arise (they are treated as bugs).
Question (compat-version): Can your module coexist with earlier and future versions of itself? Can you correctly read all old settings? Will future versions be able to read your current settings? Can you read or politely ignore settings stored by a future version? Answer:Loading older settings is generally supported for compatibility.
Question (compat-deprecation): How the introduction of your project influences functionality provided by previous version of the product? WARNING: Question with id="compat-deprecation" has not been answered!java.io.File directly?
Answer:
java.io.File is used by Ant itself, so the module uses
it too when appropriate. The Filesystems API is used where ability to
execute a script is irrelevant; or where the ability to refresh file
objects is needed.
Yes; the layer includes templates, editor annotation definitions, etc.
Question (resources-read): Does your module read any resources from layers? For what purpose? Answer: layer-actions -
Context menu actions are read from the layer folder
Loaders/text/x-ant+xml/Actions.
No.
Question (resources-preferences): Does your module uses preferences via Preferences API? Does your module use NbPreferences or or regular JDK Preferences ? Does it read, write or both ? Does it share preferences with other modules ? If so, then why ? WARNING: Question with id="resources-preferences" has not been answered!org.openide.util.Lookup
or any similar technology to find any components to communicate with? Which ones?
Answer:
Uses various getDefault methods on standard helper
classes. Looks for all ModuleInfo instances in default
lookup to know in which enabled modules to search for custom
definitions.
Looks for instances of AutomaticExtraClasspathProvider
and AntLogger in default lookup.
Just a MIME resolver.
Also a default AntLogger is registered.
No.
System.getProperty) property?
On a similar note, is there something interesting that you
pass to java.util.logging.Logger? Or do you observe
what others log?
Answer:
Generally not except for properties interpreted by Ant itself and the following:
If a longer message is logged the ant logger will handle the message as plain text and will not try to hyperlink, color, fold, etc. If not set by the user a default value of 3000 will be used.
No.
Question (exec-ant-tasks): Do you define or register any ant tasks that other can use? Answer:No.
Question (exec-classloader): Does your code create its own class loader(s)? Answer:Yes, several class loaders are created:
Ant itself is loaded from a class loader containing just
ant/lib/*.jar (or generally from
lib/*.jar in a user-specified Ant installation
directory), plus any user-specified additional classpath
entries and entries from AutomaticExtraClasspathProvider.
InstalledFileLocator is used to find
ant/lib/ant.jar and the default Ant installation
is taken to be the parent directory of the containing directory
of this (e.g. ide/ant/).
If any files ant/patches/*.jar exist, they are
loaded at the front of the classpath, to permit an IDE distribution
to bundle a version of Ant with patches (e.g. for #47708).
ant/nblib/bridge.jar is loaded from a class
loader delegating to both the main Ant loader, and the Ant
module's class loader.
Each module with a custom definition JAR in
ant/nblib/*.jar gets a class loader delegating
to both the main Ant loader, and that module's class loader.
Yes, see introspection for details.
Question (exec-privateaccess): Are you aware of any other parts of the system calling some of your methods by reflection? Answer:No.
Question (exec-process): Do you execute an external process from your module? How do you ensure that the result is the same on different platforms? Do you parse output? Do you depend on result code? Answer:
Of course, Ant is run (as a VM-internal process). Ant itself handles
platform issues for the most part. Output is sent by Ant directly to
NetBeans-specific AntLoggers.
instanceof,
work with java.lang.Class, etc.)?
Answer:
Yes, internally (not at the API level). Loading and introspecting task classes, loading Ant itself, checking for different Ant versions, etc. all require some use of reflection.
Question (exec-threading): What threading models, if any, does your module adhere to? How the project behaves with respect to threading? Answer:
IntrospectedInfo should be thread-safe and fires changes
asynchronously. Other API-visible classes are generally thread-safe
unless otherwise noted. Internal classes follow natural Datasystems,
Nodes, etc. threading models. Running an Ant target uses the
execution engine, which spawns a fresh thread.
AntLoggers are stateless and must be reentrant for multiple threads;
AntSessions and so on are thread-safe.
No policy file modifications needed. All permissions granted.
Question (security-grant): Does your code grant additional rights to some other code? Answer:Yes, running Ant creates several class loaders to which all permissions are granted. A wide variety of permissions are needed by various tasks.
Reads Ant scripts, of course. Also understands Ant 1.6's
antlib.xml syntax in custom task/type definition JARs.
None.
Question (format-clipboard): Which data flavors (if any) does your code read from or insert to the clipboard (by access to clipboard on means calling methods onjava.awt.datatransfer.Transferable?
Answer:
None.
No.
Question (perf-exit): Does your module run any code on exit? Answer:Cleans up stray editor annotations.
Question (perf-scale): Which external criteria influence the performance of your program (size of file in editor, number of files in menu, in source directory, etc.) and how well your code scales? Answer:Most interesting criteria relate to performance of Ant itself, which seems fine.
Adding an extra module with custom task definitions add a small overhead (10msec?) to launching an Ant script. The time is largely spent in Ant itself so is difficult to optimize out.
Adding new AntLoggers will slow down Ant output a little
bit, but it seems not significantly compared to typical overhead of
Ant tasks themselves.
None known.
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc. Answer:The main question is how much memory a build consumes as it runs. Can be substantial - will easily keep a default 96Mb heap filled - but does not appear to leak. Ant itself mostly uses memory linearly (i.e. allocates and soon releases it), except for deeply nested build scripts. Tasks which are likely to consume a lot of heap (e.g. Javadoc) are typically run as external processes by default.
Question (perf-wakeup): Does any piece of your code wake up periodically and do something even when the system is otherwise idle (no user interaction)? Answer:No.
Question (perf-progress): Does your module execute any long-running tasks? Answer:Running Ant processes are put in the execution engine but not displayed by it.
Loading introspected info for the Ant installation is a once-per-session hit of perhaps half a second. This would typically occur when first running an Ant script, or first getting code completion, etc.
Question (perf-huge_dialogs): Does your module contain any dialogs or wizards with a large number of GUI controls such as combo boxes, lists, trees, or text areas? Answer:The Ant Shortcut Wizard contains several panels. Otherwise all dialogs are pretty small.
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic? Answer:The Run Target... context menu on a build script is calculated from the script's targets.
Menu items which are Ant shortcuts are enabled or not according to whether the script is well-formed.
Question (perf-spi): How the performance of the plugged in code will be enforced? Answer:
Nothing special is done in this regard for most SPIs.
AntLogger has a number of mask methods which permit the
Ant module to exclude some loggers from consideration for delivery
of a given event.