bundles/org.eclipse.rap.ui.navigator/notes.txt

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>