NetBeans Architecture Answers for Auto Update Services module

General Information

Question (arch-what): What is this project good for?
Answer: Provides the APIs and SPIs to support the AutoUpdate feature.
Question (arch-overall): Describe the overall architecture.
Answer:

AutoUpdate feature provides several services to IDE: download and install available updates of installed modules, search and install new features from subscribed Update Centers, browsing and manipulating the modules in IDE installation and handling of module localizations. To use the services have to AutoUpdate supply a GUI to easy manipulating. AutoUpdate feature has to care about registration Update Centers as well.

Several several services means that Autoupdate feature contain several parts of functionality. These part of AutoUpdate should communicate each other. Moreover, some interface should be public. One of them is SPI (org.netbeans.spi.autoupdate) for Update Center backend - allows to create and subscribe the Update Center in IDE. Next there should be a API (org.netbeans.api.autoupdate) which communicate to rest of IDE and provide some services what is useful for NB installers, a non-visual client of Auto Update which make possible to use Auto Update from command line as standalone application in "admin" mode. All of them needs a APIs. This document describes proposed APIs, supposed use-cases and design of interaction Auto Update parts each other.


Naming: What is feature? Group of modules which are close connected together and cannot acts separately. I think that feature is common understand notation and fits its matter we will use it from now on.
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:

Browse all available units

Give overview of IDE installation to users, it involve overview of installed modules (grouped together as feature), overview of available updates, overview of available new features. The API can return list of UpdateUnit which describes all instances of unit, e.g. installation in IDE, all its available updates, optionlly its backup instance. UpdateUnit can represent either a feature (e.g. group of modules), a single module or a localization.
Proposed usage of API: Call List<UpdateUnit> UpdateManager.getDefault().getUpdateUnits()

Browse all units by chosen style (e.g. modules, features, localization)

Sometimes there can be a need to get overview of units by chosen style, e.g. feature, module or localization.
Proposed usage of API: Call List<UpdateUnit> UpdateManager.getDefault().getUpdateUnits(UpdateStyle style)

Browse installed modules

When an API client needs to get overview of installed modules.
Proposed usage of API: Call List<UpdateUnit> UpdateManager.getDefault().getUpdateUnits(UpdateStyle style) and filter units which haven't been installed yet.

Search for new functionality

Someone is searching for some functionality which can be installed into IDE. It needs a set of available UpdateUnits which are applicable to active IDE. UpdateManager will search all available UpdateUnit given attribute.

Install new functionality

An client needs to install new functionality into the IDE installation. She knows what unit and what version wants to install. Needs to identify if the functionality is ready to install, resolve its dependencies, identify possible problems and locate other unit what have to be installed together with asked functionality.
Proposed usage of API:
• Client needs install NetBeans module in required minimal specification version.
• Find corresnponing UpdateUnit by module's code name and finds UpdateElement what fits the required version.
• So, the client now have UpdateElement which wants to install.
• Take the OperationContainer for install, e.g. OperationContainer.createForInstall
• Adds the element into container OperationContainer.add(UpdateElement) and gets OperationInfo for that operation.
• Identify other required elements: OperationInfo.getRequiredElements()
• Check if there is no broken dependencies: OperationInfo.getBrokenDependency() Note: if there are some broken dependencies then operation cannot continue.
• If all okay, then install the unit: OperationContainer.doOperation()

Update of installed unit

A client needs to update some unit of functionality which is already installed. She knows what unit and what update element (by version) wants to install. Needs to identify possible problems with update install, resolve its dependencies, identify possible problems and locate other unit what have to be installed together with asked functionality.
Proposed usage of API: See above Install new functionality

Uninstall functionality

An client needs to uninstall some functionality from IDE installation. She knows what unit wants to uninstall. Needs to identify if the functionality is ready to uninstall, resolve its dependencies, identify possible problems and locate other unit what will be disabled together.
Proposed usage of API:
• Client knows UpdateElement which wants to uninstall.
• Take the OperationContainer for uninstall, e.g. OperationContainer.createForUninstall
• Adds the element into container OperationContainer.add(UpdateElement) and gets OperationInfo for that operation.
• Identify other required elements: OperationInfo.getRequiredElements()
• If all okay, then uninstall the unit: OperationContainer.doOperation()

Switch off functionality

