NetBeans Architecture Answers for Navigator API module

General Information

Question (arch-what): What is this project good for?
Answer: Navigator module is a base API module which provides:
• A place for modules to show structure/outline of their documents
• Ability for modules to show their view only when special document(node) is active in the system
• UI for switching between multiple views available for currently active document(node)
• Coalescing of fast coming selected node changes to show content for
Question (arch-overall): Describe the overall architecture.
Answer:

Navigator API is good for clients (module writers) that want to show some structure or outline of their document in dedicated window, allowing end user fast navigation and control over the document.

API allows its clients to plug in their Swing based views easily, which then will be automatically shown in specialized Navigator UI.

org.netbeans.spi.navigator.NavigatorPanel org.netbeans.spi.navigator.NavigatorHandler
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:

Basic Usage Steps

In order to plug in a view into Navigator UI for certain document (data) type, module writers need to write a NavigatorPanel implementation marked with @Registration.

Writing NavigatorPanel implementation

Implementing NavigatorPanel interface is easy, you can copy from template basic implementation BasicNavPanelImpl.java.

Advices on important part of panel implementation:
• Instantiation: Your implementation of NavigatorPanel is instantied automatically by the system if you register it using @Registration.
• getComponent method: Simply create and return your UI representation of your data in Swing's JComponent envelope. Just be sure that you don't create new JComponent subclass per every call, as performance will suffer then.

• panelActivated and panelDeactivated methods wraps an 'active' life of your panel implementation. In panelActivated, grab your data from given Lookup, usually by looking up its asociated DataObject or FileObject to take data from. Also remember to attach listeners to lookup result, perhaps also to data itself and trigger UI update with new data. Code will typically look like this:
  

          /** JavaDataObject used as example, replace with your own data source */
          private static final Lookup.Template MY_DATA = new Lookup.Template(JavaDataObject.class);
  
          public void panelActivated (Lookup context) {
              // lookup context and listen to result to get notified about context changes
              curResult = context.lookup(MY_DATA);
              curResult.addLookupListener(/** your LookupListener impl here*/);
              Collection data = curResult.allInstances();
              // ... compute view from data and trigger repaint
          }
              

  Do *not* perform any long computation in panelActivated directly, see below.
  In panelDeactivated, be sure to remove all listeners to context given to you in panelActivated.

• Long computation of content: What if rendering your Navigator view takes long time, more than several milliseconds? Right approach is to create and run new task using RequestProcessor techniques, each time when panelActivated call arrived or your listeners on data context got called.
  While computing, UI of Navigator view should show some please wait message.

Registering NavigatorPanel impl

Declarative registration of your NavigatorPanel impl connects this implementation with specific content type, which is type of the document, expressed in mime-type syntax, for example 'text/x-java' for java sources. Infrastructure will automatically load and show your NavigatorPanel impl in UI, when currently activated Node is backed by primary FileObject whose FileObject.getMimeType() equals to content type specified in your registering annotation (see more options below).

Advanced Content Registration - Linking to Node's Lookup

There may be situations where linking between your Navigator view and activated Node's primary FileObject is not enough or not possible at all. This simply happens when the data you want to represent in Navigator are not accessible through primary FileObject or DataObject. Usual example is Multiview environment, where more views of one document exists.

The solution is to bind content of your Navigator view directly to your TopComponent. Then, whenever your TopComponent gets activated in the system, Navigator UI will show th content you connected to it.

Steps to do:
• Choose your content type, could be either well known or arbitrary, say 'text/my-amazing-type' and do all basic steps described in above use case.

• Implement NavigatorLookupHint interface like this:

          class AmazingTypeLookupHint implements NavigatorLookupHint {
              public String getContentType () {
                  return "text/my-amazing-type";
              }
          }
               

• Alter your TopComponent to contain your NavigatorLookupHint implementation (AmazingTypeLookupHint in this case) in its lookup, returned from TopComponent.getLookup() method.

• Another option you have is to alter lookup of your Node subclass instead of directly altering lookup of your TopComponent. See Node.getLookup() method. Then Navigator will show your desired content whenever your Node subclass will be active in the system.
  However, keep in mind that this option is less preferred, because it only uses implementation detail knowledge that default implementation of TopComponent.getLookup() includes also results from lookup of asociated Node. So this approach will stop working if you change default behaviour of TopComponent.getLookup() method.

Programmatic activation of NavigatorPanel

Programmatic activation of specific navigator panel activates and shows navigator panel in navigation area, as if user had selected the panel manually. API clients are expected to use programmatic activation to activate/select preferred panel from a set of available panels.

