Hadoop接口分类

Interface Classification

Audience

Hadoop uses the following kinds of audience in order of increasing/wider visibility:

• Private:
  • 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).
• Limited-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.
• Public
  • The interface is for general use by any application.

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.

Stability

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.

• Stable
  • Can evolve while retaining compatibility for minor release boundaries; in other words, incompatible changes to APIs marked Stable are allowed only at major releases (i.e. at m.0).
• Evolving
  • Evolving, but incompatible changes are allowed at minor release (i.e. m .x)
• Unstable
  • 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
• Deprecated
  • APIs that could potentially removed in the future and should not be used.

http://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/InterfaceClassification.html