< prev index next >

src/java.base/share/classes/java/lang/Deprecated.java

Print this page
rev 15239 : more release => version

*** 27,49 **** import java.lang.annotation.*; import static java.lang.annotation.ElementType.*; /** ! * A program element annotated @Deprecated is one that programmers ! * are discouraged from using, typically because it is dangerous, ! * or because a better alternative exists. Compilers warn when a ! * deprecated program element is used or overridden in non-deprecated code. ! * ! * <p>Use of the @Deprecated annotation on a local variable ! * declaration or on a parameter declaration or a package declaration ! * has no effect on the warnings issued by a compiler. * * @author Neal Gafter * @since 1.5 * @jls 9.6.4.6 @Deprecated */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE}) public @interface Deprecated { } --- 27,93 ---- import java.lang.annotation.*; import static java.lang.annotation.ElementType.*; /** ! * A program element annotated {@code @Deprecated} is one that programmers ! * are discouraged from using. An element may be deprecated for any of several ! * reasons, for example, its usage is likely to lead to errors; it may ! * be changed incompatibly or removed in a future version; it has been ! * superseded by a newer, usually preferable alternative; or it is obsolete. ! * ! * <p>Compilers issue warnings when a deprecated program element is used or ! * overridden in non-deprecated code. Usage of a deprecated element may also ! * be flagged by various analysis tools. Use of the {@code @Deprecated} ! * annotation on a local variable declaration or on a parameter declaration ! * or a package declaration has no effect on the warnings issued by a compiler. ! * ! * <p>This annotation has a boolean-valued element {@code condemned}. ! * A value of {@code true} indicates intent to remove the annotated program ! * element in a future version. A value of {@code false} indicates that use of ! * the annotated program element is discouraged but, at the time the ! * annotated program element was specified, that there was no specific ! * intent to remove it. ! * ! * <p>This annotation has a string-valued element {@code since}. This value ! * indicates the version in which the annotated program element was first ! * deprecated. ! * ! * @apiNote ! * It is strongly recommended that the reason for deprecating a program element ! * be explained in that element's documentation, using the {@code @deprecated} ! * javadoc tag. This documentation should also suggest and link to a ! * recommended replacement API, if applicable. A replacement API often ! * has subtly different semantics, so such issues should be discussed as ! * well. ! * ! * <p>The {@code @Deprecated} annotation should always be present if ! * the {@code @deprecated} javadoc tag is present, and vice-versa. * * @author Neal Gafter * @since 1.5 * @jls 9.6.4.6 @Deprecated */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE}) public @interface Deprecated { + /** + * Indicates whether the annotated element is subject to removal in a + * future version. The default value is {@code false}. + * + * @return whether the element is subject to removal + * @since 9 + */ + boolean condemned() default false; + + /** + * Returns the version in which the API element became deprecated. + * The version string is in the same format and namespace as the value of + * the {@code @since} javadoc tag. The default value is the empty + * string. + * + * @return the version string + * @since 9 + */ + String since() default ""; }
< prev index next >