NetBeans Architecture Answers for org.netbeans.modules.xml.xam module

General Information

Question (arch-what): What is this project good for?
Answer: The xam module (XAM Module) provides a framework for domain model developers to use when creating new models. This framework was started to encapsulate common practices used when creating XML based models for XML schema and WSDL.

List of the main features:

• Definition and partial implementation of both a generic and XML specific model. The model supports eventing, Undo/Redo, sync, and simple transactions. XML based models extend generic models and add support for resolution.
Question (arch-overall): Describe the overall architecture.
Answer:

XAM (Extensible Abstract Model) was developed as part of an effort to create tools friendly schema model. This module was the extraction of useful patterns for undo/redo, simple write transactions (in this sense a transaction supports Isloation and Durability (to the extent possible) by allowing a single writer and deferring dispatching of events to the end of the transaction, lazy initialization, , inter/intra model references, and model creation. org.netbeans.modules.xml.xam - Represents a domain independent model and associated artifacts such as a factory, source, and the concept of a reference. org.netbeans.modules.xml.xam.dom - Provides entities for working on XML based models. This package depends on org.w3c packages and assumes a mapping between an xml tree and a strongly typed binding. This package also provides the ability to resolve other models A client will normally subclass the appropriate abstract model and component and thus have a starting point for a domain model (examples are the wsdl and schema models).

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:

domain model developer

A domain model developer would determine the appropriate extension package. A model outside of XML would extend org.netbeans.modules.xml.xam.AbstractModel, and have the components in the domain extend org.netbeans.modules.xml.xam.AbstractComponent. The org.netbeans.modules.xml.xam.AbstractFactory can also be used for creation of models. The factory provides the creational, the model provides the entry point into the domain model as well as a concrete reference point to register for events. The component serves as the root of the domain level objects. This provides some consistency across models as the original intention was to be able to provide a unified model across different XML vocabularies. An XML model developer would likely want to start using the XDM model which provides the full fidelty XML document model. This is in the xml/xdm module (described seperately). The XML module developer would also incorporate the facilities for reading and writing to a catalog. This is incorporated into methods available to subclasses in the xam.dom and xdm.xam models. The project based catalog facility provides the ability to support versioned catalog files which allow local access but URL based location attributes.
Question (arch-time): What are the time estimates of the work?
Answer:

The initial implementation has been completed.

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

Unit tests are provided as part of this module. FindBugs has also been run on the source base.

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

The sources for the module are in NetBeans CVS in xml/xam directory.

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

• org.openide.util - The module is needed for compilation. The module is used during runtime. Specification version 6.8.1 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:

JDK supported platforms.

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

1.5.

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

jre only.

Deployment

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

no additional jars required

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:

installed anywhere.

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

yes as well as limiting access to only friend modules.

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

This module was developed from the bottom up (the api is not yet stable) and thus a friend declaration is required before the module can be used.

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. There are no settings used by this module.

Access to resources

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

XAM mutation is done to a javax.swing.Document, no direct file access is used.

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:

no externally registered services are used.

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:

no

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

There are several uses of dynamic runtime information. These uses will be communicated in the JavaDoc.

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

XAM supports only a single writer but multiple readers, thus supporting the dirty read behavior. The implementation uses a java.util.concurrency semaphore to ensure a single transaction. Incorrect transaction usage (either attempting to mutate outside a transaction or starting a second transaction within an existing transaction generates a runtime error). When a transaction is completed, events are fired synchronously. XAM also provides a facility for periodic updating the model based on changes to the underlying document. The initial parsing is done on the RequestProcessor thread; however, mutation and event firing is done from the AWT thread.

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:

none

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

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 components in the domain model. There is a limited fixed cost per component and some models have 100,000 + components. In general, the number of components is correlated with the size of the model source.

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:

The default model is about 5000 bytes and a component is about 20 bytes. The XML model is roughly the same size and a XML component is 21 bytes. This is the base size and the number of containing components can change the size dramatically.

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:

none

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

This the super class so the performance is tied with the domain model.