Overview

# NetBeans Architecture Answers for Settings module

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

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

## Interfaces table

##### Group of java interfaces

Interface Name | In/Out | Stability | Specified in What Document?
SettingsAPI | Exported | Official | .../org/openide/util/doc-files/api.html
ServicesAPI | Exported | Official | .../org/openide/util/doc-files/api.html
OptionsAPI | Exported | Official | .../org/openide/options/doc-files/api.html
XmlSettingsPersistence | Exported | Official | .../netbeans/spi/settings/doc-files/api.html
FilesystemsAPI | Imported | Official | .../openide/filesystems/doc-files/api.html
LoadersAPI | Imported | Official | .../org/openide/loaders/doc-files/api.html
UtilitiesAPI | Imported | Official | .../org/openide/util/doc-files/api.html
NodesAPI | Imported | Official | .../org/openide/nodes/doc-files/api.html
ModulesAPI | Imported | Official | .../org/openide/modules/doc-files/api.html
org.openide.options | Imported | Official | .../overview-summary.html
org.openide.windows | Imported | Official | .../overview-summary.html
org.openide.actions | Imported | Official | .../overview-summary.html

##### Group of property interfaces

Interface Name | In/Out | Stability | Specified in What Document?
org.openide.util.SharedClassObject.initialize | Imported | Private | `SystemOption` needs to know whether the `SharedClassObject` is just performing initialization and this is done using `this.getProperty ("org.openide.util.SharedClassObject.initialize")` which returns null if initialize is not called and `Boolean.TRUE` if it is.

##### Group of dtd interfaces

Interface Name | In/Out | Stability | Specified in What Document?
sessionsettings-1_0.dtd | Exported | Stable | .../dtds/sessionsettings-1_0.dtd `-//NetBeans//DTD Session settings 1.0//EN`
properties-1_0.dtd | Exported | Under Development | .../www.netbeans.org/dtds/properties-1_0.dtd `-//NetBeans org.netbeans.modules.settings.examples//DTD XML ProxySettings 1.0//EN`

##### Group of layer interfaces

Interface Name | In/Out | Stability | Specified in What Document?
RuntimeInstancesRegistry | Exported | Official | .../org/netbeans/spi/settings/doc-files/api.html xml/memory: Associates runtime instance with environment provider.
ServicesDisplayRegistry | Exported | Official | .../org/openide/util/doc-files/api.html UI/Services: The root folder for displaying options.

## General Information

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

Answer: Settings are persistent objects with a set of properties, that should be available via lookup. Properties are expected to be changed. Implementation of setting doesn't care about persistence issues, which is responsibility of settings infrastructure. XML persistence support is provided in a standalone autoload module core-settings.jar. But a typical setting is a system option, which uses serialization at the moment. Also service types must be mentioned here. Service type can be desribed as typed a named settings.

- SettingsAPI
- ServicesAPI
- OptionsAPI
- XmlSettingsPersistence

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!

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

WARNING: Question with id="arch-where" has not been answered!

## Project and platform dependencies

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

Answer: It uses various kinds of API's:

- FilesystemsAPI
- LoadersAPI
- UtilitiesAPI
- NodesAPI
- ModulesAPI
- org.openide.options
- org.openide.windows
- org.openide.actions

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

Answer: SAX parser.

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

Answer: Platform independent.

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

Answer: JRE 1.3

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: `SystemOption` and `ServiceType` are inside `openide.jar`; But the settings infrastructure is distributed between `openide.jar` and `core.jar`; Instead of `SystemOption` or `ServiceType` can be used arbitrary object , that cooperate with convertor. Infrastracture for convertos is in `core-settings.jar`;

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

Answer: `openide.nbm` and `core.nbm`) are reachable via the Update Center .

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: `openide.jar` and `core.jar` must be in the shared location as it is part of the core of NetBeans. `core-settings.jar.jar` can be anywhere.

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

Answer: `SystemOption` and `ServiceType` are publicly accessible. The settings infrastructure for `SystemOptions` resides in `core.jar` and is considered private except `InstanceDataObject` which is in `openide.jar`, which is public. Infrastracture for convertos is in `core-settings.jar` exposes some packages explicitly declaring them in manifest, which means that all other packages are inaccessible.

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

WARNING: Question with id="deploy-dependencies" has not been answered!

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

## Access to resources

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

Answer: No.

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:

Provided layers:

