JSP.7.1.2.2 Прослушиватели/Listeners Событий
Библиотека тэгов может содержать классы, которые являются прослушивателями событий (см. спецификацию Servlet 2.3). Классы-прослушиватели перечисляются в дескрипторе библиотеки тэгов, и JSP-контейнер автоматически инстанциирует и регистрирует их. Контейнер нужен для размещения всех TLD-файлов (см. в Разделе JSP.7.3.1 детали об их идентификации), чтения их элементов-прослушивателей и рассмотрения прослушивателей событий как расширений этих же прослушивателей, перечисленных в web.xml. Порядок регистрации прослушивателей не определён, но они регистрируются до старта приложения.
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.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.1 Введение
Библиотека Тэгов/Tag Library абстрагирует функциональность, используемую JSP-страницей, определяя специализированный (суб)язык, что делает возможным более естественно использовать эту функциональность в JSP-страницах.
Акции, вводимые Библиотекой Тэгов, могут использоваться авторами JSP-страниц явно при авторизации - вручную, или неявно - через использование утилит авторизации. Библиотеки Тэгов особенно применимы в утилитах авторизации, поскольку позволяют сосредоточиться на главном, а параметры, указанные в экземпляре акции, сами передают информацию утилите.
Акции, которые предоставляются из библиотеки тэгов, импортируются в JSP-страницу путём использования директивы taglib. Они доступны для использования на странице через префикс, заданный этой директивой.
Акции могут создавать новые объекты, которые могут затем передаваться другим акциям или обрабатываться программно элементами скриптинга в JSP-странице.
Библиотеки тэгов являются переносимыми: они могут использоваться на любой JSP-странице вне зависимости от того, какой язык скриптинга используется на этой странице.
Механизм развёртывания тэгов содержит информацию для:
Выполнения JSP-страницы, использующей эту библиотеку тэгов.
Авторизации или модификации JSP-страницы.
Проверки JSP-страницы.
Представления JSP-страницы конечному пользователю.
Библиотека Тэгов описывается через Tag Library Descriptor ( TLD)/Дескриптор Библиотеки Тэгов, документ XML, рассматриваемый ниже.
JSP.7.2.1 Упакованные Библиотеки Тэгов
Утилиты авторизацииJSP-страниц и JSP-контейнеры должны принимать библиотеку тэгов, упакованную в JAR-файл. При поставке в JSP-контейнере применяются стандартные соглашения по JAR, описанные в спецификации Servlet 2.3, включая соглашения для зависимостей расширений.
Упакованные библиотеки тэгов обязаны иметь как минимум один файл дескриптора библиотеки тэгов.
Спецификация JSP 1.1 разрешала только один TLD, в META-INF/taglib.tld, а в JSP 1.2 разрешены несколько библиотек тэгов. См. в об идентификации TLD.
JSP.7.2.2 Размещение Java-Классов
Библиотека тэгов содержит классы для инстанциации на этапе трансляции и классы для инстанциации на этапе запроса. Первые содержат классы TagLibraryValidator и TagExtraInfo. Вторые содержат классы обработчика тэгов и прослушивателя событий.
Применяются обычные соглашения по классам Java: как часть web-приложения они обязаны находиться внутри либо JAR-файла в директории WEB-INF/lib, либо в директории WEB-INF/classes. JAR, содержащий упакованные библиотеки тэгов, может быть сброшен в директорию WEB-INF/ lib, чтобы сделать его классы доступными на этапе запроса (а также на этапе трансляции, см. ).
Отображение между 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.2Библиотеки Тэгов
Библиотека тэгов это коллекция акций, инкапсулирующая некоторую функциональность, используемую в JSP-странице. Библиотека тэгов становиться доступной JSP-странице через использование директивы taglib, которая идентифицирует эту библиотеку тэгов с помощью URI (Universal Resource Identifier/Универсальный Идентификатор Ресурсов).
URI, идентифицирующий библиотеку тэгов, может быть любым верным URI, который может использоваться для уникальной идентификации семантики библиотеки тэгов. URI, идентифицирующий библиотеку тэгов, ассоциируется с файлом Tag Library Description (TLD) и с классами обработчиков тэгов, как указано далее в .
JSP.7.3.1 Идентификация Дескрипторов Библиотек Тэгов
Файл дескриптора библиотеки тэгов (ДБТ) именуется с использованием расширения “.tld”, которое указывает, что это файл ДБТ.
Если размещены внутри файла JAR, файлы ДБТ обязаны находиться в директории META-INF или в её субдиректории.
При размещении непосредственно в web-приложении файлы ДБТ обязаны всегда находиться в директории WEB-INF или в одной из её субдиректорий.
Документ ОТД для ДБТ это .
JSP.7.3.2 Путь Ресурса TLD
URI в директиве taglib отображается в контексте относительного пути (это обсуждается в ). Контекст относительного пути это URL без указания компонентов - протокола и хоста, начинающийся с “/” и называемый путь ресурса TLD.
Путь ресурса TLD интерпретируется относительно корневой директории web-приложения и должен указывать непосредственно на TLD-файл или на JAR-файл, содержащий TLD-файл в META-INF/taglib.tld.
Если путь ресурса TLD - не один из этих вариантов, будет возникать фатальная ошибка трансляции.
URI, описывающий библиотеку тэгов, отображается в путь ресурса TLD через отображение taglib, и в интерпретацию крайнего варианта, которая используется, если отображение не содержит URI.
Отображение taglib строится из явного отображения taglib в web.xml (описано в ), которое расширяется неявными вхождениями, выведенными из упакованных библиотек тэгов в web-приложение (описано в ), и неявными вхождениями, известными JSP-контейнеру.
Интерпретация варианта "на крайний случай" нацелена на случайное использование своего механизма, как в цикле разработки Web-Приложения: тогда URI интерпретируется как непосредственный путь к TLD (см. ).
JSP.7.3.3 Отображение taglib в web.xml
Файл web.xml может содержать явное отображение taglib между путями ресурсов URI и TLD, описанное с использованием элементов taglib Дескриптора Публикации Web-Приложения в файле WEB-INF/web.xml, как описано в спецификации Servlet 2.3 и в .
Элемент 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, как указано в .
В web.xml не должно быть входов с тем же значением taglib-uri.
<taglib-location>
taglib-location содержит место размещения (в качестве ресурса) Файла Дескриптора Библиотеки Тэгов для данной библиотеки тэгов.
<!ELEMENT taglib-location (#PCDATA)>
PCDATA ::= размещение ресурса (как указано в ); где можно найти файл TLD.
JSP.7.3.4 Неявное Отображение Входов из TLD
Отображение taglib, описанное в web.xml, расширяется за счёт новых вхождений, извлекаемых из файлов TLD Web-Приложения.
Новые вхождения обсчитываются так:
Каждый TLD-файл проверяется. Если он содержит элемент <uri>, создаётся новый элемент <taglib> с субэлементом
<taglib-uri>, значением которого является значение элемента <uri>, и с субэлементом <taglib-location>, указывающим на TLD-файл.
Если созданный элемент <taglib> содержит разные <taglib-uri>
для каждого отображения taglib, он добавляется.
Этот механизм предоставляет автоматическое отображение URI в TLD, а также поддержку нескольких TLD в одном JAR-пакете.
Обратите внимание, что эта функциональность не требует явного именования места размещения TLD-файла, которого мог бы потребовать механизм типа протокола jar:.
Заметьте также, что этот механизм не добавляет дублирующие вхождения.
JSP.7.3.5 Неявное Отображение Входов из Контейнера
Контейнер также может добавлять дополнительные вхождения к отображению taglib. Как и в предыдущем случае, входы добавляются только для тех URI, которые не представлены в отображении. Концептуально эти вхождения соответствуют TLD, описывающему эти библиотеки тэгов. Эти неявные вхождения отображения соответствуют библиотекам, которые известны контейнеру, который отвечает за предоставление их реализации, либо через обработчики тэгов, либо через механизм, описанный в Разделе .
JSP.7.3.6 Определение Ресурса Пути TLD
Путь ресурса TLD может быть определён из атрибута uri директивы taglib, как показано ниже. В последующем разъяснении “абсолютным URI” называется такой, который начинается с названия протокола и имени хоста, а “относительный URI” даётся так, как указано в , т.е. без протокола и имени хоста.
Все шаги описаны так, будто они выполнялись, но реализация может использовать различные стратегии для получения того же результата.
JSP.7.3.6.1 Вычисление Размещения TLD
Карта taglib, генерированная в Разделах и , может содержать одно или более вхождений <taglib></taglib>. Каждое такое вхождение идентифицируется по TAGLIB_URI, который является значением субэлемента <taglib-uri>. Этот TAGLIB_URI может быть абсолютным URI, либо относительным URI, который начинается (или не начинается) с “/”.
Каждое вхождение определяет также TAGLIB_LOCATION следующим образом:
Если субэлемент <taglib-location> это относительный URI, начинающийся с “/”, то TAGLIB_LOCATION является этим URI.
Если субэлемент <taglib-location> это относительный URI, не начинающийся с “/”, то TAGLIB_LOCATION является разрешением этого URI относительно /WEB-INF/web.xml (результатом этого разрешения является относительный URI, начинающийся с “/”).
JSP.7.3.6.2 Вычисление Ресурса Пути TLD
Здесь показано, как разрешить директиву taglib для вычисления пути ресурса TLD на базе значения атрибута uri директивы taglib.
Если uri является ABS_URI, абсолютным URI. Идёт поиск в карте taglib вхождения, чей TAGLIB_URI является ABS_URI. Если он найден, соответствующее TAGLIB_LOCATION является путём ресурса TLD. Если он не найден, возникает ошибка трансляции.
Если uri является ROOT_REL_URI, относительным URI, начинающимся с “/”. Идёт поиск в карте taglib вхождения, чей TAGLIB_URI является ROOT_REL_URI. Если он найден, соответствующее TAGLIB_LOCATION является путём ресурса TLD. Если он не найден, ROOT_REL_URI
является путём ресурса TLD.
Если uri является NOROOT_REL_URI, относительным URI, не начинающимся с “/”. Идёт поиск в карте taglib вхождения, чей TAGLIB_URI является NOROOT_REL_URI. Если он найден, соответствующее TAGLIB_LOCATION является путём ресурса TLD. Если он не найден, NOROOT_REL_URI разрешается относительно текущей JSP-страницы, где появилась директива; это значение (по определению, это спецификация относительного URI, начинающегося с “/”) является путём ресурса TLD.
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.3.9 Хорошо Известные URI
JSP-контейнер может “знать” некоторые URI и может предоставлять альтернативные реализации для библиотек тэгов, описанных этими URI, но пользователь обязан видеть поведение как таковое, описанное описанием требуемой, переносимой библиотеки тэгов, указанной в URI.
JSP-контейнер обязан всегда использовать отображение, специфицированное для URI, в дескрипторе публикации web.xml, если он имеется. Если публикатор хочет использовать платформозависимую реализацию хорошо известного URI, отображение такого URI должно быть удалено во время публикации.
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.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)>
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.1 Механизмы Времени/Этапа Трансляции
Определённая проверка на этапе трансляции проводится в Tag Library Descriptor (TLD). В некоторых случаях для предоставления поддержки этой информации необходимо наличие класса TagExtraInfo.
JSP.7.5.2 Ошибки Времени Запроса
В некоторых случаях может динамически выполняться дополнительная проверка на этапе запроса в методах обработчиков тэгов. Если обнаруживается ошибка, вызывается экземпляр JspException. Если ошибка не отловлена, этот объект вызовет механизм errorpage спецификации JSP.
JSP.7.5 Проверка
Есть несколько причин, почему структура JSP-страницы должна соответствовать некоторым правилам проверки:
Семантика времени запроса/request-time; например, субэлемент может требовать информации от некоторого включающего (содержащего его) элемента на этапе запроса.
Поддержка утилит авторизации; например, утилита может требовать упорядочить акции.
Методологические ограничения; например, группа разработчиков может ограничить способ использования некоторых возможностей.
Проверка может выполняться на этапе трансляции или на этапе запроса. Обычно проверка на этапе трансляции даёт больше информации, и спецификация JSP 1.2 предоставляет очень гибкий механизм проверки на этапе трансляции.
JSP.7.6.1 Как Определить Новые Неявные Объекты
Мы предлагаем придерживаться следующего стиля введения неявных объектов:
Определить библиотеку тэгов.
Акция, называемая defineObjects определяет необходимые объекты.
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.
JSP.7.6 Соглашения и Другие Вопросы
Этот раздел не является нормативным, хотя отражает практику разработки.
JSP.8.1.1 Протокол, Видимый Web-Сервером
JSP-контейнер локализует соответствующий экземпляр класса реализации JSP-страницы и направляет ему запросы, используя протокол Servlet. JSP-контейнеру может потребоваться создать такой класс динамически из исходной JSP-страницы до направления ей объектов request и response.
Класс Servlet
определяет контракт между JSP-контейнером и классом реализации JSP-страницы.
Если используется протокол HTTP, контракт описывается классом HttpServlet. Большинство JSP-страниц используют протокол HTTP, но другие протоколы также разрешены данной спецификацией.
JSP-контейнер автоматически делает несколько серверных/server-side объектов доступными объекту реализации JSP-страницы. См. .
JSP.8.1.1.1 Протокол, Видимый Автором JSP-Страницы
JSP-спецификация определяет контракт между JSP-контейнером и автором JSP-страницы. Этот контракт определяет обязательства, которые автор может установить для акций, описанных на JSP-странице.
Главной частью этого контракта является метод _jspService(), который генерируется автоматически JSP-контейнером из JSP-страницы.
Детальная информация об этом контракте дана в. Контракт описывает также, как автор JSP может обозначить, какие акции будут предприниматься, когда будут вызываться методы реализации страницы init() и destroy(). В спецификации JSP 1.2 это делается через определение методов с именами jspInit() и jspDestroy()
в объявлении элемента скриптинга в JSP-странице.
Метод jspInit(), если он имеется, будет вызываться для подготовки страницы перед направлением первого запроса. Аналогично, JSP-контейнер может затребовать ресурсы, используемые JSP-страницей, если запрос не обслуживается JSP-страницей, через вызов её метода jspDestroy(), если он имеется.
Автор JSP-страниц не может (пере)определять методы Servlet через объявление элемента скриптинга.
JSP-спецификация резервирует имена методов и переменных, начинающиеся с jsp, _jsp, jspx и _jspx, в любом сочетании регистров.
JSP.8.1.1.2 Интерфейс HttpJspPage
Выполнению контракта между JSP-контейнером и автором JSP-страницы помогает требование о том, что класс Servlet, соответствующий JSP-странице, обязан реализовывать интерфейс HttpJspPage (или интерфейс JspPage, если протокол - не HTTP).
Рисунок J2EE.8.1 Контракт между JSP-Страницей и JSP-Контейнером.
 |
