Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "PDE/API Tools"
(→Usecases) |
(→Usecases) |
||
| Line 56: | Line 56: | ||
These are the usecases that we would like to cover with the API tooling:<br> | These are the usecases that we would like to cover with the API tooling:<br> | ||
<ul> | <ul> | ||
| − | <li>API Management: comparison, browing, visualizing<li> | + | <li>API Management: comparison (ensure backward compatibility), browing, visualizing<li> |
<li>Global Find references: This could be used to find all usages of an API from data stored in a "repository". The repository could be a database, a file in memory,...<br> | <li>Global Find references: This could be used to find all usages of an API from data stored in a "repository". The repository could be a database, a file in memory,...<br> | ||
It could also be used to find all usages of internal codes inside bundles. This is a useful information for committers when they want modify an internal method.<br> They could know who they are going to break and have a proactive way to solve this issue (add another method, inform users about a future breakage,...)</li> | It could also be used to find all usages of internal codes inside bundles. This is a useful information for committers when they want modify an internal method.<br> They could know who they are going to break and have a proactive way to solve this issue (add another method, inform users about a future breakage,...)</li> | ||
<li>Version checking: It will help users to update theirs bundle version numbers according to the kind of changes made in a bundle: fix, new API,...</li> | <li>Version checking: It will help users to update theirs bundle version numbers according to the kind of changes made in a bundle: fix, new API,...</li> | ||
| − | <li>Build analysis: JRE used to build vs JRE used to run, check dependencies</li> | + | <li>Build analysis: JRE used to build vs JRE used to run, check dependencies. Check that a plugin uses only API that is available in the '''lower bound''' of the Prerequisites.</li> |
| − | <li> | + | <li>Prerequisite browing: find out what we use and why</li> |
</ul> | </ul> | ||
Revision as of 16:00, 6 September 2007
API tooling is a collection of utilities that can be used in API maintenance and consistency checks. We hope to explore four directions here:
- API Comparison tool
- API comparison – discover new APIs, modified APIs, flag APIs that are modified in a non-backward compatible way
- Bundle version checking – use API comparison results to see if version number of a bundle has been properly incremented
- Reference Extractor tool
- Usage discovery – allow developers to discover who is using their APIs and non-APIs
- Usage validation – check if usage of APIs from other bundles fits into Eclipse standards
Also note that there is an ongoing work on API visualization.
Contents
Present state
At present we have functional API comparison tool that received moderate amount of testing.
The Reference extractor has reference extraction working but only skeleton code exists for processing of queries.
Plans
JDT models as a source: in addition to the processing of .class files, add code to create API snapshots from JDT models. The Javadoc tags then could be used to pass "soft" API restrictions to the tool such as "this interface can not be implemented by clients".
Scalable repository: in addition to files on file system, support storage of API snapshot in an SQL database. Pros: improved scalability and reliability; new functionality could be added an a form of queries, possibly, via Web interface.
API Comparison tool
API Comparison tool: discovers backward compatibility problems and new APIs
The tool can be used to create API snapshot of a set of bundles / jars / directories. The snapshot is used as a baseline to compare against another version of the source code to discover problems in API backward compatibility and new APIs.
The tool is written in modular fashion. It has an “engine” with replaceable input and output. Presently OSGi bundles, Java jars, and directories can be used as an input sources. The snapshot output is saved into zip-ed xml file. Comparison results are produced as XML file which is transformed into HTML for ease of reading.
User guide to the API comparison tool
Developer guide to the API comparison tool
Reference Extractor tool
The Reference Extractor tool is there to answer the following three questions:
- Who is using my APIs/non-APIs
- What my code is using
- Identify "internal" methods being used
It does it by processing code to extract dependency information from it. The request are combined in the repository that could be queried to find downstream dependencies.
Developer guide to the Reference Extractor tool
Usecases
These are the usecases that we would like to cover with the API tooling:
- API Management: comparison (ensure backward compatibility), browing, visualizing
- Global Find references: This could be used to find all usages of an API from data stored in a "repository". The repository could be a database, a file in memory,...
It could also be used to find all usages of internal codes inside bundles. This is a useful information for committers when they want modify an internal method.
They could know who they are going to break and have a proactive way to solve this issue (add another method, inform users about a future breakage,...) - Version checking: It will help users to update theirs bundle version numbers according to the kind of changes made in a bundle: fix, new API,...
- Build analysis: JRE used to build vs JRE used to run, check dependencies. Check that a plugin uses only API that is available in the lower bound of the Prerequisites.
- Prerequisite browing: find out what we use and why
Open issues
- How to markup the code with information for the API tool. Information like "can you subclass, instantiate, implement,...".
- SPI are technically speaking API, but with the freedom of being changed at any time.
- The tool must be able to:
- run headless without any workspace, embedded in releng builds.
- notify developers asap of issues
- must scale
- input could be: bundles, jars, Eclipse installation, directory of .class files or jars
- should be able to specify what an API is in a input file
- batch and incremental processing
Links
Evolving Java-based APIs - What is considered an API in Eclipse.
Resources
Eclipse Bugzilla - Eclipse bug tracking database.
PDE Incubator - New projects that might be incorporated into PDE in future.
PDE UI Home Page - The main PDE UI web site.