NetBeans Architecture Answers for Issue Tracking module

General Information

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

The module allows to integrate Bugtracking systems into the IDE workflow.

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

The Bugtracking SPI/API makes it possible to integrate bugtracking system providers into the IDE workflow:
- to access and manage bugtracking Issues via the Tasks Dashboard
- to make bugtracking functionality accessible for integration with other subsystems in the IDE - e.g. VCS, Team Support (aka kenai.com, java.net)


BugrackingSPI - Enables Bugtracking modules to fully integrate into Bugtracking Issue Management facilities and other IDE workflow.

BugrackingAPI - Provides Bugtracking functionality for other subsystems in the IDE.

SPI Registration:
A bugtracking module extends BugtrackingConnector and registers it via the BugtrackingConnector.Registration annotation.

Cookbook and sample implementation:
For a more detailed description on how to start writting a bugtracking plugin for NetBeans see also the Bugtracking Cookbook (sample module attached).

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 main Bugtracking SPI and API Use Cases are based on:
- the Issue Management Use Cases. For additional information see also Tasks Dashboard UI spec


Registration and setup

The Bugtracking SPI provides a way to register bugtracking plugins and to setup remote Repository configurations of one kind.

Accessing Issues

All registered plugins provide the capability to access Issues from a Repository via:
- their ID
- based on a simple text criteria
- the capability to create, edit and execute more complex Queries

Issue management

For the needs of Issue Management all registered plugins provide: - the capability to create and edit Issues
- basic Issue information like id, summary, priority, scheduling ...

Automated Issue Operations

All registered plugins provide bugtracking functionality (if available) to other IDE workflows via the Bugtracking API. - e.g. attaching files, closing Issues, etc.

See also the more detailed API/SPI requirements.

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

The module is done.

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

Module's APIs will be tested by unit tests, all areas should be covered.

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.

Project and platform dependencies

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

These modules are required in project.xml:

• Progress - The module is needed for compilation. The module is used during runtime. Specification version 1.40 is required.
• ProgressSwing - The module is needed for compilation. The module is used during runtime. Specification version 1.40 is required.
• Keyring-API - The module is needed for compilation. The module is used during runtime. Specification version 1.0 is required.
• OptionsDialogSPI - The module is needed for compilation. The module is used during runtime. Specification version 1.29 is required.
• GeneralQueriesAPI - The module is needed for compilation. The module is used during runtime. Specification version 1.14 is required.
• SettingsAPI - The module is needed for compilation. The module is used during runtime. Specification version 1.41 is required.
• org.netbeans.modules.team.commons - The module is needed for compilation. The module is used during runtime. Specification version 1.45 is required.
• ActionsAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.13 is required.
• org.openide.awt - The module is needed for compilation. The module is used during runtime. Specification version 7.2 is required.
• DialogsAPI - The module is needed for compilation. The module is used during runtime. Specification version 7.9 is required.
• ExplorerAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.8 is required.
• FilesystemsAPI - The module is needed for compilation. The module is used during runtime. Specification version 9.0 is required.
• InputOutputAPI - The module is needed for compilation. The module is used during runtime. Specification version 1.16 is required.
• LoadersAPI - The module is needed for compilation. The module is used during runtime. Specification version 7.61 is required.
• ModulesAPI - The module is needed for compilation. The module is used during runtime. Specification version 7.34 is required.
• NodesAPI - The module is needed for compilation. The module is used during runtime. Specification version 7.23 is required.
• WeakListener.setAccessible - The module is needed for compilation. The module is used during runtime. Specification version 9.3 is required.
• LookupAPI - The module is needed for compilation. The module is used during runtime. Specification version 8.0 is required.
• UtilitiesAPI - The module is needed for compilation. The module is used during runtime. Specification version 9.3 is required.
• WindowSystemAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.24 is required.
Question (dep-non-nb): What other projects outside NetBeans does this one depend on?
Answer:

The module does NOT depend on any external projects.

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

The module does NOT depend on OS-specific features, it is pure Java.

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

1.7

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

No, JRE is enough.

Deployment

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

Just the module's JAR file.

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:

Does not matter.

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

Packages org.netbeans.modules.bugtracking.spi and org.netbeans.modules.bugtracking.api are declared as public, all others are left private.

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:

No special requirements here.

Compatibility with environment

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

Yes

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

The module does not implement or define any standards.

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:

Yes, the module is designed to evolve over time. Currently the module persists bugtracking repository properties (see  o.n.m.bugtracking.spi.RepositoryInfo) and some Tasks Dashboard settings via the standard NbPreferences API and ignores all other settings. It is expected, that it can live happily with future releases.

