The interface taxonomy classification provided by Apache Yetus annotations is for guidance to developers and users of interfaces. The classification guides a developer to declare the targeted audience or users of an interface and also its stability.
Benefits to the user of an interface: Knows which interfaces to use or not use and their stability.
Benefits to the developer: to prevent accidental changes of interfaces and hence accidental impact on users or other components or system. This is particularly useful in large systems with many developers who may not all have a shared state/history of the project.
Yetus provides the following interface classification, derived from the OpenSolaris taxonomy and, to some extent, from taxonomy used inside Yahoo. Interfaces have two main attributes: Audience and Stability
Audience denotes the potential consumers of the interface. While many interfaces are internal/private to the implementation, others are public/external interfaces and are meant for wider consumption by applications and/or clients. For example, POSIX definitions in libc are external, while large parts of the kernel are internal or private interfaces. Also, some interfaces are targeted towards other specific subsystems.
Identifying the audience of an interface helps define the impact of breaking it. For instance, it might be okay to break the compatibility of an interface whose audience is a small number of specific subsystems. On the other hand, it is probably not okay to break a protocol interfaces that millions of Internet users depend on.
Yetus uses the following kinds of audience in order of increasing/wider visibility:
The interface is for internal use within a project(such as Apache Hadoop) and should not be used by applications or by other projects. It is subject to change at anytime without notice. Most interfaces of a project are Private (also referred to as project-private).
The interface is used by a specified set of projects or systems (typically closely related projects). Other projects or systems should not use the interface. Changes to the interface will be communicated/ negotiated with the specified projects. For example, in the Apache Hadoop project, some interfaces are LimitedPrivate{HDFS, MapReduce} in that they are private to the HDFS and MapReduce subprojects.
The interface is for general use by any application.
Stability denotes how stable an interface is, as in when incompatible changes to the interface are allowed. Yetus provides the following levels of stability.
Can evolve while retaining compatibility for minor release boundaries; in other words, incompatible changes to APIs marked Stable are generally only allowed at major releases (i.e. at m.0).
Evolving, but incompatible changes are allowed at minor release (i.e. m .x)
Incompatible changes to Unstable APIs are allowed any time. This usually makes sense for only private interfaces.
However one may call this out for a supposedly public interface to highlight that it should not be used as an interface; for public interfaces, labeling it as Not-an-interface is probably more appropriate than “Unstable”.
Examples of publicly visible interfaces that are unstable (i.e. not-an-interface): GUI, CLIs whose output format will change
APIs that could potentially be removed in the future and should not be used.
How should the classification be recorded for the annotated APIs?
Each interface or class will have the audience and stability recorded using annotations in org.apache.yetus.classification package.
The javadoc generated by the maven target javadoc:javadoc lists only the public API.
One can derive the audience of java classes and java interfaces by the audience of the package in which they are contained. Hence it is useful to declare the audience of each java package as public or private (along with the private audience variations).
Why aren't the java scopes (private, package private and public) good enough?
But I can easily access a private implementation interface if it is Java public. Where is the protection and control?
Why bother declaring the stability of a private interface? Aren't private interfaces always unstable?
What is the harm in applications using a private interface that is stable? How is it different than a public stable interface?
Why bother with Limited-private? Isn't it giving special treatment to some projects? That is not fair.
Can't a private interface be treated as project-private also? For example what is the harm in projects in the Apache Hadoop extended ecosystem, having access to private classes?
Aren't all public interfaces stable?