Package org.opends.server.types

Annotation Type PublicAPI

  • @Documented
@Retention(RUNTIME)
@Target({PACKAGE,TYPE,METHOD,CONSTRUCTOR})
public @interface PublicAPI
    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.

    This annotation type may be used to describe things like:
    • The stability of the code (how likely it is to change in the future and whether those changes may be incompatible with previous implementations).
    • Whether third-party code may be allowed to create new instances of the associated object type.
    • Whether a class or method may be extended by third-party code.
    • Whether a class or method may be invoked by third-party code.


    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 mayInvoke=true but a method in that class is marked with 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.

    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.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      boolean mayExtend
      Indicates whether the associated class/interface/method may be extended/implemented/overridden by third-party code.
      boolean mayInstantiate
      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.
      boolean mayInvoke
      Indicates whether the associated method may be invoked by third-party code.
      String notes
      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.
      StabilityLevel stability
      Retrieves the stability level for the associated class or method.

    • Element Detail

      • stability

        StabilityLevel stability
        Retrieves the stability level for the associated class or method.
        Returns:
        The stability level for the associated class or method.
        Default:
        org.opends.server.types.StabilityLevel.PRIVATE

      • mayInstantiate

        boolean mayInstantiate
        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).
        Returns:
        true if third-party code should be allowed to create new instances of the associated object type, or false if not.
        Default:
        false

      • mayExtend

        boolean mayExtend
        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.
        Returns:
        true if the associated class/interface/method may be extended by third-party code, or false if not.
        Default:
        false

      • mayInvoke

        boolean mayInvoke
        Indicates whether the associated method may be invoked by third-party code.
        Returns:
        true if third-party code should be allowed to invoke the associated method, or false if not.
        Default:
        false

      • notes

        String notes
        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.
        Returns:
        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.
        Default:
        ""