001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2008 Sun Microsystems, Inc.
015 * Portions Copyright 2012-2015 ForgeRock AS.
016 */
017package org.opends.server.types;
018
019
020
021
022
023import java.lang.annotation.Documented;
024import java.lang.annotation.ElementType;
025import java.lang.annotation.Retention;
026import java.lang.annotation.RetentionPolicy;
027import java.lang.annotation.Target;
028
029
030
031/**
032 * This class defines an annotation type that can be used to describe
033 * the position of a package, class, or method in the OpenDS public
034 * API (including to denote that the associated code should NOT be
035 * considered part of the public API).  Third-party developers should
036 * pay attention to these annotations in order to understand how best
037 * to interact with the OpenDS code.  For the purposes of this
038 * annotation, a "third-party developer" should be assumed to refer to
039 * anyone who is interacting with the OpenDS code in a manner in which
040 * their work is not expected to become part of the core OpenDS code
041 * base.
042 * <BR><BR>
043 * This annotation type may be used to describe things like:
044 * <UL>
045 *   <LI>The stability of the code (how likely it is to change in the
046 *       future and whether those changes may be incompatible with
047 *       previous implementations).</LI>
048 *   <LI>Whether third-party code may be allowed to create new
049 *       instances of the associated object type.</LI>
050 *   <LI>Whether a class or method may be extended by third-party
051 *       code.</LI>
052 *   <LI>Whether a class or method may be invoked by third-party
053 *       code.</LI>
054 * </UL>
055 * <BR><BR>
056 * Note that for cases in which there are conflicting public API
057 * annotations, the most specific annotation should be considered
058 * authoritative.  For example, if a class is marked with
059 * {@code mayInvoke=true} but a method in that class is marked with
060 * {@code mayInvoke=false}, then third-party code should not attempt
061 * to invoke that method because the method-level annotation is more
062 * specific (and therefore overrides) the less-specific class-level
063 * annotation.
064 * <BR><BR>
065 * If a method does not include this annotation, then it should be
066 * assumed to inherit the class-level annotation.  If a class does not
067 * include this annotation, then it should be assumed to inherit the
068 * package-level annotation.  If a package does not include this
069 * annotation, then it should be assumed the package is private and
070 * should not be used by third-party code.
071 */
072@Documented
073@Retention(RetentionPolicy.RUNTIME)
074@Target({ ElementType.PACKAGE,
075          ElementType.TYPE,
076          ElementType.METHOD,
077          ElementType.CONSTRUCTOR })
078public @interface PublicAPI
079{
080  /**
081   * Retrieves the stability level for the associated class or method.
082   *
083   * return The stability level for the associated class or method.
084   */
085  StabilityLevel stability() default StabilityLevel.PRIVATE;
086
087
088
089  /**
090   * Indicates whether third-party code should be allowed to directly
091   * create new instances of the associated object type by calling the
092   * constructor or a static factory method defined in that class.
093   * Note that even in cases where third-party code should not
094   * instantiate a given object type, it may be permissible for
095   * third-party code to invoke methods on instances of that object
096   * obtained elsewhere (e.g., provided as an argument to a method
097   * overridden by the third-party code).
098   *
099   * return {@code true} if third-party code should be allowed to
100   *          create new instances of the associated object type, or
101   *          {@code false} if not.
102   */
103  boolean mayInstantiate() default false;
104
105
106
107  /**
108   * Indicates whether the associated class/interface/method may be
109   * extended/implemented/overridden by third-party code.  In some
110   * cases, the OpenDS code may define an abstract class, interface,
111   * or non-final method that is intended only for internal use and
112   * may be extended by internal code but should not be extended by
113   * classes outside the OpenDS code base.
114   *
115   * return  {@code true} if the associated class/interface/method
116   *          may be extended by third-party code, or {@code false} if
117   *          not.
118   */
119  boolean mayExtend() default false;
120
121
122
123  /**
124   * Indicates whether the associated method may be invoked by
125   * third-party code.
126   *
127   * return  {@code true} if third-party code should be allowed to
128   *          invoke the associated method, or {@code false} if not.
129   */
130  boolean mayInvoke() default false;
131
132
133
134  /**
135   * Retrieves a string that may contain additional notes that should
136   * be taken into consideration by third-party developers that may be
137   * interested in using the associated code.
138   *
139   * return  A string that may contain additional notes that should
140   *          be taken into consideration by third-party developers
141   *          that may be interested in using the associated code.
142   */
143  String notes() default "";
144}
145