The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

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

Глава JSP.7

Расширения Тэгов


В этой главе рассматриваются возможности библиотеки тэгов по введению новых акций в JSP-страницу.

Сюда относятся поддержка переносимости, механизм проверки и поддержка утилит авторизации.
 

Здесь дан также концептуальный обзор библиотеки тэгов. Рассмотрен Tag Library Descriptor/Дескриптор Библиотеки Тэгов и директива taglib. Детальное описание задействованных API даётся в Главе JSP.10.

JSP.7.1 Введение

Библиотека Тэгов/Tag Library абстрагирует функциональность, используемую JSP-страницей, определяя специализированный (суб)язык, что делает возможным более естественно использовать эту функциональность в JSP-страницах.


Акции, вводимые Библиотекой Тэгов, могут использоваться авторами JSP-страниц явно при авторизации - вручную, или неявно - через использование утилит авторизации. Библиотеки Тэгов особенно применимы в утилитах авторизации, поскольку позволяют сосредоточиться на главном, а параметры, указанные в экземпляре акции, сами передают информацию утилите.


Акции, которые предоставляются из библиотеки тэгов, импортируются в JSP-страницу путём использования директивы taglib. Они доступны для использования на странице через префикс, заданный этой директивой.

Акции могут создавать новые объекты, которые могут затем передаваться другим акциям или обрабатываться программно элементами скриптинга в JSP-странице.


Библиотеки тэгов являются переносимыми: они могут использоваться на любой JSP-странице вне зависимости от того, какой язык скриптинга используется на этой странице.


Механизм развёртывания тэгов содержит информацию для:

Библиотека Тэгов описывается через Tag Library Descriptor ( TLD)/Дескриптор Библиотеки Тэгов, документ XML, рассматриваемый ниже.

JSP.7.1.1 Цели

Механизм расширения/развёртывания тэгов преследует следующие цели:

JSP.7.1.2 Обзор

Процессинг/обработка JSP-страницы концептуально состоит из следующих этапов:

Parsing\Разбор

JSP-страницы могут авторизоваться с использованием двух различных синтаксисов: JSP- и XML-синтаксиса. Семантика и проверка страницы  с синтаксисом JSP даётся со ссылкой на семантику и проверку эквивалентного документа с синтаксисом XML.


Первый этап - разбор JSP-страницы. Разбираемая страница разворачивается путём выполнения директив include. Информация из TLD используется на данном этапе и включает идентификацию специальных тэгов так, что происходит некоторая обработка директивами taglib на JSP-странице.

Validation\Проверка

Библиотеки Тэгов в XML-документе обрабатываются в порядке их появления на странице. Каждая библиотека проверяется на наличие класса-проверщика/validator class. Если он имеется, весь документ становится доступным её методу validate() как объект PageData. Если JSP-контейнер поддерживает jsp:id, то эта информация может использоваться для предоставления информации оместонахождении ошибок. Каждый специальный тэг в библиотеке проверяется на наличие класса TagExtraInfo. Если класс имеется, вызывается метод isValid().

Translation\Трансляция

Далее документ XML обрабатывается для создания класса реализации JSP-страницы. В ходе этого процесса могут создаваться переменные скриптинга.

Каждая специальная акция будет предоставлять информацию о переменных, либо статично - в TLD, либо более гибко - через использование метода getVariableInfo класса TagExtraInfo.

Execution\Выполнение

После того как класс реализации JSP-страницы ассоциирован с JSP-страницей, он будет рассматриваться как любой другой Servlet-класс: запросы будут направляться экземплярам этого класса. На этапе прогона экземпляры обработчиков будут создаваться, а их методы будут вызываться.

JSP.7.1.2.1 Обработчики Тэгов

Семантика специфики специальной акции в библиотеке тэгов описывается через класс обработчика тэга, который обычно инстанциируется на этапе прогона классом реализации JSP-страницы.

Если библиотека тэгов известна JSP-контейнеру (Раздел JSP.7.3.9), это контейнер может использовать альтернативные реализации, пока семантика сохраняется.


Обработчик тэга это класс Java, реализующий интерфейс Tag, IterationTag или BodyTag и являющийся представлением специальной акции на этапе прогона.

Класс реализации JSP-страницы инстанциирует класс обработчика тэга или использует существующий объект обработчика тэга для каждой акции на JSP-странице. Объект обработчика это Java-объект, реализующий интерфейс javax.servlet.jsp.tagext.Tag. Объект обработчика отвечает за взаимодействие JSP-страницы и дополнительных серверных объектов/server-side objects.


Существуют три главных интерфейса: Tag, IterationTag и BodyTa.

Использование интерфейсов упрощает создание обработчика тэга из существующего Java-объекта.

Имеются также два класса поддержки, которые могут использоваться в качестве базовых классов: TagSupport и BodyTagSupport.

В JSP 1.2 имеется новый интерфейс, помогающий поддерживать целостность данных и обслуживать ресурсы при возникновении исключительных ситуаций.

Интерфейс TryCatchFinally может добавляться в класс, реализующий любой интерфейс: Tag, IterationTag или BodyTag.

