07.hadoop-2.7.2官网文档翻译-Hadoop接口类别

作者: 疯狂小兵 | 2016-07-13 | 阅读
「编辑」 「本文源码」

动机

这里提供的接口分类是为指导开发者和用户的接口。该分类引导开发人员声明目标受众或者接口的用户,并且也声明它的稳定性。

  • 对接口的用户的好处:知道哪个接口可用或不可用以及他们的稳定性

  • 对开发者的好处:防止接口的意外变化,对用户或其他组件或系统的意外影响。对于不都有分享状态/历史的项目的很多开发者,这是特别有用的大系统。

接口分级

Hadoop采用以下接口分类,该分类从OpenSolaris分类衍生出来并在一定程度上,来自于雅虎内部使用的分类。

接口有两种主要属性:受众和稳定

Audience(受众)

Audience指出接口的潜在消费者。虽然许多接口都是内部实现或私有实现,其他的公共/外部接口是为了更广泛的被程序/客户端消费的。

比如,在POSIX中,libc是外部或公共的接口,而内核中大部分是内部或私有接口。也有一些接口是针对其他特定的子系统的。

识别接口的受众有助于定义打破它的影响。例如,打破受众是小数量指定子系统的接口的兼容性可能是OK的。另一方面,打破上百万的互联网用户依赖的协议接口可能是不好的。

为了增加可见度,Hadoop使用下面的几种受众:

  • Private

    • 该接口是为项目内部使用的(比如HDFS,MapReduce),并且不应该被应用程序或其他项目使用。它可以在任何时候没有提示的改变。项目中的大部分接口都是私有的(也可以叫:project-private)。
  • Limited-Private

    • 该接口被指定的项目集或者系统(一般是紧密相关的项目)使用。其他项目或系统不应当使用该接口。接口的更改要与指定的姓名进行沟通,协商。 比如:在Hadoop项目中,一些接口是LimitedPrivate{HDFS,MapReduce},但他们对于HDFS或者MapReduce项目是私有的。
  • Public

    • 该接口一般被任何应用程序使用。

Hadoop没有Company-Private(公司私有)的分类,意思是公司内部的其他项目依赖使用的API。因为它不支持开源项目。某些API也被注解为@VisibleForTesting(来自com.google.common .annotations.VisibleForTesting)-这些都是要严格用于单元测试并应该被视为私有的API。

Stability(稳定)

Stability指出在接口进行不兼容的改变时,一个接口的稳定性。Hadoop的API有一下几种稳定级别。

  • Stable(稳定)

    • 可以进化,同时保持小版本边界的兼容性。换句话说就是,只在主版本允许不兼容的改变被标记为稳定状态。
  • Evolving(演进)

    • 正在演进,但是在小版本中允许不兼容的变化。
  • Unstable(不稳定)

    • 任何时候都允许不稳定API的不兼容性改变。通常只用于私有接口场景。

    • 然而,有人可能会称之为一个所谓的公共接口,强调它不应该被用来作为一个接口。对于公共接口,标记它为非接口可能比不稳定态更适合。

      • 不稳定公共访问接口的例子(非接口):GUI,输出格式改变的CLI。
  • Deprecated(过期)

    • 那些在未来会被移除或不应该再被使用的接口。

分类是如何记录的

Hadoop的API是如何分类被记录的呢?

  • 使用org.apache.hadoop.classification包内的注解,每个接口或类都有受众和稳定性记录

  • 由maven target javadoc:javadoc 生成的javadoc仅仅包含公共API。

  • 通过他们所包含的包的受众,可以得到java类和java接口的受众。因此,将每个包的受众声明为Public或private(随着私有受众的变化)是有用的。

