Revision as of 16:22, 16 September 2010

Eclipse 4.0 SDK Review

Eclipse 4.0 Early Adopter Release was released at the end of July. The final few months of this release were a time of great churn ("Get 'er done !"), meaning that we had no time to review and/or modify the existing architecture but had to go with what we had.

Now we have a chance to go back and examine the decisions we've made and make whatever adjustments are necessary during the current 4.1 SDK development cycle. This includes not only code patterns, API and such but also packaging issues such as bundle names and dependencies...

Note, while we have this opportunity we have to act soon, we expect to start getting defects reported by the components and if we delay too long it'll just end up being 'too late' again.

This page is broken into various 'component areas' loosely alligned with the parts of the code that are affected by the decisions. For each we should determine the correct approach and then move towards it as fast as possible, the ouput from the discussions about topics on this page should be actual work items, defining the chosen implementation, who's going to drive it and some estimate of how long it'll take.

Extensions

We know we need to handle legacy extensions in the compatibility layer but beyond that what's our story? The current e4 approach was to use 'descriptors' that would be added through the model 'snippet' extension. If we want to go this route we still need to flesh it out to include, at minimum, perspectives and windows.

Are there any existing extension points (org.eclipse.ui.menus, views, edtiors...) that it would make sense to support directly in e4?

What is the current state of the compatibility layer's handling of our surrent extensions?

What are the 'deltas' used for? This is in this section because the original discussions revolved around its use in managing bundles coming/going but there is no apparent use for this mechanism at the moment.

How do we contribute Addons ?

API

E4 exposes its API(s) in ways that are fundamentally different from how they were exposed in 3.x (sort of the whole point actually...;-). The idea for this isn't to nail down the specifics of any of the particular API's but rather to define the patterns needed to implement a particular piece of API as well as seeing if we can determine heuristics that will help us determine which API mechanism is most appropriate to use to expose new capabilities.

Each of these needs to be both examined to determine if the capability it being exposed through the correct mechanism and to ensure that all API is 'discoverable'.

Context / Services

Access to services is through the context but:

Which ones are available?

Are we missing any?

Are there elements in the context that, while not services, should be considered API?

How do folks discover them? This is the important question, once we know how to propely define a new API service providing new ones should just be a 'rinse and repeat' crank-turning.

We need a clear explanation of how both active parts and selection are handled.

Looking at the context the other way around do we really need everything that's currently there?

Annotations

DI is an extremely powerful and flexible mechanism. Its 'looseness' is both its greatest strength and potentially its major weakness. This is again mostly about how a user can determine what the valid annotations are and how they can be used.

How do folks contribute new anntations in a manner that makes them discoverable?

Tags

It's questionable whether or not tags should ever be considered API but they are available and may be appropriate to use in some cases. Should we determine that we want to allow tags we need to determine the discoverability mechanism as well. Note that we currently don't handle nuances usch as 'fixed' perspectives so we're either going to have to augment the model or use tags. The main advantage to using tags is that it allows the EMF model structure to remain constant while adding special case handling.

Context Useage

What's in the context?

Why is it there?

Is it API?

Why so much churn (as defined by the number of RATs firing in variour situations)?

Enterprise Ready

Aside from just getting everything to work we also need to bring the 4.1 code up to snuff as far as being ready for enterprise level customers. This means having an implementation for all of the 'checkbox' items (NLS, BiDi, Accessibility, others??) but also to 'harden' the current code but providing better exception trapping and logging (with a special focus on trying to provide the most informative messages as possible).

We should do a general code review to ensure that hacks are eliminated (we have places where there is in-line code that should be moved into either the Model or Part services...). At the same time we should be on the lookout for places where we could safe up the code.

Safety checks:

• should be around all execution of contributed code (as in 3.x).
• All event publications should be wrapped because they can indirectly invoke 'user' code
• Others ?

NLS

There are actually two different mechanisms used by the 3.x version of eclipse (and the current compatibility layer):

