Предложение по усовершенствованию JDK (JEP) 277 (« Усовершенствованное устаревание ») предлагает «обновить аннотацию амортизации и предоставить инструменты для усиления хвостовой части жизненного цикла объекта». Некоторые ограничения текущего @ java.lang.Deprecated беспокоили меня в течение некоторого времени. Я особенно хотел бы иметь возможность предоставлять текст @Deprecated вместо того, чтобы заставлять помещать пояснительный текст в соответствующий комментарий Javadoc @deprecated . В этой статье я рассмотрю пользовательскую аннотацию, которая дает представление о типе дополнительных метаданных, которые JEP 277 предлагает включить в новую улучшенную аннотацию @Deprecated .
В приведенном ниже листинге кода содержится определение dustin.examples.annotations.Deprecated , реализации, которая в основном отражает то, что описано в предложении JEP 277 .
dustin.examples.annotations.Deprecated
|
001
002
003
004
005
006
007
008
009
010
011
012
013
014
015
016
017
018
019
020
021
022
023
024
025
026
027
028
029
030
031
032
033
034
035
036
037
038
039
040
041
042
043
044
045
046
047
048
049
050
051
052
053
054
055
056
057
058
059
060
061
062
063
064
065
066
067
068
069
070
071
072
073
074
075
076
077
078
079
080
081
082
083
084
085
086
087
088
089
090
091
092
093
094
095
096
097
098
099
100
101
102
103
104
105
106
107
108
109
110
111
|
package dustin.examples.annotations;import java.lang.annotation.Documented;import java.lang.annotation.Retention;import java.lang.annotation.RetentionPolicy;import java.lang.annotation.Target;import static java.lang.annotation.ElementType.*;import static java.lang.annotation.ElementType.TYPE;/** * Conceptual improvement on standard @java.lang.Deprecated annotation * based on preliminary discussion related to JEP 277 and on * desire to include context details with deprecation annotation * rather than relying on presence of Javadoc's @deprecated. * * Javadoc comments in this annotation definition are largely * based on descriptions in JEP 277 (http://openjdk.java.net/jeps/277). */@Documented@Retention(RetentionPolicy.RUNTIME)@Target({CONSTRUCTOR,FIELD,LOCAL_VARIABLE,METHOD,PACKAGE,PARAMETER,TYPE})public @interface Deprecated{ /** * JEP 277-defined reasons and associated explanations. */ public enum Reason { /** * This API has been deprecated without any reason having been given. * This is the default value; everything that's deprecated today * implicitly has a deprecation reason of UNSPECIFIED. */ UNSPECIFIED, /** * This API is earmarked for removal in a future JDK release. Note, * the use of the word "condemned" here is used in the sense of a * structure that is intended to be torn down. The term is not mean * to imply any moral censure. */ CONDEMNED, /** * Use of this API can lead to data loss, deadlock, security * vulnerability, incorrect results, or loss of JVM integrity. */ DANGEROUS, /** * This API is no longer necessary, and usages should be removed. * No replacement API exists. Note that OBSOLETE APIs might or * might not be marked CONDEMNED. */ OBSOLETE, /** * This API has been replaced by a newer API, and usages should be * migrated away from this API to the newer API. Note that SUPERSEDED * APIs might or might not be marked CONDEMNED. */ SUPERSEDED, /** * Calling this has no effect or will unconditionally throw an exception. */ UNIMPLEMENTED, /** * This API is not a stable part of the specification, and it may * change incompatibly or disappear at any time. */ EXPERIMENTAL; } /** * Provides any combination of one or more of the enum constants, * although not all combinations make sense. It is syntactically possible, * though perverse, to provide an empty array. Such a case should be * treated as if UNSPECIFIED were present. * * @return One or more Reasons for deprecation; default value is the enum * constant UNSPECIFIED and absence of values should be treated as such. */ Reason[] value(); /** * Provides Strings representing any APIs that replace this API. * This should not specify any replacements if reason is OBSOLETE. * * @return Strings returned by this method should be links to replacement * APIs for the API being deprecated. Each string should be in the same * format as the @link Javadoc tag. */ String[] replacement(); /** * Provides the release in which the API was deprecated. * * @return Release number at which this API became deprecated * in a free-form syntax String with the release numbering * following the same scheme as the @since Javadoc tag. */ String since(); /** * Provides the anticipated complete removal of this deprecated API * if any known date or version is anticipated for the API's removal. * This value is most likely to be set for reasons of CONDEMNED, * OBSOLETE, and SUPERSEDED. This value is NOT described in JEP 277. * * @return Date or version in which it is anticipated that this * API will be removed altogether. */ String anticipatedRemoval() default "Not Planned";} |
В следующем листинге кода приведены примеры применения вышеупомянутой аннотации к устаревшему классу.
DeprecatedClass.java: примеры использования улучшенного @Deprecated
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
|
package dustin.examples.annotations.demo;import java.text.DateFormat;import java.text.SimpleDateFormat;import static dustin.examples.annotations.Deprecated.Reason.*;/** * Demonstrates how new and improved @Deprecated might be used. */@dustin.examples.annotations.Deprecated( value={SUPERSEDED, CONDEMNED}, since="1.5", anticipatedRemoval="1.9", replacement="dustin.examples.annotations.demo.OtherClass")public class DeprecatedClass{ final DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ"); @dustin.examples.annotations.Deprecated( value={DANGEROUS}, since="1.0", replacement="java.text.SimpleDateFormat#SimpleDateFormat") public DateFormat getDateFormatter() { return dateFormat; }} |
Этот последний пример демонстрирует использование улучшенной аннотации @Deprecated . Элемент « anticipatedRemoval @Deprecated аннотации @Deprecated не упоминается в JEP 277, и я присвоил ему значение по умолчанию для ситуаций, в которых устаревшая конструкция может не иметь ожидаемой даты удаления, а скорее не рекомендуется для предупреждения только о ее новом использовании.
Приведенные выше листинги кода демонстрируют определение новой и улучшенной аннотации @Deprecated например, изложенной в JEP 277. Однако в JEP 277 предлагается гораздо больше, чем наличие улучшенной аннотации. В предложении также обсуждаются «изменения времени выполнения» для предоставления «предупреждений об использовании устаревших API на основе подписки» , «усовершенствования инструмента зависимостей» для анализа зависимостей аннотаций в моде, аналогичном и, возможно, даже основанном на инструменте jdeps , и « Улучшения Javadoc. ”
Хотя поддержка пользовательских аннотаций в Java упростила реализацию версии @Deprecated , отражающей многие идеи в JEP 277, новый и улучшенный @java.lang.Deprecated будет обладать многими преимуществами, которых не имеет пользовательская аннотация Java, такими как встроенная. -в поддержке в JDK и использования классами JDK. Предоставленный JDK @Deprecated также продолжит пользоваться преимуществами IDE и инструментария, такими как вычеркнутые имена устаревших конструкций кода.
| Ссылка: | Как может выглядеть новый @Deprecated? от нашего партнера JCG Дастина Маркса в блоге Inspired by Actual Events . |