[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
AW: [pde-dev] [api tools] Extensibility proposals and questions
|
Hi Oleg,
First, with control.xml I referred to the persited form of
IControl, so the file resulting from using the export functionality of the ui. I
am currently not using the ui but generate such a control.xml file and using the
batch mode of the tool. (SnapshotCommands)
Concerning the ClassFileReader: I still see the need to be
able to analyse class files, I am not familiar enough with JDT
though to say whether source and class format can be handled by mainly the
logic.
Now coming back to the extensibility
topic:
What I would like to have extendable is how and from what
source ApiElements are generated. Consider a bunch of jars and some meta data
format that describes dependencies between the jars (possibly including a
mechanism like reexport). I would like to be able to plug in code that reads
that meta data and determines the jars to be analysed and then returns the
corresponding ApiElements.
Although I do not plan to extend the api tools to other
languages it should be possible to allow such extensions.
A major question here is how much change to the
codebase will be accepted?
To give you an overview what I currently have in mind (take
it as a draft):
- IContainerType
- create an ISourceContainer from
container specific information (e.g. from a URL pointing to a
jar)
- provide an ISourceReaders for an
InputStreams
- provide an IApiComparators for an
IApiElements
- provide an
IApiElementFilters
- ISourceContainer
- provide IApiElements
- ISourceReader
- create IApiElement from
InputStream
- IApiComparator
- compare two IApiElements
I think that most of the existing code can be reused
to implement this (e.g. ClassFileReader to implement ISourceReader) but the API
of the API Tools would see massive changes I think.
Code sharing between BundleContainer and JarContainer
would look like:
- They would both use the same ISourceReader implementation
(to read class file streams), BundleContainer may have an additional reader
e.g. for extension points
- They would IApiComparator, again BundleContainer may have
more to compare extension point api elements
- Same for IApiElementFilters
- The containers themselves could both use helper classes
like JarScanner to retrieve InputStreams
As long as containers are written for the Java world I do
not see a problem concerning code reuse. However as soon as it comes to
different languages I agree that it will be no trivial task. But at least it
would be possible to implement if anybody wanted to.
To come to an end:
As I already said this are ideas, some may not be thought
to an end. So any comment is welcome.
I currently had a look only at the api comparison part of
the tools, so I might not have noticed generating problems for the reference
collector part.
Most important question is to what extend will changes to
the code base be acceptable. (Is anybody building anything on top of api
tools?)
And one last question out of curiosity:
Java 1.4 is still the version to be compatible
with?
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
Von:
pde-dev-bounces@xxxxxxxxxxx [mailto:pde-dev-bounces@xxxxxxxxxxx] Im Auftrag
von Oleg Besedin
Gesendet: Mittwoch, 5. September 2007
18:20
An: Eclipse PDE general developers list.
Betreff: Re:
[pde-dev] [api tools] Extensibility proposals and questions
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 ... _______________________________________________
pde-dev mailing
list
pde-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/pde-dev
