The interface taxonomy classification provided here 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.
Hadoop adopts the following interface classification, this classification was 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, other are public/external interfaces that are meant for wider consumption by applications and/or clients. For example, in posix, libc is an external or public interface, 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 interface that millions of Internet users depend on.
Hadoop uses the following kinds of audience in order of increasing/wider visibility:
Hadoop doesn’t have a Company-Private classification, which is meant for APIs which are intended to be used by other projects within the company, since it doesn’t apply to opensource projects. Also, certain APIs are annotated as @VisibleForTesting (from com.google.common .annotations.VisibleForTesting) - these are meant to be used strictly for unit tests and should be treated as “Private” APIs.
The interface is for internal use within the project (such as HDFS or MapReduce) 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 Hadoop project, some interfaces are LimitedPrivate{HDFS, MapReduce} in that they are private to the HDFS and MapReduce projects.
Stability denotes how stable an interface is, as in when incompatible changes to the interface are allowed. Hadoop APIs have the following levels of stability.
Can evolve while retaining compatibility for minor release boundaries; in other words, incompatible changes to APIs marked as Stable are allowed only at major releases (i.e. at m.0).
Incompatible changes to Unstable APIs are allowed at 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.
How will the classification be recorded for Hadoop APIs?
Each interface or class will have the audience and stability recorded using annotations in org.apache.hadoop.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.
Lets treat all private interfaces as Hadoop-private. What is the harm in projects in the Hadoop family have access to private classes?
Aren’t all public interfaces stable?