Overview

# NetBeans Architecture Answers for ant/project module

- Author: jglick@netbeans.org
- Answers as of: Dec 7, 2006
- Answers for questions version: 1.24
- Latest available version of questions: 1.26

WARNING: answering questions version 1.24 rather than the current 1.26.

## Interfaces table

##### Group of java interfaces

Interface Name | In/Out | Stability | Specified in What Document?
AntProjectAPI | Exported | Official | Mostly an SPI for creating project types centered around the Ant build tool. Permits Ant-based project types to be registered and supplies various support implementations to help satisfy the contract of `Project` and various optional interfaces.
Progress | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime.
ProjectAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 1.6 is required.
ProjectUIAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 1.8 is required.
GeneralQueriesAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime.
org.openide.awt | Imported | Official | ../org-openide-awt/overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
DialogsAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
FilesystemsAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
LoadersAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime.
ModulesAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
NodesAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
UtilitiesAPI | Imported | Official | ../org-openide-util/overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
WindowSystemAPI | Imported | Official | .../overview-summary.html The module is needed for compilation. The module is used during runtime. Specification version 6.5 is required.

##### Group of property interfaces

Interface Name | In/Out | Stability | Specified in What Document?
netbeans.do.not.check.xalan | Exported | Private | The "netbeans.do.not.check.xalan" property switches off the startup check for buggy Xalan. See issue #70130 for more information.

## General Information

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

Answer:

Provides the basic infrastructure by which Ant-based projects can be created, read and write configuration parameters and properties from/to disk, satisfy common queries and interfaces, etc. See Javadoc and build system design document.

Question (arch-overall): Describe the overall architecture.

Answer: AntProjectAPI -

Mostly an SPI for creating project types centered around the Ant build tool. Permits Ant-based project types to be registered and supplies various support implementations to help satisfy the contract of `Project` and various optional interfaces.

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:

Mostly an SPI for use by project type providers to create the project type. Also includes a small API/SPI for other projects to find what Ant build steps are necessary to create a certain build product, for use in inter-project dependencies.

Ant project support faq:

#### How to use support for storing project properties?

Q: I'm creating a customizer (properties dialog) for my project type. I wan't to use the support for simple data types. What do I need to do?

You basicaly need to do two things. First create the representation of the project properties which can be used in the GUI. Second at some time convert the objects back to the ANT properties form and store them into the project.

- Creating the object representation.
  1. Create new instance of StoreGroup for each group of properties you want to store later e.g. project and prvate. Sometimes it might be useful to create temporary source group which will only be used for creating the models without being used for storing. E.g. for properties which need special handling.
  2. Call the factory methods e.g. createBooleanButtonModel, createStringDocument, etc. which will create the swing models for you.
  3. Use the models in your Swing controls by calling setModel() or setDocument()
- Storing the models back to the proprties of project.
  1. Get the EditableProperties you want to store the model in e.g. private or project properties
  2. Call the store method on given SourceGroup with the EditableProperties as parameter
  3. Manually store models which need some special handling.

Question (arch-time): What are the time estimates of the work?

Answer:

Mostly complete; see Issuezilla for remaining items.

Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented?

Answer:

Should be covered by unit tests.

Question (arch-where): Where one can find sources for your module?

Answer:

The sources for the module are in NetBeans CVS in ant/project directory.

## Project and platform dependencies

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

Answer:

Filesystems, Datasystems (limited use and only internally), Project API, General Queries API, Utilities (e.g. `Mutex`).

Default answer to this question is:

These modules are required in project.xml file:

- Progress - The module is needed for compilation. The module is used during runtime.
- ProjectAPI - The module is needed for compilation. The module is used during runtime. Specification version 1.6 is required.
- ProjectUIAPI - The module is needed for compilation. The module is used during runtime. Specification version 1.8 is required.
- GeneralQueriesAPI - The module is needed for compilation. The module is used during runtime.
- org.openide.awt - The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
- DialogsAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
- FilesystemsAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
- LoadersAPI - The module is needed for compilation. The module is used during runtime.
- ModulesAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
- NodesAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
- UtilitiesAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.2 is required.
- WindowSystemAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.5 is required.