An client needs to switch off (disable) some functionality in IDE installation. Needs to resolve its dependencies, identify possible problems and locate other unit what will be disabled together.
Proposed usage of API:
• Client knows UpdateElement which wants to uninstall.
• Take the OperationContainer for disable, e.g. OperationContainer.createForDisable
• Adds the element into container OperationContainer.add(UpdateElement) and gets OperationInfo for that operation.
• Identify other required elements: OperationInfo.getRequiredElements()
• If all okay, then disable the unit: OperationContainer.doOperation()

Switch on functionality

Like Switch off functionality An client needs to switch on (enable) some functionality in IDE installation.

Rollback of previous update

Sometimes an client needs to rollback of installed update of unit to previous version. Needs to resolve its dependencies, identify possible problems and locate other unit what are affected by rollback.
Proposed usage of API: Like above Switch off functionality
• Client knows UpdateElement which wants to uninstall.
• Take the OperationContainer for enable, e.g. OperationContainer.createForEnable
• Adds the element into container OperationContainer.add(UpdateElement) and gets OperationInfo for that operation.
• Identify other required elements: OperationInfo.getRequiredElements()
• If all okay, then enable the unit: OperationContainer.doOperation()

Resolve problems what accrued while processing operation

OperationContainer and OperationInfo identifies some problems, i.e. broken dependencies, needs to install more units, the operation causes disable some other modules and so on. The client can use this information to consult these with end-user.

Make IDE up-to-date

Sometimes need to make whole IDE installation up-to-date. Find all available updates of installed units and install the latest available version. It is covered by previous use-cases.

Get all subscriptions to Update Center

Show me all registered subscriptions to Update Center, e.g. get me list of UpdateUnitProvider. Proposed usage of API: Call UpdateUnitProviderFactory.getUpdateUnitProviders()

Subscribe new Update Center

If there is a new Update Center which is not already subscribed into IDE user wants to subscribe new one Update Center which will be connected from that time in periodically checks. There should be a factory where subscribe new one Update Center, known types of Update Center have own factory method. Proposed usage of API: Simply call UpdateUnitProviderFactory.create() which creates and registered new one subscription in the system and will be used from that time in the future.

Customization of Update Center subscription

An user wants to enable or disable of Update Center subscription. Proposed usage of API: Simply call UpdateUnitProviderFactory.setEnable(UpdateUnitProvider, boolean).

Unsubscribe of some Update Center

Simple unsubscribe a chosen Update Center from the system. Need to know of chosen Update Provider Id. This Update Center won't be checked anymore. Proposed usage of API: Simply call UpdateUnitProviderFactory.remove(Id).

Refresh content of subscribed Update Center

The content of Update Provider is cached and the system works across there caches. There is a cache per each Update Center subscription. The caches are refreshed periodically by the system. But, sometime an user wants to call refresh manually. Proposed usage of API: Simply call UpdateUnitProvider.refresh().

Specify the cluster where to install

TBD

Get all installed files of given unit

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

NB6.0/M11.

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

The API will be unit tested, of course. The test over-all will be done by API clients, Autoupdate UI at first and CLI client of Autoupdate Services, which is projected as well.

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:
• org.netbeans.api.progress - The module is needed for compilation. The module is used during runtime. Specification version 1.9 is required.
• org.netbeans.bootstrap - The module is needed for compilation. The module is used during runtime. Specification version 2.6 is required.
• org.netbeans.core.startup - The module is needed for compilation. The module is used during runtime. Specification version 1.9 is required.
• org.openide.filesystems - The module is needed for compilation. The module is used during runtime. Specification version 7.0 is required.
• org.openide.modules - The module is needed for compilation. The module is used during runtime. Specification version 7.2 is required.
• org.openide.util - The module is needed for compilation. The module is used during runtime. Specification version 7.5 is required.
• org.openide.windows - The module is needed for compilation. The module is used during runtime. Specification version 6.15 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:

All platforms.

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

XXX no answer for dep-jre

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

XXX no answer for dep-jrejdk

Deployment

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

XXX no answer for deploy-jar

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

XXX no answer for deploy-nbm

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:

XXX no answer for deploy-shared

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

Autoupdate UI will depends on this API, next one client of this API would be NetBeans installer. Modules which want to declare own Update Provider (aka Update Center) depends on Autoupdate SPI.

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:

Compatibility with environment

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

XXX no answer for compat-i18n

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

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:

XXX no answer for compat-version

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

Replacement of Autoupdate module. Autoupdate didn't provide any official API in previous releases, the ad-hoc usage of Autoupdate module will be covered of proposed API.
The proposed module will keep using structure of NBM, e.g. these APIs catalog-dtd info-dtd
Also registration of Update Centers in the layer will work after.
The module provides Unique ID to tracking of active users. unique-id
In module's preferences are stored properties what UpdateUnitProvider are enabled or disabled and when has been connected at the last time. enable-update-provider last-check-of-provider

Access to resources

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

Whenever updater touches a cluster, it creates .lastModified file in it and sets its timestamp to current time millis. This is an information for module system, so it knows to reset its caches.

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:

XXX no answer for resources-layer

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

XXX no answer for resources-read

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

XXX no answer for resources-mask

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:

XXX no answer for resources-preferences

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:
• Registred Update Providers (aka Update Center) are searching in org.openide.util.Lookup.
• Module loaded in running IDE are found in org.openide.util.Lookup.
Question (lookup-register): Do you register anything into lookup for other code to find?
Answer:

XXX no answer for lookup-register

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

XXX no answer for lookup-remove

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: plugin.manager.detail.view.selected -

Setting this property affects the associated module autoupdate.ui. Setting it to true results in the detailed view (all visible plugins) been selected when Installed tab is opened in Plugin Manager. Otherwise the simple view (high-level features) is selected.

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

The associated module autoupdate.ui provides possibility to open plugin manager dialog (PluginManagerUI) with the specified tab. That is controlled by setting this string property to one of the following values:

• update
• available
• local
• installed

If property is not set (as default) then default tab is choosen due to the UI spec.

Proposed usage of API:

final FileObject fo = FileUtil.getConfigFile("Actions/System/org-netbeans-modules-autoupdate-ui-actions-PluginManagerAction.instance");
CallableSystemAction action = (CallableSystemAction) DataObject.find(fo).getCookie(InstanceCookie.class).instanceCreate();
action.putValue("InitialTab", "installed");
action.performAction();
            

Show-In-AutoUpdate-Client - Each module can control whether it shall be visible in a UI that presents updates, installed modules, etc. This can be done by defining OpenIDE-Module-Show-In-AutoUpdate-Client: false (or true) in its own manifest. This attribute shall take precedence over any default deduced by the UI (e.g. don't show autoload modules for example). unpack200 - If bin/unpack200 executable isn't in the JDK executing the NetBeans application (as is the case since JDK14 and newer), the updater searches for a preference in NbPreferences.forModule(OperatorContainer.class).get("unpack200", null) which is usually located in a user directory in file config/Preferences/org/netbeans/modules/autoupdate/services.properties and if specified, it uses the alternative unpack200 to process legacy NBM files encoded that way.
Question (exec-ant-tasks): Do you define or register any ant tasks that other can use?
Answer:

XXX no answer for exec-ant-tasks

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

XXX no answer for exec-classloader

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

XXX no answer for exec-reflection

Question (exec-privateaccess): Are you aware of any other parts of the system calling some of your methods by reflection?
Answer:

XXX no answer for exec-privateaccess

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:

XXX no answer for exec-process

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

XXX no answer for exec-introspection

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

The API is threadsafe. The objects are immutable.

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

XXX no answer for security-policy

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

XXX no answer for security-grant

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:

XXX no answer for format-types

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

XXX no answer for format-dnd

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:

XXX no answer for format-clipboard

Performance and Scalability

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

XXX no answer for perf-startup

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

XXX no answer for perf-exit

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:

None.

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

The number of objects to handling is limited in reality to count of modules loaded in running IDE plus published plugings on Update Centers. It cannot reach over the Autoupdate Services capability.

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

XXX no answer for perf-mem

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:

XXX no answer for perf-wakeup

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

XXX no answer for perf-progress

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:

XXX no answer for perf-huge_dialogs

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

XXX no answer for perf-menus

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

The performance is affected by responsiveness Update Providers (plugged via proposed SPI) which are mined for available updates or new functionality. Also these providers are responsible for downloading of chosen files. The critical dependence on traffic accessibility of user's connection to Internet. These dependencies will be transparent to the users and won't affect API usage.