JSP.7.1.2.2 Прослушиватели/Listeners Событий

Библиотека тэгов может содержать классы, которые являются прослушивателями событий (см. спецификацию Servlet 2.3). Классы-прослушиватели перечисляются в дескрипторе библиотеки тэгов, и JSP-контейнер автоматически инстанциирует и регистрирует их. Контейнер нужен для размещения всех TLD-файлов (см. в Разделе JSP.7.3.1 детали об их идентификации), чтения их элементов-прослушивателей и рассмотрения прослушивателей событий как расширений этих же прослушивателей, перечисленных в web.xml. Порядок регистрации прослушивателей не определён, но они регистрируются до старта приложения.

JSP.7.1.3 Простые Примеры

В качестве примеров мы рассмотрим прототипы использования развёртывания тэгов, кратко остановившись на преимуществах этих механизмов.

JSP.7.1.3.1 Простые Акции


Простейшая акция просто делает что-нибудь, возможно - с параметрами, для модификации этого "что-нибудь" и улучшения использования. Акция этого типа может быть реализована через обработчик тэга, который реализует интерфейс Tag. Этот обработчик тэга должен использовать только метод doStartTag(), который вызывается при обнаружении начального/стартового тэга. Он имеет доступ к атрибутам тэга и информации о статусе JSP-страницы. Эта информация передаётся объекту Tag через вызовы setter-метода, прежде чем будет вызван doStartTag().


Поскольку часто встречаются простые акции с пустым телом, Tag Library Descriptor может использоваться для указания на то, что данный тэг всегда предполагается как пустой. Такая индикация позволяет лучше проверять ошибки на этапе трансляции и даёт код более высокого качества в классе реализации JSP-страницы.

JSP.7.1.3.2Акции с Телом/Body


Другой набор простых акций требует, чтобы что-нибудь происходило, когда обнаруживается начальный тэг и когда обнаруживается конечный тэг. Интерфейс Tag может также использоваться для этих акций. Метод doEndTag() похож на метод doStartTag(), за исключением того, что он вызывается при обнаружении конечного тэга акции. Результат вызова doEndTag показывает, вычисляется ли оставшаяся часть страницы, или нет.

JSP.7.1.3.3Условия


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

JSP.7.1.3.4 Итерации
 

Для итераций необходим интерфейс IterationTag. Метод doAfterBody() вызывается для определения необходимости повторного обсчёта тела.

JSP.7.1.3.5 Акции, Обрабатывающие Своё Тело


Рассмотрим акцию, которая обсчитывает своё тело несколько раз, создавая поток данных ответа. Для этого используется протокол IterationTag. Если результат повторной интерпретации будет в дальнейшем обрабатываться, по каким-то соображениям, в том числе и просто может быть отброшен, то нам нужен способ "отвлечь" вывод/output от повторных обсчётов. Это выполняется путём создания объекта BodyContent и использования метода setBodyContent(), который является частью интерфейса BodyTag. BodyTag также предоставляет метод doInitBody(), вызываемый после setBodyContent() и до первого обсчёта тела, что является удобным моментом для взаимодействия с телом/body.

JSP.7.1.3.6 Кооперирующиеся Акции


Кооперирующиеся акции могут предлагать наилучший способ описания необходимой функциональности. Например, одна акция может использоваться для описания информации, приводящей к созданию серверного объекта, а другая может использовать этот объект где-либо на этой странице. Эти акции могут кооперироваться явно через переменные скриптинга: одна акция создаёт объект и даёт ему имя; другая ссылается на объект по имени.

Переменные скриптинга кратко обсуждаются далее.

Две акции могут также кооперироваться неявно. Гибкий и удобный механизм кооперирования акций использует вложение структуры акций для описания области видимости. В данной спецификации это поддерживается через предоставление обработчика каждого тэга и обработчика тэга его родителя (если имеется) через вызов метода setParent(). Статический метод findAncestorWithClass в TagSupport может затем использоваться для локализации обработчика тэга и, после локализации, для выполнения операций в обработчике тэга.
 

JSP.7.1.3.7 Акции, Определяющие Переменные Скриптинга


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

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

На этапе запроса обработчик тэга будет ассоциировать объекты с переменными скриптинга через объект pageContext. Транслятор JSP-страницы отвечает за то, чтобы автоматически снабжать кодом, необходимым для выполнения "синхронизации" между значениями pageObject и переменными скриптинга.

JSP.7.2Библиотеки Тэгов

Библиотека тэгов это коллекция акций, инкапсулирующая некоторую функциональность, используемую в JSP-странице. Библиотека тэгов становиться доступной JSP-странице через использование директивы taglib, которая идентифицирует эту библиотеку тэгов с помощью URI (Universal Resource Identifier/Универсальный Идентификатор Ресурсов).

URI, идентифицирующий библиотеку тэгов, может быть любым верным URI, который может использоваться для уникальной идентификации семантики библиотеки тэгов. URI, идентифицирующий библиотеку тэгов, ассоциируется с файлом Tag Library Description (TLD) и с классами обработчиков тэгов, как указано далее в Разделе JSP.7.3.

