спецификации, руководства, описания, API

Как и Когда Осудить API

Что "Осуждаемый" Означает
Когда Осудить
Как Осудить
- Используя @Deprecated Аннотацию
- Используя @deprecated Javadoc Тег

Что "Осуждаемый" Означает

Вы, возможно, услышали термин, "самоуничижительный юмор," или юмор, который минимизирует важность динамика. Осуждаемый класс или метод походят на это. Это больше не важно. Это настолько незначительно, фактически, что больше недопустимо использовать это, так как это было заменено и может прекратить существование в будущем.

Java обеспечивает способ выразить осуждение, потому что, поскольку класс развивается, его API (прикладной программный интерфейс) неизбежно изменяется: методы переименовываются для непротиворечивости, новые и лучшие методы добавляются, и полевое изменение. Но такие изменения представляют проблему. Вы должны иметь в наличии старый API, пока разработчики не делают переход к новому, но Вы не хотите, чтобы они продолжали программировать к старому API.

Возможность осудить класс, метод, или задействованное поле решает проблему. Java поддерживает два механизма для осуждения: и аннотация, (поддерживаемый запуск с J2SE 5.0) и тег Javadoc (поддерживаемый с тех пор 1.1). Существующие звонки в старый API продолжают работать, но аннотация заставляет компилятор выпускать предупреждение, когда это находит ссылки на осуждаемые элементы программы. Тег Javadoc и связанные комментарии предупреждают пользователей против использования осуждаемого элемента и говорят им, что использовать вместо этого.

Когда Осудить

Когда Вы разрабатываете API, тщательно рассматриваете, заменяет ли он старый API. Если это делает, и Вы хотите поощрить разработчиков (пользователи API) переходить на новый API, то осуждаете старый API. Допустимые причины осудить API включают:

Это небезопасно, ошибочно, или очень неэффективно
Это уходит в будущем выпуске
Это поощряет плохо кодировать методы

Осуждение является разумным выбором во всех этих случаях, потому что оно сохраняет "обратную совместимость", поощряя разработчиков измениться на новый API. Кроме того, комментарии осуждения помогают разработчикам решить, когда переместиться в новый API, и так должны кратко упомянуть технические причины осуждения.

Не необходимо осудить отдельные задействованные поля (свойства) осуждаемого класса, если, конечно, Вы не хотите объяснить конкретный вопрос о свойстве.

Как Осудить

Запускаясь с J2SE 5.0, Вы осуждаете класс, метод, или поле при использовании @Deprecated аннотация. Дополнительно, можно использовать @deprecated Тег Javadoc говорит разработчикам, что использовать вместо этого.

Используя причины аннотации компилятор Java, чтобы генерировать предупреждения, когда осуждаемый класс, метод, или поле используются. Компилятор подавляет предупреждения осуждения, если осуждаемый элемент используется в пределах объекта, который непосредственно осуждается или используется в пределах того же самого наиболее удаленного класса или используется в объекте, который аннотируется, чтобы подавить предупреждение.

Вам строго рекомендуют использовать Javadoc @deprecated тег с соответствующими комментариями, объясняющими, как использовать новый API. Это гарантирует, что у разработчиков будет осуществимый миграционный путь от старого API до нового API. Для получения дополнительной информации см. Используя @deprecated Тег Javadoc.

ОТМЕТЬТЕ: Спецификация языка Java требует, чтобы компиляторы выпустили предупреждения когда классы, методы, или поля, отмеченные с @Deprecated аннотация используется. Компиляторы не требуются Спецификацией языка Java выпустить предупреждения когда классы, методы, или поля, отмеченные с @deprecated К тегу Javadoc получают доступ, хотя компиляторы Sun в настоящий момент делают так. Однако, нет никакой гарантии, что компилятор Sun будет всегда выпускать такие предупреждения.

Используя @Deprecated Аннотацию

J2SE 5.0 представляет новую функцию языка, названную аннотациями (также названный метаданными). Одна из встроенных аннотаций языка Java @Deprecated аннотация. Чтобы использовать это, Вы просто предшествуете классу, методу, или задействованному объявлению с "@Deprecated".

Используя @Deprecated аннотация, чтобы осудить класс, метод, или поле гарантирует, что все компиляторы выпустят предупреждения, когда код будет использовать тот элемент программы. Напротив, нет никакой гарантии, что все компиляторы будут всегда выпускать предупреждения, основанные на @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 тег, чтобы заставить 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) {
...
}

Свяжитесь с Нами