Hadoop注解InterfaceAudience InterfaceStability

Hadoop注解InterfaceAudience InterfaceStability
- 1. InterfaceAudience
- 2. InterfaceStability

Hadoop注解InterfaceAudience InterfaceStability

最近学习Hadoop时，看到InputFormat上面两个注解，是以前没有见过的，做一个简单记录
@InterfaceAudience.Public
@InterfaceStability.Stable

1. InterfaceAudience

InterfaceAudience源码

/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */
package org.apache.hadoop.classification;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

/** * Annotation to inform users of a package, class or method's intended audience. * Currently the audience can be {@link Public}, {@link LimitedPrivate} or * {@link Private}. <br> * All public classes must have InterfaceAudience annotation. <br> * <ul> * <li>Public classes that are not marked with this annotation must be * considered by default as {@link Private}.</li> * * <li>External applications must only use classes that are marked * {@link Public}. Avoid using non public classes as these classes * could be removed or change in incompatible ways.</li> * * <li>Hadoop projects must only use classes that are marked * {@link LimitedPrivate} or {@link Public}</li> * * <li> Methods may have a different annotation that it is more restrictive * compared to the audience classification of the class. Example: A class * might be {@link Public}, but a method may be {@link LimitedPrivate} * </li></ul> */
@InterfaceAudience.Public
@InterfaceStability.Evolving
public class InterfaceAudience {
  /** * Intended for use by any project or application. */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  public @interface Public {};
  
  /** * Intended only for the project(s) specified in the annotation. * For example, "Common", "HDFS", "MapReduce", "ZooKeeper", "HBase". */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  public @interface LimitedPrivate {
    String[] value();
  };
  
  /** * Intended for use only within Hadoop itself. */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  public @interface Private {};

  private InterfaceAudience() {} // Audience can't exist on its own
}

从源码中可以看出，InterfaceAudience有3个类型，用来说明被注解的类使用的作用范围

Public：可以给任何项目和应用程序使用

LimitedPrivate：仅仅可以使用在“Common”、“HDFS”、“MapReduce”、“ZooKeeper”、“HBase”

Private：仅仅可以在Hadoop本身内使用

2. InterfaceStability

InterfaceStability源码

/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */
package org.apache.hadoop.classification;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

import org.apache.hadoop.classification.InterfaceAudience.LimitedPrivate;
import org.apache.hadoop.classification.InterfaceAudience.Private;
import org.apache.hadoop.classification.InterfaceAudience.Public;

/** * Annotation to inform users of how much to rely on a particular package, * class or method not changing over time. Currently the stability can be * {@link Stable}, {@link Evolving} or {@link Unstable}. <br> * * <ul><li>All classes that are annotated with {@link Public} or * {@link LimitedPrivate} must have InterfaceStability annotation. </li> * <li>Classes that are {@link Private} are to be considered unstable unless * a different InterfaceStability annotation states otherwise.</li> * <li>Incompatible changes must not be made to classes marked as stable.</li> * </ul> */
@InterfaceAudience.Public
@InterfaceStability.Evolving
public class InterfaceStability {
  /** * Can evolve while retaining compatibility for minor release boundaries.; * can break compatibility only at major release (ie. at m.0). */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  public @interface Stable {};
  
  /** * Evolving, but can break compatibility at minor release (i.e. m.x) */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  public @interface Evolving {};
  
  /** * No guarantee is provided as to reliability or stability across any * level of release granularity. */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  public @interface Unstable {};
}

从源码可以看出，InterfaceStability有3个类型，用来说明被注解的类的稳定性

Stable：说明主版本是稳定的，不同主版本之间可能不兼容

Evolving：说明在不停的变化，不同小版本之间也可能不兼容

UnStable：无法保证其可靠性和稳定性