Example: Several TopComponents in multiview arrangement, TopComponentA and TopComponentB. Both components provide the same NavigatorLookupHint impl, which is recognized by two providers NavigatorPanelA and NavigatorPanelB. Now when TopComponentA becomes activated (has a focus), it's desirable to select/show NavigatorPanelA from navigator panels. On the other side, when TopComponentB is activated, NavigatorPanelB should be activated automatically.
Steps to do to activate panel programmatically:
• Get the instance of NavigatorPanel implementation that you want to activate/show in navigator area.
  See Instantiation rules.

• Call NavigatorHandler.activatePanel(NavigatorPanel panel)
  .

Setting activated node of Navigator window

Sometimes clients need to alter activated Nodes of Navigator window, to better represent Navigator area content within the whole application. See TopComponent.getActivatedNodes() and TopComponent.Registry.html#getActivatedNodes() to find out what activated nodes of TopComponent and whole system mean.

Use Case Example: NavigatorPanel implementation shows list or tree of some Nodes in Navigator area. When user selects a Node in the list or tree, it is desirable to show selected Node's properties in Properties window and enable proper actions in main menu. Exactly this can be done by presenting Node selected in the list/tree as activated Node of Navigator window.
Steps to specify activated Nodes of Navigator window:
• In your implementation of NavigatorPanel, implement method getLookup() to return Lookup instance filled with Node(s) that you want to set as activated Nodes of Navigator window.

• Be sure to update Lookup content properly, for example using InstanceContent as follows:

          class MyNavigatorPanel implements NavigatorPanel {
          
              /** Dynamic Lookup content */
              private final InstanceContent ic;
              /** Lookup instance */
              private final Lookup lookup;
              
              public MyNavigatorPanel () {
                  this.ic = new InstanceContent();
                  this.lookup = new AbstractLookup(ic);
              }
          
              public Lookup getLookup () {
                  return lookup;
              }
  
              /** Call this method when activated Nodes change is needed, 
              * for example when selection changes in your NavigatorPanel's Component
              */
              private void selectionChanged (Node oldSel, Node newSel) {
                  ic.remove(oldSel);
                  ic.add(newSel);
              }
              
              ... impl of rest of your NavigatorPanel
              
          }
               

Adding UndoRedo support to the navigation view

Some complex navigation views need support for undoing and redoing edit changes done either directly in the view or in document which the view is representing.

Steps to support undo and redo in navigation view:
• Implement your navigation view as NavigatorPanelWithUndo, which is NavigatorPanel interface with extra method getUndoRedo().

• All other things remain the same as with basic NavigatorPanel usage. UndoRedo support returned from NavigatorPanelWithUndo.getUndoRedo() is propagated to the Navigator TopComponent and returned as its UndoRedo support. For details see TopComponent.getUndoRedo() and UndoRedo interface.

• Example of NavigatorPanelWithUndo implementation:

          class MyNavigatorPanelWithUndo implements NavigatorPanelWithUndo {
          
              /** UndoRedo support, substitute with your impl */
              private final UndoRedo undo = new UndoRedo.Manager();
          
              public UndoRedo getUndoRedo () {
                  return undo;
              }
              
              ... rest of the NavigatorPanelWithUndo impl ...
  
          }
               

Removing active Node/DataObject related NavigatorPanels from Navigator window

In certain situations it's not desired to show NavigatorPanel implementations related to DataObject of active Node in Navigator window. Typically you need to have active Node of some type, so that actions in the system works properly. But you don't want to show NavigatorPanels that "come" with such active Node.

Steps to remove such NavigatorPanels:
• Implement interface NavigatorLookupPanelsPolicy, return kind of policy that suits you from getPanelsPolicy() method.

• Put implementation instance into your TopComponent's subclass lookup, see TopComponent.getLookup() for details.

• Now when your TopComponent becomes active in the system, found panels policy is used to limit/affect set of available NavigatorPanel implementations.

Integration of Explorer view into Navigator

Explorer views comes handy when showing Nodes in varienty of situations and it is just natural to be able to integrate them into Navigator window. Working with explorer views is described at ExplorerUtils javadoc. Integration with Navigator is easy and there are only subtle differencies from integration into TopComponent.

Steps to integrate some kind of Explorer View into Navigator:
• Implement NavigatorPanel interface and return created explorer view from getComponent() method. Creating explorer view is described in ExplorerUtils.

• Return lookup created using ExplorerUtils.createLookup(ExplorerManager, ActionMap) from getLookup() method of NavigatorPanel.

• Use ExplorerUtils.activateActions(ExplorerManager, boolean) for actions activation and deactivation in panelActivated and panelDeactivated.