JSP.7.2.1 Упакованные Библиотеки Тэгов

Утилиты авторизацииJSP-страниц и JSP-контейнеры должны принимать библиотеку тэгов, упакованную в JAR-файл. При поставке в JSP-контейнере применяются стандартные соглашения по JAR, описанные в спецификации Servlet 2.3, включая соглашения для зависимостей расширений.

Упакованные библиотеки тэгов обязаны иметь как минимум один файл дескриптора библиотеки тэгов.

Спецификация JSP 1.1 разрешала только один TLD, в META-INF/taglib.tld, а в JSP 1.2 разрешены несколько библиотек тэгов. См. в Разделе JSP.7.3.1 об идентификации TLD.

JSP.7.2.2 Размещение Java-Классов

Библиотека тэгов содержит классы для инстанциации на этапе трансляции и классы для инстанциации на этапе запроса. Первые содержат классы TagLibraryValidator и TagExtraInfo. Вторые содержат классы обработчика тэгов и прослушивателя событий.

Применяются обычные соглашения по классам Java: как часть web-приложения они обязаны находиться внутри либо JAR-файла в директории WEB-INF/lib, либо в директории WEB-INF/classes. JAR, содержащий упакованные библиотеки тэгов, может быть сброшен в директорию WEB-INF/ lib, чтобы сделать его классы доступными на этапе запроса (а также на этапе трансляции, см. Раздел JSP.7.3.7).

Отображение между URI и TLD объясняется далее.

JSP.7.2.3 Директива Библиотеки Тэгов

Директива taglib в JSP-страниц объявляет, что эта страница использует библиотеку тэгов, уникально идентифицирует эту библиотеку через URI и ассоциирует префикс тэга с использованием акций библиотеки.


JSP-контейнер отображает URI, используемый в директиве taglib, в Tag Library Descriptor/Дескриптор Библиотеки Тэгов за два шага: сначала разрешает URI в путь ресурса TLD, а затем получает TLD-объект из пути ресурса TLD. Если JSP-контейнер не может локализовать путь ресурса TLD для данного URI, должна происходить фатальная ошибка трансляции. Аналогично, фатальной ошибкой трансляции является развёртывание/разрешение значения атрибута uri в два различных пути ресурса TLD. Для директивы taglib будет фатальной ошибкой, если она появится после акций, использующих префикс, вводимый ею.

JSP.7.3 Дескриптор Библиотеки Тэгов

Дескриптор Библиотеки Тэгов/Tag Library Descriptor (TLD) это XML-документ, который описывает библиотеку тэгов. TLD библиотеки тэгов используется JSP-контейнером для интерпретации страниц, которые содержат директивы taglib, ссылающиеся на эту библиотеку тэгов. TLD используется также утилитами авторизации/создания JSP-страниц, которые будут генерировать JSP-страницы, использующие библиотеку, и авторами, делающими то же самое вручную.


TLD содержит документацию о библиотеке в целом и о каждом из её тэгов, информацию о версии JSP-контейнера и о библиотеке и информацию о каждой акции, определённой в этой библиотеке тэгов.


TLD может именовать класс TagLibraryValidator, который может проверять соответствие JSP-страницы набору ограничений, ожидаемых этой библиотекой тэгов.


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

Каждый верный атрибут содержит указания на то, является ли он мандатным, может ли он принимать выражения времени запроса, и дополнительную информацию.

Файл TLD используется для предоставления информации о библиотеке тэгов. Он может быть прочитан утилитами без инстанциации объектов или классов загрузчика.


Наш подход соответствует соглашениям в других технологиях J2EE.

ОТД для дескриптора библиотеки тэгов организовано так, что нужные элементы имеют необязательный атрибут ID. Этот атрибут может использоваться другими документами, типа документации продавца, для предоставления аннотаций по информации TLD.

JSP.7.3.1 Идентификация Дескрипторов Библиотек Тэгов

Файл дескриптора библиотеки тэгов (ДБТ) именуется с использованием расширения ".tld", которое указывает, что это файл ДБТ.

Если размещены внутри файла JAR, файлы ДБТ обязаны находиться в директории META-INF или в её субдиректории.

При размещении непосредственно в web-приложении файлы ДБТ обязаны всегда находиться в директории WEB-INF или в одной из её субдиректорий.


Документ ОТД для ДБТ это  "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd".

JSP.7.3.2 Путь Ресурса TLD

URI в директиве taglib отображается в контексте относительного пути (это обсуждается в Разделе JSP.2.2.1). Контекст относительного пути это URL без указания компонентов - протокола и хоста, начинающийся с "/" и называемый путь ресурса TLD.

Путь ресурса TLD интерпретируется относительно корневой директории web-приложения и должен указывать непосредственно на TLD-файл или на JAR-файл, содержащий TLD-файл в META-INF/taglib.tld.

Если путь ресурса TLD - не один из этих вариантов, будет возникать фатальная ошибка трансляции.

