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