[e4-dev] API and package structure

[Eric Moffatt <emoffatt@xxxxxxxxxx>]

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