Spec-Zone .ru
спецификации, руководства, описания, API
|
Вы, возможно, услышали термин, "самоуничижительный юмор," или юмор, который минимизирует важность динамика. Осуждаемый class или метод походят на это. Это больше не важно. Это настолько незначительно, фактически, что больше недопустимо использовать это, так как это было заменено и может прекратить существование в будущем.
Java обеспечивает способ выразить осуждение, потому что, поскольку class развивается, его API (прикладной программный интерфейс) неизбежно изменяется: методы переименовываются для непротиворечивости, новые и лучшие методы добавляются, и полевое изменение. Но такие изменения представляют проблему. Вы должны иметь в наличии старый API, пока разработчики не делают переход к новому, но Вы не хотите, чтобы они продолжали программировать к старому API.
Возможность осудить class, метод, или задействованное поле решает проблему. Java поддерживает два механизма для осуждения: и аннотация, (поддерживаемый запуск с J2SE 5.0) и тег Javadoc (поддерживаемый с тех пор 1.1). Существующие звонки в старый API продолжают работать, но аннотация заставляет компилятор выпускать предупреждение, когда это находит ссылки на осуждаемые элементы программы. Тег Javadoc и связанные комментарии предупреждают пользователей против использования осуждаемого элемента и говорят им, что использовать вместо этого.
Когда Вы разрабатываете API, тщательно рассматриваете, заменяет ли он старый API. Если это делает, и Вы хотите поощрить разработчиков (пользователи API) переходить на новый API, то осуждаете старый API. Допустимые причины осудить API включают:
Осуждение является разумным выбором во всех этих случаях, потому что оно сохраняет "обратную совместимость", поощряя разработчиков измениться на новый API. Кроме того, комментарии осуждения помогают разработчикам решить, когда переместиться в новый API, и так должны кратко упомянуть технические причины осуждения.
Не необходимо осудить отдельные задействованные поля (свойства) осуждаемого class, если, конечно, Вы не хотите объяснить конкретный вопрос о свойстве.
Запускаясь с J2SE 5.0, Вы осуждаете class, метод, или поле при использовании @Deprecated
аннотация. Дополнительно, можно использовать @deprecated
Тег Javadoc говорит разработчикам, что использовать вместо этого.
Используя причины аннотации компилятор Java, чтобы генерировать предупреждения, когда осуждаемый class, метод, или поле используются. Компилятор подавляет предупреждения осуждения, если осуждаемый элемент используется в пределах объекта, который непосредственно осуждается или используется в пределах того же самого наиболее удаленного class или используется в объекте, который аннотируется, чтобы подавить предупреждение.
Вам строго рекомендуют использовать Javadoc @deprecated
тег с соответствующими комментариями, объясняющими, как использовать новый API. Это гарантирует, что у разработчиков будет осуществимый миграционный путь от старого API до нового API. Для получения дополнительной информации см. Используя @deprecated
Тег Javadoc.
ОТМЕТЬТЕ: Спецификация языка Java требует, чтобы компиляторы выпустили предупреждения когда классы, методы, или поля, отмеченные с @Deprecated
аннотация используется. Компиляторы не требуются Спецификацией языка Java выпустить предупреждения когда классы, методы, или поля, отмеченные с @deprecated
К тегу Javadoc получают доступ, хотя компиляторы Sun в настоящий момент делают так. Однако, нет никакой гарантии, что компилятор Sun будет всегда выпускать такие предупреждения.
J2SE 5.0 представляет новую функцию языка, названную аннотациями (также названный метаданными). Одна из встроенных аннотаций языка Java @Deprecated
аннотация. Чтобы использовать это, Вы просто предшествуете class, методу, или задействованному объявлению с "@Deprecated".
Используя @Deprecated
аннотация, чтобы осудить class, метод, или поле гарантирует, что все компиляторы выпустят предупреждения, когда код будет использовать тот элемент программы. Напротив, нет никакой гарантии, что все компиляторы будут всегда выпускать предупреждения, основанные на @deprecated
Тег Javadoc, хотя компиляторы Sun в настоящий момент делают так. Другие компиляторы, возможно, не выпускают такие предупреждения. Таким образом, использование @Deprecated
аннотация, чтобы генерировать предупреждения более переносима то доверие @deprecated
Тег Javadoc.
Кроме того, @Deprecated аннотация заставляет javadoc-сгенерированную документацию быть отмеченной "Осуждаемая" везде, где тот элемент программы появляется.
ОТМЕТЬТЕ: Осуждение применяется к классам и к отдельным методам или свойствам, не к их именам. Для единственного метода возможно осудить и неосудить перегрузки. Для неосуждаемого свойства возможно скрыть или переопределить осуждаемый, который удаляет осуждение. Как разработчик API, это - Ваша обязанность осудить переопределения осуждаемого метода, если фактически они должны быть осуждены.
Следующее является простым примером использования @Deprecated аннотации от java.lang.Thread
:
public class Thread implements Runnable { ... @Deprecated public final void stop() { synchronized (this) { ...
Можно использовать @deprecated
тег, чтобы заставить Javadoc показать элемент программы как осуждающийся. @deprecated
тег должен сопровождаться пространством или новой строкой. В абзаце после @deprecated
тегируйте, объясните, почему элемент был осужден и предлагает, что использовать вместо этого.
Javadoc генерирует специальный HTML, основанный на @deprecated
теги: это перемещает абзац после @deprecated
тегируйте к передней стороне описания, помещая это курсивом и предшествуя этому с предупреждением, "Примечание: foo осуждается", полужирным. Это также добавляет "Осуждаемый" полужирным к любым элементам индекса, упоминая осуждаемый объект.
Теговый абзац может быть пустым, но пустые абзацы осуждения являются невоспитанностью, потому что они не помогают пользователю фиксировать предупреждения, которые являются результатом осуждения. Включайте абзацы, отмеченные с @link
или @see
теги, которые обращаются к новым версиям той же самой функциональности. Это обычно - не хорошая идея упомянуть расписание для постепенного сокращения осуждаемого API; это - бизнес-решение, которое лучше всего передается другие пути.
Для получения дополнительной информации об использовании @deprecated
Тег Javadoc, см. Javadoc - Генератор Документации API Java.
Следующие примеры показывают, как использовать @deprecated
Тег Javadoc. Они также иллюстрируют @Deprecated
аннотация, чтобы подчеркнуть, что эти два должны использоваться вместе.
Вот пример наиболее распространенной формы осуждаемого метода (для Javadoc 1.2 и позже):
/** * @deprecated As of release 1.3, replaced by {@link #getPreferredSize()} */ @Deprecated public Dimension preferredSize() { return getPreferredSize(); }
Если перестройка API более чем переименовывала, осуждение может быть более сложным. Вот пример метода, от которого отрекаются:
/** * Delete multiple items from the list. * * @deprecated Not for public use. * This method is expected to be retained only as a package * private method. Replaced by * {@link #remove(int)} and {@link #removeAll()} */ @Deprecated public synchronized void delItems(int start, int end) { ... }