This document discusses APIs, API management, and API tools in Eclipse. It defines what an API is and outlines ground rules for Eclipse Platform APIs. It describes API management practices like maintaining documentation and tracking usage. API tools help identify binary compatibility issues when evolving APIs between versions. The document also discusses API versioning schemes and how to increment versions based on the type of changes made.

1. Vikas Chandra (PDE and GMF committer)
Eclipse and API tooling
© 2014 IBM Corporation

2. © 2014 IBM Corporation
Overview
What is an API
Ground rules for Eclipse Platform API
API management
API tools – API Use Scan
API Binary Compatibility/Versioning
API tools for Binary compatibility and Versioning

3. What is an API?
Set of defined functions and methods for
interfacing with the underlying operating
system or another program or service
•Producer of API & Consumer of API
•Behavior of API – consistent
•More relevant for software vendors for
masses
© 2014 IBM Corporation

4. Eclipse APIs , Distinguish API/non-API
 API elements - documented /have specification
 Non-API elements - internal implementation details usually without
documentation or specifications
 API - API package ( advertised in documentation) , API class, API
interface, API constructor, API field
 Non-API – non-API package, All classes and interfaces in non-API
package, Non-public classes and interfaces in API packages, Default
access and private methods, fields etc, not documented
© 2014 IBM Corporation

5. © 2014 IBM Corporation
API rules
FOR PRODUCERS
When evolving the Component API from release to
release, do not break existing clients.
API changes must not invalidate formerly legal
client code.
Every aspect of the API matters to some client.
( hypothetical)

6. © 2014 IBM Corporation
API rules
FOR CONSUMERS
Honor all contracts
Do not rely on incidental behavior
Do ensure that an API method's preconditions are met before
calling the method
Do not pass null as a parameter to an API method unless the
parameter is explicitly documented as allowing null
Do not use instanceof and cast expressions to increase what
is known about an object beyond what the API supports

7. © 2014 IBM Corporation
Not following rules
Fail when run with a different mix of co-resident
plug-ins
 Fail on different version
 Fail with patches
Cost associated with this.

8. © 2014 IBM Corporation
Why API management
 Producer - replaces API, changes signature, makes provisional APIs
 Consumer – make references to non-APIs, internal functions
DISASTER
Producer should ship compatible APIs
Consumer should respect API rules

9. API Tools/Restrictions
 @noreference - Indicates that other bundles must not reference this member by name
 @noimplement - Indicates that other bundles must not implement this interface
 @noextend - Indicates that other bundles must not extend the class/ interface it
appears on
 @noinstantiate - Indicates that other bundles must not create instances of this class.
 @nooverride - Indicates that other bundles must not extend
© 2014 IBM Corporation

10. © 2014 IBM Corporation
API Management
Manage API
Maintain APIs
Reporting API defect
Reporting usage of non-API code
Identifying binary incompatibility
Versioning based on eclipse versioning scheme

11. © 2014 IBM Corporation
API use scan
View of how APIs used in component
For example which APIs of *.swt* are used in all of my
components *.mycomponent.*
Reports Illegal use
Reports internal and internal-permissible
Reports general API use
Can get this at compile time based on preference options

12. TYPICAL USE SCAN REPORT
© 2014 IBM Corporation

13. © 2014 IBM Corporation
API Use Scan
For producers
1. Inform clients how to use
2. Avoid breaking changes till client migrated.
For consumers
1. Inform producer when they break API
2. Send Use scan report to producer.
Can associate with the build ( example eclipse )

14. Achieving API Binary Compatibility
A change to a type is binary compatible with preexisting binaries if
preexisting binaries that previously linked without error will continue to link
without error
© 2014 IBM Corporation
Evolving PACKAGE
 Add API package Binary compatible
 Delete API package Breaks compatibility
 Add API type to API package Binary compatible
 Delete API type from API package Breaks compatibility
 Add non-public (non-API) type to API package Binary compatible
 Delete non-public (non-API) type from API package Binary compatible
 Change non-public (non-API) type in API package to make public Binary compatible
 Change public type in API package to make non-public Breaks compatibility
………………..

15. Evolving method, class, interface
Evolving METHOD
 Change body of method or constructor Binary compatible
 Change formal parameter name- Binary compatible
 Change method name- Breaks compatibility
 Add or delete formal parameter- Breaks compatibility
 Change type of a formal parameter- Breaks compatibility
 Change result type (including void)- Breaks compatibility
 ……….
Evolving Classes, Interface
Increase access – generally compatible , decrease access – generally incompatible.
Add new interface with method –Fine , Use as superinterface of interface API – Not Fine
© 2014 IBM Corporation
Deprecate before removing, Also provide with alternate API

16. © 2014 IBM Corporation
Binary Incompatibility
Assume you are developing a component
When would it break API from version 1 to version 2
There are numerous ways that the API could be broken
Easy to get it wrong
API tooling takes care of it

17. © 2014 IBM Corporation
API baseline
Set API baseline to previous version
Any API issue will be flagged
Developer should deal with this issue
Any API issue is configurable via the preference
page

18. Versioning
API tools help in versioning
The major segment indicates breakage in the API
The minor segment indicates externally visible changes like
new API,
The service segment indicates bug fixes
The qualifier segment indicates a particular build.
© 2014 IBM Corporation

19. © 2014 IBM Corporation
Versioning ( contd..)
Suppose a new API is added
You need to increase minor version
Also add @since tag

20. © 2014 IBM Corporation
Resources
 http://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html ( Binary compatibility)
 http://www.eclipse.org/articles/Article-API-Use/ ( API use in eclipse)
 http://wiki.eclipse.org/Evolving_Java-based_APIs ( Evolving APIs)
 http://wiki.eclipse.org/Version_Numbering ( Versioning)
 https://wiki.eclipse.org/PDE/API_Tools/Restrictions ( API Restrictions)

21. © 2014 IBM Corporation
Thank You
Vikas Chandra
Vikas.Chandra@in.ibm.com