When Should Internal Interfaces be Promoted to Public? (FSE 2016)

Commonly, software systems have public (and stable) interfaces, and internal (and possibly unstable) interfaces. Despite being discouraged, client developers often use internal interfaces, which may cause their systems to fail when they evolve. To overcome this problem, API producers may promote internal interfaces to public. In practice, however, API producers have no assistance to identify public interface candidates. In this paper, we study the transition from internal to public interfaces. We aim to help API producers to deliver a better product and API clients to benefit sooner from public interfaces. Our empirical investigation on five widely adopted Java systems present the following observations. First, we identified 195 promotions from 2,722 internal interfaces. Second, we found that promoted internal interfaces have more clients. Third, we predicted internal interface promotion with precision between 50%–80%, recall 26%–82%, and AUC 74%–85%. Finally, by applying our predictor on the last version of the analyzed systems, we automatically detected 382 public interface candidates.

Transcript

1. When Should Internal Interfaces Be
   Promoted to Public?
   André Hora, Marco Tulio Valente,
   Romain Robbes, Nicolas Anquetil
   FSE 2016
   

   View Slide

2. Outline
   1.Context
   2.Problem
   3.Study Design
   4.Results
   5.Final Remarks
   2
   

   View Slide

3. Software Evolution
   Software systems are under constant
   evolution
   New features, bug-fixes, refactoring
   Up to 90% of development costs
   3
   

   View Slide

4. Library Evolution
   4
   

   View Slide

5. API Evolution Good Practices
   1. API developers should deprecate API elements with
   clear replacement messages to facilitate migration
   2. API clients should only use public and stable APIs to
   avoid backward-incompatibility
   5
   

   View Slide

6. API Evolution Good Practices
   1. API developers should deprecate API elements with
   clear replacement messages to facilitate migration
   2. API clients should only use public and stable APIs to
   avoid backward-incompatibility
   ✖
   [Robbes et al., 2012, Brito et al. 2016]
   6
   

   View Slide

7. API Evolution Good Practices
   1. API developers should deprecate API elements with
   clear replacement messages to facilitate migration
   2. API clients should only use public and stable APIs to
   avoid backward-incompatibility
   7
   

   View Slide

8. Public Interfaces
   Stable, Supported, Documented
   Clients can use
   eg: java.util.List
   8
   

   View Slide

9. Public Interfaces
   Stable, Supported, Documented
   Clients can use
   eg: java.util.List
   Internal Interfaces
   Unstable, Unsupported, Undocumented
   Clients should not use
   eg: org.eclipse.jdt.internal.ui.JavaPlugin
   9
   

   View Slide

10. Examples of Internal Interfaces
    org.eclipse.jdt.internal.ui.IJavaHelpContextIds
    org.junit.internal.AssumptionViolatedException
    org.junit.internal.runners.InitializationError
    org.hibernate.internal.util.ReflectHelper
    org.hibernate.internal.CoreMessageLogger
    sun.misc.Unsafe
    10
    

    View Slide

11. Examples of Internal Interfaces
    org.eclipse.jdt.internal.ui.IJavaHelpContextIds
    org.junit.internal.AssumptionViolatedException
    org.junit.internal.runners.InitializationError
    org.hibernate.internal.util.ReflectHelper
    org.hibernate.internal.CoreMessageLogger
    sun.misc.Unsafe
    *.internal.*
    sun.*
    11
    

    View Slide

12. “Packages containing implementation details have
    internal in the name. They are unsupported and
    subject to change. Client code must never
    reference internal elements.”
    “sun.* packages are not part of the supported,
    public interface. Writing java programs that
    rely on sun.* is risky: those classes are not
    portable, and are not supported.”
    Java Documentation
    Eclipse Documentation
    12
    

    View Slide

13. Outline
    1.Context
    2.Problem
    3.Study Design
    4.Results
    5.Final Remarks
    13
    

    View Slide

14. 44% of 512 Eclipse clients use
    internal interfaces
    [Businge et al., 2013]
    Clients often use internal interfaces!
    14
    

    View Slide

15. 23% out of 9,702 Eclipse clients
    use internal interfaces (45K files)
    [Boa Infrastructure]
    Ultra-large scale level
    Clients often use internal interfaces!
    44% of 512 Eclipse clients use
    internal interfaces
    [Businge et al., 2013]
    15
    

    View Slide

16. Internal interfaces may
    become Public
    Eclipse client asks:
    “CharOperation is technically
    internal but it seems generally
    useful enough to use elsewhere. I
    would like to see it made public.”
    Eclipse developer answers:
    “We could indeed surface it into
    a public package”
    16
    

    View Slide