Question (dep-non-nb): What other projects outside NetBeans does this one depend on?

Answer:

None.

Question (dep-platform): On which platforms does your module run? Does it run in the same way on each?

Answer:

Any.

Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?

Answer:

1.4+.

Question (dep-jrejdk): Do you require the JDK or is the JRE enough?

Answer:

JRE, though many Ant tasks likely to be used by the project do require the JDK.

## Deployment

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

Answer:

Just a JAR.

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:

Anywhere.

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

Answer:

Yes, only API and SPI packages are exported.

Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one?

Answer:

       OpenIDE-Module-Module-Dependencies: org.netbeans.modules.project.ant/1 > 1.12.22

## Compatibility with environment

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

Answer:

Supports localized project display names. Does not support I18N of Ant build scripts, though I18N of build output is possible (not yet implemented) via `AntLogger` in the Ant Module API.

Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow?

Answer:

There are no known generally accepted standards for project metadata, so no.

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:

Projects are stored using namespaced XML so the schemas are versioned. Possible for project type providers to upgrade old projects.

## Access to resources

Question (resources-file): Does your module use `java.io.File` directly?

Answer:

Yes. Since Ant deals only with disk files, many aspects of this module deal directly with `File`s. Other parts use `FileObject` where appropriate.

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:

No.

Question (resources-read): Does your module read any resources from layers? For what purpose?

Answer:

No.

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

Answer:

No.

## 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:

Ant-based project type providers are searched for in lookup. `AntArtifactQuery` looks for implementations in lookup.

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

Answer:

The delegating singleton project factory is registered for the Project API to find. There is a delegating implementation of `AntArtifactQueryImplementation`.

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?

Answer:

Standard property evaluators mirror system properties, as does Ant.

netbeans.do.not.check.xalan - The "netbeans.do.not.check.xalan" property switches off the startup check for buggy Xalan. See issue #70130 for more information.

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?

WARNING: Question with id="exec-ant-tasks" has not been answered!

Question (exec-classloader): Does your code create its own class loader(s)?

Answer:

No.

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

Answer:

No.

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:

No. (The Ant module does run Ant, though in-VM.)

Question (exec-introspection): Does your module use any kind of runtime type information (`instanceof`, work with `java.lang.Class`, etc.)?

Answer:

A check for buggy Xalan is performed during startup. The test tries to lookup org.apache.xalan.Version class. If the class is not found, the buggy Xalan is not on the classpath. If the class can be resolved, other checks (not using Java reflection) are performed.

Question (exec-threading): What threading models, if any, does your module adhere to?

Answer:

Uses the Project API's read-write lock for most purposes. Some classes, such as the file built query implementation, use ad-hoc synchronization.

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

Answer:

No.

Question (security-grant): Does your code grant additional rights to some other code?

Answer:

No.

## 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 and writes project metadata as XML and as Java Properties files. XML files are controlled by namespaced schemas with a generic wrapper and extensible segments used by the project type and perhaps other modules. Writes Ant build scripts upon request.

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. Project types may however (re-)generate any necessary build scripts on startup or opening.

Moreover, a check for buggy Xalan is performed on the startup. The test should be very fast if the buggy Xalan is not detected. See issue #70130 for more information.

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

Answer:

No. Project types would commonly save any outstanding changes on exit however.

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:

Size of project metadata, perhaps, though typically this would be small. Number of files in the case of `GlobFileBuiltQuery`.

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:

Probably little for the project itself. `GlobFileBuiltQuery` consumes a modest amount of memory per file.

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:

No. (Ant builds run by the Ant module are run in the Execution Engine.)

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:

No GUI.

Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic?

Answer:

No.

Question (perf-spi): How the performance of the plugged in code will be enforced?

Answer:

No special provisions.

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.