• Classes that extend the org.eclipse.osgi.util.NLS class: For eclipse this is used to define the 'static' strings used to construct dialogs or displayable error messages...This is a proven, viable technique and could easily be adopted by e4 developers.
  
• PDE support: This is more appilcable to the compatibility layer since it's already based on using extension points.

What we're missing is a story for how to handle e4 models that want their MUILabel information internationalized (label, tooltips and images).

Do we want to create a new TranslationService ?

Do we want to override the 'get' methods on MUILabel to 'automagically' return the translated info? (If so how do folks contribute translations for particular locales...?)

Accessibility

We need to support accessibility. This in general means:

• Keyboard support: Ensure that the renderers set up a reasonable tab order. Note that if we can do a good enough job with the 'Quick Access' then we would cover a lot of accessibility issues, especially if we had extra filters for navigation operaions.
• Screen Reader support: for us that means using IAccessible2 through the renderers. At minimum we will need to augment the model with; a specific 'accessibiliyPhrase' for an MUIElement (even containers need them) IAccessible2 also provides for the capability to reference a different widget from which the reader will retrieve the information. This is mostly used within dialogs to have a Text field/Table/Tree reference the actual 'label' widget so perhaps this isn't strctly necessary for e4.
• High Contrast: In e4 this should be possible through a specialized CSS...is it ? Special bonuses if we can get FireFox-like Ctrl + / - working against the workbench's fonts (old(er)  guys like me use this all the time...;-)
  

Intro

We have to re-implement the Intro story. While we could re-implement the mechanism in the 3.x layer to make the code more consistent (i.e. getting rid of the IntroManager/IntroPart...) it may well be that this would be far harder than providing an implementation of these classes in the compatibility layer.

Do e4 RCP apps want Intro? Do they want it in its current form or a new one?

Compatibility Workbench life-cycle

Thsi is something that needs prompt attention. The current way we define and populate the model (and the contexts) for the compatibility layer is antithetical to proper use of the model. We currently start with an almost empty window models and populate it using code in the WorkbenchWindow's 'setup' method. We also tear down large chunks of the model on close, only to re-create them on the next start. This is related to the dynamic bundle issues in that most of this work is being done to manage the dynamic bundles but the result is that we lose the ability to leverage the model itself.

The optimal solution here (if possible) would be to revamp our current life cycle so that the compatibility layer is implemented as one or more addons to the regular e4 RCP life-cycle. This will require us to re-examine how/when we create the compatibility instances of Workbench/WorkbenchWindow but this should be doable (maybe?).

Model

There are a number of model changes being proposed. These are currently being covered using this defect: https://bugs.eclipse.org/bugs/show_bug.cgi?id=324957

We must be extremely careful when making changes to the model because we currently have NO story for how to bring an existing 4.0 model up to the 4.1 version. Alternatively we could implement the mechanism to do this but my suspicion is that it's non-trivial (at least) and may need significant lead time to get the design and techniques defined.

We've identified that we need a specific 'area' container to represent the Editor Area in the compatibility layer (since it, for example, minimizes or maximizes as one unit). Should we formalize this in the model or make it a specialized rendering of an MPSContainer ?

EMail comments (for reference)

Eric ------------

Here's my take on the major areas that still require deep(er) discussion/specification, I'm leaving out the areas already identified as being 'needed' such as Welcome, NLS...since they're already on the wiki:

1) E4 Extension Architecture:

I put this one first because of its impact on the rest of the architecture. It's more relevant to the compatibility layer implementation at this point but e4 surely needs some extensions as well. Some of the issues with the current setup are:

- We currently create WorkbenchWindows in *code* rather than from some model 'template', this includes not only the Toolbars but the other trim elements as well. Note that we 'tear down' all out 'contribution' before saving the model, this is surely suspect...one ramification is that I cannot possibly implement re-ordering of tool bars since the info is removed from the model on close.

