Add a new @PublicAPI annotation type that can be used later to mark OpenDS ...

neil_a_wilson

13.15.2007 965379c614804bc8a9143a867dca9e646e1cf93a

Add a new @PublicAPI annotation type that can be used later to mark OpenDS
packages, classes, and methods to indicate what part (if any) they play in the
OpenDS public API.  This annotation type can be useful for documentation
purposes, for helping to verify whether third-party code is using appropriate
interfaces, and ensuring that what we declare as our public API does not change
in an inappropriate way between releases.

This commit also introduces a new StabilityLevel enumeration that can be used
to indicate the likelihood that the associated code will change in an
incompatible manner in the future.

Comments in the @PublicAPI annotation type and the StabilityLevel enum should
adequately describe their purpose and intended use.  At the present time, none
of the OpenDS code uses them, but we will add the @PublicAPI annotation to
OpenDS code where appropriate before the 1.0 release in order to help define
what is included in our public API.

Note that checkstyle analysis is currently disabled for this annotation type
because of an apparent checkstyle limitation that does not support the use of
Javadoc comments in methods used to define annotation type properties.

 opends/build.xml

@@ -373,7 +373,8 @@

    <checkstyle config="${checkstyle.dir}/opends-checkstyle.xml"
         failOnViolation="true">
      <fileset dir="${src.dir}" includes="**/*.java" />
      <fileset dir="${src.dir}" includes="**/*.java"
           excludes="**/PublicAPI.java" />
      <formatter type="plain" />
    </checkstyle>

@@ -401,7 +402,7 @@
      <fileset dir="${src.dir}/org/opends/server/protocols/internal"
           includes="**/*.java" />
      <fileset dir="${src.dir}/org/opends/server/types"
           includes="**/*.java" />
           includes="**/*.java" excludes="**/PublicAPI.java"/>
      <formatter type="plain" />
    </checkstyle>


 opends/src/server/org/opends/server/types/PublicAPI.java

New file
@@ -0,0 +1,153 @@
/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Portions Copyright 2007 Sun Microsystems, Inc.
 */
package org.opends.server.types;



import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;



/**
 * This class defines an annotation type that can be used to describe
 * the position of a package, class, or method in the OpenDS public
 * API (including to denote that the associated code should NOT be
 * considered part of the public API).  Third-party developers should
 * pay attention to these annotations in order to understand how best
 * to interact with the OpenDS code.  For the purposes of this
 * annotation, a "third-party developer" should be assumed to refer to
 * anyone who is interacting with the OpenDS code in a manner in which
 * their work is not expected to become part of the core OpenDS code
 * base.
 * <BR><BR>
 * This annotation type may be used to describe things like:
 * <UL>
 *   <LI>The stability of the code (how likely it is to change in the
 *       future and whether those changes may be incompatible with
 *       previous implementations).</LI>
 *   <LI>Whether third-party code may be allowed to create new
 *       instances of the associated object type.</LI>
 *   <LI>Whether a class or method may be extended by third-party
 *       code.</LI>
 *   <LI>Whether a class or method may be invoked by third-party
 *       code.</LI>
 * </UL>
 * <BR><BR>
 * Note that for cases in which there are conflicting public API
 * annotations, the most specific annotation should be considered
 * authoritative.  For example, if a class is marked with
 * {@code mayInvoke=true} but a method in that class is marked with
 * {@code mayInvoke=false}, then third-party code should not attempt
 * to invoke that method because the method-level annotation is more
 * specific (and therefore overrides) the less-specific class-level
 * annotation.
 * <BR><BR>
 * If a method does not include this annotation, then it should be
 * assumed to inherit the class-level annotation.  If a class does not
 * include this annotation, then it should be assumed to inherit the
 * package-level annotation.  If a package does not include this
 * annotation, then it should be assumed the package is private and
 * should not be used by third-party code.
 */
@Documented()
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE,
          ElementType.TYPE,
          ElementType.METHOD,
          ElementType.CONSTRUCTOR })
public @interface PublicAPI
{
  /**
   * Retrieves the stability level for the associated class or method.
   *
   * @return  The stability level for the associated class or method.
   */
  StabilityLevel stability() default StabilityLevel.PRIVATE;



  /**
   * Indicates whether third-party code should be allowed to directly
   * create new instances of the associated object type by calling the
   * constructor or a static factory method defined in that class.
   * Note that even in cases where third-party code should not
   * instantiate a given object type, it may be permissible for
   * third-party code to invoke methods on instances of that object
   * obtained elsewhere (e.g., provided as an argument to a method
   * overridden by the third-party code).
   *
   * @return  {@code true} if third-party code should be allowed to
   *          create new instances of the associated object type, or
   *          {@code false} if not.
   */
  boolean mayInstantiate() default false;