URI, описывающий библиотеку тэгов, отображается в путь ресурса TLD через отображение taglib, и в интерпретацию крайнего варианта, которая используется, если отображение не содержит URI.

Отображение taglib строится из явного отображения taglib в web.xml (описано в Разделе JSP.7.3.3), которое расширяется неявными вхождениями, выведенными из упакованных библиотек тэгов в web-приложение (описано в Разделе JSP.7.3.4), и неявными вхождениями, известными JSP-контейнеру.

Интерпретация варианта "на крайний случай" нацелена на случайное использование своего механизма, как в цикле разработки Web-Приложения: тогда URI интерпретируется как непосредственный путь к TLD (см. Раздел JSP.7.3.6.2).

JSP.7.3.3 Отображение taglib в web.xml

Файл web.xml может содержать явное отображение taglib между путями ресурсов URI и TLD, описанное с использованием элементов taglib Дескриптора Публикации Web-Приложения в файле WEB-INF/web.xml, как описано в спецификации Servlet 2.3 и в  http://java.sun.com/j2ee/dtds/web-app_2_3.dtd.
 

Элемент taglib содержит два субэлемента: taglib-uri и taglib-location.


<taglib>
 

taglib является субэлементом web-app:


<!ELEMENT web-app .... taglib* .... >


Элемент taglib предоставляет информацию о библиотеке тэгов, которая используется JSP-страницей внутри Web-Приложения.


Элемент taglib содержит два субэлемента и один атрибут:
 

<!ELEMENT taglib ( taglib-uri, taglib-location )>

<!ATTLIST taglib id ID #IMPLIED>


<taglib-uri>


Элемент taglib-uri описывает URI, идентифицирующий библиотеку тэгов, используемую в web-приложении.


