NetBeans Architecture Answers for VCS Core API module

General Information

Question (arch-what): What is this project good for?
Answer: The VCS Core module provides basic structure and libraries on which support modules for various version control systems can be based. The modules, that integrate concrete version control systems into NetBeans IDE, depend on the VCS Core module. See vcscore.netbeans.org for more information.

List of the main features:

• Simple VCS API (See http://vcscore.netbeans.org/doc/VCSAPI.html for details).
• Versioning main menu.
• Generic mount action for VCS integrations.
• Provides VcsFileSystem, that can be used as a base for VCS integration.
• Mechanism for VCS commands execution including threads management and mutual commands synchronization.
• Nodes on Runtime tab representing running and finished commands.
• Component for displaying raw text output of commands with high throughoutput.
• Generic action with a popup menu of VCS commands with a tree-like structure.
• Versioning toolbar with pre-defined six generic actions.
• Caching infrastructure for persistent storage of VCS-related information about files.
• Vcs Groups with ability to group related files that the developer work on.
• Ability to seach the VCS filesystem by file status information.
• Versioning Explorer, that allows to browse individual file revisions and run commands on individual revision(s).
• Common VCS settings.
• Mounting wizard for CVS filesystem, that can mount built-in or command-line CVS client (which are in separate modules).
Question (arch-overall): Describe the overall architecture.
WARNING: Question with id="arch-overall" has not been answered!
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?
WARNING: Question with id="arch-usecases" has not been answered!
Question (arch-time): What are the time estimates of the work?
WARNING: Question with id="arch-time" has not been answered!
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented?
WARNING: Question with id="arch-quality" has not been answered!

Project and platform dependencies

Question (dep-nb): What other NetBeans projects and modules does this one depend on?
Answer: OpenAPIs OpenAPIsExtensions
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: The module is 100% pure Java and runs on any platform, although it contains a generic infrastructure for execution of system commands (via Runtime.exec()), that are system-dependent.
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
Answer: Needs at least JRE 1.4. Different code is executed in org.netbeans.modules.vcscore.cmdline.exec.CommandExecutor on JRE 1.5 and higher. See issue #35999 for details.
Question (dep-jrejdk): Do you require the JDK or is the JRE enough?
Answer: JRE is enough.

Deployment

Question (deploy-jar): Do you deploy just module JAR file(s) or other files as well?
Answer:
• vcscore.jar - standard module 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: Module can be installed anywhere.
Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public?
Answer: All public packages are accessible, no restriction applied. Vcscore module contains VCSAPI. VcsGeneric module can use semi-private API VcsCoreImplementationAPI.
Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one?
Answer: Add following line into the module's manifest:

OpenIDE-Module-Module-Dependencies: org.netbeans.modules.vcscore/1 > 1.14.1

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: None defined or implemented.
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: Only one version of the module can be installed at a time. The settings are shared across different versions, stored and read by Java serialization and will be read in future as well.

Access to resources

Question (resources-file): Does your module use java.io.File directly?
Answer: Yes, for work associated with VCS commands execution, for temporary files and for file status cache storage.
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, files are created for menus, actions, templates, toolbars, settings storage - these are all in standard Open APIs.
Question (resources-read): Does your module read any resources from layers? For what purpose?
Answer: VCS commands written in Java are loaded from DefaultFileSystem.
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: Yes. To get system classloader, ErrorManager, installed modules (for CVS mount wizard).
Question (lookup-register): Do you register anything into lookup for other code to find?
Answer: No.
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: user.home - To get the default initial directory in file choosers and the default mount point of VcsFileSystem. netbeans.user - To determine the location of status cache persistent storage and storage of output of VCS commands to prevent OutOfMemoryErrors when commands produce a huge amount of output. user.name - To be able to compare the user name with a file locker name to determine whether the file was locked by the current user or not. Env-HOME - This property is provided by core from the set of properties of the underlying operation system. It's used to determine the user's home directory for the purpose of location of .cvspass file and other CVS configuartion files. Env-HOMEPATH - This property is provided by core from the set of properties of the underlying operation system. It's used to determine the user's home directory for the purpose of location of .cvspass file and other CVS configuartion files on Windows operating system. It's used in conjunction with Env-HOMEDRIVE property. Env-HOMEDRIVE - This property is provided by core from the set of properties of the underlying operation system. It's used to determine the user's home directory for the purpose of location of .cvspass file and other CVS configuartion files on Windows operating system. It's used in conjunction with Env-HOMEPATH property. env-cvs_rsh - This property is provided by core from the set of properties of the underlying operation system. It's used to determine the default value of CVS_RSH environment variable for :ext: cvs connection method. env-cvsroot - This property is provided by core from the set of properties of the underlying operation system. It's used to determine the default value of CVSROOT environment variable to be able to preset the CVS configuration. netbeans.vcsdebug - If this is true, some internal debug messages are printed. For testing purposes only.
Question (exec-component): Is execution of your code influenced by any (string) property of any of your components?
Answer: Yes, but only internally. org.netbeans.modules.vcscore.actions.ClusteringAction uses client property of the menu items to store the action object, that is retrieved in the action performer and org.netbeans.modules.vcscore.actions.CommandMenu uses ActionEvent.getActionCommand() to retrieve the name of the command to execute. Both actions set and retrieve the property by themselves.
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: Yes. Reflection is used for:
• In some UI components to be able to retrieve the displayed data
• To pass the VcsFileSystem instance to VCS commands written in Java so that they can run other commands and do other work that is necessary.
• In VCS APIs to be able to create instance of Command, that implements various interfaces.
• In joined CVS wizard to be able to mount filesystems of other modules.
• In some communication between VCS filesystem and versioning filesystem.
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: Yes. VCS commands are executed as external processes unless they are written in Java. We do not ensure that the result is the same on different platforms, the behavior depends on the executed process. The output is parsed and there is some code, which is dependent on the result output. This dependency is highly configurable via various parameters.
Question (exec-introspection): Does your module use any kind of runtime type information (instanceof, work with java.lang.Class, etc.)?
Answer: TBD.
Question (exec-threading): What threading models, if any, does your module adhere to?
WARNING: Question with id="exec-threading" has not been answered!
Question (security-policy): Does your functionality require modifications to the standard policy file?
WARNING: Question with id="security-policy" has not been answered!
Question (security-grant): Does your code grant additional rights to some other code?
WARNING: Question with id="security-grant" has not been answered!

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: Only text formats:
• File status cached information
• Ouptut of VCS commands into temporary files to keep low memory requirements
• Temporary files with user messages for VCS commands, that take messages from files.
• property files under SFS/vcs/defaults keeping user dafaults
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: No, only temporary files are deleted through java.io.File.deleteOnExit()
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 number of files during file status refreshing.
Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle?
Answer: No explicit limits. Technically, the available memory size is the limit...
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc.
Answer: TBD.
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: Yes, VCS commands are long running in general. They are executed asynchronously with a hardcoded limit of the number concurrently running commands.
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: There's just a joined CVS mount wizard and an infrastructure for automatic creation of simple dialogs as VCS command customizers.
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic?
Answer: Yes. The VCS commands popup menu can have an arbitrary tree structure, various commands can be present on various files. There's also an infrastructure for automatic creation of simple dialogs as VCS command customizers.
Question (perf-spi): How the performance of the plugged in code will be enforced?
WARNING: Question with id="perf-spi" has not been answered!