org.opends.server.types
Annotation Type PublicAPI

@Documented
@Retention(value=RUNTIME)
@Target(value={PACKAGE,TYPE,METHOD,CONSTRUCTOR})
@PublicAPI(stability=UNCOMMITTED,
           mayInstantiate=false,
           mayExtend=false,
           mayInvoke=false)
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

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.
java.lang.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.

stability

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract java.lang.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:

""