Bug 510982 - Add "Explain incompatibility" Quick Fix for "Add default
method" problem
Change-Id: Icce7966847c28dd3bed7bc7f2134091dc8576c37
Signed-off-by: Vikas Chandra <Vikas.Chandra@in.ibm.com>
diff --git a/bundles/org.eclipse.pde.doc.user/reference/api-tooling/api_evolution.htm b/bundles/org.eclipse.pde.doc.user/reference/api-tooling/api_evolution.htm
new file mode 100644
index 0000000..c8532de
--- /dev/null
+++ b/bundles/org.eclipse.pde.doc.user/reference/api-tooling/api_evolution.htm
@@ -0,0 +1,117 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+<head>
+ <meta name="copyright" content="Copyright (c) IBM Corporation and others 2017. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <meta http-equiv="Content-Style-Type" content="text/css">
+ <link rel="STYLESHEET" href="../../book.css" type="text/css">
+ <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"> </script>
+ <title> API Evolution</title>
+ <!-- called from org.eclipse.pde.api.tools.ui.internal.markers.ProblemExplainIncompatibilityResolution -->
+</head>
+<body>
+<h1> API Evolution</h1>
+ <p>
+ </p>
+
+ <p> API tooling is about controlling <a href="https://wiki.eclipse.org/Evolving_Java-based_APIs" target="_blank"> API Evolution</a> and <a href="https://wiki.eclipse.org/Version_Numbering" target="_blank">Version Numbering</a>.
+ </p>
+
+ <p> Read <a href="https://wiki.eclipse.org/Evolving_Java-based_APIs_2" target="_blank">Achieving API Binary Compatibility</a> for understanding the various incompatibilities.
+ </p>
+
+ <p> The following API incompatibilities have been explained in more detail below :
+ </p>
+<ol>
+ <li><strong><a href="#fieldAdditionToClass">Field Addition to Class</a></strong></li>
+ <li><strong><a href="#fieldAddtionToInterface">Field Addition to Interface</a></strong> </li>
+ <li><strong><a href="#defaultMethodAddition">Default Method Addition to Interface</a></strong></li>
+
+</ol>
+ <h2><a name="fieldAdditionToClass"></a>Field Addition to Class</h2>
+ <p> Adding an API field to an API class that is extended by Clients is dangerous in two respects:
+ </p>
+ <ul><li> It may break API contract compatibility similar to <a href="https://wiki.eclipse.org/Evolving_Java-based_APIs#Example_4_-_Adding_an_API_method" target="_blank" title="Evolving Java-based APIs">Evolving_Java-based_APIs#Example_4_-_Adding_an_API_method</a> in case of name clashes.</li>
+ <li> It may cause linkage errors in case an instance (respectively static) field hides a static (respectively instance) field, see <a rel="nofollow" class="external text" href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.4.8" target="_blank">JLS8 13.4.8</a>.<br><br>
+
+
+ <div ></a><p class="title"><b>Example - Adding a Field to Class</b></p>
+ <div ><pre class="programlisting">
+
+
+public class Base {String h = "Base";}
+public class Derived extends Base { }
+
+public class Test {
+ public static void main(String[] args) {
+ String s = new Derived().h;
+ System.out.println(s);
+ }
+}
+ <p >This program produces the output:</p>
+ Base
+
+ <p >Suppose that a public static field h is added to <code class="literal">Derived</code>:
+ </p><pre class="programlisting">
+
+ public class Derived extends Base { public static String h = "humongous"; }
+
+
+ <p>If <code class="literal">Derived</code> is recompiled but not <code class="literal">Test</code>, then running the new binary with the existing binary for <code class="literal">Test</code> will cause an <b><code class="literal">IncompatibleClassChangeError</code></b>.
+ </p>
+ <p> Furthermore, if char type h is added to Derived instead, there would be compilation error. <p>
+ </div>
+ </div>
+
+ This can not happen if all field declarations follow the usual naming conventions from <a rel="nofollow" class="external text" href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-6.html#jls-6.1" target="_blank">JLS8 6.1</a> and classes only have API fields that are either
+ <ul><li> "static final" (and hence have a name that doesn't contain any lowercase letters), or</li>
+ <li> non-static and non-final (and hence have a name that contains a least one lowercase letter)</li></ul></li></ul>
+ <p>Apart from the binary compatibility issues, it is generally good software engineering practice that API classes should not expose any non-constant fields.
+ </p>
+
+ <h2><a name="fieldAddtionToInterface"></a>Field Addition to Interface</h2>
+
+ <p>Adding an API field to an API interface that is implemented by Clients is dangerous in two respects:
+ </p>
+ <ul><li> It may break API contract compatibility similar to <a href="https://wiki.eclipse.org/Evolving_Java-based_APIs#Example_4_-_Adding_an_API_method" target="_blank" title="Evolving Java-based APIs">Evolving_Java-based_APIs#Example_4_-_Adding_an_API_method</a> in case of name clashes.</li>
+ <li> It may cause linkage errors in case an instance (respectively static) field hides a static (respectively instance) field, see <a rel="nofollow" class="external text" href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.4.8" target="_blank">JLS8 13.4.8</a>. This can not happen if all field declarations follow the usual naming conventions from <a rel="nofollow" class="external text" href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-6.html#jls-6.1" target="_blank">JLS8 6.1</a> and classes only have API fields that are either
+ <ul><li> "static final" (and hence have a name that doesn't contain any lowercase letters), or</li>
+ <li> non-static and non-final (and hence have a name that contains a least one lowercase letter)</li></ul></li></ul>
+
+ <h2><a name="defaultMethodAddition"></a>Default Method Addition to Interface</h2>
+ <p>Adding a default method will break an existing client type if it already implements another interface that declares a default method with a matching signature, and the client type already refers to the default method from the other interface (except when using the Interface.super.method() notation). The added default method will cause an IncompatibleClassChangeError at run time, see <a rel="nofollow" class="external text" href="http://docs.oracle.com/javase/specs/jls/se8/html/jls-13.html#jls-13.5.6" target="_blank">JLS8 13.5.6</a>. Furthermore, re-compiling the type will result in a compile error.<br>
+ </p>
+
+ <div></a><p class="title"><b>Example - Adding A Default Method</b></p>
+ <div ><pre class="programlisting">
+
+<p ><b><i>API</i></b></p>
+ public interface interfaceAPI {}
+
+<p ><b><i>Client Code</i></b></p>
+ public interface clientInterface {
+ default void doSomething() {
+ System.out.println("Do something client...") ;
+ }
+}
+
+public class ClientCode implements clientInterface, interfaceAPI {
+ public static void main(String[] args) {
+ new ClientCode().doSomething();
+ }
+}
+ <p >This program produces the output:</p>
+ Do something client...
+ <p >Suppose that a default method is added to <code class="literal">interfaceAPI</code>:
+ </p><pre class="programlisting">
+public interface interfaceAPI {
+ default void doSomething() {
+ System.out.println("Do something API...");
+ }
+}
+ <p>If <code class="literal">interfaceAPI</code> is recompiled but not <code class="literal">ClientCode</code>, then running the new binary with the existing binary for <code class="literal">ClientCode</code> will cause an <b><code class="literal">IncompatibleClassChangeError</code></b>.
+ </p>
+ </div>
+ </div>
+</body>
+</html>
diff --git a/bundles/org.eclipse.pde.doc.user/topics_Reference.xml b/bundles/org.eclipse.pde.doc.user/topics_Reference.xml
index 4e5da0c..9af9082 100644
--- a/bundles/org.eclipse.pde.doc.user/topics_Reference.xml
+++ b/bundles/org.eclipse.pde.doc.user/topics_Reference.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<!--
- Copyright (c) 2005, 2014 IBM Corporation and others.
+ Copyright (c) 2005, 2017 IBM Corporation and others.
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at
@@ -15,37 +15,45 @@
<!-- Define topics for the references -->
<!-- ============================================================================= -->
<toc label="Reference">
- <topic label="API Tools Ant Tasks">
- <topic href="reference/api-tooling/ant-tasks/analysis-ant-task.htm" label="Analysis Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm" label="Analysis Report Conversion Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apifreeze-ant-task.htm" label="API Freeze Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm" label="API Freeze Report Conversion Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/deprecation-ant-task.htm" label="API Deprecation Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm" label="API Deprecation Report Conversion Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiuse-ant-task.htm" label="API Use Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm" label="API Use Report Conversion Task (Producer)">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiconsumeruse-reportconversion-ant-task.htm" label="API Use Report Conversion Task (Consumer)">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apimigration-ant-task.htm" label="API Use Migration Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm" label="API Use Migration Report Conversion Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/filegeneration-ant-task.htm" label="File Generation Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/compare-ant-task.htm" label="Compare Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiusescan-problems-ant-task.htm" label="API Use Scan Problems Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiusescan-problems-reportconversion-ant-task.htm" label="API Use Scan Problems Report Conversion Ant Task">
- </topic>
+ <topic label="API Tools">
+ <topic label="API Tools Ant Tasks">
+ <topic href="reference/api-tooling/ant-tasks/analysis-ant-task.htm" label="Analysis Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm" label="Analysis Report Conversion Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apifreeze-ant-task.htm" label="API Freeze Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm" label="API Freeze Report Conversion Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/deprecation-ant-task.htm" label="API Deprecation Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm" label="API Deprecation Report Conversion Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apiuse-ant-task.htm" label="API Use Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm" label="API Use Report Conversion Task (Producer)">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apiconsumeruse-reportconversion-ant-task.htm" label="API Use Report Conversion Task (Consumer)">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apimigration-ant-task.htm" label="API Use Migration Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm" label="API Use Migration Report Conversion Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/filegeneration-ant-task.htm" label="File Generation Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/compare-ant-task.htm" label="Compare Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apiusescan-problems-ant-task.htm" label="API Use Scan Problems Ant Task">
+ </topic>
+ <topic href="reference/api-tooling/ant-tasks/apiusescan-problems-reportconversion-ant-task.htm" label="API Use Scan Problems Report Conversion Ant Task">
+ </topic>
+ </topic>
+ <topic href="reference/api-tooling/api_evolution.htm" label="API Evolution">
+ </topic>
+ <topic href="reference/api-tooling/api_javadoc_tags.htm" label="Defining API Restrictions">
+ </topic>
+ <topic href="reference/api-tooling/api_since_tags.htm" label="Javadoc @since Tag Management">
+ </topic>
</topic>
<topic label="Build Configuration">
<topic label="Builder Configuration properties" href="reference/pde_builder_config.htm" />
@@ -363,8 +371,4 @@
<topic href="reference/misc/overview-pde.html" label="PDE Plug-ins Map">
</topic>
</topic>
- <topic href="reference/api-tooling/api_javadoc_tags.htm" label="Defining API Restrictions">
- </topic>
- <topic href="reference/api-tooling/api_since_tags.htm" label="Javadoc @since Tag Management">
- </topic>
</toc>
