: Интерфейс Tag

Каталог документации / Раздел "Web мастеру, CGI, Perl, PHP, Apache" / Оглавление документа

Обзор

Пакет

Класс

Дерево

Не рекомендуются

Индекс

Справка

ПРЕДЫДУЩИЙ КЛАСС СЛЕДУЮЩИЙ КЛАСС

ФРЭЙМ БЕЗ ФРЭЙМОВ

РЕЗЮМЕ: ВНУТРЕННИЙ | ПОЛЕ | КОНСТРУКТОР | МЕТОД

ДЕТАЛИ: ПОЛЕ | КОНСТРУКТОР | МЕТОД

javax.servlet.jsp.tagext
Интерфейс Tag

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

public abstract interface Tag

Интерфейс простого обработчика тэга, который не манипулирует своим телом. Интерфейс 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, восстановлены в неспецифицированные значения. Компилятор страницы гарантирует, что release() будет вызван в обработчике Tag'а до освобождения обработчика в GC.

Пустая и Непустая Акция

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

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

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

Поле. Резюме.

static int EVAL_BODY_INCLUDE
          Вычисляет тело в существующем потоке out.

static int EVAL_PAGE
          Продолжить обсчёт страницы.

static int SKIP_BODY
          Пропустить вычисление тела.

static int SKIP_PAGE
          Пропустить остаток страницы.

Метод. Резюме.

int doEndTag ()
          Обработать конечный тэг данного экземпляра.

int doStartTag ()
          Обработать начальный тэг данного экземпляра.

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

void release ()
          Вызывается в обработчике Tag'а для освобождения состояния.

void setPageContext (PageContext pc)
          Устанавливает текущий контекст страницы.

void setParent (Tag t)
          Устанавливает родителя (ближайший содержащий обработчик тэга) данного обработчика тэга.

Поле. Детали.

SKIP_BODY

public static final int SKIP_BODY

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

EVAL_BODY_INCLUDE

public static final int EVAL_BODY_INCLUDE

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

SKIP_PAGE

public static final int SKIP_PAGE

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

EVAL_PAGE

public static final int EVAL_PAGE

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

Метод. Детали.

setPageContext

public void setPageContext(PageContext pc)

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

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

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

setParent

public void setParent(Tag t)

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

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

Параметры:: t - родительский тэг/tag или null.

getParent

public Tag getParent()

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

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

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

doStartTag

public int doStartTag()
               throws JspException

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

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

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

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

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

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

Вызывает:: JspException
См. также:: BodyTag

doEndTag

public int doEndTag()
             throws JspException

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

Этот метод будет вызываться после возвращения из doStartTag. Тело акции может или может не быть вычисленным, в зависимости от return-занчения метода doStartTag.

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

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

Вызывает:: JspException

release

public void release()

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