EDIT

Some notes about the CNF in attempt to understand things.

30 Nov 08 FRU

Documentation notes:

There is some good text potentially for the docs in:

https://bugs.eclipse.org/bugs/show_bug.cgi?id=195595

Navigator Content

The purpose of the navigatorContent extension (NCE) is to bind a content provider

and label provider to the navigator under the right circumstances depending

on what is selected.

A navigator content descriptor has a one-to-one correspondence with the

navigator content extension, which is the higher level object representing

the navigator content.

Overriding

An NCE may specify that it overrides another through the user of the override

mechanism where it specifies the NCE extension ID of the extension to override.

When doing the processing associated with the label and content provider, it is possible

that multiple NCEs meet the criteria for processing based on their triggerPoints and/or 

possibleChildren.  When this happens, the NCEs are ordered in a tree based

on the overrides specification, and then with that based on priority.

The first NCE in the tree that provides the answer (label or content) being

sought is used.

When the NCE is bound to the viewer (using the contentExtension element) it may

specify that that NCE serves as "root content" for that viewer, which allows

the viewer to start with an initial set of NCEs to process the root(s) [why exactly --

I understand intuitively but can't put it into words].

Pipelining

In some cases, it is desirable to have multiple NCEs be invoked during

content provider processing to modify the objects to be returned by the

content provider.  This is done using the pipelining mechanism where each NCE

in the tree has the opportunity to modify the objects to be returned by the

content provider.  There are also hooks for these pipelined NCEs to 

be invoked at the Add/Remove/Update/Refresh methods on the viewer.

Selecting a Content Extension (NCE)

This is done either through the possibleChildren or triggerPoints expression

on the NCE.  The enablement expression expression specifies the same expression

for both triggerPoints and possibleChildren.

The triggerPoints expression is used:

- by the NavigatorContentServiceContentProvider

to find extensions for getElements() (through the root content extensions) 

or getChildren().  Given a parent node, that content extension is used

to determine what children to provide.

- by the NavigatorPipelineService for ???

The possibleChildren expression is used for all other cases, which include:

- Label/icon/description provider

- Selecting the NCE for a drop

The current documentation on these uses is incorrect, in particular for 

the label provides, it says that the triggerPoints expression is used, but

it's not.

Dependency

Questions/Issues:

1) In NavigatorContentServicedLabelProvider, seems that we look for

label providers by looking for matching NCEs by possibleChild.

However the documentation is clear that content and label providers

are found by triggerPoint, possibleChild is used only in the content

provider getParent() case.

<mde>The API documentation for label providers is wrong. It has always been 

the case that label providers rely on the possibleChildren; we should

 correct the doc since actual implementations are relying on the 

 behavior of label providers using possible children (but only in 

 cases where the framework can't determine which extension contributed 

 the content with its short term memory mechanism). 

 Other parts of the framework (like the DND Drop Handlers) also rely on 

 possible children to determine which content extension's handlers 

 should be invoked when processing a drop operation. </mde>

2) In NavigatorContentServiceLabel provider, there seems to be special

processing to handle overriding instead of using the normal processing

to get only the relevant NCEs.  Also, the way to get the NCEs is

different depending on whether doing a getImage() or getForeground()

for example and I don't understand why.  Also

NavigatorContentServiceDescriptionProvider does not seem to consider

overrides at all.  This all seems wrong.

<mde>

The content extension has alot of complexity because it has to 

determine the overrides for each individual child along the path. 

Labels are a bit simpler because only one value can be returned. 

The override logic recursively walks the override path by the highest 

priority label provider. Overriding label providers can opt not to 

return a label (e.g. null), and the framework will fall back on the 

base label provider to provide a value.

The getForeground()/getFont() cases weren't retrofitted for 

overriding values. This was just a legacy/point in time and 

is arguably a bug. The Font and Color providers were added to 

support the Team providers (they weren't part of the original product 

framework). If anything, the getFont()/Foreground/Background() 

methods should be retrofitted to follow the patter in getText/Image().

</mde>

3) The triggerPoints and possibleChildren descriptions in the exsd are

confusing:

"The triggerPoints expression defines the nodes in a tree that should

cause this extension to be invoked for children."

"The possibleChildren expression defines the nodes in a tree that

could be contributed by this extension.  Clients should describes when

