Bug 252293 points out an issue that Common Navigator navigatorContent (extensions) (NCEs) are not properly invoked for the purpose of providing a label when the NCE overrides another.

In the course of investigating this problem, I found a few issues in this area where the label provider handling is not really right.  Unfortunately, to make it right, current users of the CNF might somehow be broken.  This could particularly apply to the Java extensions as used the WTP, and to commercial products.

In general, this is really only a problem if you have NCEs that use either triggerPoints or possibleChildren expressions.  If you use enablement expression (which sets both of these), you should not have any of these problems.

Here is the main problem:

You may not get the NCE you are expecting for a label provider.  When an object (in the CommonViewer) is first discovered by an NCE (typically as a result of the triggerPoints/enablement expression), its association with the NCE is cached for performance reasons.  If a label provider subsequently needs to be found for the object, the cache is checked, even though there may be qualifying NCEs that specify possibleChildren (and possibly overrides).  If the object is found in the cache, the cached NCE is used, causing the “correct” NCE(s) to be ignored.  However if the object is not found, the normal search for NCEs will take place.

Bug 255793 proposes an elegant solution to the problem which is to simply always have the label provider NCE be the same as the NCE that provided the content (which is how it actually works much of the time due to the caching, but not always).  However, I don’t see a way it can be implemented without a serious performance problem (if someone has a way, we can consider this, but for now I have closed it).

My proposal: Create a second cache.  The existing cache is used only for triggerPoints/enablement expressions, the second cache is used for possibleChildren expressions.  And also fix the issue in the above bug 252293 that overrides are respected when searching for label providers (and other uses of possibleChildren).  This will make the behavior deterministic and aligned with what is documented (once the doc is fixed, see below).

The downside of this is that it might break existing applications that somehow work with the current behavior.  These is where I would like to see community comment.  Please indicate your pleasure or displeasure in bug 252293. I intend to address this issue in M6, or if the comments are fast and unequivocal, I can address it in M5.

A secondary problem is that the current documentation is bad:

The current documentation for the NCE states that:

The triggerPoints expression describes the elements that will cause this extension to be invoked for either children or for labels. The possibleChildren expression describes the elements that the extension may be able to provide a parent for. Clients should describe all elements that could be set as the selection to ensure that the link with editor support can properly expand to the right node.

… and …

A navigator content extension defines a content provider and label provider that can be used to provide children whenever an element matches the triggerPoints expression and also to provide a parent whenever an element matches the possibleChildren expression.

The above statements are not correct with respect to label providers.  Label providers use the possibleChildren expression, not triggerPoints expression.  The documentation will be corrected to match the current behavior, since changing the behavior to match the documentation could break many things.

I have spent time over the last days working on a number of Common Navigator issues.  I have also marked all of the bugs that I plan to address for the 3.4.1 cycle.  If there is anything else you want in 3.4.1, please make your case with a comment in the bug report.  I now own all of the CN bugs so I will see your comment.

Please note that for 3.4.1 I cannot change the API at all, and can’t add anything to the UI, it’s really fixing bugs.  Anything beyond that will have to go into 3.5.

Also, the way I work on bugs is that bugs with patches that include test cases get worked on first, those with patches next, and then all of the rest.  So if you want something to get fixed or get in, the best way is to submit some code with tests.

I have also been working on the CN test suite, adding some more tests as I fix bugs and doing a little refactoring of it.  At some point, I will encourage people to contribute by writing test cases, it will be easy and fun to do and it’s a major contribution to making sure we don’t have future regressions.

I was inspired by Jeff’s recent post about contributing and decided to put an example of using a SourceViewer with Annotations (which took me a while to figure out) in the Platform Text Wiki.  As I’m not an expert in Platform Text (or much else at this point), I made have made some mistakes or mis-categorized things.  But that’s OK since it’s a Wiki others can quickly fix it.

Hopefully at some point more documentation will be provided on this subject in the right place (the Platform Plugin Developer Guide); maybe I will even write it if I get time. In the mean time, if you want to improve what I have done on the Wiki, please feel free.

It would be nice to have a place where us folks can contribute examples like this that can be categorized and widely distributed (perhaps made available through an update site).  Maybe there is such a place that I’m unaware of; if so I’m happy to put my example there.

As of 3.4RC4 the Platform Plugin Developer Guide how has an overview section on the Common Navigator (I was wondering who wrote these things, turns out we developers do). You can find it in the Programmer’s Guide section under
Common Navigator Framework.

When I first started using the CN, I found the tutorials on Michael’s blog, but I had a hard time with them as they were too detailed. I wanted a higher level understanding of the concepts. I’m hoping that this new documentation provides that.

If you have corrections, or want extensions or amplifications, please file a bug (against Eclipse/Platform/UI) and I will take care of it.

I just noticed that in the JUnit view when you select a test that’s failing it (now) goes to the line in the test case that has the failure. This is such a nice feature and it’s one example of how people take the time to “do the right thing” such that you hardly even notice that’s happening. Thanks to whoever built this one!