Question (compat-deprecation): How the introduction of your project influences functionality provided by previous version of the product?
Answer:

The module introduces a new SPI and API, it does not deprecate any old ones.

Access to resources

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

Yes it does, but FileObject-s are used in cases, when working with IDE relevant files.

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:

Not explicitely. Registration of some actions and the Tasks Dashboard Window is done via annotations.

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.

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 ?
Answer:

Yes, using NbPreferences for its own settings. It does not share them.

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:

The module uses default Lookup to:
- find registered bugtracking modules by searching for all  org.netbeans.modules.bugtracking.spi.BugtrackingConnector instaces. Order does not matter.
- find RepositoryQuery implementations by searching for all  org.netbeans.modules.bugtracking.spi.RepositoryQueryImplementations instances. Order does not matter.
- find implementations of  org.netbeans.modules.team.ide.spi.IDEServices and  org.netbeans.modules.team.ide.spi.ProjectServices for 1 expected instance.


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

javax.annotation.processing.Processor to handle registrations of  o.n.m.bugtracking.spi.BugtrackingConnector.Registration  - see o.n.m.bugtracking.BugtrackingRegistrationProcessor


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:

Yes:
- System.getProperty("netbeans.bugtracking.noOpenProjects") to block creating of team repositories based on open project beineg checked out from a Team Server (e.g. kenai.com, java.net).
- System.getProperty("netbeans.bugzilla.url") to override the hardcoded netbeans bugzilla url. Testing purposes only.
- System.getProperty("org.netbeans.modules.bugtracking.logPasswords") when logging repository information, the password isn't obfuscated. Diagnostic purposes only.


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

No, the module does not depend on any such public property. Maybe worth to mention, that on Issue editors, provided by the particular implementations,  setClientProperty("highlights.property", ...) is used internaly to store text higlight relevant information on TextPanes contained in those editor components.

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:

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.

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

Yes:
- the instanceof operator is used on several places, but all checks switching the control flow are made either on module private types or in cases like e.g. .equals(Object) .
-  Class.getName()  is used a couple of time, typicaly to use it for a Logger name. Otherwise no type relevant Class.* methods are not used.


Question (exec-threading): What threading models, if any, does your module adhere to? How the project behaves with respect to threading?
Answer:

The SPI defines entry points from the IDE to bugtracking implementors. There is no guarantee about threading, SPI methods can be called by any thread in any order, the SPI implementors must synchronize access to their structures as needed. All callbacks back to SPI are threadsafe.

In cases in the SPI (and accordingly and the API) where it is expected from the implementation to block for the whole time of execution it is pointed out in the javadoc.

In cases in the SPI where the call might be done in AWT and a fast exection is essential it is explicitely pointed out in the javadoc.

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:

The module does not communicate with ouside world via files/network protocols.

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

There is some internal Tasks Dashoard DnD interaction between different dashboard node containers (though not o.openide.nodes.Node).

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:

No clipboard interaction.

Performance and Scalability

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

No, also that the infrastructure waits until all projects are opened before populating the Tasks Dashboard in case it was opened from a previous session.

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

No.

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:

The amount of Issues listed in the Tasks Dashboard, though the relevant computations ( e.g. when expanding container nodes) aren't done in AWT.

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

No limits hardcoded. In extreme situations it might happen that a particular bugtracking implementation provides a too big amount of issues (tested with thousands without running into problems). Considering the fact, that the significant amount of involved data is generated in the involved bugtracking plugin, it is seen as its problem to handle such scenarious. The additional memory overhead caused by wrapping and handling the provided Issues in the bugtracking module is not relevant in the overall scheme of things.

Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc.
Answer:

Amount of memory is proportional to the size of opened issue and query editors as well as to the amount of registered repositories, queries and issues listed in the Tasks Dashboard. Exact memory consumption depends on the underlying bugtracking system implementations.


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:

Registered queries are periodicaly refeshed by a customizable interval with a default value.

Question (perf-progress): Does your module execute any long-running tasks?
Answer:

All long-running task (e.g. like executing and underlying query implementation) are done by using RequestProcessor.

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:

Yes, the Tasks Dashboard provides a tree of all known Repositories, Queries associated with those Repositories and Issues coming from those Queries. Typicaly it is not expected that a big amout of Queries is registered and only the first 50 of issues are listed, though it is possible for the user to change this setup.

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

No expensive menus or actions.

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

SPI will log (on demand) performance of calls on plugged-in implementations such like e.g. query.refresh(), issue.refresh(), ...