Re: [pde-dev] [api tools] Extensibility proposals and questions

[Oleg Besedin <obesedin@xxxxxxxxxx>]

Hi Jan,
This is a good place to discuss API
Tools project.

First, thank you to tracking down that
issue with "old" style plug-ins - greatly appreciated.

Some questions you are raising seem
to be centered on extensibility of API tools. As you found, at present
they have no "consumer" extensibility. I certainly see that different
views are possible here, but don't forget that it all comes at a cost.
Some concrete examples of where full-blown extensibility support (as opposing
to making the API tool better) might help.

Points to consider here:

- non-Java languages: To me, it seems
that determination of what is an API breaking change is highly language-specific.
Should you decide to add support for different languages, not only source
container and notion of API, but comparator and report generator would
have to be changed. As such, not much code would be reused by adopting
it to a different language. 

- common API definitions across teams:
Another point in favor of putting improvements into the API tool itself
is the expected usage pattern. We expect that the tool will be used by
multiple development teams to combine data into a common repository. For
this we don't want the definition of APIs used by one team to deviate too
much from the other team.

Overall, going with an analogy, personally,
I prefer kitchen appliances with the least number of buttons. My dishwasher
has 2 button and two dials. All I need from it is that one button that
says "wash dishes". The API tool already has too many buttons,
I would rather hope to remove some than add a new interface where people
can plug a custom soap dispenser :-). But that's just me :-).


On specific points:

- control.xml - did you mean component.xml?
In any case, those files did fall out of favor and universally became stale.
It seems that the notion of having to remember to maintain a separate file
with API information did not work for developers. Hopefully, the new Javadoc
tags will be more successful.

- What clases are considered APIs: it
is likely that a new mechanism will be added. From what I understand, it
will take a file with text patterns. Classes with names matching patters
would be treated as APIs. (That's in addition to OSGi manifests.) This
goes against the point above, but there is already a product using this
approach and, of course, we want all its users to switch to API tools.
(And there are people willing to contribute code for this :-).)

- Update site as a source: yes, it would
be interesting to add update site to the list of elements analyzed by the
tool. The "analyze full installation" option is already there
("Include all bundles" under Target platform) but probably needs
to be made more visible. 

- Extension poins as APIs - I like the
idea, but from the top of my head it is non-trivial to implement. Consider
that DTDs would have to be compared to determine compatibility and that
extension points can be moved into different bundles since 3.2. This is
an interesting area, certainly contributions will be appreciated.

- Reason
for ClassFileReader - historically,
we attempted to make API Tools into both a plug-in and a small RCP application.
For the RCP version we attempted to reduce the number of bundles involved
- hence ClassFileReader came
into play. Later it evolved to include reference resolution. As Javadocs
are generally not present in the .class files, something different, likely
JDT, will be used in future. 

Sincerely,
Oleg Besedin

"Lohre, Jan" <jan.lohre@xxxxxxx>
Sent by: pde-dev-bounces@xxxxxxxxxxx

09/05/2007 09:48 AM

Please respond to
"Eclipse PDE general developers list." <pde-dev@xxxxxxxxxxx>

To	<pde-dev@xxxxxxxxxxx>
cc
Subject	[pde-dev] [api tools] Extensibility proposals and questions

Hi,
 
first of all, if there is a mailing list
better suited for PDE Incubator API Tools, please point me there.
 
I see some potential to introduce extensibility
to the api tools:
1. SourceContainer
What classes have to be taken into account?
Currently this is done for bundles, jars
and directories by scanning the provided URL for .class files. And then
filtering out what is not considered API.          
 
For bundles using PDE code and thus relying
on plugin metadata (Exported-Packages), for jars and directories .internal
in the package name is used to determine non-API.
 
Just for PDE use cases I would see more than
one Container implementation, e.g. target (analyse a full installation),
updatesite (it may be neccessary to analyse jars contained in jars) and
bundle.
Other technologies may have other metadata
to describe api elements.
 
I would propose to establish an extension
point to provide SourceContainers for a type that can be set in the control.xml
like
<container type="type-id" location="location-of-sources"/>.
Additionally I would allow container elements to have arbitrary child nodes
so one can add type specific data.
 
Another question would be what else has to
be considered API?
Shouldn't a plugin api report contain extension
points as api elements?
Other technologies may have other non-java
elements to be considered api.
 
To allow technology specific non-java api
elements one possibility may be to allow SourceContainers to provide special
ApiReaders that produce IApiElements, the default one being a java class
analyser. Of course one would also have to provide compare and report handling
for those elements.
 
2. Api definition
What is Api breakage?
For example if an interface is not designed
to be implemented by clients, addition of methods is no breakage.
Such an extension would have to plug into
both IApiElement creation and comparison. For example one might define
an annotation @DoNotImplement and annotate an interface with it and add
a method in the next version. During IApiElement creation this additional
information has to be stored, during comparison the Diff found by the Comparator
can be deleted before being passed to the reporter.
 
What do you think? Any comments are welcome.
 
 
Why is there a ClassFileReader implemented
in the api tools? Why not use the one in JDT?
As far as a I understood the DevGuide the
reason is performance. Is the special parser significantly faster than
the JDT parser?
To allow extenders to analyse additional
data (like annotations) more information may be neccessary than currently
provided by the specialized parser.
 
 
Kind regards,
Jan
 
Jan Lohre
Developer
SAP AG
Dietmar-Hopp-Allee
69190 Walldorf Germany
T   +49 6227 7 43017
F   +49 6227 78-43856
mailto:jan.lohre@xxxxxxx
www.sap.com
 
Sitz der Gesellschaft/Registered
Office: Walldorf, Germany
Vorstand/SAP Executive Board:
Henning Kagermann(Sprecher/CEO),
Shai Agassi, Léo Apotheker, Werner Brandt, Claus Heinrich, Gerhard Oswald,
Peter Zencke
Vorsitzender des Aufsichtsrats/Chairperson
of the SAP Supervisory Board: Hasso Plattner
Registergericht/Commercial
Register: Mannheim
No HRB 350269
 
Diese E-Mail kann Betriebs-
oder Geschäftsgeheimnisse oder sonstige vertrauliche Informationen enthalten.
Sollten Sie diese E-Mail irrtümlich erhalten haben, ist Ihnen eine Kenntnissnahme
des Inhalts, eine Vervielfältigung oder Weitergabe der E-Mail ausdrücklich
untersagt. Bitte benachrichtigen Sie uns und vernichten Sie die empfangene
E-Mail.
Vielen Dank.
 
This e-mail may contain trade
secrets or privileged, undisclosed, or otherwise confidential information.
If you have received this e-mail in error, you are hereby notified that
any review, copying, or distribution of it is strictly prohibited. Please
inform us immediatly and destroy the original transmittal.
Thank you for your cooperation
 _______________________________________________
pde-dev mailing list
pde-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/pde-dev