[e4-dev] Fw: API and package structure

[Eric Moffatt <emoffatt@xxxxxxxxxx>]

----- Forwarded by Eric
Moffatt/Ottawa/IBM on 04/26/2011 10:00 AM -----

From:	Eric Moffatt/Ottawa/IBM
To:	Eric Moffatt/Ottawa/IBM@IBMCA
Date:	03/30/2011 02:04 PM
Subject:	Fw: [e4-dev] API and package structure

---

----- Forwarded by Eric
Moffatt/Ottawa/IBM on 03/30/2011 02:03 PM -----

From:	Eric Moffatt/Ottawa/IBM
To:	E4 Project developer mailing list <e4-dev@xxxxxxxxxxx>
Date:	02/11/2011 02:22 PM
Subject:	Re: [e4-dev] API and package structure

---

John thanks for the excellent in-depth
analysis. This most certainly points out that we have some re-factoring
to do...;-).


One of the nice things about e4 is that
there are only two 'kinds' of API: the Model and stuff you can 'get' from
some context (either directly or through injection). I've spent the last
few days hacking on Oleg's 'Contexts' viewer as well as placing specialized
code into EclipseContext itself in order to come up with some 'context
usage' info...this uses the tool to identify what is in a particular context.
For each entry there will also be a list of the contexts *through which*
that element was 'gotten'. Since the DI engine uses the 'get(String)' method
(as does the 'get(Class T)' version) this should be complete for API purposes
(i.e. it will miss Computations that may be 'set' but never have an explicit
'get' but these are by definition not API).

Here's the complete input (this was
compiled while running the compatibility layer and may be missing some
E4-specific services, let me know if you don't see something here that
should be in an E4 App's context...



Lazy Consensus Warning:
Input will be accepted to modify this list until March 1st, then this is
 the API that we present at EclipseCon. 

NOTE: Most of you have more experience
using the base E4 API's than I do so please go over this list thoroughly
to ensure that it includes at least those elements that you have need in
your RCP development... Once we determine what's 'in' we can then decide
on how to best expose the api (and where to put the internals).

Injection Annotations:

@Inject
@Optional
@Named
@PostConstruct
@PreDestroy

E4 Specific  injection:

@CanExecute
@Execute
@Focus
@Persist


E4 Application Context:

Application Parameters:

applicationCSS (E4Workbench#CSS_URI_ARG)
applicationCSSResources
(E4Workbench#CSS_RESOURCE_URI_ARG)
applicationXMI (E4Workbench#XMI_URI_ARG)
clearPersistedState (E4Workbench#CLEAR_PERSISTED_STATE)
deltaRestore (E4Workbench#DELTA_RESTORE)
cssTheme (E4Application#THEME_ID)
initialWorkbenchModelURI
(E4Workbench#INITIAL_WORKBENCH_MODEL_URI)
instanceLocation (E4Workbench#INSTANCE_LOCATION)
persistState (E4Workbench#PERSIST_STATE)

Services:

org.eclipse.core.databinding.observable.Realm
org.eclipse.core.runtime.dynamichelpers.IExtensionTracker
org.eclipse.core.runtime.IExtensionRegistry
org.eclipse.core.runtime.Platform
org.eclipse.e4.core.commands.ECommandService
org.eclipse.e4.core.commands.EHandlerService
org.eclipse.e4.core.services.adapter.Adapter
org.eclipse.e4.core.services.events.IEventBroker
org.eclipse.e4.core.services.log.Logge
org.eclipse.e4.core.services.translation.TranslationService
org.eclipse.e4.ui.css.swt.theme.IThemeEngine
org.eclipse.e4.ui.services.IStylingEngine
org.eclipse.e4.ui.workbench.IPresentationEngine
org.eclipse.e4.ui.workbench.IResourceUtilities
org.eclipse.e4.ui.workbench.modeling.EModelService
org.eclipse.equinox.app.IApplicationContext
org.eclipse.jface.preference.PreferenceManager
org.eclipse.ui.ISharedImages
org.eclipse.ui.progress.IProgressService

Runtime Data::

activePart (IServiceCOnstants#ACTIVE_PART)
org.eclipse.e4.core.locale
(TranslationService#
LOCALE)
org.eclipse.e4.ui.model.application.MApplication
selection (ESelectionService#SELECTION)

Top Level Window Context:

Model Info: * When a context is created
for any MContext element all of its implemented interfaces
are added to its context

org.eclipse.e4.ui.model.application.commands.MBindings
org.eclipse.e4.ui.model.application.commands.MHandlerContainer
org.eclipse.e4.ui.model.application.MApplicationElement
org.eclipse.e4.ui.model.application.ui.basic.MTrimmedWindow
org.eclipse.e4.ui.model.application.ui.basic.MWindow
org.eclipse.e4.ui.model.application.ui.MContext
org.eclipse.e4.ui.model.application.ui.MElementContainer
org.eclipse.e4.ui.model.application.ui.MUIElement
org.eclipse.e4.ui.model.application.ui.MUILabel

Services:

org.eclipse.e4.ui.workbench.modeling.ESelectionService
org.eclipse.e4.ui.workbench.modeling.ISaveHandler
org.eclipse.e4.ui.workbench.modeling.EPartService

Runtime Data:

activePart (IServiceCOnstants#ACTIVE_PART)
selection (ESelectionService#SELECTION)

Part Context:

Model Info:

org.eclipse.e4.ui.model.application.commands.MBindings
org.eclipse.e4.ui.model.application.commands.MHandlerContainer
org.eclipse.e4.ui.model.application.MApplicationElement
org.eclipse.e4.ui.model.application.MContribution
org.eclipse.e4.ui.model.application.ui.basic.MPart
org.eclipse.e4.ui.model.application.ui.basic.MPartSashContainerElement
org.eclipse.e4.ui.model.application.ui.basic.MStackElement
org.eclipse.e4.ui.model.application.ui.basic.MWindowElement
org.eclipse.e4.ui.model.application.ui.MContext
org.eclipse.e4.ui.model.application.ui.MDirtyable
org.eclipse.e4.ui.model.application.ui.MUIElement
org.eclipse.e4.ui.model.application.ui.MUILabel

Services:

org.eclipse.e4.ui.workbench.modeling.EPartService

Onwards,
Eric

From:	John Arthorne/Ottawa/IBM@IBMCA
To:	E4 Project developer mailing list <e4-dev@xxxxxxxxxxx>
Date:	01/31/2011 09:45 AM
Subject:	Re: [e4-dev] API and package structure
Sent by:	e4-dev-bounces@xxxxxxxxxxx

---

First some very general comments:

- This does not have to be an "all or nothing" effort. I.e.,
we don't need to end up in 4.1 with no provisional API. Given the time
and resources available I suggest identifying a fairly limited core set
of API to declare this release. It's better to produce a small set of well-polished
API than a large set of API of varying quality. 
- By a rough count, the e4 bundles currently define 47 *new* provisional
API packages, and another 36 packages for the CSS support. I didn't count
the classes, but this is a *lot* of new API. One of the goals of e4 was
to make programming Eclipse easier, and I don't think an extra 83 packages
of API moves us closer to that goal. 
- To help focus the effort, it would help to think of what the target audience
of the API is, and what are the main use cases we want to support. I think
the first audience to focus on is "bread and butter" plug-in
writers. I.e., people writing simple plugins with views, editors, commands,
etc. The other group is people writing their own applications that want
to customize the model, write their own stylers and renderers, etc. If
the API for this second group is not ready for 4.1 I think it would be
ok to leave some of it provisional. 
- The segment "e4" needs to be dropped from all package and class
names because this code is no longer in the e4 incubator. The simplest
change would be to just drop the extra segment... org.eclipse.e4.core*
becomes org.eclipse.core.*, etc. In some cases this would cause collision
with 3.x packages so they would have to take on different names. The other
approach would be to maintain a strong separate between 3.x and 4.x package
names, by calling all 4.x packages something like org.eclipse.platform.*.
I kind of like this idea of maintaining a hint in the package name to delineate
"old" from "new" ways of doing things, but I'm curious
to hear what others think. 

On to specifics, I see four main areas of potential API:

1) Core: contexts and injection. Overall I think this provisional API is
in very good shape, and it's the one I'm least worried about.

2) Eclipse Application Services. Unfortunately I don't think much of this
is ready to become real API, and I know there is little work going into
it in 4.1. I think the best hope here is to let Orion drive the work on
what a new, simple platform API might look like. Since Orion is forced
to start over from scratch, it is our best opportunity to rethink and redefine
what this core API looks like. Also validating that the API can be written
in _javascript_ will give us a lot of confidence that we can do a cross-language
API. We are Java experts so I am confident we can take a JS API and translate
it to Java (the other direction I'm not so sure about). Also, I think the
logging and status handling services in particular need to be reconsidered
in light of the significant work Tom has done in 3.7 Equinox to produce
a unified logging story. 

3) CSS. The provisional e4.ui.css.* packages right now are a mixed bag.
There are a few packages of well defined API, and many other packages that
seem to be a mixture of API and implementation without a great deal of
thought to the separation. Unless someone has a big chunk of time to invest
in cleaning this up for 4.1, I suggest leaving all of this provisional
for 4.1. The main way this stuff will be used is by application authors
writing CSS files, which can be done without any Java API as far as I know.
Being able to plug into and extend the CSS engine itself seems secondary.

4) Modeled workbench. I'm glad there are other experts in this area because
it's not at all clear to me what the API exposure of the model should be.
From the perspective of a typical plug-in writer, exposing the model seems
like far too much information. If my plug-in makes too many assumptions
about the shape of the model it will unlikely to work properly in a different
application that has a different model. If you imagine that we had made
the physical structure of the workbench into API in 3.x, I think we would
have been severely limited in what we could do in the future. I'm also
worried about the idea of maintaining binary compatibility for auto-generated
code - I have no idea what kind of constraints that puts on the evolution
of the model definition that is used to generate it. I have more thoughts
on the model API but would like to hear the opening position on API from
the modeling experts on the team. Over the years I have heard the full
spectrum from "no API" to "the model is the only API we
need" in this area. 

John

Eric Moffatt/Ottawa/IBM@IBMCA
Sent by: e4-dev-bounces@xxxxxxxxxxx

01/18/2011 04:20 PM

Please respond to
E4 Project developer mailing list <e4-dev@xxxxxxxxxxx>

To	e4-dev@xxxxxxxxxxx
cc
Subject	[e4-dev] API and package structure

Our current package structure has grown in a basically 'organic' manner
up to now. I don't think that anybody on this list would declare the current
project/package structure to be ideal and it's time for a final (?) refactoring.
The API and the corresponding package structure are co-dependent so we
should look at both at the same time. This should also help us focus our
documentation efforts. 

The scenario that lead to this email was that Oleg had factored some code
out of the existing ModelServiceImpl into a 'ModelUtils' class. The reason
was that he needed the code accessible from the model project in order
to implement some translation methods within the generated code. Unfortunately
the service's implementation currently exists in the 'org.eclipse.e4.ui.workbench'
package, leading to circular dependencies... 

It's fairly obvious that we should be able to package both the model and
part services at a layer lower than 'workbench' but what's the correct
place for them ? 

The more general questions are: 

What's API ? 
How should we package the API to reduce dependencies ?

Anything identified as API  should not be contained within a package
that is mostly unrelated implementation code. Ideally we'd end up with
a single package that depends on as little else as possible but allows
access to anything we declare as API + some implementation packages providing
our particular implementations for folks that don't want to re-invent the
wheel. 

So the initial question is "What's API and is it in the right place
?" 

For example: 

IPresentationEngine is API but is currently in the wrong place (o.e.e.u.workbench
again) 
EModelService and EPartService ditto 

Also worth looking at are whether packages we declare as API have non-API
(or even obsolete) content...for example the 'org.eclipse.e4.core.services'
project contains many things that I suspect are not part of the *graduated*
API. 

Regards, 
Eric _______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev
_______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev




WorkbenchContext:

activeChildContext
activeContexts [WB, WBW, Part]
activeEditor [WB, WBW, Part]
activeEditorId [WBW, Part]
activeEditorInput
activePart [WB, WBW, Part]
activePartId [WBW, Part]
activeShell [Part]
activeSite
activeWorkbenchWindow [WB, WBW, Part]
activeWorkbenchWindowShell
applicationCSS [WB]
applicationCSSResources [WB]
applicationXMI
clearPersistedState [WB]
cssTheme [WB]
debugString
deltaRestore [WB]
e4ActivePart [WB, WBW]
initialWorkbenchModelURI [WB]
instanceLocation [WB]
limbo [Perspective]
localActiveShell [Part]
localContexts
menu:org.eclipse.ui.main.menu [Anonymous Context]
org.eclipse.core.commands.CommandManager [WB]
org.eclipse.core.commands.contexts.ContextManager [WB, WBW, MultiPageEditorSite]
org.eclipse.core.databinding.observable.Realm
org.eclipse.core.runtime.dynamichelpers.IExtensionTracker [WB, WBW]
org.eclipse.core.runtime.IExtensionRegistry [WB, WBW]
org.eclipse.core.runtime.Platform
org.eclipse.e4.core.commands.ECommandService [WB, WBW, Part, MultiPageEditorSite]
org.eclipse.e4.core.commands.EHandlerService [WB, WBW, Part, MultiPageEditorSite]
org.eclipse.e4.core.internal.contexts.ContextObjectSupplier
org.eclipse.e4.core.locale [WB]
org.eclipse.e4.core.services.adapter.Adapter
org.eclipse.e4.core.services.contributions.IContributionFactory [WB, Anonymous Context, WBW, Part]
org.eclipse.e4.core.services.events.IEventBroker [WB, WBW, Part]
org.eclipse.e4.core.services.log.ILoggerProvider [WB]
org.eclipse.e4.core.services.log.Logger [WB, WBW, Part]
org.eclipse.e4.core.services.translation.TranslationService [WB, Perspective, WBW, Part]
org.eclipse.e4.ui.bindings.EBindingService [WB, WBW]
org.eclipse.e4.ui.bindings.keys.KeyBindingDispatcher [WB]
org.eclipse.e4.ui.css.swt.theme.IThemeEngine
org.eclipse.e4.ui.model.application.MApplication [WB, Anonymous Context, WBW]
org.eclipse.e4.ui.services.EContextService [WB, WBW, MultiPageEditorSite]
org.eclipse.e4.ui.services.IStylingEngine[WBW, Perspective, WB, Part, popup:org.eclipse.jdt.ui.PackageExplorer, popup:#TextEditorContext, popup:#TextRulerContext, popup:#OverviewRulerContext]
org.eclipse.e4.ui.workbench.IExceptionHandler
org.eclipse.e4.ui.workbench.IPresentationEngine [WB, WBW, Perspective]
org.eclipse.e4.ui.workbench.IResourceUtilities [WB, WBW]
org.eclipse.e4.ui.workbench.IWorkbench [WB]
org.eclipse.e4.ui.workbench.modeling.EModelService [WB, WBW]
org.eclipse.e4.ui.workbench.renderers.swt.MenuManagerRenderer
org.eclipse.e4.ui.workbench.renderers.swt.MenuManagerRendererFilter
org.eclipse.e4.ui.workbench.swt.factories.IRendererFactory [WBW, WB, Part]
org.eclipse.equinox.app.IApplicationContext [WB]
org.eclipse.jface.bindings.BindingManager [WB]
org.eclipse.jface.preference.PreferenceManager
org.eclipse.jface.window.IShellProvider
org.eclipse.osgi.framework.log.FrameworkLog [WB]
org.eclipse.osgi.service.debug.DebugOptions [WB]
org.eclipse.swt.widgets.Display [WB]
org.eclipse.ui.activities.IWorkbenchActivitySupport
org.eclipse.ui.commands.ICommandImageService
org.eclipse.ui.commands.ICommandService
org.eclipse.ui.contexts.IContextService
org.eclipse.ui.IDecoratorManager [WB]
org.eclipse.ui.IEditorRegistry [WB]
org.eclipse.ui.internal.intro.IIntroRegistry
org.eclipse.ui.internal.ISelectionConversionService
org.eclipse.ui.internal.registry.ActionSetRegistry
org.eclipse.ui.internal.registry.ActionSetRegistry
org.eclipse.ui.internal.registry.WorkingSetRegistry
org.eclipse.ui.internal.registry.WorkingSetRegistry
org.eclipse.ui.internal.services.IServiceLocatorCreator
org.eclipse.ui.internal.services.IWorkbenchLocationService
org.eclipse.ui.internal.themes.IThemeRegistry
org.eclipse.ui.internal.themes.IThemeRegistry
org.eclipse.ui.internal.wizards.ExportWizardRegistry
org.eclipse.ui.internal.wizards.ExportWizardRegistry
org.eclipse.ui.internal.wizards.ImportWizardRegistry
org.eclipse.ui.internal.wizards.ImportWizardRegistry
org.eclipse.ui.internal.wizards.NewWizardRegistry
org.eclipse.ui.internal.wizards.NewWizardRegistry
org.eclipse.ui.internal.Workbench
org.eclipse.ui.IPerspectiveRegistry [WB]
org.eclipse.ui.ISaveablesLifecycleListener [WBW, MultiPageEditorSite]
org.eclipse.ui.ISharedImages [WB]
org.eclipse.ui.IWorkbench [WBW, WB]
org.eclipse.ui.IWorkingSetManager [WB]
org.eclipse.ui.keys.IBindingService
org.eclipse.ui.menus.IMenuService
org.eclipse.ui.model.IContributionService
org.eclipse.ui.operations.IWorkbenchOperationSupport [WB]
org.eclipse.ui.progress.IProgressService [WB]
org.eclipse.ui.services.IEvaluationService [WB]
org.eclipse.ui.services.ISourceProviderService
org.eclipse.ui.swt.IFocusService
org.eclipse.ui.testing.TestableObject
org.eclipse.ui.views.IViewRegistry [WB]
parentContext
partServiceRoot [WB]
persistState [WB]
presentationURI [WB]
rendererFactoryUri [WB]
selection [WB, WBW, Part]
showInInput
showInSelection

TrimmedWindowImpl (IDEWindow) Context:

activeChildContext
activeContexts [WB, WBW, Part]
activeEditor [WB, WBW, Part]
activeEditorId [WBW, Part]
activeEditorInput
activePart [WB, WBW, Part]
activePartId [WBW, Part]
activeSite
activeWorkbenchWindow [WB, WBW, Part]
activeWorkbenchWindowShell
debugString
e4ActivePart [WB, WBW]
localActiveShell [Part]
localContexts
org.eclipse.core.runtime.dynamichelpers.IExtensionTracker [WB, WBW]
org.eclipse.e4.core.commands.EHandlerService [WB, WBW, Part, MultiPageEditorSite]
org.eclipse.e4.core.internal.contexts.ContextObjectSupplier
org.eclipse.e4.core.services.events.IEventBroker [WB, WBW, Part]
org.eclipse.e4.ui.bindings.EBindingService [WB, WBW]
org.eclipse.e4.ui.internal.workbench.PartServiceImpl
org.eclipse.e4.ui.model.application.commands.MBindings
org.eclipse.e4.ui.model.application.commands.MHandlerContainer
org.eclipse.e4.ui.model.application.MApplicationElement
org.eclipse.e4.ui.model.application.ui.basic.MTrimmedWindow
org.eclipse.e4.ui.model.application.ui.basic.MWindow
org.eclipse.e4.ui.model.application.ui.MContext
org.eclipse.e4.ui.model.application.ui.MElementContainer
org.eclipse.e4.ui.model.application.ui.MUIElement
org.eclipse.e4.ui.model.application.ui.MUILabel
org.eclipse.e4.ui.services.EContextService
org.eclipse.e4.ui.workbench.modeling.EModelService [WB, WBW]
org.eclipse.e4.ui.workbench.modeling.EPartService [WBW, Perspective, Part]
org.eclipse.e4.ui.workbench.modeling.ESelectionService [WBW]
org.eclipse.e4.ui.workbench.modeling.ISaveHandler [WBW]
org.eclipse.e4.ui.workbench.modeling.IWindowCloseHandler
org.eclipse.jface.window.IShellProvider
org.eclipse.swt.widgets.Shell
org.eclipse.ui.internal.handlers.IActionCommandMappingService
org.eclipse.ui.internal.menus.LegacyActionPersistence
org.eclipse.ui.internal.services.IWorkbenchLocationService
org.eclipse.ui.IPartService [Part]
org.eclipse.ui.ISelectionService
org.eclipse.ui.IWorkbenchPage [WBW]
org.eclipse.ui.IWorkbenchWindow [WB, WBW, Part, MultiPageEditorSite, PageSite]
parentContext
partServiceRoot [WBW]
selection [WB, WBW, Part]
showInInput
showInSelection

PerspectiveImpl (org.eclipse.jdt.ui.JavaPerspectove:

activeChildContext
debugString
handler::org.eclipse.ui.window.pinEditor
org.eclipse.e4.ui.model.application.MApplicationElement
org.eclipse.e4.ui.model.application.ui.advanced.MPerspective
org.eclipse.e4.ui.model.application.ui.MContext
org.eclipse.e4.ui.model.application.ui.MElementContainer
org.eclipse.e4.ui.model.application.ui.MUIElement
org.eclipse.e4.ui.model.application.ui.MUILabel
org.eclipse.e4.ui.workbench.modeling.EPartService [WBW, Perspective, Part]
parentContext

PartImpl (org.eclipse.jdt.ui.PackageExplorer) Context

activeShell
debugString
handler::org.eclipse.ui.file.save
handler::org.eclipse.ui.file.saveAll
handler::org.eclipse.ui.navigate.backwardHistory
handler::org.eclipse.ui.navigate.forwardHistory
org.eclipse.e4.core.commands.EHandlerService [WB, WBW, Part, MultiPageEditorSite]
org.eclipse.e4.core.internal.contexts.ContextObjectSupplier
org.eclipse.e4.core.services.events.IEventBroker [WB, WBW, Part]
org.eclipse.e4.ui.model.application.commands.MBindings
org.eclipse.e4.ui.model.application.commands.MHandlerContainer
org.eclipse.e4.ui.model.application.MApplicationElement
org.eclipse.e4.ui.model.application.MContribution
org.eclipse.e4.ui.model.application.ui.basic.MPart
org.eclipse.e4.ui.model.application.ui.basic.MPartSashContainerElement
org.eclipse.e4.ui.model.application.ui.basic.MStackElement
org.eclipse.e4.ui.model.application.ui.basic.MWindowElement
org.eclipse.e4.ui.model.application.ui.MContext
org.eclipse.e4.ui.model.application.ui.MDirtyable
org.eclipse.e4.ui.model.application.ui.MUIElement
org.eclipse.e4.ui.model.application.ui.MUILabel
org.eclipse.e4.ui.workbench.modeling.EPartService [WBW, Perspective, Part]
org.eclipse.swt.widgets.Composite
org.eclipse.ui.IKeyBindingService [Part]
org.eclipse.ui.internal.services.IWorkbenchLocationService [WB, WBW]
org.eclipse.ui.internal.ViewReference
org.eclipse.ui.internal.WorkbenchPartReference$3
org.eclipse.ui.IWorkbenchPartSite
org.eclipse.ui.progress.IProgressService [WB]
org.eclipse.ui.progress.IWorkbenchSiteProgressService [Part]
parentContext