PublishedApi Handling published Java API automatically How to - PowerPoint PPT Presentation

PublishedApi – Handling published Java API automatically How to provide a stable but changeable API to external developers V1.0 | 2017-06-27

Introduction About me  Andreas Turban  Andreas.Turban@vector.com > Work E-Mail  Andreas.Turban@net-baustelle.de > Private E-Mail  Employed at Vector Informatik GmbH since 2006 as  Product Architect  Senior Software Development Engineer > www.vector.com 2/40

Introduction Application Programming Interface (API)  For the presentation:  An application programming interface (API) is a well defined set of Java classes including their fields and methods  The API is used by code which is NOT internal code, also called client > By clients which are not part of the same project > Clients use only the API to build their own code not the whole project  The client code is written by other people using the API  So the API is published and can not be changed easily 3/40

Agenda Introduction  Why stable API matters PublishedApi PublishedApi PostProcessing API Change Documentation References 4/40

Why stable API matters API stability  Suppose we write an API, which is used by different people  We do not control or have the source code of the users > So we can‘t change all usage of the API, we have to deal with existing code  And we want to change our API  What is part of our API and what is internal?  What can we change without breaking the existing clients?  How do we communicate the change?  These are all well known problems  The easiest solution is to give the API a version number 5/40

Why stable API matters Versioning - Quick reminder  Versions are used to describe compatibility of an API  Most used scheme  „ Semantic Versioning “ > http://semver.org/  Given a version number MAJOR.MINOR.PATCH, increment the:  MAJOR version when you make incompatible API changes,  MINOR version when you add functionality in a backwards-compatible manner, and  PATCH version when you make backwards-compatible bug fixes.  But how do we as developers know, if a change is a major, minor or patch change? 6/40

Why stable API matters Change Categories  We as developer have to group every change in the categories:  Major  Minor  Patch  But this can be a tedious and error-prone process 7/40

Why stable API matters Change Example  Example of a compatible looking but incompatible change  We add a new method to an interface, which is implemented by a client  Original:  New method isExecutable(): 8/40

Why stable API matters Change Example  This change breaks the compatibility of the API  Because every client now has to implement the new method isExecutable() 9/40

Why stable API matters Change Rules  But which changes are compatible or incompatible?  There are rules for it:  The Eclipse wiki lists 148 rules to achieve API Binary Compatibility in Java > https://wiki.eclipse.org/Evolving_Java-based_APIs_2  But we as developers are not good in applying over 100 rules to each tiny code change  The process is too tedious and error-prone  So lets write a program which does the work! 10/40

Agenda Introduction Why stable API matters  PublishedApi PublishedApi PostProcessing API Change Documentation References 11/40

PublishedApi Idea  We need a program analysing our code changes and check the compatibility rules «resource» E.g. an Eclipse RCP Product Jars API Java compiler «resource» «resource» «resource» «resource» writes code PostProcessing published class source code class files API Jar files Product Developer stops compilaton calls [on error] [on API class] API supervision «feedback» 12/40

PublishedApi Idea  The usage of the API by external people whould be: done by external people writes code «resource» Only used for An OSGi bundle or source code compilation! some other extension External Developer Not for execution. jar Java compiler «resource» «resource» API Jar External Jar «resource» Product execution Product Jars Normal OSGI bundle The running Eclipse which start an Eclipse RCP RCP 13/40

PublishedApi Vector Solution  At Vector we call our solution PublishedApi  It compares the current java source with a reference in a database  CompatibilityDatabase  It issues errors if changes were made without properly changing the versions 14/40

PublishedApi How does it work?  All API classes are annotated with  @PublishedApi  So all classes with @PublishedApi are part of a certain API and will be supervised automatically  These classes must be kept stable or otherwise there will be a compile error 15/40

PublishedApi How does it work?  Example: 16/40

PublishedApi How does it work?  If we make an incompatible change:  Error:  The current Version information in your workspace and in the CompatibilityDatabase have the same major version, but there is a breaking change in this class.  New method “ public boolean isExecutable ()”.  You have to increment the major version to make this change. 17/40

PublishedApi How does it work?  If we make a compatible change:  There will be a warning:  PublishedApi: The method "public void newMethod()" in the class "DefRef" is new. 18/40

PublishedApi How does it work?  One part of the solution is a Plug-In in the Java compiler  AnnotationProcessor > https://docs.oracle.com/javase/7/docs/technotes/guides/apt/GettingStarted.html  The annotation processor is automatically called by the Java compiler, if an @PublishedApi class is compiled  The annotation processor will stop the compilation, if there is an error  So nobody can unintentionally break the API 19/40

Agenda Introduction Why stable API matters PublishedApi  PublishedApi PostProcessing API Change Documentation References 20/40

PublishedApi PostProcessing General  The other part of the solution is a PostProcessor  This step can change the compiled Java classes after the compiler run  Only the compile API jar is changed not the jars used for runtime execution  This is used in multiple ways  Hide certain methods  Divide the API in multiple @PublishedApiDomains > E.g. different API for different users  Document deprecation  Etc. 21/40

PublishedApi PostProcessing How does it work  The post processor uses the ASM library to read and rewrite the class files:  http://asm.ow2.org/ > „ ASM is an all purpose Java bytecode manipulation and analysis framework. It can be used to modify existing classes or dynamically generate classes, directly in binary form .” http://asm.ow2.org/ [2017-06-29]  The following steps are all implemented as ASM visitors on the API class files 22/40

PublishedApi PostProcessing Hide Methods from PublishedApi  Suppose we have a class  We want to hide a method, which uses a non published type  Example:  But now we have to publish the MyInternalType  Otherwise clients will not compile 23/40

PublishedApi PostProcessing Hide Methods from PublishedApi  The post processor supports to strip methods from the API  Example: 24/40

PublishedApi PostProcessing Hide Methods from PublishedApi  The annotation @KeepSecretFromPublishedApi will remove the method from the class file  But only for the client during compilation  So we do not have to publish MyInternalType  And no client will see the method in code completion etc.  Note: Reflection by the client will still work 25/40

PublishedApi PostProcessing Delete Implementation Bytecode  The post processor removes all implementation byte code an reference of API classes  This makes it possible only to provide the API classes for client not other dependencies  Example  A class uses an internal type in its implementation > Field: private final InternalType myfield; > Now the Java compiler needs the internal type to analyze the class  When we strip the whole internal implementation the Java compiler can use the class without the internal type 26/40

PublishedApi PostProcessing Deprecate API  There is the Java annotation @Deprecated  But this will deprecate the usage for clients and internal code  Sometime we just want to Deprecate the usage for clients 27/40

PublishedApi PostProcessing Deprecate API  The @PublishedDeprecated is transformed into the @Deprecated java annotation during post processing  So the client will see a Java warning, if the method is used  But internal code can use the method without warnings 28/40

PublishedApi PostProcessing Usage Not Allowed  There are some cases in the Java compiler, when internal types are needed for compilation, but are not part of the API  Examples: > private inner classes, needs to be present due to reflection information > Subtypes of enums need to be published as well  So we need to add these classes, but no client shall use them directly  The post processor will automatically mark the internal types with  @Deprecated  @UsageNotAllowed (“Reason why it shall not be used”) 29/40

PublishedApi PostProcessing PublishedApiDomain  We can also split the API in multiple parts  We annotate the classes with the allowed usages, for each domain  The enum DomainType defines the possible domains  The @PublishedApiDomain defines for each class the allowed usage 30/40