Eclipse, OSGi and API Tooling




                                                                   Chris Aniszczyk (Ecli...
Who am I?
    • Chris Aniszczyk
         Senior Software Engineer at EclipseSource
         Plug-in Development Environm...
Overview
    • The need for tooling
    • Tooling features
    • Tooling in action!
    • Future work
    • Summary
    • ...
The need for tooling

    Remember Kirk’s gigantic Modularity diagram?




4
3    Eclipse, OSGi and API Tooling | Chris An...
Define API
    • APIs are published contracts
       Producers specify the contracts
           Honor contracts release ...
The Ideal Release Equation

     Developer: Compatibility (producer)

                                                    ...
The Ideal Never Happens...

                   Developer: (features + deprecation +
                  Optional extensions ...
What have we done as developers?
    • We use Javadoc™ to document contracts
        This class is not intended to be ins...
More things we do…
    • Manually examine API changes or use some external
      tool before a release (aka the API Police...
And we still fail...




10
 9        Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
And we still fail...
     • At Eclipse, we have had issues with projects
       unintentionally breaking API...
     • Out...
Disclaimer
     • This presentation isn’t about API design

     • API design is still your problem
         Designing qu...
Good fences...




     • Check out some of Joshua Bloch’s presentations
       around API (How to Design API and Why it M...
API Tooling Features




14
13   Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
API Tooling to the Rescue!
     • Reports
           Illegal API use
           Binary incompatibility relative to a bas...
Specifying API Contracts
     • Use Javadoc tags
         E.g. @noimplement, @noextend, @noreference, @noinstantiate


  ...
API Tooling Javadoc Tags




17
16       Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
Example of Published API




18
17       Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
API Usage
     • Once the APIs are specified, the user needs to make
       sure that he/she is using them appropriately.
...
Why API Usage Scans?
     API producers can see what internals are being used
     •   Inform clients how to use proper AP...
Validating Binary Compatibility
     • Evolving APIs such that they are backwards
       compatible with existing binaries...
API Comparisons
     • What’s changed between versions?




22
21       Eclipse, OSGi and API Tooling | Chris Aniszczyk | ...
System Library Validation
     • Validate system library use based on a bundle’s
       required execution environment (BR...
Migration Assistance
     • “What will be broken if I move to a new version?”
     • “Will my plug-in still run on an olde...
Bundle version number management
     • http://wiki.eclipse.org/index.php/Version_Numbering
     • The tooling takes care ...
OSGi Versioning 101
     • major.minor.micro.qualifier
          major - An incompatible update; breaking API
          ...
API Tooling in Action (example of bug 191231/191232)




27
25         Eclipse, OSGi and API Tooling | Chris Aniszczyk | ©...
API Tooling in Action (API Usage Report)




28
26        Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 Eclipse...
API Tooling in Action (System Library Validation)




29
29         Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 20...
API Tooling in Action (API Comparison)




30
30        Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSo...
API Tooling Parts




31
31   Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
API Profile and API Components
     • These are the two major pieces used by the API
       tooling tools to make diagnosi...
API Description
     • This contains the specific restrictions for all the API
       types of an API component
     • It ...
Filtering of API Problems
     • Each component can define a problem filter
     • The filtering can be used to remove fro...
Two aspects: IDE and build process
     • Each feature is available from within the IDE or inside
       a headless build ...
Build support
     • Addition of new ant tasks:
         Generation of .api_description file
         Comparison of SDK ...
API Error/Warning Preferences




37
37       Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
API Setup Wizard




38
38       Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
API Profile (Baseline) Preferences




39
39       Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
API Profile (Baseline) Wizard




40
40       Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
Future work




41
41   Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
To be done...
     • Handling of package level versioning
     • Support extended to support more than just bundles
      ...
Summary




43
43   Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
API Tooling Summary
     • Help you to define your API restrictions
     • Keep a consistent and standard presentation of ...
Links
     • Wiki
         http://wiki.eclipse.org/Api_Tooling

     • Bugzilla
         https://bugs.eclipse.org/bugs/e...
Q & A

46
46   Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
Upcoming SlideShare
Loading in...5
×

OSGi, Eclipse and API Tooling

3,110

Published on

A presentation I gave at OSGi DevCon London 2010...

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
3,110
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
88
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide














































  • OSGi, Eclipse and API Tooling

    1. 1. Eclipse, OSGi and API Tooling Chris Aniszczyk (EclipseSource) zx@eclipsesource.com http://eclipsesource.com 1 1 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    2. 2. Who am I? • Chris Aniszczyk  Senior Software Engineer at EclipseSource  Plug-in Development Environment (PDE) Co-Lead  Been doing OSGi before it was en vogue  Committer Representative on Eclipse’s Board of Directors  Co-author Eclipse RCP Book 2nd Edition  I dabble with many things at Eclipse.org • My blog  http://aniszczyk.org • Follow me on Twitter  http://twitter.com/caniszczyk 2 2 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    3. 3. Overview • The need for tooling • Tooling features • Tooling in action! • Future work • Summary • Q&A 3 2 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    4. 4. The need for tooling Remember Kirk’s gigantic Modularity diagram? 4 3 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    5. 5. Define API • APIs are published contracts  Producers specify the contracts  Honor contracts release after release  Evolve the contracts for enhancements and fix problems  Consumers adhere to the contracts  Implement the contracts per specification  Use provided implementations per contract specifications 5 4 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    6. 6. The Ideal Release Equation Developer: Compatibility (producer) + Client: Honor API contract (consumer) = Free migration!!! 6 5 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    7. 7. The Ideal Never Happens... Developer: (features + deprecation + Optional extensions to existing features + Replacement API + Provisional API) + Client: Illegal internal references = Migration at a cost 7 6 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    8. 8. What have we done as developers? • We use Javadoc™ to document contracts  This class is not intended to be instantiated or subclassed by clients.  Has no effect if not read  Inconsistent wording, placement, and use • Use component.xml to specify APIs (at Eclipse.org)  Out of date, not maintained  Why? Because there’s no tooling and it’s separate from the code • We use package names to categorize as public/internal, but all packages are exported • We use OSGi package exports (x-internal and x-friends) to limit visibility, but does not prevent access to internal types • We use Eclipse’s access rules to discourage use, but this can be turned off 8 7 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    9. 9. More things we do… • Manually examine API changes or use some external tool before a release (aka the API Police)  Changes between releases can be significant  Validation is time consuming and error prone  Lost development time (due to checking and bugs found) 9 8 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    10. 10. And we still fail... 10 9 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    11. 11. And we still fail... • At Eclipse, we have had issues with projects unintentionally breaking API... • Outside of Eclipse, it highly varies...  “Commons collections 3.0 is binary compatible with version 2.1 and 2.0 except for certain methods on one class. As the release was a major version, this is permitted, however it was unintentional and an error... the chosen solution is to provide a work around by releasing v2.1.1 and v3.1.” • Surely you’ve come across API issues, right? 11 10 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    12. 12. Disclaimer • This presentation isn’t about API design • API design is still your problem  Designing quality APIs is tough  Ensuring consistent behavior  Evolving APIs is tricky • But there are things that tooling can help with… 12 11 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    13. 13. Good fences... • Check out some of Joshua Bloch’s presentations around API (How to Design API and Why it Matters) and some of the EclipseCon API design presentations... 13 12 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    14. 14. API Tooling Features 14 13 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    15. 15. API Tooling to the Rescue! • Reports  Illegal API use  Binary incompatibility relative to a baseline  Incorrect bundle version numbers  Missing or malformed @since tags  Leakage of non-APIs types inside APIs  Execution Environment validation • Tightly integrated toolset in the Eclipse SDK  Currently limited to Plug-in projects/OSGi bundles  Runs as a builder (auto-build, incremental and full builds)  Immediate feedback as you develop and use APIs 15 14 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    16. 16. Specifying API Contracts • Use Javadoc tags  E.g. @noimplement, @noextend, @noreference, @noinstantiate • Benefits  Contracts live with the code for producers and consumers  Content assist helps developers  Available for projects that are not using 1.5 annotations  Restrictions appear in published Javadoc APIs in a standard way  Tools can process tags 16 15 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    17. 17. API Tooling Javadoc Tags 17 16 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    18. 18. Example of Published API 18 17 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    19. 19. API Usage • Once the APIs are specified, the user needs to make sure that he/she is using them appropriately. • API usage is flagging any kind of illegal usage of API: reference to an API that is not supposed to be referenced, implementation of an interface that is not supposed to be implemented, …. • A consequence of wrong API usage is a potential binary incompatible change error. 19 18 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    20. 20. Why API Usage Scans? API producers can see what internals are being used • Inform clients how to use proper API • Determine what new API needs to be added • Know what clients will be broken • Avoid breaking internals until clients have migrated 20 19 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    21. 21. Validating Binary Compatibility • Evolving APIs such that they are backwards compatible with existing binaries  http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs  It is easy to get it wrong  Now the tooling takes care of this • The user simply specifies an API baseline  Generally this means pointing to the previous release (N – 1) 21 20 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    22. 22. API Comparisons • What’s changed between versions? 22 21 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    23. 23. System Library Validation • Validate system library use based on a bundle’s required execution environment (BREE)  if a bundle claims to run on J2SE-1.4, access to members in J2SE-1.5 and higher are flagged as illegal  See OSGi Specification on Execution Environments 23 22 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    24. 24. Migration Assistance • “What will be broken if I move to a new version?” • “Will my plug-in still run on an older target version?” • We simply re-resolve the references against X, with the code in X+1 • Of course you can get the same information if you compile, but that requires more setup... 24 23 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    25. 25. Bundle version number management • http://wiki.eclipse.org/index.php/Version_Numbering • The tooling takes care of letting the user know when the minor or major version of a bundle should be changed according to rules described in the document:  A new API that is not a breaking change requires the minor version to be incremented  A new API that is a breaking change requires the major version to be incremented • No support for the micro version yet...  Technically speaking, this version should be changed as soon as any modification is made in the source code: comment change, method body change,… 25 24 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    26. 26. OSGi Versioning 101 • major.minor.micro.qualifier  major - An incompatible update; breaking API  minor - A backward compatible update; API stable  micro - A bug fix  qualifier - build date; lexicographic • Versions should encode compatibility at the bundle and package level... aid in evolution... • They aren’t a marketing number! 26 25 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    27. 27. API Tooling in Action (example of bug 191231/191232) 27 25 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2008 EclipseSource
    28. 28. API Tooling in Action (API Usage Report) 28 26 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    29. 29. API Tooling in Action (System Library Validation) 29 29 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    30. 30. API Tooling in Action (API Comparison) 30 30 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    31. 31. API Tooling Parts 31 31 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    32. 32. API Profile and API Components • These are the two major pieces used by the API tooling tools to make diagnosis on the code • An API profile can be seen like a PDE target platform • An API profile is a collection of API components • It is initialized using an Eclipse SDK installation plugins directory (or some other directory of bundles) • Inside the IDE, a profile corresponding to the workbench contents is automatically created 32 32 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    33. 33. API Description • This contains the specific restrictions for all the API types of an API component • It is kept up-to-date inside the workbench by using resource listeners • It is exported inside the binary bundles or generated at build time using an ant task. 33 33 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    34. 34. Filtering of API Problems • Each component can define a problem filter • The filtering can be used to remove from reports known breakages. • For example, an API breakage has been approved by the PMC and you don’t want to get it reported for each build. • The problem filter is also part of the binary plug-in 34 34 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    35. 35. Two aspects: IDE and build process • Each feature is available from within the IDE or inside a headless build process via Ant tasks • The IDE support is required to help the Eclipse developer while the code is written • The build process support is required to provide feedback during the Eclipse build. This also allows other projects to use it inside their builds. 35 35 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    36. 36. Build support • Addition of new ant tasks:  Generation of .api_description file  Comparison of SDK drops: binary compatibility, api usage reports • Integration inside the Eclipse builds (headless mode) • Integration inside ant build (no Eclipse running) 36 22 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    37. 37. API Error/Warning Preferences 37 37 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    38. 38. API Setup Wizard 38 38 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    39. 39. API Profile (Baseline) Preferences 39 39 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    40. 40. API Profile (Baseline) Wizard 40 40 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    41. 41. Future work 41 41 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    42. 42. To be done... • Handling of package level versioning • Support extended to support more than just bundles  Pure Java™ projects  Plug-in extension points • Improve integration with Eclipse rel-eng build reporting • Determine compatible version range of required bundles • And what you might suggest... 42 42 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    43. 43. Summary 43 43 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    44. 44. API Tooling Summary • Help you to define your API restrictions • Keep a consistent and standard presentation of API restrictions • Detect binary breakage between a baseline and the current version • Detect wrong API usage • Detect wrong @since tags and inconsistent bundle versioning • Detect Execution Environment problems... • Supports more than just Eclipse (hi OSGi folks)! 44 44 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    45. 45. Links • Wiki  http://wiki.eclipse.org/Api_Tooling • Bugzilla  https://bugs.eclipse.org/bugs/enter_bug.cgi?product=PDE • Get Involved  https://dev.eclipse.org/mailman/listinfo/pde-dev 45 45 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    46. 46. Q & A 46 46 Eclipse, OSGi and API Tooling | Chris Aniszczyk | © 2010 EclipseSource
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×