Identification of promoted eclipse unstable interfaces using clone detection technique

The Eclipse framework is a popular and widely used framework that has been evolving for over a decade. The framework provides both stable interfaces (APIs) and unstable interfaces (non-APIs). Despite being discouraged by Eclipse, client developers often use non-APIs which may cause their systems to fail when ported to new framework releases. To overcome this problem, Eclipse interface producers may promote unstable interfaces to APIs. However, client developers have no assistance to aid them to identify the promoted unstable interfaces in the Eclipse framework. We aim to help API users identify promoted unstable interfaces. We used the clone detection technique to identify promoted unstable interfaces as the framework evolves. Our empirical investigation on 16 Eclipse major releases presents the following observations. First, we have discovered that there exists over 60% non-API methods of the total interfaces in each of the analyzed 16 Eclipse releases. Second, we have discovered that the percentage of promoted non-APIs identified through clone detection ranges from 0.20% to 10.38%.

💡 Research Summary

**
The paper investigates the prevalence of unstable (non‑API) interfaces in the Eclipse framework and the extent to which these interfaces are promoted to stable (API) interfaces over the course of the framework’s evolution. The authors note that Eclipse provides both stable APIs and unstable internal interfaces (identified by the “internal” substring in package names). Although Eclipse discourages the use of non‑APIs because they are undocumented, subject to change, and may be removed without notice, many client developers still rely on them, leading to compatibility problems when migrating to newer releases.

To address the lack of systematic assistance for developers to discover which non‑APIs have been promoted, the authors propose using a code clone detection technique. They formulate two research questions: (RQ1) What proportion of methods in each Eclipse major release are non‑APIs? (RQ2) What proportion of non‑API methods are later promoted to APIs?

Data collection and methodology
The study covers 16 major Eclipse SDK releases from version 1.0 (Nov 2001) to 4.6 (June 2016). The NiCad clone detection tool is employed for two purposes: (1) extracting all method signatures from each release, and (2) performing cross‑release clone detection to identify identical or highly similar method bodies across versions. A method is classified as a non‑API if its fully qualified name contains the substring “internal”. For each older release (E_old) the set of newly introduced non‑API methods is computed by subtracting the methods that already existed in earlier releases. This set, called E_old‑new, is then compared against subsequent releases (E_new) using NiCad’s cross‑clone mode with configurations for Type‑I (exact), Type‑II (renamed identifiers, literals, etc.), and Type‑III (added/removed statements) clones.

A clone pair where the method from the older release is a non‑API (internal) and the corresponding method in the newer release is not internal is interpreted as a promotion from non‑API to API. The promotion rate is calculated as the number of such promoted clone pairs divided by the total number of newly introduced non‑API methods in the older release.

Results
RQ1: Across all 16 releases, non‑API methods consistently account for more than 60 % of the total methods. The absolute number of non‑API methods grows with each release, indicating that Eclipse continues to introduce many internal interfaces while the proportion of stable APIs does not keep pace.

RQ2: The proportion of non‑API methods that are promoted to APIs is modest, ranging from 0.20 % to 10.38 % across the studied releases. The highest observed promotion rate (10.38 %) occurs for non‑APIs introduced in Eclipse 3.2 that become APIs by Eclipse 3.6. Even over the 15‑year span from Eclipse 1.0 to 4.6, only 0.97 % of the 30,766 non‑API methods introduced in the earliest release were promoted. These figures demonstrate that the promotion process is slow and that the majority of internal interfaces remain unstable throughout the framework’s lifecycle.

Discussion and threats to validity
The authors acknowledge that their analysis focuses solely on methods, ignoring other program elements such as fields, variables, or classes that might also be promoted. The reliance on string matching (“internal”) to identify non‑APIs could miss edge cases where internal code is exposed without the conventional naming. Moreover, clone detection may produce false positives (e.g., coincidental similarity) or false negatives (e.g., heavily refactored code that no longer matches any clone type). Nevertheless, the use of NiCad, a well‑validated tool, and the inclusion of all three clone types mitigate many of these concerns.

Implications
The findings have two practical implications. First, developers who depend on non‑APIs should be aware that only a tiny fraction of these interfaces become officially supported, increasing the risk of breakage when upgrading Eclipse. Second, the clone‑based approach provides an automated way to surface promoted interfaces, which could be integrated into tooling (e.g., IDE plugins) to alert developers of safer alternatives.

Future work
Potential extensions include: (1) expanding the analysis to other program elements (fields, classes) and to other ecosystems (e.g., Android, Apache libraries); (2) correlating promotion events with real‑world bug reports or compatibility failures to assess impact; (3) developing machine‑learning models that predict which non‑APIs are likely to be promoted based on code metrics, usage statistics, and historical promotion patterns; and (4) building a recommendation system that proactively suggests promoted APIs to developers during code authoring.

Conclusion
By applying clone detection across multiple Eclipse releases, the study quantitatively demonstrates that non‑API methods dominate the Eclipse code base and that the promotion of these unstable interfaces to stable APIs is infrequent. The methodology proves effective for automatically identifying promotion events, offering a valuable aid to both framework maintainers and client developers seeking to reduce dependency on fragile internal interfaces.