001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.classification;
019
020import java.lang.annotation.Documented;
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023
024/**
025 * Annotation to inform users of a package, class or method's intended audience.
026 * Currently the audience can be {@link Public}, {@link LimitedPrivate} or
027 * {@link Private}. <br>
028 * All public classes must have InterfaceAudience annotation. <br>
029 * <ul>
030 * <li>Public classes that are not marked with this annotation must be
031 * considered by default as {@link Private}.</li> 
032 * 
033 * <li>External applications must only use classes that are marked
034 * {@link Public}. Avoid using non public classes as these classes
035 * could be removed or change in incompatible ways.</li>
036 * 
037 * <li>Hadoop projects must only use classes that are marked
038 * {@link LimitedPrivate} or {@link Public}</li>
039 * 
040 * <li> Methods may have a different annotation that it is more restrictive
041 * compared to the audience classification of the class. Example: A class 
042 * might be {@link Public}, but a method may be {@link LimitedPrivate}
043 * </li></ul>
044 */
045@InterfaceAudience.Public
046@InterfaceStability.Evolving
047public class InterfaceAudience {
048  /**
049   * Intended for use by any project or application.
050   */
051  @Documented
052  @Retention(RetentionPolicy.RUNTIME)
053  public @interface Public {};
054  
055  /**
056   * Intended only for the project(s) specified in the annotation.
057   * For example, "Common", "HDFS", "MapReduce", "ZooKeeper", "HBase".
058   */
059  @Documented
060  @Retention(RetentionPolicy.RUNTIME)
061  public @interface LimitedPrivate {
062    String[] value();
063  };
064  
065  /**
066   * Intended for use only within Hadoop itself.
067   */
068  @Documented
069  @Retention(RetentionPolicy.RUNTIME)
070  public @interface Private {};
071
072  private InterfaceAudience() {} // Audience can't exist on its own
073}