- I see no use of the 'deltas' file. I know we have discussed how this might be used but it currently seems to have no advantages over simply storing the model. Note that if we want a properly dynamic plug-in story the framework will have to be capable of handling new / removed extensions in a 'live' environment (aka 'hot oil change')...

2) Context (over) use:

While the context / DI make a truly powerful combination I think that we may be over-using it, especially as far as command management goes but also for basics like active part...we should likely review all of our current uses of the Context to assure ourselves that everything is needed...

General:

I'm +1 for a general code review, looking to make sure that we haven't left behind various 'interim' fixes that are no longer necessary We should review all of our uses of 'tags' and decide what's API and what isn't Model review....if we need changes then teh earlier the better so we have more time to deal with the model 'upgrade' issues

A less code oriented note about the 4.1 SDK...perhaps we should put together a 'scoreboard' where we can keep track of what's been checked, what defects they found and who to contact. We could publish this on the wiki (or nor) but at the moment we don't have any way to measure our progress against 4.1...

Paul ------------------

1) probably related to Eric's #1. We currently read the extension points that make sense and convert them to model elements. Because of lifecycle, we've been creating them at inopportune moments (i.e. building a WorkbenchWindow around an MWindow model element, but after our primary model has been created). Should we be accessing extensions and model containers in some kind of merged fashion? Or should we be moving extension point readers into e4 model creation steps, so they're out of the compat layer all together.

2) we hard code a lot of creation into compat objects. i.e. WorkbenchWindow and Part initializeDefaultServices(). For services or information that we need to be level dependent, we should probably be using the Add-on mechanism to make sure event listeners are in place, and the creation of an EclipseContext at the appropriate model element to trigger the creation at that level.

3) provinding services and data to handlers in the EclipseContexts

3a) if you are adding data to your MPart context, it has to possibly be visible at 4 levels

- a popup menu in your MPart is an MPopupMenu with its own context, parented off of the MPart context

- the MPart context will be used by regular part toolbar or part dropdown menu (for "views")

- if the window toolitems or window menu items execute that command, they use the MWindow context and should be able to see the data

- keybindings get their @Execute and @CanExecute information from the MApplication context

3b) you can add a "service" 5 ways, each with different implications for when it is available

- when the MPart is created you can just set X.class.getName() => xInstance

- you can set X.class.getName() => context function, that will instantiate and return the xInstance when asked

- you can use the event broker to listen for a context being set, and then perform one of the above 2 steps

- you can provide a context function through DS which will then be available at the root context

- you can simply provide an OSGi service which will be available at the root context

4) rendering: visible. Our attribute doesn't quite mean what we'd like.

ex: toBeRendered - that's obvious, if it's false, the renderers can't see it. In the case of parts, that means there's probably a tab in a stack for it.

visible ... true == for most things that means it can be instantiated and we'll set widget.setVisible(true). visible ... false == it might be instantiated and setVisible(false). It might not be instantiated

it seems that we are describing 3 states: toBeRendered (can the renders see it), instantiated (can it have a widget), and hidden (can the user see it).

5) we went with a display filter for menus, so that on an SWT.Show we process a lot of MMenuContributions and visibility (and other stuff). It has 2 side effects that bear examining now

- if a submenu is empty, you must still have it there with "(none available)". Otherwise it will never be processed.

- a lot of inconsistency in ordering, positioning, and existence. This is because the menu mode structure is not stable at all. Another possibility would be to create the stable menu structure and then allow their rendering status or visibility to be updated on an SWT.Show.

Remy -----------------

1. Need to sort out how e4 parts will co-exist with 3.x parts. https://bugs.eclipse.org/bugs/show_bug.cgi?id=323506

2. Finalize the semantics of the shared area. https://bugs.eclipse.org/bugs/show_bug.cgi?id=321864

3. Need localization story for e4.

Tom -----------------

Major design break because ui.workbench depends on SWT which violates the core e4 design where only the renderers have a dependency on UI-Toolkits. https://bugs.eclipse.org/bugs/show_bug.cgi?id=319713