17. Internal interfaces may
    become Public
    Eclipse client asks:
    “CharOperation is technically
    internal but it seems generally
    useful enough to use elsewhere. I
    would like to see it made public.”
    Eclipse client asks:
    “CharOperation is technically
    internal but it seems generally
    useful enough to use elsewhere. I
    would like to see it made public.”
    Eclipse client asks:
    “CharOperation is technically
    internal but it seems generally
    useful enough to use elsewhere. I
    would like to see it made public.”
    Eclipse developer answers:
    “We could indeed surface it into
    a public package”
    Eclipse developer answers:
    “We could indeed surface it into
    a public package”
    Eclipse developer answers:
    “We could indeed surface it into
    a public package”
    17
    

    View Slide

18. Stable
    Documented
    Clients can use
    Unstable
    Undocumented
    Clientes should not use
    Internal Interfaces Public Interfaces
    Internal interfaces may
    become Public
    org.eclipse.internal.foo.Bar
    2,155 145 (7%)
    org.eclipse.foo.Bar
    18
    

    View Slide

19. Internal interfaces may
    become Public
    19
    

    View Slide

20. Internal interfaces may
    become Public
    Which interfaces initially
    projected as internal should be
    promoted to public?
    20
    

    View Slide

21. Outline
    1.Context
    2.Problem
    3.Study Design
    4.Results
    5.Final Remarks
    21
    

    View Slide

22. Research Questions
    • RQ1. Is there a relationship between internal
    interface usage and promotion?
    • RQ2. Can we predict that an internal interface
    will be promoted to a public one?
    • RQ3. Can we detect that an internal interface
    is a candidate to be promoted to a public one?
    22
    

    View Slide

23. Experiment Design
    Public x Internal
    interfaces
    Case
    studies
    23
    

    View Slide

24. Experiment Design
    Promoted x non-promoted
    internal interfaces
    24
    

    View Slide

25. Experiment Design
    Usage
    metrics
    Domestic
    metrics
    25
    

    View Slide

26. Outline
    1.Context
    2.Problem
    3.Study Design
    4.Results
    5.Final Remarks
    26
    

    View Slide

27. RQ1
    Is there a relationship between internal
    interface usage and promotion?
    27
    

    View Slide

28. RQ1. Is there a relationship between internal
    interface usage and promotion?
    1. Separation of interfaces in
    promoted and non-promoted
    }
    }
    Non-promoted
    internal interfaces
    Promoted internal interfaces
    2. Comparison of promoted
    and non-promoted internal
    interfaces (Mann-Whitney U
    test & Cliff’s Delta)
    28
    

    View Slide

29. RQ1. Is there a relationship between internal
    interface usage and promotion?
    29
    

    View Slide

30. RQ1. Is there a relationship between internal
    interface usage and promotion?
    30
    

    View Slide

31. RQ1. Is there a relationship between internal
    interface usage and promotion?
    Promoted and non-promoted internal
    interfaces present distinct distribution
    regarding their usage metrics
    31
    

    View Slide

32. RQ2
    Can we predict that an internal interface
    will be promoted to a public one?
    32
    

    View Slide

33. RQ2. Can we predict that an internal
    interface will be promoted to a public one?
    Precision 50%–80%, recall
    26%– 82%, AUC 74%–85%
    Random-forest classifier
    to predict promotion
    33
    

    View Slide

34. Random-forest classifier
    to predict promotion
    RQ2. Can we predict that an internal
    interface will be promoted to a public one?
    Precision 50%–80%, recall
    26%– 82%, AUC 74%–85%
    Internal interface promotions can be
    predicted with high confidence
    34
    

    View Slide

35. Outline
    1.Context
    2.Problem
    3.Study Design
    4.Results
    5.Final Remarks
    35
    

    View Slide

36. Final Remarks
    Internal interfaces are
    common practice: 21%
    (6,085 out of 28,503)
    Clients often use internal
    interfaces: 23.5% (2,277 out
    of 9,702 Eclipse clients)
    Internal interface promotions
    happen in real-world systems:
    7% (195 out of 2,722)
    Promoted and non-promoted
    internal interfaces present
    distinct usage patterns
    Internal interface promotions can be
    predicted with high confidence
    36
    

    View Slide

37. When Should Internal Interfaces Be
    Promoted to Public?
    André Hora, Marco Tulio Valente,
    Romain Robbes, Nicolas Anquetil
    FSE 2016
    

    View Slide