this content extension could provide a parent for elements that match

the expression."

I think a clearer description is:

The triggerPoints expression defines the tree nodes for which this

extension (and associated content/label providers) is to be invoked.

<mde>Remove "label providers" and we're good. </mde>

The possibleChildren expression defines the content provider to be

selected when processing the ITreeContentProvider.getParent() call.

<mde>As well as the DND Drop Handler and Action Providers.</mde>

4) Why is the overridden tree computed only on

findDescriptorsForPossibleChild and not for

findDescriptorsForTriggerPoint?  The extension point documentation for

the overrides element says that the overrides only applied to

triggerpoints, it does not mention possibleChildren (except in

reference to the OnlySuppressedifExtVisibleAndActive option is set,

but it still seems to say that only triggerPoints is actually used).

<mde>It might be worth setting up an hour to go through a deep dive 

for this material. If I recall correctly, there was a challenge in 

computing all of the triggerpoint overrides a priori, but the 

overrides are used. The NavigatorContentServiceContentProvider 

processes a given element for children (e.g. getChildren()), 

and then invokes the overridden providers directly (from within 

the Service content provider) to compute the overridden tree. 

The possible children through doesn't have a use case like this, 

and so these can be computed and returned as needed.</mde>

5) More confusion (from the overrides exsd):

"InvokeAlwaysRegardlessOfSuppressedExt (default): Indicates that this

extension is a first class extension; it should be given opportunities

to contribute content regardless if its suppressedExtensionId is

visible or active to the viewer. Thus, the extension is a first-class

extension and an overriding extension. It will be invoked whenever its

triggerPoints expression is matched. When the suppressed extension and

its triggerPoints extension is matched, it will be invoked with the

contributed items from its suppressed extension; the suppressed

extension will not be given an opportunity to directly contribute."

The last sentence of this is unclear.  I think it would be better (and

consistent with the rest of the explanations) if the suppressed

extension was just suppressed, it is never invoked at all.

<mde>The use cases here are as follows:

1. I want to contribute my stuff, and I want to specialize an existing provider 

like Java, and

2. I want to just specialize another provider, and if it's not turned on, I don't 

even need to be considered.

So in neither case is it completely suppressed, but rather in case 2 it acts 

like a domino of its source provider. I just want to make sure we don't 

lose this meaning in the update of the documentation </mde>

6) Should the NCE class and NavigatorContentDescriptor classes be

combined? They seem to be one-to-one and there is a lot of code that

seems to convert from one to another for no good reason.

<mde>The Descriptor/Extension pattern is used for every part of the framework, here's why:

A Manager handles Descriptors; Managers are singletons, and each known extension

has exactly one Descriptor. The state associated with a Descriptor is just an API 

convenience layer on top of the IConfigurationElement API. These are relatively 

lightweight, and their lifecycle is the lifecycle of the Manager, which is 

effectively the lifecycle of the workbench.

A Service handles Extensions; Services are 1 instance per Common Navigator viewer 

(or whatever client is using the Service). Each Service creates an Extension 

and manages a map from Descriptor (1 instance for each extension for all 

viewers) to its Extension (1 instance for each instance viewer). The Extension 

instance creates instances of classes defined by the plugin extension metadata; 

each of these instances has an associated lifecycle (init .. do work .. dispose) 

and can hold on to system resources (label providers can hold Fonts or Colors, 

content providers might talk to a data source across a network). Most of these 

classes aren't necessarily designed to be re-entrant (they make assumptions 

about the current state of a given viewer, like whether to show 

Packages as hierarchical or flattened). So if I create a Project Explorer, 

and then separately create a MyCustomView and bind Java to each of them, 

I'll have 1 Java Descriptor, and 2 Java Extensions in memory.

Collapsing Descriptors into Extensions would be a fundamental change to the 

framework, eliminate the assumption that there's 1 content 

provider/label provider/etc for each view instance, and make it hard or 

impossible to know when each of the instantiated classes from each 

plugin extension can be disposed. I would not recommend this.

</mde>

7) There are substantial chunks of duplicate code where only one

line is different between the similar methods.

<mde>If you can provide a few examples, I might be able to provide some 

insights here; in many cases, I tried to use the same simple patterns 

throughout the frameworks to keep the overall complexity down, which 

can lead to this kind of pattern.</mde>