eclipse and api tooling
DESCRIPTION
Eclipse and API toolingTRANSCRIPT
© 2014 IBM Corporation
Eclipse and API tooling
Vikas Chandra (PDE and GMF committer)
© 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
© 2014 IBM Corporation
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
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
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)
© 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
© 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.
© 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
© 2014 IBM Corporation
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
API Management
Manage API
Maintain APIs
Reporting API defect
Reporting usage of non-API code
Identifying binary incompatibility
Versioning based on eclipse versioning scheme
© 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
© 2014 IBM Corporation
TYPICAL USE SCAN REPORT
© 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 )
© 2014 IBM Corporation
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
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
………………..
© 2014 IBM Corporation
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
Deprecate before removing, Also provide with alternate API
© 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
© 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
© 2014 IBM Corporation
Versioning
API tools help in versioningThe 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
Versioning ( contd..)Suppose a new API is added
You need to increase minor version
Also add @since tag
© 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)