  /**
   * Indicates whether the associated class/interface/method may be
   * extended/implemented/overridden by third-party code.  In some
   * cases, the OpenDS code may define an abstract class, interface,
   * or non-final method that is intended only for internal use and
   * may be extended by internal code but should not be extended by
   * classes outside the OpenDS code base.
   *
   * @return  {@code true} if the associated class/interface/method
   *          may be extended by third-party code, or {@code false} if
   *          not.
   */
  boolean mayExtend() default false;



  /**
   * Indicates whether the associated method may be invoked by
   * third-party code.
   *
   * @return  {@code true} if third-party code should be allowed to
   *          invoke the associated method, or {@code false} if not.
   */
  boolean mayInvoke() default false;



  /**
   * Retrieves a string that may contain additional notes that should
   * be taken into consideration by third-party developers that may be
   * interested in using the associated code.
   *
   * @return  A string that may contain additional notes that should
   *          be taken into consideration by third-party developers
   *          that may be interested in using the associated code.
   */
  String notes() default "";
}


 opends/src/server/org/opends/server/types/StabilityLevel.java

New file
@@ -0,0 +1,134 @@
/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Portions Copyright 2007 Sun Microsystems, Inc.
 */
package org.opends.server.types;



/**
 * This class implements an enumeration whose values may be used to
 * indicate the stability level of API classes and/or methods.  Code
 * which is part of the OpenDS public API should be marked with a
 * {@code COMMITTED}, {@code UNCOMMITTED}, {@code VOLAITLE}, or
 * {@code OBSOLETE} stability level in order to indicate the relative
 * likelihood that the associated interface will be changed in an
 * incompatible way in the future.
 * <BR><BR>
 * Third-party developers are free to create code that introduces
 * dependencies on OpenDS APIs that are marked {@code COMMITTED},
 * {@code UNCOMMITTED}, or {@code VOLATILE}, with an understanding
 * that the less stable an OpenDS API is, the more likely that
 * third-party code which relies upon it may need to be altered in
 * order to work properly with future versions.
 * <BR><BR>
 * Changes to the stability level of a class or package should only be
 * made between major releases and must be denoted in the release
 * notes for all releases with that major version.  If a public API
 * element that is marked {@code COMMITTED}, {@code UNCOMMITTED}, or
 * {@code VOLATILE} is to be made private, it is strongly recommended
 * that it first be transitioned to {@code OBSOLETE} before ultimately
 * being marked {@code PRIVATE}.
 * <BR><BR>
 * New packages and classes introduced into the OpenDS code base may
 * be assigned any stability level.  New methods introduced into
 * existing classes that are part of the public API may be created
 * with any stability level as long as the introduction of that method
 * is compliant with the stability level of the class.  If a method
 * that is part of the OpenDS public API is not marked with an
 * explicit stability level, then it should be assumed that it has the
 * same stability level as the class that contains it.
 */
public enum StabilityLevel
{
  /**
   * The associated package, class, or method may be made available
   * for third-party use, and the APIs that it exposes should be
   * considered stable.  Incompatible changes may only be introduced
   * between major versions, and even then such changes should be
   * considered very rare and will require strong justification and
   * be explicitly denoted in the release notes for all releases with
   * that major version.
   * <BR><BR>
   * Note that interface changes may be allowed between non-major
   * releases if they do not impact backward compatibility.
   */
  COMMITTED,



  /**
   * The associated package, class, or method may be made available
   * for third-party use, and the APIs that it exposes may be
   * considered moderately stable.  Incompatible changes may be
   * introduced between major and/or minor versions, but only with
   * strong justification and explicit denotation in the release notes
   * for all subsequent releases with that major version.
   * <BR><BR>
   * Note that interface changes may be allowed between non-major and
   * non-minor releases if they do not impact backward compatibility.
   */
  UNCOMMITTED,



  /**
   * The associated package, class, or method may be made available
   * for third-party use, but the APIs that it exposes should not be
   * considered stable.  Incompatible changes may be introduced
   * between major, minor, and point versions, and may also be
   * introduced in patches or hotfixes.  Any incompatible interface
   * changes should be denoted in the release notes for all subsequent
   * releases with that major version.
   * <BR><BR>
   * Note that if it is believed that a given class or interface will
   * likely have incompatible changes in the future, then it should be
   * declared with a stability level of {@code VOLATILE}, even if that
   * those incompatible changes are expected to occur between major
   * releases.
   */
  VOLATILE,



  /**
   * The associated package, class, or method should be considered
   * obsolete, and no new code should be created that depends on it.
   * The associated code may be removed in future versions without any
   * additional prior notice.
   */
  OBSOLETE,



  /**
   * The associated package, class, or method should not be considered
   * part of the OpenDS private API and should not be used by
   * third-party code.  No prior notice is required for incompatible
   * changes to code with a {@code PRIVATE} classification.
   */
  PRIVATE;
}