(revised) As Chris pointed out the test execution time is amazing, that completely changed my life.  Now I can spot performance regressions very quickly and fix them sooner.

I was just doing some work on my product’s code to import XSD definitions, which I have not touched in probably a couple of years and I ran across this comment (in my code):

// This is the effective simple type, either from the baseType
// or the contentType, the XSD stuff figures this out (thanks Ed!)

It brought back memories of initially writing the code when I was new to Eclipse and my product required an XSD importer. Luckily I found Ed’s implementation with the EMF and I could use it standalone which is exactly what I wanted. I was also struck by the quality of the code and its reliability and robustness, all the way down to the fact that the toString()s on all of the objects were consistently helpful. Dealing with XSD is not easy, and this code made it as pleasurable as possible (under the circumstances).

Combine that with the fact that Ed was always immediately responsive to my questions on the newsgroups really impressed me.

Little did I know that one day I would actually be working on Eclipse itself, and have the opportunity to contribute as Ed and others like him have. He and many others in the Eclipse project have set a very high bar for how things ought to work and I only hope that I can live up to this.

You can find this at the Common Navigator Framework Wiki page. I welcome any comments or corrections.

Hopefully, if I get enough time this week, I am planning on writing some text for a section in the Platform Plugin Developer’s Guide to include general instruction on the CNF based on Michael’s (and my) work. If anyone’s interested in helping or providing text for this, please let me know.

In order to be responsive in the 3.5 timeframe with the CNF, I would like to get as many uses cases as possible. Please indicate things you have done, things you are doing, or things you want to do. Also include some contact information so I can get ahold of you if I have questions. And if there are references to particular bugs or enhancements of interest please also link to them.

Here is the wiki page where you can record these.

I have personal experience developing using the CNF with an RCP application that uses resources, so I feel I understand this pretty well. So I’m most interested in those cases that don’t involve using resources. And I would be interested in why you chose not to use resources.

I’m the Platform UI group’s newest committer and my main interest at this point is the Common Navigator.  I have been using it in the development of my RCP application now for about 9 months, but I’m by no means an expert.  However, I’m sure I will become one soon.  My intention as a committer is to build a community around working on the Common Navigator such that many people will be contributing patches or test cases (or even just bugs).  I also hope to make a large dent in the bug/feature request backlog for 3.5 such that more people will find the Common Navigator useful.

I will be watching the eclipse.platform and eclipse.platform.rcp newsgroups and will try to respond to messages about the Common Navigator quickly.  It would be helpful if you could tag such messages [CommonNavigator] so I can easily find them.

At this point, the only source of useful overview documentation for the Common Navigator are the excellent tutorials at Michael Elder’s (the author of the CN) blog. Soon I hope to get some of this transferred into the Eclipse Plugin Developer’s Guide.

RCP applications can quickly and easily use the CN to show the resources in the workspace.  This assumes that your RCP application uses resources (which is another discussion).  The CN can also be used for non-resource RCP applications, in that case, these instructions don’t apply, as the objects treated by the CN have to be created directly by the RCP application.

If you are planning to use the CN in an RCP application that uses resources, there are 3 (2 of which are completely undocumented) things you must do:

1. Call org.eclipse.ui.internal.ide.model.WorkbenchAdapterBuilder.registerAdapters() in your WorkbenchAdvisor initialize() or preStartup() methods. (You also need to do this if you are planning on using the older Resource Navigator). This hooks up the adapters from the core (mainly resource) components to the navigator support.
2. To get the icons for projects correctly registered, you need to execute this code also in the WorkbenchAdvisor initialize() or preStartup() methods:

   
   final String ICONS_PATH = "icons/full/";
   final String PATH_OBJECT = ICONS_PATH + "obj16/";
   Bundle ideBundle = Platform.getBundle(IDEWorkbenchPlugin.IDE_WORKBENCH);
   declareWorkbenchImage(configurer, ideBundle, IDE.SharedImages.IMG_OBJ_PROJECT,
       PATH_OBJECT + "prj_obj.gif", true);
   declareWorkbenchImage(configurer, ideBundle, IDE.SharedImages.IMG_OBJ_PROJECT_CLOSED,
       PATH_OBJECT + "cprj_obj.gif", true);
   
   ...
   
   private void declareWorkbenchImage(IWorkbenchConfigurer configurer_p, Bundle ideBundle, String symbolicName,
   String path, boolean shared) {
      URL url = ideBundle.getEntry(path);
      ImageDescriptor desc = ImageDescriptor.createFromURL(url);
      configurer_p.declareImage(symbolicName, desc, shared);
   }
   

3. Hook the root of the CN up to the workspace by adding this method to your WorkbenchAdvisor:

   public IAdaptable getDefaultPageInput()  {
       IWorkspace workspace = ResourcesPlugin.getWorkspace();
       return workspace.getRoot();
   }

I realize having to use internal classes is not the way we want to do things, and there are currently some bugs outstanding about this that we hope to get resolved in 3.5 (not sooner because they would require API changes).