Enum StabilityLevel

  • All Implemented Interfaces:
    Serializable, Comparable<StabilityLevel>

    @PublicAPI(stability=UNCOMMITTED,
               mayInstantiate=false,
               mayExtend=false,
               mayInvoke=true)
    public enum StabilityLevel
    extends Enum<StabilityLevel>
    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 COMMITTED, UNCOMMITTED, VOLAITLE, or OBSOLETE stability level in order to indicate the relative likelihood that the associated interface will be changed in an incompatible way in the future.

    Third-party developers are free to create code that introduces dependencies on OpenDS APIs that are marked COMMITTED, UNCOMMITTED, or 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.

    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 COMMITTED, UNCOMMITTED, or VOLATILE is to be made private, it is strongly recommended that it first be transitioned to OBSOLETE before ultimately being marked PRIVATE.

    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.
    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description
      COMMITTED
      The associated package, class, or method may be made available for third-party use, and the APIs that it exposes should be considered stable.
      OBSOLETE
      The associated package, class, or method should be considered obsolete, and no new code should be created that depends on it.
      PRIVATE
      The associated package, class, or method should be considered part of the OpenDS private API and should not be used by third-party code.
      UNCOMMITTED
      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.
      VOLATILE
      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.
    • Enum Constant Detail

      • COMMITTED

        public static final StabilityLevel COMMITTED
        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.

        Note that interface changes may be allowed between non-major releases if they do not impact backward compatibility.
      • UNCOMMITTED

        public static final StabilityLevel UNCOMMITTED
        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.

        Note that interface changes may be allowed between non-major and non-minor releases if they do not impact backward compatibility.
      • VOLATILE

        public static final StabilityLevel VOLATILE
        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.

        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 VOLATILE, even if that those incompatible changes are expected to occur between major releases.
      • OBSOLETE

        public static final StabilityLevel OBSOLETE
        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.
      • PRIVATE

        public static final StabilityLevel PRIVATE
        The associated package, class, or method should 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 PRIVATE classification.
    • Method Detail

      • values

        public static StabilityLevel[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
        for (StabilityLevel c : StabilityLevel.values())
            System.out.println(c);
        
        Returns:
        an array containing the constants of this enum type, in the order they are declared
      • valueOf

        public static StabilityLevel valueOf​(String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        IllegalArgumentException - if this enum type has no constant with the specified name
        NullPointerException - if the argument is null