<!ELEMENT taglib-uri (#PCDATA)>

PCDATA ::= спецификация URI.


Телом элемента taglib-uri может быть абсолютный или относительный URI, как указано в Разделе JSP.2.2.1.

В web.xml не должно быть входов с тем же значением taglib-uri.


<taglib-location>


taglib-location
содержит место размещения (в качестве ресурса) Файла Дескриптора Библиотеки Тэгов для данной библиотеки тэгов.
 

<!ELEMENT taglib-location (#PCDATA)>

PCDATA ::= размещение ресурса (как указано в Разделе JSP.2.2.1); где можно найти файл TLD.

JSP.7.3.4 Неявное Отображение Входов из TLD

Отображение taglib, описанное в web.xml, расширяется за счёт новых вхождений, извлекаемых из файлов TLD Web-Приложения.

Новые вхождения обсчитываются так:

Этот механизм предоставляет автоматическое отображение URI в TLD, а также поддержку нескольких TLD в одном JAR-пакете.

Обратите внимание, что эта функциональность не требует явного именования места размещения TLD-файла, которого мог бы потребовать механизм типа протокола jar:.

Заметьте также, что этот механизм не добавляет дублирующие вхождения.

JSP.7.3.5 Неявное Отображение Входов из Контейнера

Контейнер также может добавлять дополнительные вхождения к отображению taglib. Как и в предыдущем случае, входы добавляются только для тех URI, которые не представлены в отображении. Концептуально эти вхождения соответствуют TLD, описывающему эти библиотеки тэгов. Эти неявные вхождения отображения соответствуют библиотекам, которые известны контейнеру, который отвечает за предоставление их реализации, либо через обработчики тэгов, либо через механизм, описанный в Разделе JSP.7.3.9.

JSP.7.3.6 Определение Ресурса Пути TLD

Путь ресурса TLD может быть определён из атрибута uri директивы taglib, как показано ниже. В последующем разъяснении "абсолютным URI" называется такой, который начинается с названия протокола и имени хоста, а "относительный URI" даётся так, как указано в Разделе 2.5.2, т.е. без протокола и имени хоста.

Все шаги описаны так, будто они выполнялись, но реализация может использовать различные стратегии для получения того же результата.

JSP.7.3.6.1 Вычисление Размещения TLD


Карта taglib, генерированная в Разделах JSP.7.3.3, JSP.7.3.4 и JSP.7.3.5, может содержать одно или более вхождений <taglib></taglib>. Каждое такое вхождение идентифицируется по TAGLIB_URI, который является значением субэлемента <taglib-uri>. Этот TAGLIB_URI может быть абсолютным URI, либо относительным URI, который начинается (или не начинается) с "/".

Каждое вхождение определяет также TAGLIB_LOCATION следующим образом:

JSP.7.3.6.2 Вычисление Ресурса Пути TLD
 

Здесь показано, как разрешить директиву taglib для вычисления пути ресурса TLD на базе значения атрибута uri директивы taglib.

JSP.7.3.6.3 Рассмотрение Использования
 

Явное отображение web.xml предоставляет явное описание библиотек тэгов, используемых в web-приложении.

Неявное отображение из TLDs означает, что JAR-файл, реализующий библиотеку тэгов, может быть раскрыт и использован непосредственно через его постоянные URI.


Использование относительного URI в карте taglib даёт возможность задания очень кратких имён в директиве taglib. Например, если карта:


<taglib>

<taglib-uri>/myPRlibrary</taglib-uri>

<taglib-location>/WEB-INF/tlds/PRlibrary_1_4.tld</taglib-location>

</taglib>
 

тогда она может использоваться как:
 

<%@ taglib uri="/myPRlibrary" prefix="x" %>


Наконец, правило отката/fallback (запасной вариант) позволяет директиве taglib ссылаться непосредственно к TLD. Это чрезвычайно хорошо подходит для ускоренной разработки в ущерб гибкости и экономии.

Например, в предыдущем случае оно делает возможным:
 

<%@ taglib uri="/WEB-INF/tlds/PRlibrary_1_4.tld" prefix="x" %>

JSP.7.3.7 Загрузчик Классов Времени Трансляции

Набор классов, доступных во время трансляции, - тот же, что и для времени прогона/runtime: классы основной платформы Java, в JSP-контейнере и в файлах классов в WEB-INF/classes, в JAR-файлах в WEB-INF/lib и, косвенно, классы, обозначенные через использование атрибута class-path в файле-манифесте META-INF/MANIFEST этих JAR-файлов.

JSP.7.3.8 Ассемблирование Web-Приложения

Как часть процесса ассемблирования web-приложения, Application Assembler будет создавать директорию WEB-INF/  с соответствующими субдиректориями lib/ и classes/, размещать JSP-страницы, Servlet-классы, вспомогательные классы и библиотеки классов в соответствующих местах и создаёт файл WEB-INF/web.xml, который связывает всё это воедино.

Библиотеки тэгов, полученные в стандартном формате JAR, могут быть помещены непосредственно в WEB-INF/lib. Это автоматически добавляет все TLDs из JAR-файла, делая их URI их элементами <uri>, видимыми отображению URI в TLD.

Ассемблер может создавать вхождения taglib в web.xml для каждой из библиотек, которые им используются.
Частью ассемблирования (и позже - публикации) может быть создание и/или изменение информации, специализирующей библиотеку тэгов; см. Раздел JSP.7.6.3.

JSP.7.3.9 Хорошо Известные URI

JSP-контейнер может "знать" некоторые URI и может предоставлять альтернативные реализации для библиотек тэгов, описанных этими URI, но пользователь обязан видеть поведение как таковое, описанное описанием требуемой, переносимой библиотеки тэгов, указанной в URI.

JSP-контейнер обязан всегда использовать отображение, специфицированное для URI, в дескрипторе публикации web.xml, если он имеется. Если публикатор хочет использовать платформозависимую реализацию хорошо известного URI, отображение такого URI должно быть удалено во время публикации.

JSP.7.4 Формат Дескриптора Библиотеки Тэгов

В этом разделе описано ОТД (Определение Типа Данных), для JSP версии 1.2, Дескриптора Библиотеки Тэгов/Tag Library Descriptor. Версия JSP 1.2 содержит информацию, дополнившую версию JSP 1.1, а также некоторые изменения в именах элементов, сделанные для улучшения совместимости с другими спецификациями. Формат TLD в 1.1 обязан приниматься контейнерами JSP 1.2.

Нотация


<!NOTATION WEB-JSPTAGLIB.1_2 PUBLIC "-//Sun Microsystems, Inc.//DTD

JSP Tag Library 1.2//EN">


<taglib>


Элемент taglib это корень/root документа. taglib имеет два атрибута.


<!ATTLIST taglib

id

ID

#IMPLIED

xmlns

CDATA

#FIXED

"http://java.sun.com/JSP/TagLibraryDescriptor"

>
 

Элемент taglib имеет также различные субэлементы, которые определяют:

tlib-version версию реализации библиотеки тэгов
jsp-version мандатную версию спецификации JSP, от которой зависит библиотека тэгов
short-name простое короткое имя по умолчанию, которое может использоваться утилитой авторизации JSP-страниц для создания имён с мнемоническими значениями; например, it может использоваться как предпочтительное значение префикса в директивах taglib
uri URI, уникально идентифицирующий эту taglib
display-name элемент display-name, содержащий краткое имя, которое предназначается для отображения утилитами
small-icon необязательная маленькая иконка, которая может использоваться утилитами
large-icon необязательная большая иконка, которая может использоваться утилитами
description строка, описывающая "use/использование" этой taglib
validator необязательная информация класса TagLibraryValidator
listener необязательная спецификация прослушивателя событий

<!ELEMENT taglib

(tlib-version, jsp-version, short-name, uri?, display-name?, small-icon?, large-icon? description?, validator?, listener*, tag+)>


<tlib-version>
 

Описывает версию (номер) библиотеки тэгов.


Синтаксис:


<!ELEMENT tlib-version (#PCDATA)>

#PCDATA ::= [0-9]*{ "."[0-9] }0..3


<jsp-version>


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


Синтаксис:
 

<!ELEMENT jsp-version (#PCDATA)>

#PCDATA ::= [0-9]*{ "."[0-9] }0..3.


<short-name>


Определяет простое краткое имя, которое может использоваться утилитами авторизации JSP-страниц для создания имён с мнемоническим значением; например, it может использоваться как предпочтительное значение префикса в директивах taglib и/или для создания префиксов для ID'ов. Не используйте пробелы и не начинайте с цифры и символа подчёркивания.


Синтаксис:


<!ELEMENT short-name (#PCDATA)>

#PCDATA ::= NMTOKEN


<uri>


Определяет публичный URI, уникально идентифицирующий данную версию библиотеки тэгов.


<!ELEMENT uri (#PCDATA)>


<description>


Определяет произвольную текстовую строку, описывающую библиотеку тэгов, переменную, атрибут или проверщик.


<!ELEMENT description (#PCDATA)>


<validator>


Определяет необязательный TagLibraryValidator, который может использоваться для проверки возможности использования JSP-страницей этой библиотеки тэгов. Проверщик может иметь некоторые необязательные параметры инициализации.


validator
может иметь несколько субэлементов, определяющих:

validator-class класс, реализующий javax.servlet.jsp.tagext.TagLibraryValidator
init-param необязательные параметры инициализации
description необязательное описание проверщика

Синтаксис элемента таков:


<!ELEMENT validator (validator-class, init-param*, description?)>


<validator-class>


Определяет класс необязательного TagLibraryValidator'а.


<!ELEMENT validator-class (#PCDATA)>


<init-param>


Определяет параметр инициализации.

init-param может иметь несколько субэлементов, определяющих:

param-name имя параметра
param-value значение параметра
description необязательное описание параметра

Синтаксис элемента:


<!ELEMENT init-param (param-value, param-value, description?)>


<param-name>


Имя параметра.


<!ELEMENT param-name (#PCDATA)>


<param-value>


Значение параметра.


<!ELEMENT param-value (#PCDATA)>


<listener>


Определяет необязательный объект прослушивателя событий, инстанциируемый и регистрируемый автоматически.


<!ELEMENT listener (listener-class)>


<listener-class>


Элемент listener-class объявляет класс в приложении, который обязан быть зарегистрирован как компонент прослушивателя web-приложения. См. детали в спецификации Servlet 2.3.


<!ELEMENT listener-class (#PCDATA)>


<tag>


tag
определяет акцию в данной библиотеке тэгов.


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


Элемент tag имеет один атрибут:


<!ATTLIST tag id ID #IMPLIED>


tag
может иметь несколько субэлементов, определяющих:

name уникальное имя акции
tag-class класс обработчика тэга, реализующий javax.servlet.jsp.tagext.Tag
tei-class необязательный подкласс javax.servlet.jsp.tagext.TagExtraInfo
body-content тип содержимого тела
display-name краткое имя, предназначенное для отображения утилитами
small-icon необязательная маленькая иконка, которая может использоваться утилитами
large-icon необязательная большая иконка, которая может использоваться утилитами
description необязательная специфическая информация тэга
variable необязательная информация переменной скриптинга
attribute все атрибуты этой акции
example необязательный пример использования этого тэга

Синтаксис элемента:
 

<!ELEMENT tag

(name, tag-class, tei-class?, body-content?, display-name?, small-icon?, large-icon?, description?, variable*, attribute*, example?)>


<tag-class>


Определяет класс реализации для этой специальной акции. Класс обязан реализовывать интерфейс javax.serlvet.jsp.tagext.Tag. Этот элемент необходим.


Синтаксис:


<!ELEMENT tag-class (#PCDATA)>

#PCDATA ::= полное квалифицированное имя Java-класса


<tei-class>


Определяет субкласс javax.servlet.jsp.tagext.TagExtraInfo для данного тэга. Это необязательный элемент.


Синтаксис:


<!ELEMENT tei-class (#PCDATA)>

#PCDATA ::= полное квалифицированное имя Java-класса


<body-content>


Предоставляет подсказку о содержимом тела данной акции. В первую очередь предназначен для использования утилитами компоновки/создания страниц.


Имеются три специфицированных на данный момент значения:

tagdependent Тело акции передаётся без изменений для интерпретации самим обработчиком тэга и написано большей частью на другом "language", например, встроенные операторы SQL. Тело акции может быть пустым. Никакое закавычивание не выполняется.
JSP Тело акции содержит элементы, использующие синтаксис JSP. Тело акции может быть пустым.
empty Тело акции обязано быть пустым.

Значение по умолчанию - "JSP".


Синтаксис:


<!ELEMENT body-content (#PCDATA)>

#PCDATA ::= tagdependent | JSP | empty.


Значения зависят от регистра.


<display-name>


Элементы display-name содержат краткое имя, которое предназначено для отображения утилитами.


Синтаксис:


<!ELEMENT display-name (#PCDATA)>


<large-icon>


Элемент large-icon содержит имя файла, содержащего большое (32 x 32) изображение-иконку. Имя файла это путь в библиотеке тэгов относительно размещения TLD. Изображение обязано быть в формате JPEG или GIF, а имя файла обязано заканчиваться суффиксом ".jpg" или ".gif", соответственно. Эта иконка может использоваться утилитами.


Синтаксис:


<!ELEMENT large-icon (#PCDATA)>


<small-icon>


Элемент small-icon содержит имя файла, содержащего маленькое (16 x 16) изображение-иконку. Имя файла это путь в библиотеке тэгов относительно размещения TLD. Изображение обязано быть в формате JPEG или GIF, а имя файла обязано заканчиваться суффиксом ".jpg" или ".gif", соответственно. Эта иконка может использоваться утилитами.


Синтаксис:


<!ELEMENT small-icon (#PCDATA)>


<variable>


Предоставляет информацию о переменных скриптинга, определённых этим тэгом. Для тэга будет ошибкой (времени трансляции), если он имеет один или более субэлементов-переменных, имеющих класс TagExtraInfo, который возвращает ненулевой объект.

 

Субэлементы-переменные имеют форму:

name-given постоянное/константное имя переменной
name-from-attribute имя атрибута, чьё значение (на этапе трансляции) даст имя переменной. Необходимо наличие одного из субэлементов: name-given или name-from-attribute
variable-class имя класса переменной. По умолчанию java.lang.String
declare объявлена переменная или нет. По умолчанию true
scope область видимости определённой переменной скриптинга. По умолчанию NESTED
description необязательное описание переменной

Синтаксис:

 

<!ELEMENT variable

((name-given | name-from-attribute), variable-class?, declare?, scope?, description?)>


<name-given>


Имя переменной скриптинга. Необходимо наличие name-given или name-from-attribute.


Синтаксис:


<!ELEMENT name-given (#PCDATA)>


<name-from-attribute>


Имя атрибута, чьё значение (на этапе трансляции) даст имя переменной. Необходимо наличие одного из субэлементов: name-given или name-from-attribute.


Синтаксис:


<!ELEMENT name-from-attribute (#PCDATA)>


<variable-class>


Необязательное имя класса переменной скриптинга. По умолчанию java.lang.String.


Синтаксис:


<!ELEMENT class (#PCDATA)>


<declare>


Объявлена переменная скриптинга или нет. См. TagExtraInfo. Это элемент необязателен, и установлен по умолчанию в "true".


Синтаксис:


<!ELEMENT declare #PCDATA)>

#PCDATA ::= true | false | yes | no


<scope>


Область видимости переменной скриптинга. См. TagExtraInfo. Это элемент необязателен, и установлен по умолчанию в "NESTED".


Синтаксис:


<!ELEMENT scope #PCDATA)>

#PCDATA ::= NESTED | AT_BEGIN | AT_END


<attribute>


Предоставляет информацию об атрибуте данной акции. Atribute определяет атрибут id для внешнего связывания.


<!ATTLIST attribute id ID#IMPLIED>
 

Субэлементы attribute'а имеют форму:

name имя атрибута (необходим)
required необходимо или не обязательно наличие атрибута (по выбору)
rtexprvalue может ли значение атрибута динамически вычисляться во время прогона выражением скриптлета (по выбору)
type тип значения атрибута (по выбору)
description необязательное описание атрибута

Синтаксис:


<!ELEMENT attribute (name, required?,rtexprvalue?, type?, description?)>


<name>


Определяет каноническое имя определяемого тэга или атрибута.


Синтаксис:


<!ELEMENT name (#PCDATA)>

#PCDATA ::= NMTOKEN


<required>


Определяет, является содержащий вложение/nesting атрибут required/необходимым или optional/"по выбору".


Синтаксис:


<!ELEMENT required (#PCDATA)>

#PCDATA ::= true | false | yes | no


Если отсутствует, то по умолчанию "false", т.е. это атрибут optional.


<rtexprvalue>


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


Синтаксис:


<!ELEMENT rtexprvalue (#PCDATA)>

#PCDATA ::= true | false | yes | no


Если отсутствует, по умолчанию - "false", т.е. атрибут имеет статическое/static значение.


<type>


Определяет тип Java значения атрибута. Для литеральных значений (rtexprvalue = false) тип всегда - java.lang.String. Если rtexprvalue установлен в true, тогда type определяет тип возвращаемого значения, ожидаемый от любого выражения скриптлета, специфицированного как значение этого атрибута.

Значение данного атрибута должно совпадать со значением свойства основного компонента JavaBean.


Синтаксис:

<!ELEMENT type (#PCDATA)>

#PCDATA ::= полное квалифицированное имя Java-класса - тип результата


Пример:


<type> java.lang.Object </type>


<example>


Содержимое этого элемента предназначается в качестве примера использования тэга. Этот элемент не интерпретируется JSP-контейнером и не воздействует на семантику тэга.


<!ELEMENT example (#PCDATA)>

JSP.7.5 Проверка

Есть несколько причин, почему структура JSP-страницы должна соответствовать некоторым правилам проверки:

Проверка может выполняться на этапе трансляции или на этапе запроса. Обычно проверка на этапе трансляции даёт больше информации, и спецификация JSP 1.2 предоставляет очень гибкий механизм проверки на этапе трансляции.

JSP.7.5.1 Механизмы Времени/Этапа Трансляции

Определённая проверка на этапе трансляции проводится в Tag Library Descriptor (TLD). В некоторых случаях для предоставления поддержки этой информации необходимо наличие класса TagExtraInfo.

JSP.7.5.1.1 Информация Атрибута

Tag Library Descriptor содержит базовую синтаксическую информацию. Атрибуты описываются с включением его имени, являются ли они необязательными или мандатными и принимают ли они выражения времени запроса. Кроме того, элемент bodycontent может использоваться для указания на то, что акция обязаны быть пустой.

Все ограничения, описанные в TLD, обязаны форсироваться. Автор библиотеки тэгов может принять как данное, что экземпляр обработчика тэга соответствует акции, которая удовлетворяет всем ограничениям, указанным в TLD.

JSP.7.5.1.2 Классы Проверщика

Класс TagLibraryValidator может быть указан в TLD библиотеки тэгов для запроса проверки этой JSP-страницы. XML-просмотр JSP-страницы экспонируется через класс PageData, и класс validator/проверщика может выполнять любую проверку, которую автор библиотеки тэгов сочтёт необходимой.

JSP-контейнер может по выбору уникально идентифицировать все XML-элементы в XML-просмотре JSP-страницы через атрибут jsp:id. этот атрибут может использоваться для предоставления большей информации о местонахождении ошибки. механизм класса проверщика является новым для спецификации JSP 1.2.

TagLibraryValidator
может быть передан некоторым параметрам инициализации в TLD. Это облегчает многократное использование классов проверщика. Мы ожидаем, что validator-классы будут написаны на базе различных механизмов схемы XML (DTDs, XSchema, Relaxx, других). Стандартные классы проверщика могут быть внедрены в последующих версиях спецификации JSP, если когда-нибудь появится полный стандарт схемы.

JSP.7.5.1.3 Проверка Класса TagExtraInfo


Дополнительная проверка на этапе трансляции может выполняться путём использования метода isValid класса TagExtraInfo. Метод isValid вызывается на этапе трансляции и передаётся в экземпляр Tag Dat в качестве его аргумента.

Механизм isValid был первоначальным механизмом проверки, введённым в JSP 1.1 вместе с механизмами Расширения Тэгов. Библиотеки тэгов, созданные для запуска в контейнерах JSP 1.2, должны использовать механизм класса проверщика.

JSP.7.5.2 Ошибки Времени Запроса

В некоторых случаях может динамически выполняться дополнительная проверка на этапе запроса в методах обработчиков тэгов. Если обнаруживается ошибка, вызывается экземпляр JspException. Если ошибка не отловлена, этот объект вызовет механизм errorpage спецификации JSP.

JSP.7.6 Соглашения и Другие Вопросы

Этот раздел не является нормативным, хотя отражает практику разработки.

JSP.7.6.1 Как Определить Новые Неявные Объекты

Мы предлагаем придерживаться следующего стиля введения неявных объектов:

JSP-страница может сделать эти объекты доступными так:


<%@ tablig prefix="me" uri="......" %>

<me:defineObjects />

.... начинается использование объектов ....


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


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


Этот механизм, вместе с доступом к информации метаданных, позволяет продвигать новинки наряду со стандартом.


Примечание: если новая возможность добавлена к спецификации JSP и продавец также предоставляет эту возможность через свой специфический механизм, стандартным механизмом, как указано в спецификации JSP, будет "win". Это значит, что механизмы, специфичные для продавца, могут постепенно перейти в спецификацию, если докажут свою пригодность.

JSP.7.6.2 Доступ к Информации о Продавце

Если продавец хочет ассоциировать некоторую информацию, не описанную в текущей версии TLD, с некоторой библиотекой тэгов, он может сделать это, вставив информацию в контролируемый им документ, включив этот документ в часть WEB-INF JAR-файла там, где находится Tab Library/Библиотека Тэгов, и используя стандартные механизмы Servlet 2.2 для доступа к этой информации. Продавец может теперь использовать ID-механизмы для ссылки на элемент внутри TLD.

JSP.7.6.3Настройка Библиотеки Тэгов

Библиотека тэгов может быть специализирована в ходе ассемблирования и публикации. Например, библиотека тэгов, предоставляющая доступ к базам данных, может быть специализирована информацией логина и пароля.

В web.xml в спецификации Servlet 2.2 нет подходящего места для специализированной информации. Стандартизованный механизм, возможно, станет частью последующей JSP-спцификации, но пока советуем авторам библиотек тэгов размещать такую информацию в хорошо известном месте какого-нибудь ресурса в части WEB-INF/ Web-Приложения давать к ней доступ через вызов getResource() в ServletContext.




Партнёры:
PostgresPro
Inferno Solutions
Hosting by Hoster.ru
Хостинг:

Закладки на сайте
Проследить за страницей
Created 1996-2024 by Maxim Chirkov
Добавить, Поддержать, Вебмастеру