Top Description Inners Methods
org.apiguardian.api

public @Interface API

extends Annotation
Annotations
@Target:TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE
@Retention:RUNTIME
@Documented
Static Imports
java.lang.annotation.ElementType.CONSTRUCTOR, .ElementType.FIELD, .ElementType.METHOD, .ElementType.PACKAGE, .ElementType.TYPE, .RetentionPolicy.RUNTIME
@API is used to annotate public types, methods, constructors, and fields within a framework or application in order to publish their status and level of stability and to indicate how they are intended to be used by consumers of the API.

If @API is present on a type, it is considered to hold for all public members of the type as well. However, a member of such an annotated type is allowed to declare a Status of lower stability. For example, a class annotated with @API(status = STABLE) may declare a constructor for internal usage that is annotated with @API(status = INTERNAL).

If @API is present on a package, it is considered to hold for all public types in its package. The same rules for lowered stability apply as if they were specified on a type.

Since
1.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
API.Status

Indicates the status of an API element and therefore its level of stability as well.

Method Summary

Modifier and TypeMethod and Description
public String[]
consumers()

List of packages belonging to intended consumers.

public String
since()

The version of the API when the status was last changed.

public API.Status
status()

The current status of the API.

Inherited from java.lang.annotation.Annotation:
annotationTypeequalshashCodetoString

Method Detail

consumersback to summary
public String[] consumers()

List of packages belonging to intended consumers.

The supplied packages can be fully qualified package names or patterns containing asterisks that will be used as wildcards.

Defaults to "*", signifying that the API is intended to be consumed by any package.

sinceback to summary
public String since()

The version of the API when the status was last changed.

Defaults to an empty string, signifying that the since version is unknown.

statusback to summary
public API.Status status()

The current status of the API.

org.apiguardian.api back to summary

public final Enum API.Status

extends Enum<API.Status>
Class Inheritance
Indicates the status of an API element and therefore its level of stability as well.

Field Summary

Modifier and TypeField and Description
public static final API.Status
DEPRECATED

Should no longer be used.

public static final API.Status
EXPERIMENTAL

Intended for new, experimental features where the publisher of the API is looking for feedback.

public static final API.Status
INTERNAL

Must not be used by any external code.

public static final API.Status
MAINTAINED

Intended for features that will not be changed in a backwards-incompatible way for at least the next minor release of the current major version.

public static final API.Status
STABLE

Intended for features that will not be changed in a backwards-incompatible way in the current major version.

Constructor Summary

AccessConstructor and Description
private
Status()

Method Summary

Modifier and TypeMethod and Description
public static API.Status
valueOf(String name)

public static API.Status[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

DEPRECATEDback to summary
public static final API.Status DEPRECATED

Should no longer be used. Might disappear in the next minor release.

This status is usually used in combination with the standard annotation @Deprecated because that annotation is recognized by IDEs and the compiler. However, there are also cases where this status can be used on its own, for example when transitioning a MAINTAINED feature to an INTERNAL one.

EXPERIMENTALback to summary
public static final API.Status EXPERIMENTAL

Intended for new, experimental features where the publisher of the API is looking for feedback.

Use with caution. Might be promoted to MAINTAINED or STABLE in the future, but might also be removed without prior notice.

INTERNALback to summary
public static final API.Status INTERNAL

Must not be used by any external code. Might be removed without prior notice.

MAINTAINEDback to summary
public static final API.Status MAINTAINED

Intended for features that will not be changed in a backwards-incompatible way for at least the next minor release of the current major version. If scheduled for removal, such a feature will be demoted to DEPRECATED first.

STABLEback to summary
public static final API.Status STABLE

Intended for features that will not be changed in a backwards-incompatible way in the current major version.

Constructor Detail

Statusback to summary
private Status()

Method Detail

valueOfback to summary
public static API.Status valueOf(String name)
valuesback to summary
public static API.Status[] values()