- `core-settings.jar org/netbeans/modules/settings/resources/mf-layer`
- In `core.jar` in org/netbeans/core/resources/mf-layer.xml

Provided folderes:

- RuntimeInstancesRegistry - xml/memory: Associates runtime instance with environment provider.

- ServicesDisplayRegistry - UI/Services: The root folder for displaying options.

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

Answer: Many times mentioned in this document. See this document.

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

Answer: Yes `core-settings.jar` override `xml/lookup/Netbeans/DTD_Session_settings_1_0.instance` in `core.jar` and mainly its attributes. So, if is `core-settings.jar` present, then take over functionality of settings infrastructure implemented in `core.jar`.

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

- In `InstanceDataObject.createSettingsFile` is looked up `ServiceType.Registry` to be sure, that ServiceType is unique.
- Also `ClassLoader` is looked up often to find `ModuleManager.SystemClassLoader` .
- Hack for system options implemented in `SharedClassObject.findObject` lookes for instance of setting class in the active session to find serialized state of the option, if such state exists it is deserialized before the object is returned from lookup, then all SystemOptions are deserialized at this place the first time anybody asks for the option.

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

Answer: Yes. There is registered `Environment.Provider` which is ultimately used to provide `Lookup`, that provides `InstanceCookie`. This is a second way how can mainly `InstanceDataObject` call outside implementation (first one are method calls by reflection).

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: Neither java system nor (`System.getProperty`) property. But attributes attached to `FileObject` are used for configuration. This configuration is too complex and can't be separated from entity registration and so on. So, here is description of configuration. org.openide.util.SharedClassObject.initialize - `SystemOption` needs to know whether the `SharedClassObject` is just performing initialization and this is done using `this.getProperty ("org.openide.util.SharedClassObject.initialize")` which returns null if initialize is not called and `Boolean.TRUE` if it is.

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: Yes reflection is used heavily.

- There is used reflection to create new instance of setting. Either direcltly `newInstance` or factory method, that is defined in setting file.
- Setting infrastructure registers its own PropertyChangeListener to know about changes and calls `addPropertyChangeListener` on setting instances. There is also called pair method `removePropertChangeListener`.
- For synchronization of file name with instance name is called on setting instance method `getDisplayName` and `getName`.
- If settings is implemented as `SystemOption`, then there is necessary to know if is project specific or global, to be able to reset it to default value after another project was chosen. Then there is called method `isGlobal` by reflection on instance of setting.
- If `XMLPropertiesConvertor` is used for settings based on xml with grammar defined by `-//NetBeans org.netbeans.modules.settings.examples//DTD XML ProxySettings 1.0//EN`, then methods `readProperties` and `writeProperties` is used on instance of setting.

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

Answer: There are method invocations between parts of setting infrastructure.

- If there is created new persistent instance of setting object in the runtime, then `InstanceDataObject` that comes from `openide.jar`, calls method responsible for storing setting on disk. This method is expected to have following decaration `public void methodName (java.io.Writer w, Object inst)`. Which method and from which module is invoked depends on configuration.
- If new persistent instances of setting was created, then infrastructure must be notified about it, to be able to listen on changes and ensure , that all changes will be stored. Then from `InstanceDataObject` is used `Lookup` to find `InstanceCookie`. Then method `setInstance` is invoked on instance of `InstanceCookie`. This binds instance of setting to setting infrastructure. Which `Lookup` and then also which `InstanceCookie` is used depends again on cofiguration. description of configuration.
- Also org.openide.util.SharedClassObject.reset is called from org.netbeans.modules.settings.convertors.XMLSettingsSupport.SettingsRecognizer.

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 external process.

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

Answer: No answer

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:

- sessionsettings-1_0.dtd - `-//NetBeans//DTD Session settings 1.0//EN`
- properties-1_0.dtd - `-//NetBeans org.netbeans.modules.settings.examples//DTD XML ProxySettings 1.0//EN`

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

Answer: No special implementation.

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 special implementation.

## Performance and Scalability

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

Answer: No. Instances are provided on request, the same is true for activity of infrastructure.

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: Not completely relevant questin in this case. There is not so much important how many settings will be defined, but how heavily will be used.

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

Answer: No.

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

Answer: Hardly to estimate.

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. Perhaps if ToolsOption is showed, then createing of nodes defined in UI/Services may take relatively enough time, but not sure if this should be considered as part of setting infrastructure.

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.

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?

WARNING: Question with id="perf-spi" has not been answered!

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