org.apiguardian.api.API Maven / Gradle / Ivy
/*
* Copyright 2002-2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apiguardian.api;
import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
/**
* {@code @API} is used to annotate public types, methods, constructors, and
* fields within a framework or application in order to publish their
* {@link #status} and level of stability and to indicate how they are intended
* to be used by {@link #consumers} of the API.
*
* If {@code @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 {@link Status} of lower stability. For example,
* a class annotated with {@code @API(status = STABLE)} may declare a constructor
* for internal usage that is annotated with {@code @API(status = INTERNAL)}.
*
* @since 1.0
*/
@Target({ TYPE, METHOD, CONSTRUCTOR, FIELD })
@Retention(RUNTIME)
@Documented
public @interface API {
/**
* The current {@linkplain Status status} of the API.
*/
Status status();
/**
* The version of the API when the {@link #status} was last changed.
*
*
Defaults to an empty string, signifying that the since
* version is unknown.
*/
String since() default "";
/**
* 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 {@code "*"}, signifying that the API is intended to be
* consumed by any package.
*/
String[] consumers() default "*";
/**
* Indicates the status of an API element and therefore its level of
* stability as well.
*/
enum Status {
/**
* Must not be used by any external code. Might be removed without prior
* notice.
*/
INTERNAL,
/**
* Should no longer be used. Might disappear in the next minor release.
*/
DEPRECATED,
/**
* Intended for new, experimental features where the publisher of the
* API is looking for feedback.
*
*
Use with caution. Might be promoted to {@link #MAINTAINED} or
* {@link #STABLE} in the future, but might also be removed without
* prior notice.
*/
EXPERIMENTAL,
/**
* 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
* {@link #DEPRECATED} first.
*/
MAINTAINED,
/**
* Intended for features that will not be changed in a backwards-incompatible
* way in the current major version.
*/
STABLE;
}
}