1 /*
   2  * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.lang.annotation.*;
  29 import static java.lang.annotation.ElementType.*;
  30 
  31 /**
  32  * A program element annotated {@code @Deprecated} is one that programmers
  33  * are discouraged from using. An element may be deprecated for any of several
  34  * reasons, for example, its usage is likely to lead to errors; it may
  35  * be changed incompatibly or removed in a future version; it has been
  36  * superseded by a newer, usually preferable alternative; or it is obsolete.
  37  * 
  38  * <p>Compilers issue warnings when a deprecated program element is used or
  39  * overridden in non-deprecated code. Usage of a deprecated element may also
  40  * be flagged by various analysis tools. Use of the {@code @Deprecated}
  41  * annotation on a local variable declaration or on a parameter declaration
  42  * or a package declaration has no effect on the warnings issued by a compiler.
  43  *
  44  * <p>This annotation has a boolean-valued element {@code condemned}.
  45  * A value of {@code true} indicates intent to remove the annotated program
  46  * element in a future version. A value of {@code false} indicates that use of
  47  * the annotated program element is discouraged but, at the time the
  48  * annotated program element was specified, that there was no specific
  49  * intent to remove it.
  50  *
  51  * <p>This annotation has a string-valued element {@code since}. This value
  52  * indicates the version in which the annotated program element was first
  53  * deprecated.
  54  *
  55  * @apiNote
  56  * It is strongly recommended that the reason for deprecating a program element
  57  * be explained in that element's documentation, using the {@code @deprecated}
  58  * javadoc tag. This documentation should also suggest and link to a
  59  * recommended replacement API, if applicable. A replacement API often
  60  * has subtly different semantics, so such issues should be discussed as
  61  * well.
  62  *
  63  * <p>The {@code @Deprecated} annotation should always be present if
  64  * the {@code @deprecated} javadoc tag is present, and vice-versa.
  65  * 
  66  * @author  Neal Gafter
  67  * @since 1.5
  68  * @jls 9.6.4.6 @Deprecated
  69  */
  70 @Documented
  71 @Retention(RetentionPolicy.RUNTIME)
  72 @Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
  73 public @interface Deprecated {
  74     /**
  75      * Indicates whether the annotated element is subject to removal in a
  76      * future version. The default value is {@code false}.
  77      *
  78      * @return whether the element is subject to removal
  79      * @since 9
  80      */
  81     boolean condemned() default false;
  82 
  83     /**
  84      * Returns the version in which the API element became deprecated.
  85      * The version string is in the same format and namespace as the value of
  86      * the {@code @since} javadoc tag. The default value is the empty
  87      * string. 
  88      *
  89      * @return the version string
  90      * @since 9
  91      */
  92     String since() default "";
  93 }