• Take inspiration from following example code which integrates ListView with Navigator:

          public class ListViewNavigatorPanel extends JPanel implements NavigatorPanel, ExplorerManager.Provider {
  
              private ExplorerManager manager;
              private ListView listView;
              private Lookup lookup;
              private Action copyAction;
  
              public ListViewNavigatorPanel () {
                  manager = new ExplorerManager();
                  ActionMap map = getActionMap();
                  copyAction = ExplorerUtils.actionCopy(manager);
                  map.put(DefaultEditorKit.copyAction, copyAction);
                  map.put(DefaultEditorKit.cutAction, ExplorerUtils.actionCut(manager));
                  map.put(DefaultEditorKit.pasteAction, ExplorerUtils.actionPaste(manager));
                  map.put("delete", ExplorerUtils.actionDelete(manager, true)); // or false
  
                  lookup = ExplorerUtils.createLookup(manager, map);
  
                  listView = new ListView();
                  fillListView(listView);
  
                  add(listView);
              }
  
              public String getDisplayName() {
                  return "List view panel";
              }
  
              public String getDisplayHint() {
                  return "List view based navigator panel";
              }
  
              public JComponent getComponent() {
                  return this;
              }
  
              public void panelActivated(Lookup context) {
                  ExplorerUtils.activateActions(manager, true);
              }
  
              public void panelDeactivated() {
                  ExplorerUtils.activateActions(manager, false);
              }
  
              public Lookup getLookup() {
                  return lookup;
              }
  
              public ExplorerManager getExplorerManager() {
                  return manager;
              }
  
              private void fillListView(ListView listView) {
                  try {
                      Node testNode = new AbstractNode(Children.LEAF);
                      manager.setRootContext(testNode);
                      manager.setSelectedNodes(new Node[]{testNode});
                  } catch (PropertyVetoException ex) {
                      Exceptions.printStackTrace(ex);
                  }
              }
          }
                  

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

(June 8, 2005) Basic design and implementation are somehow written and compilable, but not tested so far. Estimated time for work left is three-four weeks of one-man work. Important milestone is merge into main trunk, which should happen in early August.

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

Unit tests will be written ensuring that implementation loads, instantiates and calls client's SPI correctly. Usual manual testing will be performed as well. As whole API is rather small, it will be easily covered by unit tests as a whole.

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

The sources for the module are in the NetBeans Mercurial repositories.

Project and platform dependencies

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

Navigator module depends on: OpenAPIs -

For acces to winsys TopComponent, Nodes, lookup, general utilities like icon obtaining, bundles.

Loaders -

API implementation has to access data objects for obtaining mime types.

The default answer to this question is:


These modules are required in project.xml:

• CommonAnnotationsAPI - The module is needed for compilation. The module is used during runtime. Specification version 1.30 is required.
• org.openide.awt - The module is needed for compilation. The module is used during runtime. Specification version 6.10 is required.
• FilesystemsAPI - The module is needed for compilation. The module is used during runtime. Specification version 9.0 is required.
• LoadersAPI - The module is needed for compilation. The module is used during runtime. Specification version 7.61 is required.
• NodesAPI - The module is needed for compilation. The module is used during runtime. Specification version 6.2 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.52 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:

No platform deps

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

1.4 or greater

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

JRE AFAIK

Deployment

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

Just one regular jar.

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:

Anywhere

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

Yes.

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:

Nothing.

Compatibility with environment

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

Yes, there is not much I18N.

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

No new unusual standard, just layer-based xml registration and SPI interface NavigatorPanel that clients has to implement.

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 it will. However this is open issue now - whether to store settings (like filter values) for Navigator API clients and how.

Question (compat-deprecation): How the introduction of your project influences functionality provided by previous version of the product?
WARNING: Question with id="compat-deprecation" has not been answered!

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:

Navigator registers an action to show the navigator window.

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

Yes Navigator module reads registered view providers from specific folder Navigator/Panels.

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 ?
WARNING: Question with id="resources-preferences" has not been answered!

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:

activated_node -

Navigator listen to system activated node changes and sets activated node for Navigator top component accordingly. Local activated node is set from system activated node if any provider agrees to display content for data object behind the node. Navigator relies on default lookup mechanism of TopComponent to populate its activated node. Currently it means that if node backed by JavaDataObject is activated node in the system, it is also activated node for Navigator's top component. So main menu actions like Compile File, Move Class etc. work as usual when Navigator window is active. Also, lookup of currently selected Node is searched for NavigatorPanel SPI instances.

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? On a similar note, is there something interesting that you pass to java.util.logging.Logger? Or do you observe what others log?
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, just instatiating registered providers.

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:

Class.newInstance() RTTI is used to load registered view providers.

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

Navigator and Threading

Navigator API itself doesn't define any specific threading model, it's up to clients to handle threading. API just instructs clients which SPI methods should execute fast and tell them to use Request Processor for long runnign computation of Navigator view content.

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:

Nothing.

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:

Nothing, API itself is out of this, but client's performance is affected by a type of document behind selected node - so the size and complexness of java, xml documents will affect performance of related Navigator clients.

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:

Not much, just one lighweight envelope TopComponent.

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, but clients will face this.

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:

Just javadoc recommandations.