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>
<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 или подтип класса реализации обработчика тэга. Эта информация может использоваться специализированным контейнером для специфических хорошо известных библиотек тэгов; см. .
Элемент 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 | Тело акции обязано быть пустым. |
Синтаксис:
<!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)>
