NetBeans Architecture Answers for Ant module

General Information

Question (arch-what): What is this project good for?
Answer:

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:

1. AntLogger -

   Permits customization of the way Ant output is displayed.

2. register-defs -

   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.

3. AutomaticExtraClasspathProvider -

   Permits additions to the default Ant classpath.

4. IntrospectedInfo -

   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.

5. AntTargetExecutor -

   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.

Question (arch-usecases): Describe the main use cases of the new API. Who will use it under what circumstances? What kind of code would typically need to be written to use the module?
Answer:

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 NetBeans CVS in ant directory.

Project and platform dependencies

Question (dep-nb): What other NetBeans projects and modules does this one depend on?
Answer:

• FilesystemsAPI and DatasystemsAPI for dealing with files including Ant scripts.

• NodesAPI, ActionsAPI, WindowSystemAPI, OptionsAPI, EditorAPI, etc. for providing the various GUI components of the module.

• ModulesAPI - for finding enabled modules to possibly load custom definitions from.
• ExecutionAPI - for running scripts in the execution engine.
• InputOutputAPI - for displaying output from Ant in the Output Window.
• JavaSupportAPIs - for getting an appropriate class loader from a given source file.
Question (dep-non-nb): What other projects outside NetBeans does this one depend on?
Answer:
1. Ant - Ant itself, of course. 1.5.3+ is required, 1.7.0 recommended (and currently bundled); some features may be limited to newer versions.
Question (dep-platform): On which platforms does your module run? Does it run in the same way on each?
Answer:

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.

Deployment

Question (deploy-jar): Do you deploy just module JAR file(s) or other files as well?
Answer:

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.

Question (deploy-nbm): Can you deploy an NBM via the Update Center?
Answer:

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.

Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public?
Answer:

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.

Compatibility with environment

Question (compat-i18n): Is your module correctly internationalized?
Answer:

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!

Access to resources

Question (resources-file): Does your module use 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.

Question (resources-layer): Does your module provide own layer? Does it create any files or folders in it? What it is trying to communicate by that and with which components?
Answer:

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.

Question (resources-mask): Does your module mask/hide/override any resources provided by other modules in their layers?
Answer:

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!

Lookup of components

Question (lookup-lookup): Does your module use 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.

Question (lookup-register): Do you register anything into lookup for other code to find?
Answer:

Just a MIME resolver. Also a default AntLogger is registered.

Question (lookup-remove): Do you remove entries of other modules from lookup?
Answer:

No.

Execution Environment

Question (exec-property): Is execution of your code influenced by any environment or Java system (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.

Question (exec-component): Is execution of your code influenced by any (string) property of any of your components?
Answer:

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:

1. 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. ide5/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).

2. ant/nblib/bridge.jar is loaded from a class loader delegating to both the main Ant loader, and the Ant module's class loader.

3. 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.

Question (exec-reflection): Does your code use Java Reflection to execute other code?
Answer:

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.

Question (exec-introspection): Does your module use any kind of runtime type information (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.

Question (security-policy): Does your functionality require modifications to the standard policy file?
Answer:

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.

Format of files and protocols

Question (format-types): Which protocols and file formats (if any) does your module read or write on disk, or transmit or receive over the network? Do you generate an ant build script? Can it be edited and modified?
Answer:

Reads Ant scripts, of course. Also understands Ant 1.6's antlib.xml syntax in custom task/type definition JARs.

Question (format-dnd): Which protocols (if any) does your code understand during Drag & Drop?
Answer:

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 on java.awt.datatransfer.Transferable?
Answer:

None.

Performance and Scalability

Question (perf-startup): Does your module run any code on startup?
Answer:

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.

Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle?
Answer:

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.