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