FAQ

  • 为什么java的范围(private,package private 和public)不够好

    • java的返回不够完全。为了其他内部组件的使用,类经常被强制为公共类型。它没有像C++中的友元或子包私有类型。
  • 如果java是公共的,我可以很容易的获得一个私有的实现。保护和控制在哪里?

    • 该目的不是提供绝对的访问控制。它的目标是与用户或开发者交流。一个人可以访问libc的私有实现方法;然而如果改变内部实现细节,你的程序将会崩溃并且你也不会从支持libc的人们那里获得任何同情。 如果你使用了非公开的接口,你懂的..
  • 为什么要费事声明一个私有接口的稳定性呢?私有接口总是不稳定的吗?

    • 私有接口不总是不稳定的。在他们稳定可以获取系统内部实行的情况下,可以将这些属性提供给它的内部用户或接口的开发者。

      • 例如:在HDFS中,NN-DN协议是私有的但是稳定的,可以帮助实现滚动升级。它传达了该接口不应该以非兼容性更改,即使它也是私有的。

      • 例如:在HDFS中,fsimage的稳定可以帮助提高回滚的灵活性。

  • 在应用程序中使用一个私有的稳定接口有什么危害?它和公共的稳定接口有什么不同呢?

    • 当一个私有接口被标记为稳定,意味着只能在主版本中改变。如果该接口的提供者想更改该接口的内部用户,稳定性将会被打破。此外一个公共稳定的接口即使在主版本也不大可能会打破兼容性(即使允许打破兼容性)。 因为更改的影响是巨大的。如果你使用了私有接口(先不管稳定性如何),会有不兼容的危险。
  • 为什么要操心Limited-private?它不是给予一些项目的特别待遇吗?这是不公平的。

    • 首先,大部分接口是公共或私有的;事实上,让我们规定它更强大:使得它为私有除非想要把它暴露出去作为一般使用。

    • 有限私有适用于不为一般使用的接口的。他们暴露给需要指定钩子的相关项目。这样的分类在限制性接口的供应者和消费者间有一个成本。 如果在未来有打破接口兼容性的需要,这两个将不得不协同工作。例如,供应者和消费者将不得不共努力得到各自的项目的协同发布。 如果你可以不使用私有这样做,这将不应该被轻视。如果接口是真的为所有应用程序的一般用途,那么这样做。 但是记住标记接口为公共需要承担巨大责任。有时限制性私有刚刚好。

    • 限制性私有接口的一个很好的例子是BlockLocations,这是相当底层的接口,我们希望将他暴露给MR可能是HBase。我们可能会改变他的轨迹,那是我们会与MR团队在版本对接上有个协调。 虽然MR和HDFS总是在同一天发布,他们也可能改变轨迹。

    • 如果你在许多项目上有限制性私有的接口,那么你是在愚弄你自己,那几乎就是公共的了。

    • 对于Hadoop家族,声明一个指定的受众类别叫Hadoop级别私有或许是值得的。

  • 让我们对所有的接口作为Hadoop的私有。那Hadoop家族中的项目访问私有类有什么危害吗?

    • 我们想要MR访问在HDFS内部实现的class类,在代码中曾经有许多这样的层侵略,导致我们最近几年一直在清理。我们不希望想HDFS和MR这样的主要组件间内没有分隔的层入侵重新回来。
  • 所有的公共接口都是稳定的吗?

    • 可能会在公共接口的早期标记为演进,在这里,会为兼容性努力,但是兼容性在小版本可能会被打破。

    • 公共接口不稳定的一个例子是,基于接口提供了一个标准的实现但仍然在开发中。比如,在进入市场的第一次尝试,大部分公司提供新的NFS协议的实现,即使该协议还没有被IETF全部完成。实现者不能使接口进化的原因至少存在。 因为稳定性是有标准组织控制的。这里就适当的为接口打上不稳定的标签。


版权声明:本文由 在 2016年07月13日发表。本文采用CC BY-NC-SA 4.0许可协议,非商业转载请注明出处,不得用于商业目的。
文章题目及链接:《07.hadoop-2.7.2官网文档翻译-Hadoop接口类别》




  相关文章:

「游客及非Github用户留言」:

「Github登录用户留言」:

TOP