Спецификация Java Server Pages 1.2

JSP.10.1.1 Интерфейс Tag



Синтаксис


public interface Tag


Все Известные Субинтерфейсы: BodyTag, IterationTag


Описание

Это интерфейс простого обработчика тэга, который не хочет манипулировать своим содержимым. Интерфейс Tag определяет базовый протокол между обработчиком Tag и классом реализации JSP-страницы. Он определяет жизненный цикл и методы, вызываемые начальным и конечным тэгами.

Свойства


Интерфейс Tag специфицирует setter и getter-методы для основных свойств pageContext и parent. Объект реализации JSP-страницы вызывает setPageContext и setParent в этом порядке до вызова doStartTag() или doEndTag().


Методы

Есть две основные акции: doStartTag и doEndTag. После того как все соответствующие свойства инициализированы, методы doStartTag и doEndTag могут быть вызваны обработчиком тэга. Между этими вызовами принимается, что обработчик тэга имеет состояние, которое обязано сохраняться. После вызова doEndTag обработчик тэга доступен для последующих вызовов (и предполагается, что сохраняет свои свойства).


Жизненный цикл

Детали жизненного цикла описываются ниже диаграммой перехода, со следующими комментариями:

  • [1] Этот переход предназначен для выпуска долгоживущих данных. Не даётся никаких гарантий долговечности свойств.

    [2] Этот перенос происходит, если, и только если, тэг заканчивается нормально без вызова исключения.

  • [3] Заметьте, что, поскольку нет никаких гарантий статуса свойств, тэг, имеющий установленными какие-либо свойства по выбору/optional, может быть использован повторно, только если эти свойства устанавливаются в новое (известное) значение. Это значит, что обработчики тэгов могут использоваться только с тем же “AttSet” (набором установленных атрибутов).



  • Просмотрите интерфейс TryCatchFinally на предмет дополнительных деталей относительно обработки исключений и обслуживания ресурсов.

После того как все вызовы обработчика тэга выполнены, в нём вызывается метод release.

После вызова метода release, принимается, что все свойства, включая parent

и pageContext, устанавливаются в неспецифицированное значение/unspecified. Компилятор страницы гарантирует, что release() будет вызван в обработчике Tag, до того как обработчик будет освобождён для GC.


Пустые и Непустые Акции


Если файл TagLibraryDescriptor указывает, что акция обязана всегда быть пустой акцией, через <body-content> - “empty”, тогда метод doStartTag() обязан возвращать SKIP_BODY. В ином случае, метод doStartTag() может вернуть SKIP_BODY или EVAL_BODY_INCLUDE.

Если возвращён SKIP_BODY, тело, если имеется, не обсчитывается.

Если возвращён EVAL_BODY_INCLUDE, тело обсчитывается и "передаётся" текущему out/выводу.

JSP.10.1.1.1 Поля


public static final int EVAL_BODY_INCLUDE

  Вычисляет тело в существующем потоке out. Верное return-значение для doStartTag.

public static final int EVAL_PAGE

  Продолжить вычисление страницы. Верное return-значение для doEndTag().

public static final int SKIP_BODY

  Пропустить вычисление тела. Верное return-значение для doStartTag и doAfterBody.

public static final int SKIP_PAGE

  Пропустить оставшуюся часть страницы. Верное return-значение для doEndTag.

JSP.10.1.1.2 Методы


public int doEndTag()

Обрабатывает конечный тэг данного экземпляра. Этот метод вызывается объектом реализации JSP-страницы для всех обработчиков Tag. Этот метод будет вызываться после возвращения из doStartTag. Тело акции может или может не вычисляться, в зависимости от return-значения doStartTag.

Если этот метод возвращает EVAL_PAGE, остаток страницы продолжит вычисляться.

Если этот метод возвращает SKIP_PAGE, остаток страницы не вычисляется, и запрос выполняется. Если этот запрос был направлен или включён из другой страницы (или Servlet), выполняется вычисление только текущей страницы. JSP-контейнер будет ресинхронизировать любые значения переменных, которые обозначены таковыми в TagExtraInfo, после вызова doEndTag().

Вызывает:JspException, JspException

public int doStartTag()

Обрабатывает начальный тэг данного экземпляра. Этот метод вызывается объектом реализации JSP-страницы.

Метод doStartTag принимает, что свойства pageContext и parent установлены. Он также принимает, что любые свойства, экспонированные как атрибуты, также установлены. В момент вызова этого метода тело ещё не вычислено.

Этот метод возвращает Tag.EVAL_BODY_INCLUDE или Body-Tag.EVAL_BODY_BUFFERED для обозначения того, что тело акции должно быть повторно вычислено, или SKIP_BODY - для обозначения противоположного.




Если Tag возвращает EVAL_BODY_INCLUDE, результат вычисления тела (если имеется) включается в текущий “out” JspWriter, когда он появляется. а затем вызывается doEndTag().

BodyTag.EVAL_BODY_BUFFERED является единственно верным значением, если обработчик тэга реализует BodyTag.

JSP-контейнер будет ресинхронизировать любые значения переменных, которые обозначены как таковые в TagExtraInfo, после вызова doStartTag().

Вызывает: JspException, JspException

См. также: BodyTag

public Tag getParent()

Получает родителя (ближайшего внешнего/содержащего обработчика тэга) для данного обработчика тэга.

Метод getParent() может использоваться для навигации по структуре вложенного обработчика тэга во время прогона для взаимодействия специальных акций; например, метод find-AncestorWithClass() в TagSupport предоставляет подходящий способ выполнения этого.

В текущей версии спецификации имеется только один формальный способ указания на рассматриваемый тип обработчика тэга: его класс реализации, описанный в субэлементе tag-class элемента tag. Он разворачивается неформальным способом, давая разрешение автору библиотеки тэгов указывать рассматриваемый тип в описании субэлемента. Этот тип должен быть подтипом класса реализации обработчика тэга или void. Это дополнительное ограничение может быть обработано специализированным контейнером, который знает об этой специфической библиотеке тэгов, как в случае со стандартной библиотекой тэгов JSP.

public void release()

Вызывается для освобождения состояния/release state. Компилятор страницы гарантирует, что объект реализации JSP-страницы будет вызывать этот метод для всех обработчиков тэгов, но между ними может быть несколько вызовов doStartTag и doEndTag.

public void setPageContext(PageContext pc)

Устанавливает текущий контекст страницы. Этот метод вызывается объектом реализации JSP-страницы до вызова doStartTag().

Это значение *не* переустанавливается методом doEndTag() и обязано быть переустановлено явно реализацией страницы, если оно изменяется между вызовами doStartTag().

pc - Контекст страницы для данного обработчика тэга.

public void setParent(Tag t)

Устанавливает родителя (ближайшего внешнего обработчика тэга) для данного обработчика тэга. Вызывается объектом реализации JSP-страницы до вызова doStartTag().

Это значение *не* переустанавливается методом doEndTag() и обязано быть переустановлено явно реализацией страницы.

Параметры:

t - тег-родитель или null.


Содержание раздела