На Рисунке J2EE.8.1 показаны включённые контракты. Теперь мы рассмотрим этот процесс более детально.
JSP.8.1 Модель JSP-Страницы
JSP-страница представлена на этапе выполнения объектом реализации JSP-страницы и выполняется JSP-контейнером. Объект реализации JSP-страницы - это servlet/сервлет. JSP-контейнер направляет запросы от клиента объекту реализации JSP-страницы и ответы объекта реализации JSP-страницы - клиенту.
JSP-страница описывает создание объекта response из объекта request
для данного протокола, возможно, создавая и/или используя в ходе этого процесса некоторые другие объекты. JSP-страница может также указывать, как должны обрабатываться некоторые события.
В JSP 1.2 только события init и destroy являются допустимыми событиями.
JSP.8.2.1 Контракты API
Контракт между JSP-контейнером и Java-классом, реализующим JSP-страницу, соответствует интерфейсу Servlet. См. детали в спецификации Servlet 2.3.
Ответственность за выполнение этого контракта лежит на реализации JSP-контейнера, если JSP-страница не использует атрибут extends директивы jsp.
Если атрибут extends директивы jsp
используется, автор JSP-страниц обязан гарантировать, что суперкласс, заданный в атрибуте extends, поддерживает этот контракт.
Таблица JSP.8-1 Как JSP-Контейнер Обрабатывает JSP-Страницы
| Метод может по выбору/optionally быть определён в JSP-странице. Метод вызывается при инициализации JSP-страницы. Если метод вызывается, доступны все методы сервлета, включая getServletConfig(). |
void jspInit() |
| Метод по выбору определяется в JSP-странице. Метод вызывается при уничтожении страницы. |
void jspDestroy() |
| Метод не может быть определён в JSP-странице. JSP-контейнер автоматически генерирует этот метод, базируясь на содержимом JSP-страницы. Метод вызывается при каждом клиентском запросе. | void _jspService(<ServletRequestSubtype>, <ServletResponseSubtype>) throws IOException, |
JSP.8.2.2 Параметры Запроса и Ответа
Как видно из Таблицы JSP.8-1, методы контракта между JSP-контейнером и JSP-страницей требуют наличия параметров запроса и ответа.
Формальным типом параметра запроса (который в этой спецификации называется <ServletRequestSubtype>) является интерфейс, расширяющий javax.servlet.ServletRequest. Этот интерфейс обязан определять зависящий от используемого протокола запроса контракт между JSP-контейнером и классом, реализующим JSP-страницу.
Аналогично и формальный тип параметра ответа (называемый в этой спецификации <ServletResponseSubtype>) является интерфейсом, расширяющим javax.servlet.Servlet-Response. Этот интерфейс обязан определять зависящий от используемого протокола ответа контракт между JSP-контейнером и классом, реализующим JSP-страницу. Интерфейсы запроса и ответа вместе описывают зависящий от протокола контракт между JSP-контейнером и классом, реализующим эту JSP-страницу.
HTTP-контракт определяется интерфейсами javax.servlet.http.HttpServletRequest и javax.servlet.http.HttpServletResponse. Интерфейс JspPage ссылается на эти методы, но не может синтаксически описать методы, вызывающие подтипы Servlet(Request,Response). Однако интерфейсы для специфических протоколов, которые расширяют JspPage, могут делать это, так же, как HttpJspPage описывает их для протокола HTTP.
JSP-контейнеры, соответствующие этой спецификации (классами реализации JSP-страницы и работой JSP-контейнера), обязаны реализовывать интерфейсы запроса и ответа (request и response) для HTTP-протокола, как описано в этом разделе.
JSP.8.2.3 Опущение Атрибута extends
Если атрибут extends директивы page (см. ) в JSP-странице не используется, JSP-контейнер может генерировать любой класс, удовлетворяющий контракту, описанному в Таблице JSP.8-1, если он трансформирует JSP-страницу.
В следующих примерах иллюстрирует общий/родовой HTTP-суперкласс, названный ExampleHttpSuper. В показан подкласс, названный _jsp1344, который расширяет ExampleHttpSuper и является классом, сгенерированным из JSP-страницы.
Используя отдельные классы _jsp1344 и ExampleHttpSuper, транслятор JSP-страницы не нуждается в поиске информации, содержит ли JSP-страница объявления с jspInit() или jspDestroy(). Это значительно упрощает реализацию.
Пример Кода 8.1 Общий HTTP-Суперкласс
imports javax.servlet.*;
imports javax.servlet.http.*;
imports javax.servlet.jsp.*;
/**
* Пример суперкласса для HTTP JSP-класса
*/
abstract class ExampleHttpSuper implements HttpJspPage {
private ServletConfig config;
final public void init(ServletConfig config) throws ServletException {
this.config = config;
jspInit();
public void jspInit() {
}
public void jspDestroy() {
}
}
final public ServletConfig getServletConfig() {
return config;
}
// Этот метод не является final, поэтому он может быть переопределён более точным методом
public String getServletInfo() {
return “Суперкласс для HTTP JSP”; // можно и получше?
}
final public void destroy() {
jspDestroy();
}
/**
* Точка входа в сервис.
*/
final public void service(ServletRequest req, ServletResponse res)
throws ServletException, IOException {
// количество отловленных исключений увеличится при наличии внутренней ошибки.
HttpServletRequest request = (HttpServletRequest) req;
HttpServletResponse response = (HttpServletResponse) res;
_jspService(request, resonse);
/**
* Абстрактный метод, предоставляемый JSP-процессором в подклассе,
* обязан быть определён в подклассе.
*/
abstract public void _jspService(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException;
}
Пример Кода 8.2 Java-Класс, Генерируемый из JSP-страницы
imports javax.servlet.*;
imports javax.servlet.http.*;
imports javax.servlet.jsp.*;
/**
* Пример класса, генерируемого для JSP.
*
* Имя класса непредсказуемо.
* Мы принимаем, что это пакет HTTP JSP (как чаще всего и бывает)
*/
class _jsp1344 extends ExampleHttpSuper {
// Следующий код вставлен непосредственно через объявления.
// Любые следующие части могут или могут не иметься;
// если они не определены здесь, будут использоваться
// методы суперкласса.
public void jspInit() {....}
public void jspDestroy() {....}
// Следующий метод генерируется автоматически
// JSP-процессором.
// Тело/body JSP-страницы
public void _jspService(HttpServletRequest request,
HttpServletResponse response)
throws ServletException, IOException {
// инициализация неявных переменных
HttpSession session = request.getSession();
ServletContext context =
getServletConfig().getServletContext();
// для этого примера мы принимаем, что директива буферизована
JSPBufferedWriter out = new
JSPBufferedWriter(response.getWriter());
// далее идёт код из скриптлетов, выражений и статического текста.
}
}
JSP.8.2.4 Использование Атрибута extends
Если автор JSP-страниц использует extends, генерируемый класс идентичен классу из , за исключением того, что имя этого класса это имя, специфицированное в атрибуте extends.
Контракт класса реализации JSP-страницы не изменяется. JSP-контейнер должен проверить (обычно через отражение/reflection), что предоставленный суперкласс:
Реализует HttpJspPage, если протокол - HTTP, либо JspPage - в ином случае.
Все методы в интерфейсе Servlet объявлены final.
Дополнительно к этому, автор JSP-страницы отвечает за то, штаа предоставленный суперкласс выполняет следующее:
метод service() из Servlet API вызывает метод _jspService();
метод
init(ServletConfig) хранит конфигурацию, даёт к ней доступ как к getServletConfig, затем вызывает jspInit;
метод destroy вызывает jspDestroy.
JSP-контейнер может выдавать фатальную ошибку трансляции, если обнаружит, что предоставленный суперкласс не удовлетворяет этим требованиям, но большинство JSP-контейнеров эту проверку не будут выполнять.
JSP.8.2 Класс Реализации JSP-Страницы/Page Implementation Class
JSP-контейнер создаёт класс реализации JSP-страницы для каждой JSP-страницы. Имя класса реализации JSP-страницы зависит от особенностей реализации. Объект реализации JSP-страницы принадлежит к зависящему от реализации именованному архиву. Этот архив может отличаться от одной JSP-страницы к другой. Неименованный архив не должен использоваться без явного “импортирования” класса.
JSP-контейнер может создавать для JSP-страницы класс реализации, либо суперкласс может быть предоставлен автором JSP-страницы с помощью атрибута extends директивы page.
Механизм extends предназначен для опытных пользователей. Он должен использоваться предельно осторожно, так как он ограничивает возможность принятия решений JSP-контейнером. Он может, к примеру, свести на нет усилия по повышению производительности.
Класс реализации JSP-страницы будет реализовывать Servlet, а протокол Servlet будет использоваться для направления запросов классу.
Класс реализации JSP-страницы может зависеть от поддержки других классов. Если класс реализации JSP-страницы упакован в WAR, все связанные классы должны будут быть включены, так что пакет будет переносим на все JSP-контейнеры.
Автор JSP-страницы пишет JSP-страницу, ожидая, что клиент и сервер будут взаимодействовать по определённому протоколу. JSP-контейнер обязан гарантировать, штаа запросы и ответы для страницы используют нужный протокол. Большинство JSP-страниц используют протокол HTTP, и их классы реализаций обязаны реализовать интерфейс HttpJspPage, который расширяет JspPage. Если это не HTTP-протокол, тогда класс реализует интерфейс, расширяющий JspPage.
JSP.8.3 Буферизация
JSP-контейнер буферизует данные (если директива jsp специфицирует это, используя атрибут buffer), когда они высылаются от сервера клиенту.
Headers/"Шапки" клиенту не высылаются, пока не вызван первый метод flush. Следовательно, ни одна из операций, имеющих отношение к шапкам, таких как методы setContentType, redirect или error, не является верной до тех пор, пока метод flush не начнёт выполняться и шапки не начнут высылаться.
Класс javax.servlet.jsp.JspWriter буферизует вывод и высылает его. Класс JspWriter используется в методе _jspService, как в следующем примере:
import javax.servlet.jsp.JspWriter;
static JspFactory _jspFactory = JspFactory.getDefaultFactory();
_jspService(<SRequest> request, <SResponse> response) {
// инициализация неявных переменных ...
PageContext pageContext = _jspFactory.createPageContext(
this,
request,
response,
false,
PageContext.DEFAULT_BUFFER,
false
);
JSPWriter out = pageContext.getOut();
// ....
// .... тело идёт здесь через "out"
// ....
out.flush();
}
Вы можете найти полный листинг javax.servlet.jsp.JspWriter в .
При включённой буферизации, Вы можете всё ещё использовать метод redirect скриптлета в файле .jsp, вызывая response.redirect(какой-то URL) напрямую.
JSP.8.4.1 Имена Параметров Запроса
Все имена параметров запроса, начинающиеся с префикса "jsp", зарезервированы спецификацией JSP и не должны использоваться иначе, чем установлено данной спецификацией.
Все JSP-страницы должны игнорировать (и не зависеть от) параметры, начинающиеся с "jsp_"
JSP.8.4.2 Протокол Прекомпиляции
Запрос к JSP-странице, содержащий параметр запроса с именем "jsp_precompile", является
запросом прекомпиляции. Параметр "jsp_precompile" может не содержать значения или может содержать значения "true" или "false". В любом случае, такой запрос не должен отправляться JSP-странице.
Назначение запроса прекомпиляции в том, чтобы указать JSP-контейнеру, что нужно прекомпилировать (предварительно откомпилировать) JSP-страницу в класс реализации JSP-страницы. Это указание переправляется путём задания параметру значения "true", или не задавая никакого значения, но учтите, что запрос может быть проигнорирован.
Например:
1. ?jsp_precompile
2. ?jsp_precompile="true"
3. ?jsp_precompile="false"
4. ?foobar="foobaz"&jsp_precompile="true"
5. ?foobar="foobaz"&jsp_precompile="false"
1, 2 и 4 - действуют; запросы не будут направлены странице.
3 и 5 - верны; запрос не будет направлен странице.
6. ?jsp_precompile="foo"
- это неверно, и будет генерироваться ошибка HTTP error; 500 (Server error).
JSP.8.4 Прекомпиляция
JSP-страница, использующая протокол HTTP, будет получать HTTP-запросы.
Контейнеры, соответствующие JSP 1.2, обязаны поддерживать простой протокол прекомпиляции, а также некоторые базовые зарезервированные имена параметров. Заметьте, что протокол прекомпиляции это понятие близкое, но не то же самое, что компиляция JSP-страницы в Servlet-класс (Приложение JSP.A).
JSP.9.1.1 JspPage
Синтаксис
public interface JspPage extends javax.servlet.Servlet
Все Известные Субинтерфейсы: HttpJspPage
Все Суперинтерфейсы: javax.servlet.Servlet
Описание
Интерфейс JspPage описывает основное взаимодействие, которому класс реализации JSP-страницы обязан удовлетворять; страницы, использующие HTTP-протокол, описаны через интерфейс HttpJspPage.
Методы Два плюс Один
Этот интерфейс определяет протокол с 3 методами; только два из них: jspInit() и jspDestroy() являются частью этого интерфейса как подпись третьего метода: _jsp-Service()
зависит от специфического используемого протокола и не может быть выражен общим способом в Java.
Класс, реализующий этот интерфейс, отвечает за вызов вышеуказанных методов в нужное время, базируясь на соответствующих вызовах методов на базе Servlet'а.
Методы jspInit() и jspDestroy() могут быть определены автором JSP, но метод _jspService() определяется автоматически JSP-процессором на основе содержимого JSP-страницы.
_jspService()
Метод _jspService() соответствует телу JSP-страницы. этот метод определяется автоматически JSP-контейнером и никогда не должен определяться автором JSP.
Если суперкласс специфицируется через использование атрибута extends, то этот суперкласс может избрать выполнение некоторых акций в своём методе service() до или после вызова метода _jspService().
См. использование атрибута extends в главе JSP_Engine JSP-спецификации.
Специфика подписи зависит от протокола, поддерживаемого JSP-страницейJSP page.
public void _jspService(ServletRequestSubtype request,
ServletResponseSubtype response)
throws ServletException, IOException;
JSP.9.1.1.1 Методы
public void jspDestroy()
Метод jspDestroy() вызывается при уничтожении JSP-страницы. JSP-страница может переопределять этот метод включением его определения в элемент declaration. JSP-страница должна переопределять метод destroy() из Servlet'а.
public void jspInit()
Метод jspInit() вызывается при инициализации JSP-страницы. Реализация JSP (и класса, упоминаемого атрибутом extends, если имеется) отвечает за то, что с этой точки вызовы метода getServlet-Config()
будут возвращать требуемое значение. JSP-страница может переопределять этот метод включением его определения в элемент declaration. JSP-страница должна переопределять метод init() из Servlet'а.
JSP.9.1.2 HttpJspPage
Синтаксис
public interface HttpJspPage extends JspPage
Все Суперинтерфейсы: JspPage, javax.servlet.Servlet
Описание
Интерфейс HttpJspPage описывает взаимодействие, которое Класс Реализации JSP-Страницы обязан выполнять при использовании HTTP-протокола.
Поведение идентично поведению JspPage, за исключением подписи метода _jspService, которая теперь выражается в системе типов Java и включается в интерфейс явно.
См. Также:
JSP.9.1.2.2 Методы
public void _jspService(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Метод _jspService() соответствует телу JSP-страницы. Этот метод определяется автоматически JSP-контейнером и никогда не должен определяться автором JSP-страниц.
Если суперкласс специфицируется через использование атрибута extends, то этот суперкласс может избрать выполнение некоторых акций в своём методе service() до или после вызова метода _jspService(). См. использование атрибута extends в главе JSP_Engine JSP-спецификации.
Вызывает: IOException, ServletException
JSP.9.1.3 JspFactory
Синтаксис
public abstract class JspFactory
Описание
JspFactory является абстрактным классом, определяющим несколько factory/"фабричных"-методов, доступных JSP-странице на этапе прогона, для создания экземпляров различных интерфейсов и классов, используемых для поддержки JSP-реализации.
Соответствующая реализация JSP Engine будет, в процессе своей инициализации, инстанциировать зависящий от реализации подкласс этого класса сделает его глобально доступным для использования классами реализации JSP путём регистрации экземпляра, созданного этим классом, через static/статичный метод setDefaultFactory().
Классы PageContext и JspEngineInfo являются единственными зависящими от реализации классами, которые могут создаваться из factory/фактории.
JspFactory-объекты не должны использоваться авторами JSP-страниц.
JSP.9.1.3.3 Конструкторы
public JspFactory()
JSP.9.1.3.4 Методы
public static synchronized JspFactory getDefaultFactory()
Возвращает: факторию по умолчанию для данной реализации
public abstract JspEngineInfo getEngineInfo()
вызывается для получения специфической для реализации информации о текущей JSP-машине.
Возвращает: объект JspEngineInfo, описывающий текущую JSP-машину.
public abstract PageContext getPageContext(javax.servlet.Servlet servlet, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String errorPageURL, boolean needsSession, int buffer, boolean autoflush)
Получает экземпляр зависящего от реализации абстрактного класса javax.servlet.jsp.Page-Context для вызова Servlet и текущего отправления запроса/request и ответа/response.
Этот метод обычно вызывает раньше при обработке методом _jspService()
класса реализации JSP для того, чтобы получить объект PageContext для обрабатываемого запроса.
Вызов этого метода должен давать в результате вызов метода PageContext.initialize(). Возвращённый PageContext соответственно инициализирован.
Все объекты PageContext, полученные этим методом, должны быть освобождены через вызов releasePageContext().
Параметры:
servlet - запрашивающий сервлет
config - ServletConfig для запрашивающего Servlet'а
request - текущий запрос, находящийся в сервлете.
response - текущий ответ, находящийся в сервлете.
errorPageURL - URL страницы ответа на ошибки для запрашивающей JSP, или null.
needsSession - true, если JSP участвует в сессии.
buffer - размер буфера в байтах, PageContext.NO_BUFFER - если буфера нет, PageContext.DEFAULT_BUFFER - если по умолчанию в реализации.
autoflush - должен ли буфер автоматически зачищаться (опять зачистка...) в потоке вывода при переполнени буфера, или должно вызываться IOException?
Возвращает: page context/контекст страницы.
См. Также: .
public abstract void releasePageContext(PageContext pc)
Вызывается для освобождения ранее размещённого объекта PageContext. Даёт в результате вызов Page-Context.release(). Этот метод должен вызываться до возвращения из метода _jspService() класса реализации JSP.
Параметры:
pc - PageContext, полученный ранее методом getPageContext()
public static synchronized void setDefaultFactory(JspFactory deflt)
Устанавливает факторию по умолчанию для данной реализации. Для любой principal (основной среды работы?), кроме среды JSP Engine, недопустимо вызывать этот метод.
Параметры:
default - реализация фактории по умолчанию.
JSP.9.1.4 JspEngineInfo
Синтаксис
public abstract class JspEngineInfo
Описание
JspEngineInfo это абстрактный класс, предоставляющий информацию о текущей JSP-машине.
JSP.9.1.4.5 Конструкторы
public JspEngineInfo()
JSP.9.1.4.6 Методы
public abstract java.lang.String getSpecificationVersion()
Возвращает номер версии JSP-спецификации, поддерживаемой этой JSP-машиной.
Номера версии состоят из положительных целых чисел, разделённых точками “.”, например, “2.0” или “1.2.3.4.5.6.7”. Это позволяет использовать расширенную нумерацию для представления версий major, minor, micro и т.д.
Номер версии обязан начинаться с цифры.
Возвращает: версию спецификации, null возвращается, если номер неизвестен.
JSP.9.1 Контракт Объекта Реализации JSP-Страницы
В разделе рассматривается базовый контракт между объектом реализации JSP-страницы и его контейнером. Главный контракт определяется классами JspPage и HttpJspPage. Класс JspFactory описывает механизм портативной инстанциации всех необходимых объектов прогона, а JspEngineInfo предоставляет базовую информацию о текущем JSP-контейнере.
Ни один из классов, рассматриваемых здесь, не предназначен для использования авторами JSP-страниц; пример использования этих классов имеется в данной главе.
JSP.9.2.1 PageContext
Синтаксис
public abstract class PageContext
Описание
Экземпляр PageContext предоставляет доступ ко всем пространствам имён, ассоциированным с JSP-страницей, предоставляет доступ к некоторым атрибутам страницы, а также слой поверх деталей реализации.
Неявные объекты добавляют pageContext автоматически.
Класс PageContext является абстрактным классом, созданный как расширяемый для предоставления реализаций соответствующей средой запуска программ JSP-машины.
Экземпляр PageContext получается классом реализации JSP через вызов метода JspFactory.getPageContext() и освобождается через вызов JspFactory.releasePageContext().
Примеры использования PageContext, JspFactory и других классов в объекте реализацииJSP-страницы можно найти повсюду.
PageContext облегчает работу автора страниц/компонентов и реализатора страниц, предоставляя:
один общий API для обслуживания пространств имён с разными областями видимости
несколько удобных API для доступа к различным public-объектам
механизм получения JspWriter для вывода/output
механизм обслуживания работы страницы с сессией
механизм экспонирования атрибутов директивы page в среде скриптинга
механизмы направления или включения текущего запроса в другие активные компоненты приложения
механизм процессинга обработки исключения errorpage
Методы, Предназначенные для Кода, Генерируемого Контейнером
Некоторые методы предназначены для использования в коде, генерируемом контейнером, а не для кода, написанного авторами JSP-страниц или библиотек тэгов JSP.
Методы, поддерживающие lifecycle/жизненный цикл - initialize() и release()
Следующие методы делают возможным обслуживание вложенных JspWriter-потоков через реализацию Tag Extensions/Расширений Тэгов: pushBody() и popBody()
Методы, Предназначенные для Авторов JSP
Некоторые методы предоставляют универсальный доступ к различным объектам, представляющим области видимости/scopes. Реализация обязана использовать основные механизмы Servlet, соответствующие данной области видимости/scope, чтобы информация могла передаваться туда и обратно между Сервлетами и JSP-страницами.
Это методы: setAttribute(), getAttribute(), find-Attribute(), removeAttribute(), getAttributesScope() и getAttributeNamesIn-Scope().
Следующие методы предоставляют удобный доступ к неявным/implicit объектам: getOut(), getException(), getPage() getRequest(), getResponse(), getSession(), getServlet-Config()
и getServletContext().
Следующие методы предоставляют поддержку перенаправления/forwarding, включения в/inclusion и обработки ошибок: forward(), include() handlePageException().
JSP.9.2.1.7 Поля
public static final java.lang.String APPLICATION
Имя используется в для хранения ServletContext в таблице имён PageContext.
public static final int APPLICATION_SCOPE
Область видимости приложения: именованные ссылки остаются доступными в ServletContext, пока он не будет затребован обратно.
public static final java.lang.String CONFIG
Имя используется для хранения ServletConfig в таблице имён PageContext.
public static final java.lang.String EXCEPTION
Имя используется для хранения неотловленного исключения в списке атрибутов ServletRequest и в таблице имён PageContext.
public static final java.lang.String OUT
Имя используется для хранения текущего JspWriter в таблице имён PageContext.
public static final java.lang.String PAGE
Имя используется для хранения Сервлета в таблицах имён данного PageContext.
public static final int PAGE_SCOPE
Область видимости: (по умолчанию) именованные ссылки остаются видимыми в данном PageContext до возврата из текущего вызова Servlet.service().
public static final java.lang.String PAGECONTEXT
Имя используется для хранения этого PageContext в его собственной таблице имён.
public static final java.lang.String REQUEST
Имя используется для хранения ServletRequest в таблице имён PageContext.
public static final int REQUEST_SCOPE
Область видимости: именованные ссылки остаются доступными из Servlet-Request, ассоциированного с Сервлетом, до завершения текущего запроса.
public static final java.lang.String RESPONSE
Имя используется для хранения ServletResponse в таблице имён PageContext.
public static final java.lang.String SESSION
Имя используется для хранения HttpSession в таблице имён PageContext.
public static final int SESSION_SCOPE
Область видимости (верна, только если эта страница участвует в сессии): именованные ссылки остаются доступными из HttpSession (если он имеется), ассоциированного с Сервлетом, пока HttpSession не будет закрыта.
JSP.9.2.1.8 Конструкторы
public PageContext()
JSP.9.2.1.9 Методы
public abstract java.lang.Object findAttribute(java.lang.String name)
Ищет именованные атрибуты на странице, в запросе/request, сессии/session (если запущена) и области(-ях) видимости приложения, чтобы возвратить ассоциированные значения или null.
Возвращает: ассоциированное значение или null.
public abstract void forward(java.lang.String relativeUrlPath)
Этот метод используется для "направления" или перенаправления текущих ServletRequest и ServletResponse другому активному компоненту приложения.
Если relativeUrlPath начинается с “/”, тогда специфицированный URL вычисляется относительно DOCROOT ServletContext'а для данной JSP. Если путь не начинается с “/”, тогда специфицированный URL вычисляется относительно URL запроса, который был отображён в вызывающую JSP.
Верен только для вызова этого метода из выполнения Thread/Потока в методе _jsp-Service(...)JSP.
Если этот метод был успешно вызван, вызывающему Thread не разрешается модификация объекта ServletResponse. Любая попытка сделать это даёт непредсказуемый результат. Обычно вызывающий объект сразу же возвращается из _jspService(...) после вызова этого метода.
Параметры:
relativeUrlPath
- специфицирует относительный путь URL к целевому ресурсу, как рассмотрено выше.
Вызывает:
ServletException, IOException
IllegalArgumentException - если URL целевого ресурса не может быть разрешён/высчитан.
IllegalStateException - если ServletResponse не в том состоянии, чтобы выполнить forward/направление.
SecurityException - если вызывающий не может получить доступ к целевому ресурсу.
public abstract java.lang.Object getAttribute(java.lang.String name)
Возвращает объект, ассоциированный с именем в области видимости страницы, или null, если объект не найден.
Параметры:
name - имя атрибута для получения.
Вызывает:
NullPointerException - если имя - null.
IllegalArgumentException - если область видимости неверна.
public abstract java.lang.Object getAttribute(java.lang.String name, int scope)
Возвращает объект, ассоциированный с именем в специфицированной области видимости, или null, если объект не найден.
Параметры:
name - имя атрибута для установки.
scope - область видимости, с которой ассоциировать имя/объект.
Вызывает:
NullPointerException - если имя - null.
IllegalArgumentException - если область видимости неверна.
public abstract java.util.Enumeration getAttributeNamesInScope(int scope)
Перечисляет все атрибуты в данной области видимости.
Возвращает: перечисление имён (java.lang.String) всех атрибутов специфицированной области видимости.
public abstract int getAttributesScope(java.lang.String name)
Получает область видимости, в которой определён данный атрибут.
Возвращает: область видимости объекта, ассоциированного со специфицированным именем, или 0.
public abstract java.lang.Exception getException()
Текущее значение объекта exception (Exception).
Возвращает: любое исключение, переданное ему как errorpage.
public abstract JspWriter getOut()
Текущее значение объекта вывода/out (JspWriter).
Возвращает: поток текущего JspWriter, используемый для ответа клиенту.
public abstract java.lang.Object getPage()
Значение объекта страницы/page (Servlet).
Возвращает: экземпляр класса реализации (Servlet), ассоциированный с этим PageContext.
public abstract javax.servlet.ServletRequest getRequest()
Текущее значение объекта request (ServletRequest).
Возвращает: ServletRequest для данного PageContext.
public abstract javax.servlet.ServletResponse getResponse()
Текущее значение объекта response (ServletResponse).
Возвращает: ServletResponse для данного PageContext.
public abstract javax.servlet.ServletConfig getServletConfig()
Экземпляр ServletConfig.
Возвращает: ServletConfig для данного PageContext.
public abstract javax.servlet.ServletContext getServletContext()
Экземпляр ServletContext.
Возвращает: ServletContext для данного PageContext.
public abstract javax.servlet.http.HttpSession getSession()
Текущее значение объекта session (HttpSession).
Возвращает: HttpSession для данного PageContextили null.
public abstract void handlePageException(java.lang.Exception e)
Этот метод предназначен для обработки необработанных исключений уровня “page” путём перенаправления исключения специализированной для данной JSP странице ошибок/error page, или, если ничего не специфицировано, для выполнения акции, определяемой реализацией.
Класс реализации JSP обычно будет очищать локальный статус до вызова этого метода и будет возвращать сразу после этого. Не разрешается генерировать какой-либо вывод клиенту или модифицировать любой статус ServletResponse после этого вызова.
Этот метод сохранён для обеспечения обратной совместимости. Вновь генерируемый код должен использовать PageContext.handlePageException(Throwable).
Параметры:
e - обрабатываемое исключение.
Вызывает:
ServletException, IOException
NullPointerException - если исключение - null.
SecurityException - если вызывающий не может достичь целевого ресурса.
См. Также: public abstract void handlePageException(java.lang.Throwable t)
public abstract void handlePageException(java.lang.Throwable t)
Этот метод идентичен
handlePageException(Exception), за исключением того, что он принимает Throwable. Это предпочтительный метод, так как он даёт возможность правильной реализации семантики errorpage.
Этот метод предназначен для обработки необработанных исключений уровня “page” путём перенаправления исключения специализированной для данной JSP странице ошибок/error page, или, если ничего не специфицировано, для выполнения акции, определяемой реализацией.
Класс реализации JSP обычно будет очищать локальный статус до вызова этого метода и будет возвращать сразу после этого. Не разрешается генерировать какой-либо вывод клиенту или модифицировать любой статус ServletResponse после этого вызова.
Параметры:
t - обрабатываемый throwable.
Вызывает:
ServletException, IOException
NullPointerException - если исключение - null.
SecurityException - если вызывающий не может достичь целевого ресурса.
См. Также: public abstract void handlePageException(java.lang.Exception e)
public abstract void include(java.lang.String relativeUrlPath)
Вызывает обработку ресурса, специфицированного для обработки как часть текущих Servlet-Request и ServletResponse, в вызывающем Thread. Вывод обработки целевых ресурсов запроса записывается непосредственно в поток вывода ServletResponse.
Текущий JspWriter “out” для данной JSP очищается - как побочный эффект этого вызова - до обработки include.
Если relativeUrlPath начинается с “/”, тогда специфицированный URL вычисляется относительно DOCROOT ServletContext'а для данной JSP. Если путь не начинается с “/”, тогда специфицированный URL вычисляется относительно URL запроса, который был отображён в вызывающую JSP. Верным является только вызов этого метода из выполнения Thread в методе _jsp-Service(...) JSP.
Параметры:
relativeUrlPath - специфицирует относительный путь-URL к включаемому целевому ресурсу.
Вызывает:
ServletException, IOException
IllegalArgumentException - если URL целевого ресурса не может быть разрешён.
SecurityException - если вызывающий не может достичь целевого ресурса.
public abstract void initialize(javax.servlet.Servlet servlet, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String errorPageURL, boolean needsSession, int bufferSize, boolean autoFlush)
Метод initialize вызывается для инициализации неинициализированного PageContext, чтобы он мог быть использован классом реализации JSP для обслуживания входящих запросов и для ответов в его методе _jspService().
Этот метод обычно вызывается из JspFactory.getPageContext() для инициализации статуса.
Этот метод необходим для создания начального JspWriter и ассоциирования имени “out”
в области видимости страницы с этим вновь созданным объектом.
Этот метод не должен использоваться авторами страниц или библиотек тэгов.
Параметры:
servlet - Servlet, ассоциированный с данным PageContext.
request - текущий рассматриваемый запрос для данного Servlet.
response - текущий рассматриваемый ответ для данного Servlet.
errorPageURL - значение атрибута errorpage в директиве page, или null.
needsSession - значение атрибута session директивы page.
bufferSize - значение атрибута buffer директивы page.
autoFlush - значение атрибута autoflush директивы page.
Вызывает:
IOException - во время создания JspWriter.
IllegalStateException - если некорректно инициализирован.
IllegalArgumentException
public JspWriter popBody()
Возвращает предыдущий JspWriter “out”, сохранённый совпадающим pushBody(), и обновляет значение атрибута “out” в пространстве имён атрибута страницы scope в PageConxtext.
Возвращает: сохранённый JspWriter.
public BodyContent pushBody()
Возвращает новый объект BodyContent, сохраняет текущий “out” JspWriter и обновляет значение атрибута “out” в пространстве имён атрибута страницы scope в PageContext.
Возвращает: новый BodyContent.
public abstract void release()
Этот метод должен “reset/восстанавливать” внутренний статус PageContext, освобождая все внутренние ссылки и подготавливая PageCont для возможного использования последующим вызовом initialize(). Этот метод обычно вызывается из Jsp-Factory.releasePageContext().
Подклассы будут окружать/envelop этот метод.
Этот метод не должен использоваться авторами страниц или библиотек тэгов.
public abstract void removeAttribute(java.lang.String name)
Удаляет ссылку на объект, ассоциированную с данным именем, просматривает во всех scope в порядке scope.
Параметры:
name - имя удаляемого объекта.
public abstract void removeAttribute(java.lang.String name, int scope)
Удаляет ссылку на объект, ассоциированную с данным именем, в данной области видимости.
Параметры:
name - имя удаляемого объекта.
scope - область видимости, где идёт просмотр.
public abstract void setAttribute(java.lang.String name, java.lang.Object attribute)
Регистрирует имя и объект, специфицированные с семантикой области видимости страницы.
Параметры:
name - имя устанавливаемого атрибута.
attribute - объект для ассоциирования с этим именем.
Вызывает:
NullPointerException - если name или object - null.
public abstract void setAttribute(java.lang.String name, java.lang.Object o, int scope)
Регистрирует имя и объект, специфицированные с семантикой соответствующей области видимости.
Параметры:
name - имя устанавливаемого атрибута.
o - объект для ассоциирования с этим именем.
scope - область видимости, с которой ассоциируется name/object.
Вызывает:
NullPointerException - если name или object- null.
IllegalArgumentException - если область видимости неверна.
JSP.9.2.2 JspWriter
Синтаксис
public abstract class JspWriter extends java.io.Writer
Прямые/Direct Известные Подклассы: BodyContent
Описание
Акции и шаблонные данные JSP-страницы записываются с использованием объекта JspWriter, на который ссылаются через неявную переменную out, которая инициализируется автоматически при использовании методов в объекте PageContext.
Этот абстрактный класс эмулирует некоторую функциональность классов java.io.BufferedWriter и java.io.PrintWriter, однако он отличается тем, что вызывает java.io.IOException из методов print, в то время как PrintWriter этого не делает.
Буферизация
Начальный объект JspWriter ассоциируется с объектом PrintWriter в ServletResponse способом, зависящим от того, буферизуется страница, или нет.
Если страница не буферизуется, вывод, записываемый в этот объект JspWriter, будет записан непосредственно через PrintWriter, который будет создан, если необходимо, путём вызова метода getWriter() в объекте response.
Но если страница буферизуется, объект PrintWriter не будет создан, пока буфер не будет очищен, и операции типа setContentType() также будут разрешены. Поскольку такая гибкость частично облегчает программирование, буферизация JSP-страниц выполняется по умолчанию.
Буферизация поднимает вопрос: что делать, если буфер исчерпан/переполнен?
Можно использовать два подхода:
исчерпание буфера не является фатальной ошибкой; если буфер исчерпан, просто очистить вывод;
исчерпание буфера является фатальной ошибкой; если буфер исчерпан, вызывается исключение.
Оба подхода являются допустимыми, и, таким образом, оба поддерживаются JSP-технологией. Поведение страницы управляется атрибутом autoFlush, который по умолчанию -true.
В общем, JSP-страницы, которым необходимо удостовериться в корректности и полноте высылаемых клиентам данных, могут установить атрибут autoFlush в false, что типично для случая, когда клиентом является само приложение. С другой стороны, JSP-страницы, высылающие данные, что имеет место даже если они сконструированы только частично, могут "захотеть" установить autoFlush в true; как если бы данные высылались для немедленного просмотра в браузере. Каждое приложение должно учитывать свои специфические потребности.
Альтернативой могло бы быть создание буфера нелимитированного размера; но это имело бы тот недостаток, что процесс вычислений захватит неограниченное количество ресурсов системы.
Неявная переменная “out” класса реализации JSP имеет этот тип. Если директива page выбирает autoflush=“true”, то все операции ввода/вывода (I/O) этого класса будут автоматически очищать содержимое буфера, если условие overflow/переполнения будет достигнуто при выполнении текущей операции без очистки.
Если autoflush=“false”, все операции ввода/вывода (I/O) этого класса будут должны вызывать IOException, если выполнение текущей операции будет давать выполнение условия переполнения буфера.
См. Также: java.io.Writer, java.io.BufferedWriter, java.io.PrintWriter
JSP.9.2.2.10 Поля
protected boolean autoFlush
protected int bufferSize
public static final int DEFAULT_BUFFER
константа, обозначающая, что Writer буферизуется и использует размер буфера по умолчанию для данной реализации.
public static final int NO_BUFFER
константа, обозначающая, что Writer не буферизует вывод.
public static final int UNBOUNDED_BUFFER
константа, обозначающая, что Writer буферизуется и не лимитирован; это используется в BodyContent.
JSP.9.2.2.11 Конструкторы
protected JspWriter(int bufferSize, boolean autoFlush)
protected-конструктор.
JSP.9.2.2.12 Методы
public abstract void clear()
Очищает содержимое буфера. Если буфер уже был очищен, тогда операция clear должна вызывать IOException, сигнализируя, что некоторые данные уже безвозвратно записаны в поток вывода клиенту.
Вызывает: IOException - если возникает ошибка I/O.
public abstract void clearBuffer()
Очищает текущее содержимое буфера. В отличие от clear(), этот метод не вызывает IOExceptio, если буфер уже был очищен. Он лишь очищает текущее содержимое буфера и возвращает управление.
Вызывает: IOException - если возникает ошибка I/O.
public abstract void close()
Закрывает поток, предварительно очищая его. Этот метод не должен вызываться явно для начального JspWriter, так как код, генерируемый JSP-контейнером, будет автоматически включать вызов close().
Закрытие ранее уже закрытого потока, в отличие от flush(), не имеет эффекта.
Переопределяет: java.io.Writer.close() в классе java.io.Writer.
Вызывает: IOException - если возникает ошибка I/O.
public abstract void flush()
Очищает поток. Если поток сохранил какие-либо символы из различных методов write() в буфере, записывает их непосредственно по назначению. Затем, если назначением является другой поток символов или байтов, очищает их. Таким образом, один вызов flush очистит все буферы в цепи из Writers и OutputStreams.
Этот метод может быть вызван неявно, если ёмкость буфера исчерпана. Если поток был уже закрыт, дальнейшие вызовы write( или flush() вызовут IOException.
Переопределяет: java.io.Writer.flush() в классе java.io.Writer.
Вызывает: IOException - если возникает ошибка I/O.
public int getBufferSize()
Этот метод возвращает размер буфера, используемого JspWriter.
Возвращает: размер буфера в байтах, или 0 - если не буферизован.
public abstract int getRemaining()
Этот метод возвращает количество неиспользованных байтов буфера.
Возвращает: количество неиспользованных байтов в буфере.
public boolean isAutoFlush()
Этот метод сообщает, является ли JspWriter autoFlushing (очищается ли автоматически).
Возвращает: очищается ли данный JspWriter автоматически, или вызывает IOExceptions при достижении переполнения буфера.
public abstract void newLine()
Записывает символы новой строки. Строка - разделитель строк - определяется системным свойством line.separator, и это не обязательно просто символ новой строки (’\n’).
Вызывает:
IOException - если возникает ошибка ввода/вывода.
public abstract void print(boolean b)
Печатает булево значение. Строка произведённая java.lang.String.valueOf(boolean), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
b - печатаемый булев параметр.
Вызывает: java.io.IOException
public abstract void print(char c)
Печатает символ. Этот символ транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
c - печатаемый char.
Вызывает: java.io.IOException
public abstract void print(char[] s)
Печатает массив символов. Символы конвертируются в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
s - массив печатаемых chars.
Вызывает:
NullPointerException -если s - null.
java.io.IOException
public abstract void print(double d)
Печатает число с плавающей точкой двойной точности. Строка, производимая java.lang.String.valueOf(double), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
d- печатаемое double.
Вызывает: java.io.IOException
См. Также: java.lang.Double
public abstract void print(float f)
Печатает число с плавающей точкой. Строка, производимая java.lang.String.valueOf(float), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
f - печатаемое float.
Вызывает: java.io.IOException
См. Также: java.lang.Float
public abstract void print(int i)
Печатает целое число. Строка, производимая java.lang.String.valueOf(int), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
i - печатаемое int.
Вызывает: java.io.IOException
См. Также: java.lang.Integer
public abstract void print(long l)
Печатает длинное целое. Строка, производимая java.lang.String.valueOf(long), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
l - печатаемое long.
Вызывает: java.io.IOException
См. Также: java.lang.Long
public abstract void print(java.lang.Object obj)
Печатает объект. Строка, производимая методом java.lang.String.valueOf(Object), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
obj - печатаемый Object.
Вызывает: java.io.IOException
См. Также: java.lang.Object.toString()
public abstract void print(java.lang.String s)
Печатает строку. Если аргумент - null, тогда печатается строка “null”. Иначе символы строки конвертируются в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).
Параметры:
s - печатаемая String.
Вызывает: java.io.IOException
public abstract void println()
Обрывает текущую строку, печатая строку разделителя строк. Строка разделителя строк определяется системным свойством line.separator, и это не обязательно одиночный символ новой строки (’\n’).
Вызывает: java.io.IOException
public abstract void println(boolean x)
Печатает булево значение и затем заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(boolean b), а затем - public abstract void println().
Вызывает: java.io.IOException
public abstract void println(char x)
Печатает символ и затем заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(char c), а затем - public abstract void println().
Вызывает: java.io.IOException
public abstract void println(char[] x)
Печатает массив символов и затем заканчивает строку. Это метод ведёт себя так, будто он вызывает print(char[]) и затем println().
Вызывает: java.io.IOException
public abstract void println(double x)
Печатает число двойной точности с плавающей точкой и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(double d)
и затем public abstract void println().
Вызывает: java.io.IOException
public abstract void println(float x)
Печатает число с плавающей точкой и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(float f) и затем public abstract void println().
Вызывает: java.io.IOException
public abstract void println(int x)
Печатает целое число и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(int i) и затем public abstract void println().
Вызывает: java.io.IOException
public abstract void println(long x)
Печатает длинное целое и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(long l) и затем public abstract void println().
Вызывает: java.io.IOException
public abstract void println(java.lang.Object x)
Печатает Object и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(java.lang.Object obj) и затем public abstract void println().
Вызывает: java.io.IOException
public abstract void println(java.lang.String x)
Печатает String и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(java.lang.String s) и затем public abstract void println().
Вызывает: java.io.IOException
JSP.9.2 Неявные Объекты
Объекты PageContext и JspWriter доступны по умолчанию в качестве неявных объектов.
JSP.9.3 Пример Реализации
Экземпляр зависящего от реализации подкласса этого абстрактного базового класса может быть создан классом реализации JSP в начале её метода _jspService()
через JspFactory по умолчанию для данной реализации.
Вот пример использования этих классов:
public class foo implements Servlet {
// ...
public void _jspService(HttpServletRequest request, HttpServletResponse response)
throws IOException, ServletException {
JspFactory factory = JspFactory.getDefaultFactory();
PageContext pageContext = factory.getPageContext(
this,
request,
response,
null, // errorPageURL
false, // needsSession
JspWriter.DEFAULT_BUFFER,
true // autoFlush
);
// инициализируются неявные переменные среды скриптинга ...
HttpSession session = pageContext.getSession();
JspWriter out = pageContext.getOut();
Object page = this;
try {
// здесь тело транслированной JSP ...
} catch (Exception e) {
out.clear();
pageContext.handlePageException(e);
} finally {
out.close();
factory.releasePageContext(pageContext);
}
}
JSP.9.4.1 JspException
Синтаксис
public class JspException extends java.lang.Exception
Прямые/Direct Известные Подклассы: JspTagException
Все Реализованные Интерфейсы: java.io.Serializable
Описание
Родовое исключение, известное JSP-машине; неотловленное JspExceptions даст вызов механизма errorpage.
JSP.9.4.1.13 Конструкторы
public JspException()
Конструирует JspException.
public JspException(java.lang.String msg)
Конструирует новое JSP-исключение со специфицированным сообщением. Сообщение может быть записано в server log-файл и/или выводится пользователю.
Параметры:
msg - String, специфицирующая текст сообщения об исключении.
public JspException(java.lang.String message, java.lang.Throwable rootCause)
Конструирует новое JSP-исключение, если JSP нужно вызвать исключение и вставить сообщение о “причине” исключения, помешавшего нормальному ходу операции, включая описательное сообщение.
Параметры:
message - String, содержащая текст сообщения об исключении.
rootCause - исключение Throwable, нарушившее нормальную работу сервлета; делает это исключение сервлета необходимым.
public JspException(java.lang.Throwable rootCause)
Конструирует новое JSP-исключение, если JSP нужно вызвать исключение и вставить сообщение о “причине” исключения, помешавшего нормальному ходу операции. Сообщение об исключении базируется на локализованном сообщении об вызвавшем его исключении.
Этот метод вызывает метод getLocalizedMessage в исключении Throwable для получения локализованного сообщения об исключении. При создании подкласса для JspException, этот метод может быть переопределён для создания сообщения об исключении, разработанного для определённой страны (языка и т.п.).
Параметры:
rootCause - исключение Throwable, нарушившее нормальную работу JSP-операции, ; делает это JSP-исключение необходимым.
JSP.9.4.1.14 Методы
public java.lang.Throwable getRootCause()
Возвращает исключение, вызвавшее это JSP-исключение.
Возвращает: Throwable, вызывавшее это JSP-исключение.
JSP.9.4.2 JspTagException
Синтаксис
public class JspTagException extends JspException
Все Реализованные Интерфейсы: java.io.Serializable
Описание
Исключение используется Tag Handler/Обработчиком Тэга для обозначения неисправимой ошибки. Эта ошибка отлавливается на верхнем уровне JSP-страницы и выдаёт страницу для ошибок/errorpage.
JSP.9.4.2.15 Конструкторы
public JspTagException()
Нет сообщения.
public JspTagException(java.lang.String msg)
Конструктор с сообщением...
JSP.9.4 Исключения
Класс JspException является базовым классом для всех JSP-исключений. JspTag-Exception используется механизмом исключения тэга.
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.
