Re: [e4-dev] API and package structure

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

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