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