Версия для печати

Архив документации на OpenNet.ru / Раздел "Web мастеру, CGI, Perl, PHP, Apache" (Многостраничная версия)

Перевод руководства по JavaServer Pages JSP 1.2


Оригинал: pyramidin.narod.ru
Перевод: Александр Пирамидин

 

Спецификация
JavaServer Pages (JSP)

Версия: 1.2


Пожалуйста, направляйте комментарии по e-mail:  jsp-spec-comments@eng.sun.com


и переводчику: a_pyramidin@yahoo.com (Александр Пирамидин)



Понедельник, 27 августа, 2001 г.
Редактор: Eduardo Pelegrí-Llopart.

901 San Antonio Road
Palo Alto, CA 94303 USA
650 960-1300 факс: 650 969-9131


Статус: FCS


Релиз: 17 сентября 2001 г.

Copyright 2001 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, California 94303, U.S.A.
Все Права Зарезервированы.

ЛИЦЕНЗИЯ

Данная Спецификация защищена авторскими правами, и информация, приведённая здесь, может быть защищена одним или более патентами США, иностранными патентами или задействованными приложениями.

За исключением случаев, указанных в данной лицензии, никакая часть данной Спецификации не может воспроизводиться в любой форме и любым способом без наличия предварительного письменной авторизации Sun Microsystems, Inc. ("Sun") и её лицензоров, если имеются.

Любая часть данной Спецификации и описанной здесь информации управляется терминами и условиями данной лицензии и Export Control Guidelines, как установлено ранее в Terms of Use на сайте Sun.

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

Настоящим документом Sun предоставляет Вам лицензию на бесплатное, неисключительное пользование без права передачи (без права на сублицензию), с сохранением прав интеллектуальной собственности Sun, что является непременным условием использования данной Спецификации для внутренних целей дизайна и разработки Ваших Java-аплетов и приложений, предназначенных для работы на платформе Java, или для создания чисто рабочих реализаций данной Спецификации, которые:

(i) полную реализацию текущей версии Спецификации без подразделения или объединения её;
(ii) реализует весь интерфейс и функциональность данной Спецификации без подразделения или объединения её;
(iii) включают полную реализацию всех необязательных компонентов (как определено Спецификацией), которые Вы выбрали для реализации, без подразделения или объединения;
(iv) реализует все интерфейсы и функциональность таких необязательных компонентов без подразделения или объединения;
(v) не добавляют никаких дополнительных пакетов, классов или интерфейсов к пакетам "java.*" или "javax.*" или подпакетам или другим пакетам, определённым в данной Спецификации;
(vi) удовлетворяют всем требованиям тестирования, доступным от Sun, относящимся к самой последней версии данной Спецификации, опубликованной за шесть (6) месяцев до любого релиза реализации такой чисто рабочей реализации или обновления до неё;
(vii) не происходят от какого-либо кода-источника Sun или кодов двоичных материалов; и
(viii) не включает какого-либо первичного кода Sun или кодов двоичных материалов без отдельной соответствующей лицензии Sun. Данная Спецификация содержит информацию о правах собственности Sun и может использоваться только в соответствии с данной лицензией.

Действие данной лицензии оканчивается немедленно без предупреждения от Sun, если Вы не согласны с каким-либо из условий данной лицензии. После окончания или истечения срока действия данной лицензии Вы обязаны исключить использование или уничтожить имеющуюся у Вас Спецификацию.

ТОРГОВЫЕ МАРКИ

Никакие права названия или интересы торговых марок, сервисных марок или торговых имён Sun или лицензоров Sun не передаются по данному соглашению.

Sun, Sun Microsystems, логотип Sun, Java, логотип Java Coffee Cup, JSP и JavaServer Pages являются торговыми марками или зарегистрированными торговыми марками Sun Microsystems, Inc. в США и других странах.

ОГРАНИЧЕННАЯ ГАРАНТИЯ

ДАННАЯ СПЕЦИФИКАЦИЯ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ". SUN НЕ ДА╗Т НИКАКИХ ГАРАНТИЙ, ЯВНЫХ ИЛИ КОСВЕННЫХ (ВКЛЮЧАЯ - НО НЕ ОГРАНИЧИВАЯСЬ ИМИ - ГАРАНТИИ РЕАЛИЗУЕМОСТИ), СООТВЕТСТВИЯ ОПРЕДЕЛ╗ННОМУ НАЗНАЧЕНИЮ ИЛИ НЕНАРУШЕНИЯ УСЛОВИЙ, ЧТО СОДЕРЖИМОЕ ДАННОЙ СПЕЦИФИКАЦИИ ПОДХОДИТ ДЛЯ КАКИХ-ЛИБО ЦЕЛЕЙ ИЛИ ЧТО ЛЮБОЕ ИСПОЛЬЗОВАНИЕ ИЛИ РЕАЛИЗАЦИЯ ТАКОГО СОДЕРЖИМОГО НЕ БУДЕТ НАРУШАТЬ КАКИХ-ЛИБО ПАТЕНТОВ ТРЕТЬЕЙ СТОРОНЫ, АВТОРСКИХ ПРАВ, КОММЕРЧЕСКОЙ ТАЙНЫ ИЛИ ИНЫХ ПРАВ.
 

Данный документ не содержит каких-либо обязательств на реализацию или выпуск какой-либо части данной Спецификации в каком-либо продукте.


ДАННАЯ СПЕЦИФИКАЦИЯ МОЖЕТ СОДЕРЖАТЬ ТЕХНИЧЕСКИЕ НЕТОЧНОСТИ ИЛИ ТИПОГРАФСКИЕ ОШИБКИ. ИЗМЕНЕНИЯ ПЕРИОДИЧЕСКИ ДОБАВЛЯЮТСЯ К ИМЕЮЩЕЙСЯ ИНФОРМАЦИИ; ЭТИ ИЗМЕНЕНИЯ БУДУТ ВНЕДРЕНЫ В НОВЫЕ ВЕРСИИ ДАННОЙ СПЕЦИФИКАЦИИ, ЕСЛИ ОНИ (ВЕРСИИ) ПОЯВЯТСЯ. SUN МОЖЕТ В ЛЮБОЕ ВРЕМЯ ДЕЛАТЬ УЛУЧШЕНИЯ И/ИЛИ ВНОСИТЬ ИЗМЕНЕНИЯ В ПРОДУКТЫ И/ИЛИ ПРОГРАММЫ, ОПИСАННЫЕ В ДАННОЙ СПЕЦИФИКАЦИИ.

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

ОГРАНИЧЕНИЕ ОТВЕТСТВЕННОСТИ

В ДОПОЛНЕНИЕ К НЕ ЗАПРЕЩ╗ННОМУ ЗАКОНОМ, НИ ПРИ КАКИХ СОБЫТИЯХ SUN ИЛИ Е╗ ЛИЦЕНЗОРЫ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБОЙ УЩЕРБ, ВКЛЮЧАЯ, БЕЗ ОГРАНИЧЕНИЯ, УПУЩЕННУЮ ВЫГОДУ, ПОТЕРЮ ДАННЫХ ИЛИ ЗА ПРИЧИН╗ННЫЙ, КОСВЕННЫЙ, ПОСЛЕДУЮЩИЙ, СЛУЧАЙНЫЙ ИЛИ УМЫШЛЕННЫЙ ВРЕД, НАНЕС╗ННЫЙ КАКИМ-ЛИБО ОБРАЗОМ, ВНЕ ЗАВИСИМОСТИ ОТ ПРАВИЛ ОБ ОТВЕТСТВЕННОСТИ, ПРИЧИН╗ННЫЙ ИЛИ ОТНОСЯЩИЙСЯ К: ЛЮБОМУ ОБОРУДОВАНИЮ, ИСПОЛЬЗОВАНИЮ, МОДИФИЦИРОВАНИЮ ИЛИ ИНОМУ ИСПОЛЬЗОВАНИЮ ДАННОЙ СПЕЦИФИКАЦИИ, ДАЖЕ ЕСЛИ SUN И/ИЛИ Е╗ ЛИЦЕНЗОРЫ БЫЛИ УВЕДОМЛЕНЫ О ВОЗМОЖНОСТИ ТАКОГО УЩЕРБА/ВРЕДА.


Вы страхуете и защищаете Sun и её лицензоров от любых претензий, являющихся результатом:

(i) Вашего использования данной Спецификации;
(ii) использования или распространения Ваших Java-приложений, аплетов и/или чисто рабочих реализаций; и/или
(iii) любых претензий, которые могут явиться результатом несовместимости последующих версий или релизов любой Спецификации, использованной Вами, со Спецификацией, предоставленной Вам по данному соглашению.

ОГРАНИЧЕННЫЕ ПРАВА

Правительство США: Если данная Спецификация получена от имени или для Правительства США первичным контрактором или субконтрактором Правительства США (любого уровня), тогда права Правительства в области Программного Обеспечения и сопутствующей документации будут действовать так, как описано ранее в данной лицензии; это действует в соответствии с правилами от 48 C.F.R. 227.7201 до 227.7202-4 (для приобретений Департамента Обороны/Department of Defense (DoD)) и в соответствии с правилами 48 C.F.R. 2.101 и 12.212 (для приобретений не Департамента Обороны).

КУДА СООБЩИТЬ

Вы можете сообщить о какой-либо неоднозначности, неполноте или неточностях в связи с использованием Вами данной Спецификации ("Обратная Связь/Feedback"). В связи с тем, что Вы направляете Sun информацию Feedback, Вы, кроме того:

(i) согласны с тем, что эта информация предоставляется Вами на некоммерческой и неконфиденциальной основе, и
(ii) предоставляете Sun бессрочное, неисключительное, всемирно действующее, неотзываемое разрешение безвозмездно, с правом сублицензирования на несколько уровней сублицензирования, внедрять, публиковать и использовать без ограничений Feedback для любых целей, относящихся к данной Спецификации и её последующим версиям, реализациям, и утилитам тестирования.

Статус


Это спецификация JSP 1.2, разработанная группой экспертов JSR053 как часть процесса Java Community Process (детали - по адресу http://jcp.org/jsr/detail/53.jsp).

JSP.S.1  Процессы Сообщества Java

JCP создаёт спецификации, используя три сообщества: сообщество экспертов (the expert group),  participants\участники JCP и public\публика вообще.

Эксперты является авторами спецификаций, создавая проекты/drafts.

Проекты
проходят путь от экспертов, через участников, к публике, постепенно совершенствуясь в деталях, всегда возвращая комментарии обратно группе экспертов; final draft/окончательный проект отправляется для одобрения в Executive Committee\Исполнительный Комитет.

Лидер группы экспертов
отвечает за облегчение работы группы экспертов, авторизацию спецификации и за организацию reference implementation\справочной реализации и conformance test suite\блока тестирования на соответствие.

JSP.S.2   JCP и Эта Спецификация

JCP разработан как чрезвычайно гибкий процесс, так что каждая группа экспертов может адресовать требования специфического сообщества, обслуживаемого ею. Справочная реализация JSP 1.2 и Servlet 2.3 использует код, который разрабатывается как открытый проект-ресурс по соглашению с Apache Software Foundation.

Данная спецификация содержит главы, которые получены непосредственно из комментариев javadoc в классах API, но там, где имеются расхождения, данная спецификация имеет преимущество над комментариями javadoc.


Процесс JCP предоставляет механизм обновления спецификации в процессе поддержки через Erratas\Списки Ошибок. Если они имеются, эти списки имеют приоритет над данной спецификацией.


Приложения C и D являются нормативными; остальные приложения являются ненормативными.

 

Предисловие


Этот документ является спецификацией JavaServer Pagesтм 1.2 (JSP 1.2).


Данная Спецификация была разработана как часть процесса Java Community Process (JCP). Комментарии от Экспертов, Участников и Публики были рассмотрены, и все изменения были внесены в спецификацию, где это было необходимо.

JSP.P.1 Сравнение с JSP 1.1

JSP 1.2 расширяет Спецификацию JavaServer Pagesтм 1.1 (JSP 1.1) следующим образом:

JSP.P.2  Лицензирование Спецификации

Детали условий, по которым данный документ распространяется, даны в лицензии.

JSP.P.3  Для кого предназначен этот документ

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

JSP.P.4  Родственные Документы

Разработчики контейнеров JSP и авторы страниц JSP могут найти необходимую информацию также в следующих документах:

Таблица  JSP.P-1  Некоторые Родственные Web-Сайты
Домашняя страница JSP:  http://java.sun.com/products/jsp
Домашняя страница Servlet:  http://java.sun.com/products/servlet
Java 2 Platform, Standard Edition::  http://java.sun.com/products/jdk/1.3
Java 2 Platform, Enterprise Edition:  http://java.sun.com/j2ee
Домашняя страница XML на платформе Java:  http://java.sun.com/xml
Домашняя страница JavaBeans≥:  http://java.sun.com/beans
Домашняя страница XML на W3C:  http://www.w3.org/XML
Домашняя страница HTML на W3C:  http://www.w3.org/MarkUp
Домашняя страница XML.org:  http://www.xml.org

JSP.P.5  Немного Истории

Пионерами, выполнившими начальную работу по платформе Java, относящуюся к данной Спецификации, были: James Gosling, работавший над Web Server в Java в 1994/1995 гг. - основой сервлетов.

Расширенный проект был начат в 1996 г. Pavani Diwanji - ведущим инженером - и многими другими ключевыми участниками, перечисленными ниже. Результатом работы над этим проектом стал продукт Java Web Server компании Sun.

Некоторые проекты начались в 1999 г.. Группа экспертов по сервлетам во главе с James Davidson выпустила спецификации: Servlet 2.1 - в январе и Servlet 2.2 в декабре, а группа JSP во главе с Larry Cable и Eduardo Pelegri-Llopart выпустила JSP 1.0 в июне и JSP 1.1 - в декабре.

Год 2000 ознаменовался большим количеством разработок: многочисленные реализации контейнеров, утилит, книг и тренировочных материалов по JSP 1.1, Servlet 2.2 и платформе Java 2 Enterprise Edition. Интенсивно разрабатывались библиотеки тэгов и различные усовершенствования. Внедрение технологии JSP продолжилось в 2001 году по многим направлениям Web и сервиса JavaOne.

Проследить развитие печатной продукции весьма трудно; лучше всего это сделано на сайте  http://java.sun.com/products/jsp.

JSP.P.6  Благодарности

Успех Java Platform обусловлен деятельностью Java Community Process по её разработке. Этот процесс, вовлёкший в свою орбиту множество людей и корпораций, продвигает разработку высококачественных спецификаций эпохи Internet.


Хотя невозможно перечислить всех участвовавших в разработке этой версии Спецификации, мы хотели бы поблагодарить всех членов нашей экспертной группы. Мы использовали преимущества большой активной группы экспертов, без которой спецификации JSP не были бы созданы.


Мы хотим поблагодарить:

Alex Yiu, Alex Chaffee, Allan Scott, Amit Kishnani, Bill dehOra, Bjorn Carlson, Bob Foster, Chris Hansen, Clement Wong, Craig McClanahan, Dano Ferrin, Danny Coward, Dave Brown, Edwin Smith, Francios Jouaux, Frank Biederich, Govind Seshadri, Hans Bergsten, Howard Melman, James Strachan, Jason McGeee, Jason Hunter, Jeff Mischkinsky, Jon Rousseau, Julie Basu, Karl Avedal, Kevin Jones, Larry Cable, Larry Isaas, Magnus Rydin, Magnus Stenman, Mark Wallace, Miles Sabin, Misha Davidson, Murty Chintalapati, Nathan Abamson, Nic Ferrier, Olli Blackburn, Paul Bonfanti, Peter Petersen, Petr Jiricka, Pier Paolo Fumagalli, Pierre Delisle, Ramesh Mandava, Rod Magnuson, Sam Pullara, Satoshi Kikuchi, Scott Ferguson, Scott Snyder, Simeon Simeonov, Stephanie Bodoff, Stefano Mazzocchi, Tim Ampe, Tom Reilly, Vince Bonfanti.


Мы благодарим всё сообщество, разрабатывавшее пробные реализации, и продавцов, выпускавших утилиты авторизации и библиотеки тэгов.


Отдельно упомянем Scott Ferguson, Bob Foster, Stefano Mazzocchi и Ricardo Rocha и их работу по Главе 5. Bob Foster заслуживает благодарности за ОТД& XSchema, а сообщество Cocoon - за Cocoon & XSP. Наши благодарности Jess Holle за кропотливую работу над статьями в Главе JSP.3.


Мы хотим поблагодарить также всех авторов книг о JSP и создателей web-сайтов, отслеживавших и облегчавших работу по созданию сообщества JSP.


Редактор особо признателен участникам Java Platform Group, в особенности - James, Jon, Mala, Jeff, Connie и Graham.


Наконец, мы благодарим разработчиков программного обеспечения, web-авторов и членов группы public, прочитавших эту спецификацию, использовавших пробную реализацию и поделившихся своим опытом.

Благодаря вам, появилась технология JavaServerPages.
 


Оглавление


Статус
Предисловие

JSP.1 Обзор

JSP.2 Синтаксис Ядра и Семантика

JSP.3 Вопросы Локализации

JSP.4 Стандартные Акции

JSP.5 JSP-Документы

JSP.6 Скриптинг

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

JSP.8  JSP-Контейнер

JSP.9   Основной API

JSP.10  API  Развёртывания Тэгов

JSP.A Упаковка (Архивирование) JSP -Страниц

JSP.B  ОТД/DTD и Схема для Синтаксиса XML

JSP.C  ОТД для TagLibrary-Дескриптора, JSP 1.2

C.1 ОТД для Файлов TagLibrary-Дескриптора

JSP.D  ОТД для TagLibrary-Дескриптора, JSP 1.1

D.1 ОТД для Файлов TagLibrary-Дескриптора

JSP.E  Изменения

JSP.F  Словарь


Приложение JSP.B

ОТД
(Определение Типа Данных)
и Схема для Синтаксиса XML


Это приложение содержит ОТД и XSchema для JSP-страниц с синтаксисом XML.


Это приложение не является нормативным.


Как указано в Разделе JSP.5.4, ОТД не является хорошим описанием, пригодным для проверки документа, использующего пространства имён, типа JSP-страницы с синтаксисом XML, но то, что многие читатели знакомы с ним, делает, тем не менее, возможным её использование.

B.1 ОТД для Документов JSP

Далее идут ОТД для JSP-документов. Поскольку JSP-документ "знает" о пространстве имён, это ОТД включено здесь просто для информационных целей.
 

<!-- ОТД для JSP 1.2 -->

<!--

Это ОТД не является объектом условия или параметра во внутреннем поднаборе и не экспортирует никаких общих объектов.

-->

<!-- Constrained Names/Ограниченные Имена -->

<!ENTITY % URI "CDATA">

<!-- Uniform Resource Identifier, см. [RFC2396] -->

<!ENTITY % UriList "CDATA">

<!-- список разделённых пробелами Uniform Resource Identifiers -->

<!ENTITY % URL "CDATA">

<!-- относительный urlSpec, см. в Разделе 2.10.2. -->

<!ENTITY % BeanID "IDREF">

<!-- ранее объявленный ID боба в текущей области видимости -->

<!ENTITY % Prefix "CDATA">

<!-- Name, не содежащее символов :  -->

<!ENTITY % ClassName "CDATA">

<!-- полное квалифицированное имя класса -->

<!ENTITY % TypeName "CDATA">

<!-- полное квалифицированное имя класса или интерфейса -->

<!ENTITY % BeanName "CDATA">

<!-- имя боба/bean, как предполагается методом java.beans.Beans instantiate(). -->

<!ENTITY % Content "CDATA">

<!-- MIME-тип с последующим набором символов IANA, как " type [; S? ['charset='] char-set]

" -->

<!ENTITY % Length "CDATA">

<!-- nn для пикселной или nn% для процентной величины -->

<!ENTITY % Pixels "CDATA">

<!-- целое, представляющее величину в пикселах -->

<!ENTITY % Bool "(true|false|yes|no)">

<!-- булев -->

<!-- используется для object, applet, img, input и iframe -->

<!ENTITY % ImgAlign "(top|middle|bottom|left|right)">

<!-- Группы Элементов -->

<!ENTITY % Directives "jsp:directive.page|jsp:directive.include">

<!ENTITY % Scripts "jsp:scriptlet|jsp:declaration|jsp:expression">

<!ENTITY % Actions "jsp:useBean|jsp:setProperty|jsp:getProperty|jsp:include

|jsp:forward|jsp:plugin">

<!ENTITY % Body "(jsp:text|%Directives;|%Scripts;|%Actions;)*">

<!-- Элемент -->

<!-- Корневой элемент JSP-страницы.-->

<!ELEMENT jsp:root %Body;>

<!ATTLIST jsp:root

xmlns:jsp CDATA "http://java.sun.com/JSP/Page"

version CDATA #REQUIRED

>

<!ELEMENT jsp:directive.page EMPTY>

<!ATTLIST jsp:directive.page

language CDATA "java"

extends %ClassName; #IMPLIED

contentType %Content; "text/html; ISO-8859-1"

import CDATA #IMPLIED

session %Bool; "true"

buffer CDATA "8kb"

autoFlush %Bool; "true"

isThreadSafe %Bool; "true"

info CDATA #IMPLIED

errorPage %URL; #IMPLIED

isErrorPage %Bool; "false"

>

<!-- элемент jsp:directive.include появляется только в JSP-документах и не появляется

в XML-просмотрах JSP-страниц -->

<!ELEMENT jsp:directive.include EMPTY>

<!ATTLIST jsp:directive.include

file %URI; #REQUIRED

>

<!ELEMENT jsp:scriptlet (#PCDATA)>

<!ELEMENT jsp:declaration (#PCDATA)>

<!ELEMENT jsp:expression (#PCDATA)>

<!ELEMENT jsp:useBean %Body;>

<!ATTLIST jsp:useBean

id ID #REQUIRED

class %ClassName; #IMPLIED

type %TypeName; #IMPLIED

beanName %BeanName; #IMPLIED

scope (page

|session

|request

|application) "page"

>

<!ELEMENT jsp:setProperty EMPTY>

<!ATTLIST jsp:setProperty

name %BeanID; #REQUIRED

property CDATA #REQUIRED

value CDATA #IMPLIED

param CDATA #IMPLIED

>

<!ELEMENT jsp:getProperty EMPTY>

<!ATTLIST jsp:getProperty

name %BeanID; #REQUIRED

property CDATA #REQUIRED

>

<!ELEMENT jsp:include (jsp:param*)>

<!ATTLIST jsp:include

flush %Bool; "false"

page %URL; #REQUIRED

>

<!ELEMENT jsp:forward (jsp:param*)>

<!ATTLIST jsp:forward

page %URL; #REQUIRED

>

<!ELEMENT jsp:plugin (jsp:params?, jsp:fallback?)>

<!ATTLIST jsp:plugin

type (bean|applet) #REQUIRED

code %URI; #IMPLIED

codebase %URI; #IMPLIED

align %ImgAlign; #IMPLIED

archive %UriList; #IMPLIED

height %Length; #IMPLIED

hspace %Pixels; #IMPLIED

jreversion CDATA "1.2"

name NMTOKEN #IMPLIED

vspace %Pixels; #IMPLIED

width %Length; #IMPLIED

nspluginurl %URI; #IMPLIED

iepluginurl %URI; #IMPLIED

>

<!ELEMENT jsp:params (jsp:param+)>

<!ELEMENT jsp:param EMPTY>

<!ATTLIST jsp:param

name CDATA #REQUIRED

value CDATA #REQUIRED

>

<!ELEMENT jsp:text #PCDATA>

B.2 XSchema-Описание для Документов JSP

Далее идёт описание, использующее XML Schema:
 

<?xml version ="1.0"?>

<!DOCTYPE schema [

<!-- Патэрны -->

<!ENTITY Identifier "(\p{L}|_|$)(\p{N}|\p{L}|_|$)*">

<!ENTITY TypeName "&Identifier;(\.&Identifier;)*">

<!ENTITY WS "\s*">

<!ENTITY Import "&TypeName;(\.\*)?">

<!ENTITY ImportList "&Import;(&WS;,&WS;&Import;)*">

<!ENTITY SetProp "(&Identifier;|\*)">

<!ENTITY RelativeURL "[^:#/\?]*(:{0,0}|[#/\?].*)">

<!ENTITY Length "[0-9]*&#x25;?">

<!ENTITY AsciiName "[A-Za-z0-9_-]*">

<!ENTITY ValidContentType

"&AsciiName;/&AsciiName;(;&WS;(charset=)?&AsciiName;)?">

<!ENTITY ValidPageEncoding "&AsciiName;/&AsciiName;">

<!ENTITY Buffer "[0-9]+kb">

<!ENTITY RTexpr "&#x25;=.*&#x25;">

]>

<!--Соответствует w3c http://www.w3.org/2001/XMLSchema -->

<xsd:schema

xmlns = "http://java.sun.com/JSP/Page"

xmlns:xsd = "http://www.w3.org/2001/XMLSchema"

xmlns:jsp = "http://java.sun.com/JSP/Page"

targetNamespace = "http://java.sun.com/JSP/Page"

elementFormDefault = "qualified"

attributeFormDefault = "unqualified">

<xsd:annotation>

<xsd:documentation>

XML Schema для JSP 1.2.

Эта схема базируется на последних (от 5 мая 2001) Рекомендациях W3C по XML Schema.

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

</xsd:documentation>

</xsd:annotation>

<!-- Сложные Типы -->

<xsd:complexType name = "Body">

<xsd:annotation>

<xsd:documentation>

Body определяет элементы "верхнего уровня/top-level" в root и beanInfo.

Возможно есть другие элементы, которые должны его использовать.

</xsd:documentation>

</xsd:annotation>

<xsd:group ref = "Bodygroup" minOccurs = "0" maxOccurs = "unbounded"/>

</xsd:complexType>

<xsd:complexType name = "BasicType">

<xsd:simpleContent>

<xsd:extension base = "xsd:string">

<xsd:attribute ref = "jsp:id"/>

</xsd:extension>

</xsd:simpleContent>

</xsd:complexType>

<!-- группы -->

<xsd:group name = "Bodygroup">

<xsd:choice>

<xsd:element ref = "directive.page"/>

<xsd:element ref = "directive.include"/>

<xsd:element ref = "scriptlet"/>

<xsd:element ref = "declaration"/>

<xsd:element ref = "expression"/>

<xsd:element ref = "useBean"/>

<xsd:element ref = "setProperty"/>

<xsd:element ref = "getProperty"/>

<xsd:element ref = "include"/>

<xsd:element ref = "forward"/>

<xsd:element ref = "plugin"/>

<xsd:element ref = "text"/>

<xsd:any namespace="##other" processContents = "lax"/>

</xsd:choice>

</xsd:group>

<!-- jsp:id attribute -->

<xsd:attribute name = "id" type = "xsd:string"/>

<!--Должно иметься ограничение, что jsp:id является уникальным среди всех элементов документа. -->

<!-- Далее идут простые типы -->

<xsd:simpleType name = "RTE">

<xsd:annotation>

<xsd:documentation>

Значение выражения времени запроса

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&RTexpr;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "Bool">

<xsd:annotation>

<xsd:documentation>

Bool мог бы быть булевым, если бы принимал 1 и 0.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:NMTOKEN" >

<xsd:enumeration value = "true"/>

<xsd:enumeration value = "false"/>

<xsd:enumeration value = "yes"/>

<xsd:enumeration value = "no"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "Identifier">

<xsd:annotation>

<xsd:documentation>

Identifier это неквалифицированный Java-идентификатор.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&Identifier;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "TypeName">

<xsd:annotation>

<xsd:documentation>

TypeName это один или более Java-идентификаторов, разделённых точками без пробелов.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&TypeName;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "ImportList">

<xsd:annotation>

<xsd:documentation>

ImportList это один или более typeNames, разделённых запятыми.

Допускаются пробелы до и после запятой.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&ImportList;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "SetProp">

<xsd:annotation>

<xsd:documentation>

SetProp это Identifier или *.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&SetProp;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "RelativeURL">

<xsd:annotation>

<xsd:documentation>

RelativeURL это uriReference без символов двоеточия до первой  /, ? или #, если имеются (RFC2396).

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:anyURI">

<xsd:pattern value = "&RelativeURL;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "RTERelativeURL">

<xsd:union memberTypes = "RelativeURL RTE"/>

</xsd:simpleType>

<xsd:simpleType name = "Length">

<xsd:annotation>

<xsd:documentation>

Length это nn или nn%.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&Length;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "ExplicitBufferSize">

<xsd:annotation>

<xsd:documentation>

Размер Буфера с точным значением.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&Buffer;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "NoneBufferSize">

<xsd:annotation>

<xsd:documentation>

Размер Буфера/Buffer Size со значением "none".

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:enumeration value = "none"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "BufferSize">

<xsd:annotation>

<xsd:documentation>

Размер Буфера имеет значение xkb или none.

</xsd:documentation>

</xsd:annotation>

<xsd:union memberTypes = "ExplicitBufferSize NoneBufferSize"/>

</xsd:simpleType>

<xsd:simpleType name = "ContentType">

<xsd:annotation>

<xsd:documentation>

Contetn Type/Тип Содержимого для данной страницы.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&ValidContentType;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "PageEncoding">

<xsd:annotation>

<xsd:documentation>

Кодировка Страницы/Page Encoding для данной страницы. По умолчанию - та же, что и в ContentType.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:string">

<xsd:pattern value = "&ValidPageEncoding;"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "Scope">

<xsd:annotation>

<xsd:documentation>

верные значения scope

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:NMTOKEN">

<xsd:enumeration value = "page"/>

<xsd:enumeration value = "session"/>

<xsd:enumeration value = "request"/>

<xsd:enumeration value = "application"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "PlugInType">

<xsd:annotation>

<xsd:documentation>

верные значения типа plugin'а

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:NMTOKEN">

<xsd:enumeration value = "bean"/>

<xsd:enumeration value = "applet"/>

</xsd:restriction>

</xsd:simpleType>

<xsd:simpleType name = "AlignType">

<xsd:annotation>

<xsd:documentation>

Размер буфера - xkb.

</xsd:documentation>

</xsd:annotation>

<xsd:restriction base = "xsd:NMTOKEN">

<xsd:enumeration value = "top"/>

<xsd:enumeration value = "middle"/>

<xsd:enumeration value = "bottom"/>

<xsd:enumeration value = "left"/>

<xsd:enumeration value = "right"/>

</xsd:restriction>

</xsd:simpleType>

<!-- Элементы -->

<xsd:element name = "root">

<xsd:annotation>

<xsd:documentation>

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

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://java.sun.com/JSP/Page xsd-file-location"

Документы не должны специфицировать системный идентификатор DTD/ОТД

- Определении Типа Данных - в объявлении DOCTYPE.

</xsd:documentation>

</xsd:annotation>

<xsd:complexType>

<xsd:complexContent>

<xsd:extension base = "Body">

<xsd:attribute name = "version" fixed = "1.2" type = "xsd:string"/>

</xsd:extension>

</xsd:complexContent>

</xsd:complexType>

</xsd:element>

<xsd:element name = "directive.page">

<xsd:annotation>

<xsd:documentation>

directive.page это "директива page".

</xsd:documentation>

</xsd:annotation>

<xsd:complexType>

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "language" default = "java" type = "xsd:string"/>

<xsd:attribute name = "extends" type = "TypeName"/>

<xsd:attribute name = "contentType"

default = "text/html; ISO-8859-1" type = "ContentType"/>

<xsd:attribute name = "pageEncoding"

use = "optional" type = "PageEncoding"/>

<xsd:attribute name = "import" type = "ImportList"/>

<xsd:attribute name = "session" default = "true" type = "Bool"/>

<xsd:attribute name = "buffer" default = "8kb" type = "BufferSize"/>

<xsd:attribute name = "autoFlush" default = "true" type = "Bool"/>

<xsd:attribute name = "isThreadSafe" default = "true" type = "Bool"/>

<xsd:attribute name = "info" type = "xsd:string"/>

<xsd:attribute name = "errorPage" type = "RelativeURL"/>

<xsd:attribute name = "isErrorPage" default = "false" type = "Bool"/>

</xsd:complexType>

</xsd:element>

<xsd:element name = "directive.include">

<xsd:annotation>

<xsd:documentation>

directive.include это "директива include".

Этот элемент не появляется в XML-просмотре JSP-страниц.

</xsd:documentation>

</xsd:annotation>

<xsd:complexType>

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "file" use = "required" type = "RelativeURL"/>

</xsd:complexType>

</xsd:element>

<xsd:element name = "scriptlet" type = "BasicType">

<xsd:annotation>

<xsd:documentation>

Представление скриптлета.

</xsd:documentation>

</xsd:annotation>

</xsd:element>

<xsd:element name = "declaration" type = "BasicType">

<xsd:annotation>

<xsd:documentation>

Представление объявления.

</xsd:documentation>

</xsd:annotation>

</xsd:element>

<xsd:element name = "expression" type = "BasicType">

<xsd:annotation>

<xsd:documentation>

Представление выражения.

</xsd:documentation>

</xsd:annotation>

</xsd:element>

<xsd:element name = "text" type = "BasicType">

<xsd:annotation>

<xsd:documentation>

Точно переданный шаблонный текст.

</xsd:documentation>

</xsd:annotation>

</xsd:element>

<xsd:element name = "useBean">

<xsd:annotation>

<xsd:documentation>

useBean инстанциирует или имеет доступ к bean в специфицированной области видимости.

Ограничение: Допустимыми комбинациями атрибутов являются:

class [type] | type [( class | beanName)]

</xsd:documentation>

</xsd:annotation>

<xsd:complexType>

<xsd:complexContent>

<xsd:extension base="Body">

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "id" use = "required" type = "Identifier"/>

<xsd:attribute name = "class" type = "TypeName"/>

<xsd:attribute name = "type" type = "TypeName"/>

<xsd:attribute name = "beanName" type = "TypeName"/>

<xsd:attribute name = "scope" default = "page" type = "Scope"/>

</xsd:extension>

</xsd:complexContent>

</xsd:complexType>

</xsd:element>

<xsd:element name = "setProperty">

<xsd:annotation>

<xsd:documentation>

setProperty изменяет значение  свойства объекта.

Ограничение: Именованный объект обязан быть

"представлен" JSP-процессору через использование либо

акции jsp:useBean, либо специальной акции с ассоциированным

входом VariableInfo для этого имени.

Точные верные комбинации не выражаются в XML Schema.

Это:

name="Identifier" property="*"

name="Identifier" property="Identfiier" param="string"

name="Identifier" property="Identifier" value="string"

</xsd:documentation>

</xsd:annotation>

<xsd:complexType>

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "name" use = "required" type = "Identifier"/>

<xsd:attribute name = "property" use = "required" type = "SetProp"/>

<xsd:attribute name = "param" type = "xsd:string"/>

<xsd:attribute name = "value" type = "xsd:string"/>

</xsd:complexType>

</xsd:element>

<xsd:element name = "getProperty">

<xsd:annotation>

<xsd:documentation>

getProperty получает значение свойства объекта.

Ограничение: Именованный объект обязан быть

"представлен" JSP-процессору через использование либо

акции jsp:useBean, либо специальной акции с ассоциированным

входом VariableInfo для этого имени.

</xsd:documentation>

</xsd:annotation>

<xsd:complexType>

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "name" use = "required" type = "Identifier"/>

<xsd:attribute name = "property" use = "required" type = "Identifier"/>

</xsd:complexType>

</xsd:element>

<xsd:element name = "include">

<xsd:complexType>

<xsd:sequence>

<xsd:element ref = "param" minOccurs = "0" maxOccurs = "unbounded"/>

</xsd:sequence>

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "flush" default = "false" type = "Bool"/>

<xsd:attribute name = "page" use = "required" type = "RTERelativeURL"/>

</xsd:complexType>

</xsd:element>

<xsd:element name = "forward">

<xsd:complexType>

<xsd:sequence>

<xsd:element ref = "param" minOccurs = "0" maxOccurs = "unbounded"/>

</xsd:sequence>

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "page" use = "required" type = "RTERelativeURL"/>

</xsd:complexType>

</xsd:element>

<xsd:element name = "plugin">

<xsd:complexType> <!-- content only! -->

<xsd:sequence>

<xsd:element ref = "params" minOccurs = "0" maxOccurs = "1"/>

<xsd:element name = "fallback"

minOccurs = "0" maxOccurs = "1" type = "Body"/>

</xsd:sequence>

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "type" use = "required" type = "PlugInType"/>

<xsd:attribute name = "code" type = "xsd:anyURI"/>

<xsd:attribute name = "codebase" type = "xsd:anyURI"/>

<xsd:attribute name = "align" type = "AlignType"/>

<xsd:attribute name = "archive">

<xsd:simpleType>

<xsd:list itemType="xsd:anyURI"/>

</xsd:simpleType>

</xsd:attribute>

<xsd:attribute name = "height" type = "Length"/>

<xsd:attribute name = "hspace" type = "xsd:int"/>

<xsd:attribute name = "jreversion" default = "1.2" type = "xsd:string"/>

<xsd:attribute name = "name" type = "xsd:NMTOKEN"/>

<xsd:attribute name = "vspace" type = "xsd:int"/>

<xsd:attribute name = "width" type = "Length"/>

<xsd:attribute name = "nspluginurl" type = "xsd:anyURI"/>

<xsd:attribute name = "iepluginurl" type = "xsd:anyURI"/>

</xsd:complexType>

</xsd:element>

<xsd:element name = "params">

<xsd:complexType>

<xsd:sequence>

<xsd:element ref = "param" minOccurs = "1" maxOccurs = "unbounded"/>

</xsd:sequence>

<xsd:attribute ref = "jsp:id"/>

</xsd:complexType>

</xsd:element>

<xsd:element name = "param">

<xsd:complexType>

<xsd:attribute ref = "jsp:id"/>

<xsd:attribute name = "name" use = "required" type = "xsd:NMTOKEN"/>

<xsd:attribute name = "value" use = "required" type = "xsd:string"/>

</xsd:complexType>

</xsd:element>

</xsd:schema>


Приложение JSP.C

ОТД
для TagLibrary-Дескриптора,
JSP 1.2


В этом приложении содержится ОТД/DTD для дескриптора библиотеки тэгов (TLD) с использованием JSP 1.2.

Все JSP 1.2-контейнеры должны принимать такой TLD.
 

Это то же самое ОТД, что и  "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd", исключая некоторые изменения форматирования текста для извлечения комментариев и для того, чтобы сделать его более читабельным.

C.1 ОТД для Файлов TagLibrary-Дескриптора

Это ОТД, описывающее файл Tag Library Descriptor/Дескриптора Библиотеки Тэгов в формате JSP 1.2.
 

<!--Это ОТД, определяющее формат/синтаксис файла Дескриптора Библиотеки Тэгов (.tld) (XML) JavaServer Pages 1.2.
Tag Library/Библиотека Тэгов это JAR-файл (архив), содержащий верный экземпляр файла Дескриптора Библиотеки Тэгов (taglib.tld) в субдиректории META-INF, а также соответствующие классы реализации и другие ресурсы, необходимые для выполнения определённых в нём акций.
Использование является субъектом лицензирования.
-->
<!NOTATION WEB-JSPTAGLIB.1_2 PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN">
<!--Все ДБТ JSP 1.2 обязаны включать DOCTYPE в следующей форме:
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
-->
<!--Элемент 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 - информация по выбору/optional TagLibraryValidator'а;
listener - по выбору, спецификация прослушивателя событий.
-->
<!ELEMENT taglib (tlib-version, jsp-version, short-name, uri?, display-name?, small-icon?, large-icon?, description?, validator?, listener*, tag+)>
<!ATTLIST taglib
id ID #IMPLIED
xmlns CDATA #FIXED "http://java.sun.com/JSP/TagLibraryDescriptor">
 
<!-- Значение элемента tlib-version описывает версию (номер) этой библиотеки тэгов.
Этот элемент является мандатным/обязательным.
#PCDATA ::= [0-9]*{ "."[0-9] }0..3
-->
<!ELEMENT tlib-version (#PCDATA)
 
<!-- Значение элемента jsp-version описывает JSP-версию (номер), который необходим данной библиотеке тэгов для правильного функционирования. Этот элемент является мандатным. Для JSP 1.2 значение будет  "1.2" (без кавычек).
#PCDATA ::= [0-9]*{ "."[0-9] }0..3
-->
<!ELEMENT jsp-version (#PCDATA)>
 
<!-- Значением элемента short-name является имя, которое может использоваться утилитами авторизации JSP для создания имён с мнемоническим значением; например, оно может быть использовано предпочтительное значение префикса в директивах taglib. Не используйте пробелы и не начинайте имя с цифры или символа подчёркивания.
#PCDATA ::= NMTOKEN
-->
<!ELEMENT short-name (#PCDATA)>

<!-- Значением элемента uri является публичный URI, уникально идентифицирующий точную семантику этой библиотеки тэгов.
-->
<!ELEMENT uri (#PCDATA)>

<!-- Значением элемента description является произвольная текстовая строка, описывающая библиотеку тэгов.
-->
<!ELEMENT description(#PCDATA)>

<!-- Элемент validator предоставляет информацию о необязательном проверщике, который можно использовать для проверки соответствия использования JSP-страницей данной библиотеки тэгов.
-->
<!ELEMENT validator (validator-class, init-param*, description?)>

<!-- Элемент validator-class определяет класс TagLibraryValidator, который может использоваться для проверки соответствия использования JSP-страницей данной библиотеки тэгов.
-->
<!ELEMENT validator-class (#PCDATA)>

<!-- Элемент init-param содержит пару имя/значение как параметр инициализации.
-->
<!ELEMENT init-param (param-name, param-value, description?)>

<!-- Элемент param-name содержит имя параметра.
-->
<!ELEMENT param-name (#PCDATA)>

<!-- Элемент param-value содержит значение параметра.
-->
<!ELEMENT param-value (#PCDATA)>

<!-- Элемент listener определяет возможный/optional объект прослушивателя событий, инстанциируемый и регистрируемый автоматически.
-->
<!ELEMENT listener (listener-class)>

<!-- Элемент listener-class объявляет класс приложения, который обязан быть зарегистрирован как компонент/bean прослушивателя web-приложения.
См. детали в спецификации Servlet 2.3.
-->
<!ELEMENT listener-class (#PCDATA)>

<!-- Элемент tag определяет акцию в данной библиотеке тэгов. Элемент tag имеет один атрибут,id.
Элемент 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, реализующий семантику времени запроса для данного тэга. Этот элемент необходим.
#PCDATA ::= полное квалифицированное имя Java-класса
-->
<!ELEMENT tag-class (#PCDATA)>

<!-- Элемент tei-class указывает подкласс класса javax.serlvet.jsp.tagext.TagExtraInfo для данного тэга. Этот класс инстанциируется на этапе трансляции. Это элемент по выбору/optional.
#PCDATA ::= полное квалифицированное имя Java-класса
-->
<!ELEMENT tei-class (#PCDATA)>

<!-- Элемент body-content предоставляет информацию о содержимом тела данного тэга. Этот элемент предназначается прежде всего для утилитами компоновки страниц.
В настоящее время специфицировано 3 значения:
tagdependent - тело тэга интерпретируется самой реализацией тэга и как правило на другом "langage", например, встроенные операторы SQL
JSP - тело тэга содержит вложенный JSP-синтаксис
empty - тело тэга обязано быть пустым
Это необязательный для использования элемент; значение по умолчанию - JSP.
#PCDATA ::= tagdependent | JSP | empty
-->
<!ELEMENT body-content (#PCDATA)>

<!-- Элемент display-name содержит краткое имя, которое предназначено для отображения утилитами.
-->
<!ELEMENT display-name (#PCDATA)>

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

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

<!-- Элемент example предоставляет неформальное описание примера использования тэга.
-->
<!ELEMENT example (#PCDATA)>

<!-- Элемент variable предоставляет информацию о переменных скриптинга, определённых данным тэгом.
Ошибкой (времени трансляции) для данной акции будет считаться, если одна или более субэлементов переменной будут иметь класс TagExtraInfo, который возвращает не-null объект.
Субэлементы в variable имеют форму:
name-given - имя переменной - константа
name-from-attribute - имя атрибут. чьё значение (времени трансляции) даст имя переменной.
Необходимо наличие одного из элементов: name-given или name-from-attribute.
variable-class - имя класса переменной. java.lang.String - имя по умолчанию.
declare - объявляется переменная, или нет. "True" - значение по умолчанию.
scope - область видимости определённой переменной скриптинга. NESTED - по умолчанию.
-->
<!ELEMENT variable ( (name-given | name-from-attribute), variable-class?, de-clare?, 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 это имя класса для переменной скриптинга. Это элемент по выбору/optional; по умолчанию - java.lang.String.
-->
<!ELEMENT variable-class (#PCDATA)>

<!-- Значение элемента declare указывает, определяется переменная скриптинга, или нет.
См. детали в TagExtraInfo.
Это необязательный элемент/optional и по умолчанию - true.
-->
<!ELEMENT declare (#PCDATA)>

<!-- Значение элемента scope описывает область видимости переменной скриптинга.
См. детали в TagExtraInfo.
Это необязательный элемент/optional и значение по умолчанию - строка "NESTED". Другими допустимыми значениями являются "AT_BEGIN" и "AT_END".
-->
<!ELEMENT scope (#PCDATA)>

<!-- Элемент attribute определяет атрибут для вкладывающего/содержащего тэга.
Элемент attributre может иметь несколько субэлементов:
name - имя атрибута
attribute - необходим/required атрибут, или необязателен/optional
rtexpravalue  - является ли этот атрибут атрибутом времени выполнения/runtime
type - тип атрибута
description - описание атрибута
-->
<!ELEMENT attribute (name, required? , rtexprvalue?, type?, description?)>

<!-- Элемент name определяет каноническое имя определяемых тэга или атрибута
#PCDATA ::= NMTOKEN
-->
<!ELEMENT name(#PCDATA)>

<!-- Значение элемента required указывает, обязателен или необязателен вкладывающий атрибут. Этот элемент необязателен, и значение по умолчанию - "false".
#PCDATA ::= true | false | yes | no
-->
<!ELEMENT required (#PCDATA)>

<!-- Значение элемента rtexpvalue указывает, может ли значение атрибута динамически вычисляться на этапе запроса, что противоположно static-значению, определяемому на этапе трансляции. Этот элемент необязателен, и значение по умолчанию - "false".
#PCDATA ::= true | false | yes | no
-->
<!ELEMENT rtexprvalue (#PCDATA)>

<!-- Значение элемента type описывает Java-тип значения атрибута.
Для static-значений (которые определяются на этапе трансляции) тип всегда java.lang.String.
-->
<!ELEMENT type (#PCDATA)>
<!-- ID-атрибуты -->
<!ATTLIST tlib-version id ID #IMPLIED>
<!ATTLIST jsp-version id ID #IMPLIED>
<!ATTLIST short-name id ID #IMPLIED>
<!ATTLIST uri id ID #IMPLIED>
<!ATTLIST description id ID #IMPLIED>
<!ATTLIST example id ID #IMPLIED>
<!ATTLIST tag id ID #IMPLIED>
<!ATTLIST tag-class id ID #IMPLIED>
<!ATTLIST tei-class id ID #IMPLIED>
<!ATTLIST body-content id ID #IMPLIED>
<!ATTLIST attribute id ID #IMPLIED>
<!ATTLIST name id ID #IMPLIED>
<!ATTLIST required id ID #IMPLIED>
<!ATTLIST rtexprvalue id ID #IMPLIED>
<!ATTLIST param-name id ID #IMPLIED>
<!ATTLIST param-value id ID #IMPLIED>
<!ATTLIST listener id ID #IMPLIED>
<!ATTLIST listener-class id ID #IMPLIED>

Приложение JSP.D

ОТД для Файлов
TagLibrary-Дескриптора, JSP 1.1


В этом приложении содержится DTD/ОТД (Определение Типа Данных) для Дескриптора Библиотеки Тэгов (TLD) с использованием JSP 1.1.


Все JSP 1.2-контейнеры должны принимать такие TLD.


Это то же самое ОТД, что и  "http://java.sun.com/dtd/web-jsptaglibrary_1_1.dtd", исключая некоторые изменения форматирования для извлечения комментариев, чтобы сделать их более читабельными.

D.1 ОТД для Файлов TagLibrary -Дескриптора

Следующее ОТД описывает файл Tag Library Descriptor в формате JSP 1.1.
 

<!--Это ОТД, определяющее файл (.tld) (XML) формата/синтаксиса JavaServer Pages 1.1 Tag Library descriptor'а.
Tag Library/Библиотека Тэгов это JAR-файл, содержащий файл верных экземпляров Tag Library Descriptor'а (taglib.tld) в субдиректории META-INF вместе с с соответствующими реализующими классами и другими ресурсами, необходимыми для реализации тэгов, определённых в ней.
Использование является субъектом лицензирования.
-->
<!-- Тэг taglib является корнем документа, он определяет:
tlibversion  - версия реализации библиотеки тэгов
jspversion - версия JSP, на которой основана библиотека тэгов
shortname - простое краткое имя по умолчанию, которое может использоваться утилитами авторизации JSP для создания имён с мнемоническим значением; например, it может использоваться как предпочтительное значение префикса в директивах taglib
uri - uri, уникально идентифицирующий эту taglib
info - простая строка, описывающая "использование" этой taglib, должна различаться пользователем
-->
<!ELEMENT taglib (tlibversion, jspversion?, shortname, uri?, info?, tag+)>
<!ATTLIST taglib id ID #IMPLIED
xmlns CDATA #FIXED
"http://java.sun.com/dtd/web-jsptaglibrary_1_1.dtd"
>
<!-- Описывает версию (номер) библиотеки тэгов (dewey decimal) #PCDATA ::= [0-9]*{ "."[0-9] }0..3
-->
<!ELEMENT tlibversion (#PCDATA)>
<!--Описывает версию (номер), наличия которой требует эта библиотеки тэгов для правильного функционирования (dewey decimal)
По умолчанию 1.1
#PCDATA ::= [0-9]*{ "."[0-9] }0..3
-->
<!ELEMENT jspversion (#PCDATA)>
<!-- Определяет краткое (по умолчанию) shortname, используемое для имён тэгов и переменных, используемых/созданных этой библиотекой тэгов. Не используйте пробелы и не начинайте с цифры или символа подчёркивания.
#PCDATA ::= NMTOKEN
-->
<!ELEMENT shortname (#PCDATA)>
<!-- Определяет публичный URI, который уникально идентифицирует эту версию библиотеки тэгов. оставьте его пустым, если он не применяется.
-->
<!ELEMENT uri (#PCDATA)>
<!-- Определяет произвольную текстовую строку - описание библиотеки.
-->
<!ELEMENT info(#PCDATA)>
<!-- Этот тэг определяет уникальный tag в данной библиотеке тэгов, определяя:
- уникальное имя тэга/элемента
- подкласс класса реализации javax.servlet.jsp.tagext.Tag
- необязательный/optional подкласс от javax.servlet.jsp.tagext.TagExtraInfo
- тип содержимого тела (hint/подсказка)
- необязательную специфическую информацию тэга
- любые атрибуты
-->
<!ELEMENT tag (name, tagclass, teiclass?, bodycontent?, info?, attribute*)>
<!-- Определяет подкласс от javax.serlvet.jsp.tagext.Tag, реализующий семантику времени запросадля данного тэга. (необходим)
#PCDATA ::= полное квалифицированное имя Java-класса
-->
<!ELEMENT tagclass (#PCDATA)>
<!-- Определяет подкласс от javax.servlet.jsp.tagext.TagExtraInfo для данного тэга (необязательный). Если не задан, к классу не обращаются на этапе трансляции.
#PCDATA ::= полное квалифицированное имя Java-класса
-->
<!ELEMENT teiclass (#PCDATA)>
<!-- Предоставляет подсказку о содержимом тела тэга. Предназначен прежде всего для использования утилитами компоновки страниц.
В настоящий момент специфицированы три значения:
tagdependent - Тело тэга интерпретируется реализацией самого тэга и вероятнее всего - на другом "language/языке", например, встроенные операторы SQL.
JSP - Тело тэга содержит вложенный синтаксис JSP
empty - Тело тэга обязано быть пустым. По умолчанию (если не определено) - JSP.
#PCDATA ::= tagdependent | JSP | empty
-->
<!ELEMENT bodycontent (#PCDATA)>
<!-- Тэгattribute определяет атрибут вкладывающих/содержащих тэгов.
Определение атрибута состоит из:
- имени атрибута (необходимо)
- необходим атрибут, или по выбору (optional)
- может ли значение атрибута динамически вычисляться на этапе прогона выражением скриптлета (optional)
-->
<!ELEMENT attribute (name, required? , rtexprvalue?)>
<!-- Определяет каноническое имя определяемого тэга или атрибута.
#PCDATA ::= NMTOKEN
-->
<!ELEMENT name(#PCDATA)>
<!-- Определяет необходим/required вкладывающий атрибут, или по выбору/optional.
#PCDATA ::= true | false | yes | no
Если отсутствует, тогда по умолчанию - "false", то есть атрибут по выбору/optional.
-->
<!ELEMENT required (#PCDATA)>
<!-- Определяет, может ли вкладывающий атрибут иметь в качестве значения выражения скриптлета, т.е. может ли значение атрибута динамически рассчитываться во время запроса, что противоположно static/статическому значению, определяемому на  этапе трансляции.
#PCDATA ::= true | false | yes | no
Если отсутствует, тогда по умолчанию - "false", то есть атрибут имеет статическое значение.
-->
<!ELEMENT rtexprvalue (#PCDATA)>
<!ATTLIST tlibversion id ID #IMPLIED>
<!ATTLIST jspversion id ID #IMPLIED>
<!ATTLIST shortname id ID #IMPLIED>
<!ATTLIST uri id ID #IMPLIED>
<!ATTLIST info id ID #IMPLIED>
<!ATTLIST tag id ID #IMPLIED>
<!ATTLIST tagclass id ID #IMPLIED>
<!ATTLIST teiclass id ID #IMPLIED>
<!ATTLIST bodycontent id ID #IMPLIED>
<!ATTLIST attribute id ID #IMPLIED>
<!ATTLIST name id ID #IMPLIED>
<!ATTLIST required id ID #IMPLIED>
<!ATTLIST rtexprvalue id ID #IMPLIED>

Приложение JSP.E

Изменения


В этом приложении перечислены изменения в Спецификации JavaServer Pages.
Это приложение является ненормативным.

E.1 Изменения в PFD 2 и Финальном Проекте/Final Draft

Это окончательная версия, одобренная JCP Executive Comittee; документ был обновлён для того, чтобы отразить этот статус. Все полосы изменений/change bars были переустановлены.

E.1.1 Добавлен Механизм jsp:id

Был добавлен новый механизм, позволяющий нуждающимся JSP-контейнерам предоставлять расширенную информацию об ошибках времени трансляции из классов TagLibraryValidator. Запись TagLibraryValidator.validate() была слегка модифицирована и был добавлен новый класс ValidationMessage. Эти объекты действуют через новый атрибут jsp:id, который по выбору поддерживается JSP-контейнером и представляется только через вид XML страницы JSP. Были затронуты: Глава JSP.5 (в основном Раздел JSP.5.3.13), Глава JSP.7 (Раздел JSP.7.5.1.2) и Глава JSP.10 (Раздел JSP.10.5.5).

E.1.2 Другие Незначительные Изменения


E.1.3 Разъяснение Роли id

Мандатные интерпретации атрибута "id" в Разделе JSP 2.13.3 (что id представляет уникальные id в пределах страницы) и атрибута "scope" в Разделе JSP 2.13.4 (касающиеся области видимости вводимого значения) не форсировались большинством (возможно, всеми?) контейнерами и были несовместимы с распространённой практикой разработки библиотек специальных тэгов. Именно эти разделы интерпретировались как локализованные утверждения о стандартной акции jsp:useBean. Это было сделано недвусмысленным, и эти разделы были перемещены в Главу 4, что отразить данные изменения. Были изменены Разделы JSP.2.13.3 и JSP.2.13.4 и Глава 4.

E.1.4 Разъяснение Множественных Запросов/Multiple Requests и Потоков

E.1.5 Разъяснение JSP-Документов

Несколько разъяснений к Главе 5.

E.1.6 Разъяснение по Хорошо Известным Библиотекам Тэгов

Разъяснено, что автор библиотеки тэгов может указать в комментариях, что обработчик тэга может показывать на этапе прогона только некоторый поднабор информации, описанной через класс реализации обработчика тэга. Это применяется для специализированных реализаций известных библиотек тэгов, таких как стандартная библиотека тэгов JSP. Это разъяснение повлияло на описание элемента tag в Разделе JSP.7.4 и на описание Tag.setParent() и TagSupport.findAncestorWithClass(). Удалён последний параграф в Разделе JSP.7.3.9; у нас нет в планах удалять хорошо известный URI-механизм. В целом "прочищено" описание вычисления отображения taglib между URI и путём ресурса TLD; предыдущая версия была дебильной.

E.1.7 Разъяснено Влияние Блоков

Разъяснено правильное использование и роль блок-конструкций в скриптлетах и вложенных акциях. Это незначительно изменило Разделы JSP.2.3.3, JSP.6.4, JSP.6.4.4 и JSP.10.5.9.

E.1.8 Другие Небольшие Разъяснения

E.2 Различия между 1.2 PFD 1b и PFD 2

Change bars/полосы изменений используются в почти всех главах для обозначения изменений между PFD 1b и PFD 2. Исключение - главы 9 и 10, которые автоматически генерируются из Java-источников и не имеют полос изменений. Большинство изменений - семантические, но некоторые из них - редакторские поправки.

E.2.1 Элементы, Добавленные к Дескриптору Библиотеки Тэгов

Дескриптор Библиотеки Тэгов/Tag Library Descriptor (TLD) был расширен описательной информацией для пользователей библиотеки тэгов. Конкретнее, TLD можно теперь непосредственно вставить (например, используя таблицу стилей XSLT) в документ конечного пользователя. Был добавлен новый элемент <example> в качестве необязательного субэлемента в <tag>.

Существующий элемент <description> был сделан верным необязательным субэлементом в <variable>, <attribute> и в <validator>.

Были изменены Раздел JSP.7.4 и Приложение JSP.C. ОТД TLD 1, и Схемы/Schemas также были изменены.

E.2.2 Изменён Способ Кодировки Информации о Версии в TLD

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

В PFD версия кодировалась в пространстве имён. В PFD2 не предполагается изменять пространство имён, если только это не изменения несовместимости, и версия кодируется в элементе <jsp-version>, который теперь является мандатным.

Новый URI для пространства имён:  "http://java.sun.com/JSP/TagLibraryDescriptor".

Были изменены Глава JSP.7 и Приложение JSP.C.

E.2.3 Назначение String-Литералов Атрибутам Object

Теперь можно назначать строковые литералы атрибуту, определённому как имеющий тип Object, а также свойству типа Object. Все верные конвертации типов описаны в Разделе JSP.2.13.2 и используются по ссылке в семантике <jsp:setProperty>.

E.2.4 Разъяснение по Верным Именам Префиксов, Акций и Атрибутов

Мы дали разъяснение по верным именам для префиксов, используемых в директивах taglib, именам элементов, используемых в акциях, и именам атрибутов.

E.2.5 Разъяснение по Деталям Пустых Акций

В спецификации JSP 1.1 различаются пустые/empty и непустые/non-empty акции, хотя лучше было бы дать описание. К сожалению, эскиз/проект JSP 1.2 PFD1 не улучшил это описание. Этот проект улучшил описание, указав точнее, какие методы при этом вызываются. Были изменены Главы 2, 7 и 10.

E.2.6 Коррекция Синтаксиса, Относящегося к XML

E.2.7 Другие Изменения

Мы разъяснили также несколько других несоответствий и ошибок.

E.3 Различия между 1.2 PFD и 1.2 PFD 1b

PFD 1b является наброском, имеющим в основном изменения форматирования и минимум редакционных поправок. Этот проект показан только для того, чтобы легче было коррелировать изменения между последними и более ранними проектами.

Полосы изменений используются для обозначения изменений от PFD 1 к PFD 1b.

E.4 Различия между 1.2 PD1 и 1.2 PFD

Следующие изменения появились после версии Public Draft 1 в версии
Proposed Final Draft спецификации JSP 1.2.

E.4.1 Удаления

E.4.2 Дополнения

E.4.3 Разъяснения

E.4.4 Изменения

E.5 Различия между 1.1 и 1.2 PD1

Следующие изменения появились между JSP 1.1 и JSP 1.2 Public Draft 1.

E.5.1 Организационные Изменения

E.5.2 Новый Документ

Мы создали новый ненормативный документ "Using JSP Technology/Использование Технологии JSP". Этот документ ещё обновляется до JSP 1.2 и Servlet 2.3. Мы переместили в этот документ следующее:

E.5.3 Дополнения к API

E.5.4 Разъяснения

E.5.5 Изменения

JSP 1.2 базируется на Servlet 2.3, точнее: JSP 1.2 базируется на платформе Java 2.

E.6 Различия между 1.0 и 1.1

Спецификация JSP 1.1 создана на основе спецификации JSP 1.0. Следующие изменения были внесены между окончательным вариантом спецификации JSP 1.0 и окончательны вариантом спецификации JSP 1.1.

E.6.1 Дополнения

E.6.2 Изменения


Приложение JSP.F

Словарь


Данное приложение является справочником по главным концепциям данной спецификации.

Данное приложение является ненормативным.

action/акция
Элемент JSP-страницы, который может работать на неявных объектах и других серверных объектах/server-side objects, или может определять новые переменные скриптинга. Акции следуют синтаксису XML для элементов с начальным тэгом, телом и конечным тэгом; если body/тело является пустым, можно использовать также синтаксис пустого тэга. Этот тэг обязан использовать префикс.
action, standard/стандартная
Акция, которая определена в спецификации JSP и всегда доступна файлу JSP без импортирования.
action, custom/специальная
Акция, описанная переносимым способом дескриптором библиотеки тэгов и коллекцией Java-классов и импортированная в JSP-страницу директивой taglib.
Application Assembler/Ассемблер Приложения
Человек, который комбинирует JSP-страницы, сервлет-классы, HTML-содержимое, библиотеки тэгов и другое Web-содержимое в переносимое Web-приложение.
component contract
Контракт между компонентом и его контейнером, включающий обслуживание жизненного цикла компонента и APIs и протоколы, которые это контейнер обязан поддерживать.
Component Provider/Провайдер Компонента
Продавец компонента либо как Java-классов, либо как JSP-страницы-ресурса.
distributed container/распределённый контейнер
JSP-контейнер, который может запускать Web-приложение, размеченное как распределённое, и распределять его на несколько виртуальных Java-машин, которые могут находиться на разных хостах.
declaration/объявление
Элемент скриптинга, объявляющий методы, переменные, или их обоих, в JSP-странице. Синтаксически ограничивается символами  <%!  и  %>.
directive/директива
Элемент JSP-страницы, который даёт инструкцию JSP-контейнеру и интерпретируется во время трансляции. Синтаксически ограничивается символами <%@  и  %>.
element/элемент
Часть JSP-страницы, распознаваемая JSP-транслятором. Элемент может быть директивой, акцией или элементом скриптинга.
expression/выражение
Элемент скриптинга, содержащий верное выражение на языке скриптинга, которое вычисляется, конвертируется к String и помещается в предполагаемый объект вывода. Синтаксически ограничивается символами <%=  и  %>.
fixed template data/фиксированные шаблонные данные
Любые части JSP-файла, не описанные в спецификации JSP, такие как тэги HTML, тэги XML и текст. Шаблонные данные возвращаются клиенту в ответе или обрабатываются компонентом.
implicit object/неявный (предполагаемый) объект
Серверный объект, который определяется JSP-контейнером и всегда доступен JSP-файлу без объявления. Неявными объектами являются request, response, pageContext, session, application, out, config, page и exception.
IMPLIED
Предполагается (наличие).
(Технология) JavaServer Pages
Расширяемая технология Web, использующая шаблонные данные, специальные элементы, языки скриптинга и серверные Java-объекты для возвращения динамического содержимого клиенту. Обычно шаблонные данные - это элементы HTML или XML, а клиентом во многих случаях является Web-браузер.
JSP-контейнер
Экземпляр системного уровня, предоставляющий обслуживание жизненного цикла и поддержку времени выполнения для JSP- и Servlet-компонентов.
JSP-файл
Текстовый файл, содержащий JSP-страницу. В текущей версии спецификации JSP-файл обязан иметь расширение  .jsp
JSP-страница
Текстовый документ, который использует фиксированные шаблонные данные JSP-элементы и описывает, как обрабатывать request\запрос для создания response\ответа. Семантика JSP-страницы реализуется на этапе прогона в классе реализации JSP-страницы.
JSP-страница, front/первичная
JSP-страница, которая получает HTTP-запрос непосредственно от клиента. Она создаёт, обновляет и/или получает доступ к некоторым данным на стороне сервера и передаёт затем запрос презентационной JSP-странице.
JSP-страница, презентационная
JSP-страница, предназначенная только для целей представления содержимого. Она получает доступ к, и/или обновляет, некоторые данные на стороне сервера и встраивает фиксированные шаблонные данные для создания содержимого, которое затем пересылается клиенту.
Optional
По выбору (использование по выбору).
REQUIRED
Требуется (наличие).
scriptlet/скриптлет
Элемент скриптинга, содержащий любой фрагмент кода, который является верным для используемого в JSP-странице языка скриптов. Спецификация JSP описывает, какой скриптлет является верным, для случая, когда атрибут языка страницы - "java". Синтаксически скриптлет ограничивается символами  <%  и  %>.
tag/тэг
Участок текста между левой и правой угловыми скобками, который имеет имя, может иметь атрибуты и является частью элемента JSP-страницы. Имена тэгов известны транслятору JSP, или потому, что имя является частью спецификации JSP (в случае стандартной акции), или потому, что имя вводится с использованием Tag Library/Библиотеки Тэгов (в случае специальной акции).
tag handler/обработчик тэга
Java-класс, реализующий интерфейс Tag или BodyTag и являющийся представлением специальной акции на этапе прогона.
tag handler
JavaBean-компонент, реализующий интерфейс Tag или BodyTag и являющийся представлением специальной акции на этапе прогона.
tag library/библиотека тэгов
Коллекция специальных акций, описанных дескриптором библиотеки тэгов и Java-классами.
tag library descriptor/дескриптор библиотеки тэгов
Документ XML, описывающий библиотеку тэгов.
Tag Library Provider/Провайдер Библиотеки Тэгов
Продавец библиотеки тэгов. Типичные примеры - продавец JSP-контейнера, группа разработчиков корпорации, продавец компонентов или продавец услуг, который хочет облегчить использование своих услуг.
web application/приложение
Приложение, созданное для Internet, intranet или extranet.
web-приложение, distributable/распределяемое
Web-приложение, написанное так, что оно может публиковать в Web-контейнере, распределяемом не несколько виртуальных машин Java, запущенных на одно или нескольких хостах. Дескриптор публикации/deployment descriptor для такого приложения использует распределяемый элемент.
web-компонент
Класс сервлета или JSP-страница, работающая в JSP-контейнере и предоставляющая сервис в ответ на запросы.
Инстанциация
Создание экземпляра.
Класс реализации JSP-страницы
Класс языка программирования Java,  Servlet/Сервлет, представляющий JSP-страницу на этапе прогона, который получает объект request и обновляет объект response. Класс реализации страницы может использовать сервис, предоставляемый JSP-контейнером, включая API Servlet'а и API JSP.
Объект реализации JSP-страницы
Экземпляр класса реализации JSP-страницы, который получает объект request и обновляет объект response.
Провайдер Web-Контейнера
Продавец сервлета и контейнера JSP, поддерживающий соответствующие контракты компонентов.
Публикатор Web-Приложения
Тот, кто публикует Web-приложение в Web-контейнере, специфицируя, как минимум, префикс для корня/root Web-приложения и, в среде J2EE, отображение безопасности и ресурсов.
Элемент скриптинга
Объявление, скриптлет или выражение, синтаксис тэга которого определяется спецификацией JSP, а содержимое которого записано в соответствии с языком скриптов, используемым в JSP-странице. Спецификация JSP описывает синтаксис и семантику для случая, когда атрибут языка страницы - "java".

Глава JSP.1

Обзор


В этой главе даётся обзор технологии JavaServer Pages/Серверные Страницы Java.

JSP.1.1 Технология JavaServer Pagesтм

JavaServer Pages это технология Java 2 Platform, Enterprise Edition (J2EE) для создания приложений, генерирующих динамическое web-содержимое - HTML, DHTML, XHTML и XML. Технология JavaServer Pages даёт возможность легко создавать динамическое содержимое web-страниц, предельно мощное и гибкое.

JSP.1.1.1 Общие Понятия

Технология JavaServer Pages придаёт смысл текстуальной спецификации создания динамического response\ответа на request\запрос. Эта технология основывается на следующих понятиях:

JSP.1.1.2 Преимущества Технологии JavaServer Pages

Технология JavaServer Pages даёт следующие преимущества:

JSP.1.2 Базовые Понятия

В этом разделе рассмотрены базовые понятия, формально определённые далее в этой спецификации.

JSP.1.2.1 Что такое страница JSP?

JSP-страница это текстовый документ, описывающий процесс обработки запроса для создания ответа. Шаблонные данные смешиваются с динамическими акциями и воздвигаются на платформу Java 2 Platform.

JSP-технология поддерживает различные парадигмы авторизации динамического содержимого.

Ключевыми особенностями JavaServer Pages являются:

JSP.1.2.2 Web-Приложения

Концепция web-приложения унаследована от спецификации Servlet.

Web-приложение может состоять из следующих частей:

Спецификация JavaServer Pages унаследовала от спецификации Servlet понятия web-приложений, ServletContexts/КонтекстаСервлета, сессии, запросов и ответов. См. детали в спецификации Java Servlet 2.3.

JSP.1.2.3 Компоненты и Контейнеры

JSP-страницы и классы сервлетов вместе называются web-компонентами. JSP-страницы направляются Container\Контейнеру, который предоставляет сервис, указанный в JSP Component Contract\Контракте Компонента.

Это отделение компонента от контейнера даёт возможность многократного использования компонентов и возможностей, предоставляемых контейнером.

JSP.1.2.4 Этапы Трансляции и Выполнения

JSP-страницы являются текстуальными компонентами. Они проходят через две фазы: фазу трансляции и фазу запроса. Трансляция выполняется для страницы один раз. Фаза запроса выполняется один раз на один запрос.

JSP-страница транслируется для создания класса сервлета, класса реализации JSP-страницы, который инстанциируется во время запроса. Инстанциированный объект JSP-страницы обрабатывает запросы и создаёт ответы.

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

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

JSP.1.2.5 Роль в Платформе Java 2, Enterprise Edition

За некоторыми исключениями, интеграция JSP-страниц на платформу J2EE 1.3 наследуется из спецификации Servlet 2.3, поскольку трансляция превращает JSP-страницы в сервлеты.


Глава JSP.10

API Развёртывания Тэгов


В этой главе описываются обработчики тэгов и другие классы развёртывания тэгов, а также методы доступа к файлам Tag Library Descriptor/Дескриптора Библиотеки Тэгов. Это дополняет предыдущую главу  описанием формата файлов Tag Library Descriptor и их использование в директивах taglib.

Эта глава включает содержимое, сгенерированное автоматически из javadoc, внедрённых в реальные Java-классы и интерфейсы. Это позволяет создавать единый авторизованный документ-спецификацию.

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

Пустой тэг не имеет тела. Есть два эквивалентных синтаксиса, один - с отдельными начальным и конечным тэгами, другой - в котором начальный и конечный тэги скомбинированы в один тэг.

Следующие два пример идентичны:


<x:foo att="myObject" />

<x:foo att="myObject" ></foo>


Непустой тэг имеет начальный тэг, тело и конечный тэг.


Пример-прототип имеет форму:


<x:foo att="myObject" >

BODY

</x:foo/>


Спецификация JavaServer Pages(тм) (JSP) 1.2 предоставляет переносимый механизм для описания библиотек тэгов, включающий:


Данная глава разбита на три раздела:

Первый раздел представляет базовые классы обработчика тэга.
Во втором разделе описаны более сложные обработчики тэга, которым необходим доступ к обсчёту их тела.
Последний раздел посвящён вопросам этапа/времени трансляции.

JSP.10.1 Простые Обработчики Тэгов

Этот раздел вводит понятие обработчика тэга и описывает простейшие типы обработчика тэга.

Обработчик Тэга/Tag Handler

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

Обработчик тэга создаётся первоначально с использованием нулевого аргумента конструктора в соответствующем классе; метод java.beans.Beans.instantiate() не используется.

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

setter-метод используется для установки свойств, обнаруженных с помощью машины интроспекции JavaBeans.

Протокол, поддерживаемый обработчиком тэга, даёт возможность передавать параметры, обсчитывать и пересчитывать тело акции и получать доступ к объектам и другим обработчикам тэгов в JSP-странице.

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

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

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

Свойства

Обработчик тэга имеет несколько свойств.

Все обработчики тэгов имеют свойство pageContext для JSP-страницы, на которой находится тэг, и свойство parent для обработчика тэга ближайшей внешней/содержащей акции. Отдельные классы обработчика тэга могут иметь дополнительные свойства.

Все атрибуты специальной акции обязаны быть свойствами компонента JavaBeans, хотя некоторые свойства не могут экспонироваться в качестве атрибутов. Атрибуты, видимые JSP-транслятору, это в точности те атрибуты, которые перечислены в Дескрипторе Обработчика Тэга/(TLD).

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

setter-методы, которые должны использоваться при установке значения атрибуту специальной акции, определяются через использование интроспектора JavaBeans в классе обработчика тэга, а затем используется setter-метод, ассоциированный со свойством, имеющий то же самое имя, что и атрибут в запросе. Подразумевается (в спецификации JavaBeans - недостаточно чётко), что для каждого свойства имеется только один setter.

Неспецифицированные атрибуты/свойства не должны использоваться (через setter-метод).

После того как свойство установлено, оно считается постоянным, так что, если JSP-контейнер утверждает, что свойство уже установлено в данном экземпляре обработчика тэга, оно не должно устанавливаться ещё раз (дополнительно).

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

Обработчик Тэга как Объект, Обслуживаемый Контейнером

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

Эти ограничения на ссылки на объекты обработчика тэга и на модификацию свойств атрибутов дают JSP-контейнеру относительную свободу для эффективного обслуживания объектов обработчика тэга для достижения различных целей. Например, контейнер может реализовывать различные стратегии пулинга/pooling (создания пула) для минимизации затрат на создание, или может осуществлять установку свойств для уменьшения затрат, когда обработчик тэга находится внутри другого повторяющегося/iterative тэга.

Соглашения

Обработчик тэга реализует акцию; JSP-контейнер обязан выдерживать конверсии типов, описанные в Разделе 2.13.2, при присвоении значений атрибутам акции.

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

Пустая акция не имеет тела; она может использовать один или два синтаксиса: <foo/> или <foo></foo>. Поскольку пустые акции не имеют тела, методы, имеющие отношение к работе с телом, не вызываются.

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

Непустая акция имеет тело.

Интерфейс Tag

Обработчик тэга, который "не хочет" обрабатывать своё тело, может просто реализовывать интерфейс Tag. Обработчик тэга может "не хотеть" обрабатывать своё тело, если это пустой тэг, или из-за того, что тело просто "передаётся (дальше)/passed through".

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

Метод doStartTag() вызывается при обнаружении начального тэга, и его return-значение указывает, должно ли тело/body (если имеется) быть пропущено, или вычислено и передано текущему потоку response.

Метод doEndTag() вызывается при обнаружении конечного тэга; его return-значение указывает, должно ли продолжаться обсчитывание оставшейся части страницы, или нет.
Если в процессе обсчёта тела тэга обнаружено исключение, метод doEndTag не будет выполняться. См. в тэге TryCatchFinally методы, которые гарантированно выполняются.

Интерфейс IterationTag

Интерфейс IterationTag используется для повторяющихся вычислений тела специальной акции.

Этот интерфейс имеет единственный метод - doAfterBody(), который вызывается после каждого вычисления тела для определения необходимости дальнейших вычислений.

Повторение вычисления запрашивается значением 2, которое в JSP 1.1 определено как BodyTag.EVAL_BODY_TAG. Это константное значение сохранено в JSP 1.2 (для полной обратной совместимости), но, для улучшения ясности кода, имеется и новое имя: IterationTag.EVAL_BODY_AGAIN.
Для остановки итерации возвращаемое значение должно быть 0, то есть Tag.SKIP_BODY.

Базовый Класс TagSupport

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

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 обработчик тэга доступен для последующих вызовов (и предполагается, что сохраняет свои свойства).


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


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


После того как все вызовы обработчика тэга выполнены, в нём вызывается метод 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.

JSP.10.1.2 IterationTag


Синтаксис


public interface IterationTag extends Tag


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


Все Суперинтерфейсы: Tag


Все Известные Реализующие Классы: TagSupport


Описание


Интерфейс IterationTag расширяет интерфейс Tag через определение одного дополнительного метода, управляющего повторными вычислениями его тела.

Обработчик тэга, реализующий IterationTag, рассматривается как обработчик, реализующий Tag через методы doStartTag() и doEndTag(). IterationTag предоставляет новый метод: doAfterBody().


Метод doAfterBody() вызывается после каждого цикла итерации - вычисления тела для управления последующими вычислениями тела.

Если doAfterBody() возвращает IterationTag.EVAL_BODY_AGAIN, тогда тело снова будет вычисляться.
Если doAfterBody() возвращает Tag.SKIP_BODY, тогда тело будет пропущено и вместо него будет обсчитываться doEndTag().


Свойства


Новых свойств, в дополнение к уже имеющимся в Tag, нет.


Методы


Имеется один новый метод: doAfterBody().


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


Жизненный цикл показан на диаграмме переноса. Исключения, вызываемые в процессе обсчёта doStartTag(), BODY и doAfterBody(), прерывают последовательность выполнения и помещаются на верх стэка, если только обработчик тэга не реализует интерфейс TryCatchFinally; см. детали об этом интерфейсе.
 


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


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


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

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

JSP.10.1.2.3 Поля


public static final int EVAL_BODY_AGAIN


Запрашивает повторение обсчёта некоторого тела/body. Возвращается методом doAfterBody. Для совместимости с JSP 1.1 значение должно тщательно подбираться, чтобы быть тем же самым, что и в, теперь не рекомендуемом, BodyTag.EVAL_BODY_TAG.

JSP.10.1.2.4 Методы


public int doAfterBody()


Осуществляет (пере)обсчёт тела. Этот метод вызывается объектом реализации JSP-страницы после каждого обсчёта тела в объекте BodyEvaluation. Этот метод не вызывается, если нет обсчёта тела/body.


Если doAfterBody возвращает EVAL_BODY_AGAIN, происходит новый обсчёт тела (с последующим вызовом doAfterBody). Если doAfterBody возвращает SKIP_BODY, обсчёт тела больше не производится, значение out восстанавливается через использование метода popBody в pageContext, а затем вызывается doEndTag.

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


Возвращает: нужно ли проводить дополнительные обсчёты тела/body.


Вызывает: JspException

JSP.10.1.3 TryCatchFinally


Синтаксис


public interface TryCatchFinally


Описание


Интерфейс, в дополнение к Tag, IterationTag или BodyTag, для обработчика тэга, которому нужны дополнительные возможности для обслуживания ресурсов. Этот интерфейс предоставляет два новых метода: doCatch(Throwable) и doFinally().


Прототип вызова таков:


h = get a Tag(); // получает обработчика тэга, возможно из пула
h.setPageContext(pc); // инициализируется
h.setParent(null);
h.setFoo("foo");

// протокол вызова тэга; см. Tag.java

try {
doStartTag()...
....
doEndTag()...
}catch (Throwable t){
// реагирует на условие исключения
h.doCatch(t);
} finally {
// восстанавливает инварианты данных и освобождает вызванные ресурсы
h.doFinally();
}

... другие вызовы, возможно, с новыми setter'ами

...

h.release(); // освобождает долгосрочные ресурсы

JSP.10.1.3.5 Методы


public void doCatch(java.lang.Throwable t)


Вызывается, если возникает Throwable при обсчёте BODY внутри тэга, или любым из следующих методов: Tag.doStartTag(), Tag.doEndTag(), Iteration-Tag.doAfterBody() и BodyTag.doInitBody().


Этот метод вызывается, если Throwable возникает в одном из setter-методов.


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


Этот метод предназначен для использования в ответ на исключительное условие.


Параметры:


t
- Навигация вызываемого исключения по этому тэгу.


Вызывает: Throwable


public void doFinally()


Вызывается во всех случаях после doEndTag() для всех классов, реализующих Tag, IterationTag или BodyTag. Этот метод вызывается, даже если в BODY тэга возникло исключение, или в любом из следующих методов:

Tag.doStartTag(), Tag.doEndTag(), IterationTag.doAfterBody() и Body-Tag.doInitBody().


Этот метод не вызывается, если Throwable возникает в одном из setter-методов.

Этот метод не должен вызывать Exception.

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

JSP.10.1.4 TagSupport


Синтаксис
 

public class TagSupport implements IterationTag, java.io.Serializable


Прямые Известные Подклассы: BodyTagSupport


Все Реализованные Интерфейсы: IterationTag, java.io.Serializable, Tag


Описание


Базовый класс для определения новых обработчиков тэгов, реализующих Tag.


Класс TagSupport является служебным классом, предназначенным для использования в качестве базового класса для новых обработчиков тэгов. Класс TagSupport реализует интерфейсы Tag и IterationTag и добавляет дополнительные удобные методы, включая getter-методы для свойств в Tag. TagSupport имеет один static-метод, который включён для облегчения координации между кооперирующимися тэгами.


Многие обработчики тэгов будут расширять TagSupport и переопределять только некоторые методы.

JSP.10.1.4.6 Поля
 

protected java.lang.String id


protected PageContext pageContext

JSP.10.1.4.7 Конструкторы


public TagSupport()


Конструктор по умолчанию, все классы должны определять только public-конструктор с той же подписью и вызывать конструктор суперкласса. Этот конструктор вызывается кодом, генерируемым JSP-транслятором.

JSP.10.1.4.8 Методы
 

public int doAfterBody()


Процессинг по умолчанию для тела/body.


Возвращает: SKIP_BODY


Вызывает: JspException


См. также: public int doAfterBody()


public int doEndTag()


Процессинг по умолчанию конечного тэга, возвращающий EVAL_PAGE.


Вызывает: JspException


См. также: public int doEndTag()


public int doStartTag()


Процессинг по умолчанию начального тэга, возвращающий SKIP_BODY.


Вызывает:JspException


См. также: public int doStartTag()


public static final Tag findAncestorWithClass(Tag from, java.lang.Class klass)


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

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


Если автор библиотеки тэгов предоставляет информацию о рассматриваемом типе обработчика тэга, клиентский программный код должен быть приспособлен к этому ограничению. Точнее, Class, переданный в findAncestorWithClass, должен иметь подтип рассматриваемого типа.


Параметры:


from
- Экземпляр, с которого начинать просмотр.

klass - Совпадающий подкласс Tag'а или интерфейс.

public java.lang.String getId() - Значение атрибута id этого тэга; или null.

public Tag getParent() - Ближайший экземпляр Tag'а, заключающий в себе данный экземпляр тэга.


См. также: public Tag getParent()


public java.lang.Object getValue(java.lang.String k)


Получает значение, ассоциированное с ключом/key.


Параметры:

k - Строка-ключ.


public java.util.Enumeration getValues()


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


public void release()


Освобождает статус.


См. также: public void release()


public void removeValue(java.lang.String k)


Удаляет значение, ассоциированное с ключом.


Параметры:


k
- строка-ключ.


public void setId(java.lang.String id)


Устанавливает атрибут id для данного тэга.


Параметры:


id
- String для id.


public void setPageContext(PageContext pageContext)


Устанавливает контекст страницы.


Параметры:


pageContenxt
- PageContext.


См. также: public void setPageContext(PageContext pc)


public void setParent(Tag t)


Устанавливает вкладывающий тэг для данного тэга.


Параметры:


t
- родительский Tag.


См. также: public void setParent(Tag t)


public void setValue(java.lang.String k, java.lang.Object o)


Ассоциирует значение со String-ключом.


Параметры:


k
- String-ключ.

o - Ассоциируемое значение.

JSP.10.2 Обработчики Тэгов, которые хотят получить Доступ к Содержимому своего Body/Тела

Вычисление тела передаётся в объект bodyContent, который затем становится доступным обработчикам тэгов, реализующим интерфейс BodyTag. Класс BodyTag-Support даёт базовый класс, упрощающий написание этих обработчиков. Если обработчик Tag хочет иметь доступ к содержимому его тела, то он обязан реализовывать интерфейс BodyTag. Этот интерфейс расширяет IterationTag, предоставляя два дополнительных метода setBodyContent(bodyContent) и doInitBody() и ссылаясь на объект типа bodyContent.

bodyContent
это подкласс JspWriter'а, имеющий несколько дополнительных методов для конвертации его содержимого в String, вставки этого содержимого в другой JspWriter, получения Reader в его содержимое и очистки содержимого. Его семантика гарантирует, что размер буфера никогда не будет превышен.

Реализация JSP-страницы создаст bodyContent, если метод doStartTag() возвращает EVAL_BODY_BUFFERED. Этот объект будет передан методу doInitBody(); затем тело тэга будет обсчитано, и в ходе этого вычисления out будет привязан к bodyContent, только что переданному обработчику BodyTag .

Затем doAfterBody() будет обсчитан. Если этот метод вернёт SKIP_BODY, больше никаких вычислений тела выполнено не будет; если метод вернёт EVAL_BODY_AGAIN, тогда тело будет обсчитано, а doAfterBody() будет вызван вновь.

Содержимое экземпляра bodyContent остаётся доступным, пока не будет вызван его ассоциированный метод doEndBody().


Обычно bodyContent используется для извлечения его содержимого в String и последующего использования этой String в качестве значения для некоторой операции. Другой обычный способ использования - взять его содержимое и поместить его в поток вывода/out Stream, который был верным/действующим/valid в момент обнаружения тэга (который доступен из объекта PageContext, переданного обработчику в setPageContext).
 

JSP.10.2.1 bodyContent


Синтаксис


public abstract class bodyContent extends JspWriter


Описание


Инкапсулирует вычисление/обсчёт тела акции так, что доступен обработчику тэга. bodyContent является подклассом JspWriter'а.


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

bodyContent
имеет методы конвертации своего содержимого в String, для чтения его содержимого, и для очистки/clear своего содержимого.

Размер буфера объекта bodyContent не ограничен. Объект bodyContent не может быть в режиме autoFlush.

Невозможно вызвать flush в объекте bodyContent, так как отсутствует фоновый/backing поток.

Экземпляры bodyContent'а создаются через вызов методов pushBody и popBody класса PageContext.

bodyContent
заключён внутри другого JspWriter'а (возможно, другого объекта bodyContent), следуя структуре их ассоциированных акций.

bodyContent
становится доступным BodyTag'у через вызов setBodyContent().

Обработчик тэга может использовать этот объект до момента вызова doEndTag().

JSP.10.2.1.9 Конструкторы


protected bodyContent(JspWriter e)


Protected-конструктор. Несвязанный буфер, без autoflushing/автооочистки.

JSP.10.2.1.10 Методы
 

public void clearBody()


Очищает body без вызова исключений.


public void flush()


Переопределённый таким образом flush() не допускается. Нельзя зачищать bodyContent, поскольку позади него отсутствует фоновый/backing поток.


Переопределяет: public abstract void flush() в классе JspWriter


Вызывает: IOException


public JspWriter getEnclosingWriter()


Получает содержащий JspWriter.


Возвращает: содержащий JspWriter, переданный на этапе конструирования.


public abstract java.io.Reader getReader()


Возвращает: значение данного bodyContent как Reader.


public abstract java.lang.String getString()


Возвращает: значение данного bodyContent как String.


public abstract void writeOut(java.io.Writer out)


Записывает содержимое данного bodyContent в Writer. Подклассы могут оптимизировать общие патэрны вызова.


Параметры:


out
- writer, в который помещается содержимое вычисления этого body.


Вызывает: IOException

JSP.10.2.2 BodyTag


Синтаксис


public interface BodyTag extends IterationTag


Все Суперинтерфейсы: IterationTag, Tag


Все Известные Реализующие Классы: BodyTagSupport


Описание


Интерфейс BodyTag расширяет IterationTag путём определения дополнительных методов, позволяющих обработчику тэга манипулировать содержимым, обсчитывая его тела.

Обработчик тэга отвечает за обработку содержимого body. Например, обработчик тэга может взять содержимое тела, конвертировать его в String путём использования метода bodyContent.getString и его последующего использования. Либо обработчик тэга может взять тело содержимого и записать его в содержащий JspWriter, используя метод bodyContent.writeOut.


Обработчик тэга, реализующий BodyTag, рассматривается как обработчик, реализующий IterationTag, за исключением того, что метод doStartTag может возвратить SKIP_BODY, EVAL_BODY_INCLUDE или EVAL_BODY_BUFFERED.


Если возвращено EVAL_BODY_INCLUDE, вычисление проводится как в IterationTag.


Если возвращено EVAL_BODY_BUFFERED, будет создан объект bodyContent (в коде, генерируемом JSP-компилятором) для захвата вычисления тела.


Код, генерируемый JSP-компилятором, получает объект bodyContent через вызов метода pushBody из текущего pageContext, который дополнительно даёт эффект сохранения предыдущего значения out. Компилятор страницы возвращает этот объект через вызов метода popBody класса PageContext; этот вызов также восстанавливает значение out.


Этот интерфейс предоставляет одно новое свойство с setter-методом и новый метод акции.


Свойства


Имеется новое свойство: bodyContent, для получения объекта bodyContent, где объект реализации JSP-страницы будет размещать вычисление/обсчёт (и повторный обсчёт, если нужно) тела.

setter
-метод (setBodyContent) будет вызван только в том случае, если doStartTag() возвратит EVAL_BODY_BUFFERED.


Методы


В дополнение к setter-методу свойства bodyContent есть новый метод акции: doInitBody(), который вызывается сразу после setBodyContent() и до обсчёта тела. Этот метод вызывается только в том случае, если doStartTag() возвращает EVAL_BODY_BUFFERED.


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


Детали жизненного цикла даны ниже на диаграмме переноса. Исключения, вызываемые в процессе вычислений doStartTag(), setBodyContent(), doInit-Body(), BODY, doAfterBody(), прерывают выполнение и помещаются на верх стэка, если только обработчик тэга не реализует интерфейс TryCatchFinally; см. детали об этом интерфейсе.
 


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


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

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

Если возвращено EVAL_BODY_INCLUDE, setBodyContent() не вызывается, doInitBody() не вызывается, тело обсчитывается и "передаётся" текущему out, затем вызывается doAfterBody() и, после 0 или более итераций, вызывается doEndTag().


Если возвращено EVAL_BODY_BUFFERED, setBodyContent() вызывается, doInit-Body() вызывается, тело обсчитывается, вызывается doAfterBody() и, после 0 или более итераций, вызывается doEndTag().

JSP.10.2.2.11 Поля


public static final int EVAL_BODY_BUFFERED


Запрашивается создание нового буфера, bodyContent, в котором происходит обсчёт тела данного тэга.

Возвращается из doStartTag, если класс реализует BodyTag.

Неверным является значение doStartTag, если класс не реализует BodyTag.


public static final int EVAL_BODY_TAG


Не рекомендуется. Так как Java JSP API 1.2 использует BodyTag.EVAL_BODY_BUFFERED или IterationTag.EVAL_BODY_AGAIN.


Не рекомендуемая для использования константа, которая имеет то же значение, что и EVAL_BODY_BUFFERED и EVAL_BODY_AGAIN. Помечена как не рекомендуемая с целью продвижения этих двух различных терминов, которые являются более описательными.

JSP.10.2.2.12 Методы


public void doInitBody()


Подготавливает обсчёт/вычисление тела/body. Этот метод вызывается объектом реализации JSP-страницы после setBodyContent и до первого вычисления тела. Этот метод не вызывается для пустых тэгов или непустых тэгов, чей метод doStartTag() возвращает SKIP_BODY или EVAL_BODY_INCLUDE.

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


Вызывает:JspException


public void setBodyContent(bodyContent b)


Устанавливает свойство bodyContent. Этот метод вызывается объектом реализации JSP-страницы максимум один раз на один вызов акции. Этот метод будет вызван до doInitBody. Этот метод не будет вызван для пустых тэгов и для непустых тэгов, чей метод doStartTag() возвращает SKIP_BODY или EVAL_BODY_INCLUDE.
Если setBodyContent вызывается, значение неявного объекта out уже было изменено в объекте pageContext. Передаваемый объект bodyContent не будет содержать данных, но может использоваться повторно (и очищаться) после некоторого предыдущего вызова.

Объект bodyContent доступен с соответствующим содержимым, пока не вызван метод doEndTag, после чего он может быть использован повторно.


Параметры:


b - bodyContent

JSP.10.2.3 BodyTagSupport


Синтаксис


public class BodyTagSupport extends TagSupport implements BodyTag


Все Реализованные Интерфейсы: BodyTag, IterationTag, java.io.Serializable, Tag


Описание


Базовый класс для определения обработчиков тэгов, реализующих BodyTag.

Класс BodyTagSupport реализует интерфейс BodyTag и добавляет несколько удобных методов, включая getter-методы для свойства bodyContent и методы для получения предыдущего out JspWriter.

Многие обработчики тэгов будут расширять BodyTagSupport и переопределять только несколько методов.

JSP.10.2.3.13 Поля


protected bodyContent bodyContent

JSP.10.2.3.14 Конструкторы


public BodyTagSupport()


Конструктор по умолчанию, все подклассы должны определить public-конструктор с той же подписью и вызвать конструктор суперкласса. Этот конструктор вызывается кодом, генерируемым JSP-транслятором.

JSP.10.2.3.15 Методы

public int doAfterBody()


После вычисления/обсчёта тела: не выполнять повторного обсчёта и продолжать разбор страницы. С данными bodyContent по умолчанию ничего не делается (если они имеются).


Переопределяет: public int doAfterBody() в классе TagSupport


Возвращает: SKIP_BODY


Вызывает: JspException


public int doEndTag()


Процессинг по умолчанию конечного тэга, возвращающий EVAL_PAGE.


Переопределяет: public int doEndTag() в классе TagSupport


Возвращает: EVAL_PAGE


Вызывает: JspException


public void doInitBody()


Подготавливает обсчёт/вычисление тела/body сразу перед первым вычислением тела: нет акции.


Вызывает: JspException


public int doStartTag()


Процессинг по умолчанию начального тэга, возвращающий


Переопределяет: public int doStartTag() в классе TagSupport.


Возвращает: EVAL_BODY_BUFFERED;


Вызывает:JspException


public bodyContent getBodyContent()


Получает текущий bodyContent.


Возвращает: содержимое тела.


public JspWriter getPreviousOut()


Получает окружающий out JspWriter.


Возвращает: содержащий JspWriter, из bodyContent.


public void release()


Освобождает статус.


Переопределяет: public void release() в классе TagSupport.


public void setBodyContent(bodyContent b)


Подготавливает для обсчёта тела: прячет bodyContent.


Параметры: b - bodyContent

JSP.10.3 Пример Работы с Аннотированным Обработчиком Тэга

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

Есть и другие стратегии, которым можно следовать.

В данном примере мы принимаем, что x:iterate это тег итерации, а x:doit и x:foobar - простые тэги. Мы также принимаем, что x:iterate и x:foobar реализуют интерфейс TryCatchFinally, а x:doit - не реализует его.


<x:iterate src="foo">
  <x:doit att1="one" att2="<%=1 +1 %>"/>
  <x:foobar />
  <x:doit att1="one" att2="<%=2 +2 %>"/>
</x:iterate>
<x:doit att1="one" att2="<%=3 +3 %>"/>


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


boolean b1, b2;
IterationTag i; // для x:iterate
Tag d; // для x:doit
Tag d; // для x:foobar
page: // лэйбл для конца страницы...
// инициализируется тэг итерации
i = get tag from pool or new();
i.setPageContext(pc);
i.setParent(null);
i.setSrc("foo");
// x:iterate implements TryCatchFinally
try {
    if ((b1 = i.doStartTag()) == EVAL_BODY_INCLUDE) {
         // инициализируется тэг doit
         // код выводится из цикла для показа
         d = get tag from pool or new();
         d.setPageContext(pc);
         d.setParent(i);
         d.setAtt1("one");
    loop:
      while (1) do {
      // Игнорирую символы новой строки...
      // два вызова, сплавленные вместе
      // первый вызов x:doit
      d.setAtt2(1+1);
      if ((b2 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
          // ничего
      } else if (b2 != SKIP_BODY) {
         // Q? ошибка протокола ...
      }
      if ((b2 = d.doEndTag()) == SKIP_PAGE) {
           break page; // выполняется им.
      } else if (b2 != EVAL_PAGE) {
           // Q? ошибка протокола
      }

// вызов x:foobar
      f = get tag from pool or new();
      f.setPageContext(pc);
      f.setParent(i);
      // x:foobar implements TryCatchFinally
      try {
         if ((b2 = f.doStartTag()) == EVAL_BODY_INCLUDE) {
             // ничего
         } else if (b2 != SKIP_BODY) {
            // Q? ошибка протокола
         }
         if ((b2 = f.doEndTag()) == SKIP_PAGE) {
             break page; // выполняется им.
         } else if (b2 != EVAL_PAGE) {
            // Q? ошибка протокола
         }
} catch (Throwable t) {
         f.doCatch(t); // отловлено, может быть повторно отловлено!
} finally {
         f.doFinally();
}
// помещает f обратно в пул

// второй вызов x:doit
d.setAtt2(2+2);
if ((b2 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
    // ничего
} else if (b2 != SKIP_BODY) {
   // Q? ошибка протокола
}
if ((b2 = d.doEndTag()) == SKIP_PAGE) {
    break page; // выполняется им.
} else if (b2 != EVAL_PAGE) {
   // Q? ошибка протокола
}
if ((b2 = i.doAfterBody()) == EVAL_BODY_AGAIN) {
   break loop;
} else if (b2 != SKIP_BODY) {
   // Q? ошибка протокола
}

// цикл
}
} else if (b1 != SKIP_BODY) {
// Q? ошибка протокола
}

// конец IteratorTag ...
if ((b1 = i.doEndTag()) == SKIP_PAGE) {
   break page; // выполняется им.
} else if (b1 != EVAL_PAGE) {
   // Q? ошибка протокола
}

// третий вызов
// этот обработчик тэга может быть повторно использован из предыдущего.
d = get tag from pool or new();
d.setPageContext(pc);
d.setParent(null);
d.setAtt1("one");
d.setAtt2(3+3);
if ((b1 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
   // ничего
} else if (b1 != SKIP_BODY) {
   // Q? ошибка протокола
}
if ((b1 = d.doEndTag()) == SKIP_PAGE) {
   break page; // выполняется им.
} else if (b1 != EVAL_PAGE) {
   // Q? ошибка протокола
}
}catch (Throwable t){
i.doCatch(t); // отловлено, может быть повторно отловлено!
} finally {
i.doFinally();
}

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

Акции могут кооперироваться с другими акциями и с кодом скриптинга разными способами.

PageContext


Часто две акции в JSP-странице нужно скооперировать: когда, возможно, одна акция создаёт серверный объект, доступ к которому осуществляет вторая акция. Один из механизмов реализации этого - дать объекту имя внутри JSP-страницы; первая акция создаст объект и ассоциирует имя с ним, а вторая акция будет использовать это имя для запроса объекта.

Например, в следующем JSP-фрагменте акция foo может создать серверный объект и дать ему имя "myObject". Затем акция bar может получить доступ к этому серверному объекту и выполнить какое-нибудь действие.


<x:foo id="myObject" />

<x:bar ref="myObjet" />


В JSP-реализации отображение "имя"->значение хранится в неявном объекте pageContext. Этот объект передаётся по кругу через экземпляры обработчика Tag так, что он (объект) может использоваться для передачи информации: всё, что необходимо, это знать имя, под которым информация хранится в pageContext.


Стэк Времени Прогона/Runtime Stack

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


<foo>

<bar/>

</foo>


Эта функциональность поддерживается через BodyTagSupport.findAncestorWithClass(Tag, Class), который использует ссылку на родительский тэг, сохраняемую каждым экземпляром Tag, что эффективно представляет стэк выполнения времени/этапа прогона.

JSP.10.5 Классы Времени Трансляции

Следующие классы используются на этапе трансляции.


Tag
-отображение, Tag-имя

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

На этапе выполнения реализация JSP-страницы будет использовать доступный экземпляр Tag с соответствующими установками свойств, а затем следовать протоколу, описанному интерфейсами Tag, IterationTag, BodyTag и TryCatchFinally. Реализация гарантирует, что все экземпляры обработчика тэга инициализируются и высвобождаются, но реализация может принимать, что предыдущие установки сохраняются обработчиком тэга, чтобы уменьшить затраты на этапе прогона.


Переменные Скриптинга

JSP поддерживает переменные скриптинга, которые могут объявляться внутри одного скриптлета и использоваться в другом. JSP-акции также можно использовать для определения переменных скриптинга, чтобы использовать их затем в элементах скриптинга или в других акциях. Это особенно применимо в некоторых случаях; например, стандартная акция jsp:useBean может определять объект, который позднее используется через переменную скриптинга.

В некоторых случаях информация переменных скриптинга может быть описана непосредственно в TLD, используя элементы. Особый случай - типичная итерация атрибута &quotid". В других случаях логика, определяющая определение экземпляром акции переменной скриптинга, может быть довольно сложной, и имя класса TagExtraInfo используется вместо данного в TLD. Метод getVariableInfo этого класса используется во время трансляции для получения информации о каждой переменной, которая будет создана во время запроса, когда данная акция выполняется. Метод передаётся в TagDat-экземпляр, содержащий значения атрибутов времени трансляции.

Проверка/Validation

TLD-файл содержит несколько частей информации, которая используется для проверки синтаксиса на этапе трансляции. Он содержит также два расширяемых механизма проверки: класс TagLibraryValidator может использоваться для проверки всей JSP-страницы, а класс TagExtraInfo может использоваться для проверки специфической акции. В некоторых случаях дополнительная проверка на этапе запроса будет выполняться динамически внутри методов в экземпляре Tag. Если обнаружена ошибка, может быть вызван экземпляр JspTagException. Если ошибка не выловлена, этот объект будет вызывать механизм errorpage JSP.


TagLibraryValidator
является дополнением к спецификации JSP 1.2 и заканчивается очень открыто, будучи значительно более мощным, чем механизм TagExtraInfo. JSP-страница представляется через объект PageData, который абстрагирует XML-просмотр JSP-страницы. Экземпляр PageData будет предоставлять InputStream (только для чтения) в странице. Последующие спецификации могут добавить другие просмотры страницы (DOM, SAX, JDOM являются кандидатами). В настоящее время эти просмотры могут генерироваться из InputStream и, возможно, кэшироваться для повышения производительности (вызов просмотра страницы делается "только для чтения").

JSP-контейнер может по выбору поддерживать атрибут jsp:id для более качественной проверки ошибок. Если атрибут поддерживается, контейнер будет отслеживать JSP-страницы по мере передачи контейнеру и назначать каждому элементу уникальный идентификатор "id", который передаётся как значение атрибута jsp:id. Каждый XML-элемент, доступный в XML-просмотре, будет расширен этим атрибутом. TagLibraryValidator может затем использовать этот атрибут в одном или более объектах ValidationMessage. Затем контейнер, в свою очередь, может использовать эти значения для предоставления более точной информации о местонахождении ошибки.


Детали Проверки


Более детально, проверка выполняется так:


Во-первых, JSP-страница разбирается с использованием информации в TLD. На этом этапе проверяются атрибуты - мандатные и по выбору/optional.


Во-вторых, для всех директив taglib страницы, в лексическом порядке их появления, вызывается класс их ассоциированного проверщика (если имеется). Это вызывает выполнение нескольких дополнительных шагов.

Первый шаг выполняется для получения инициализированного экземпляра проверщика путём, либо:

Имя класса - такое, какое указано в элементе <validator-class>, а Map, переданный в setInitParameters() - такой, как описано в элементе <init-params>. Предполагается, что все классы TagLibraryValidator сохраняют свои initParameters до тех пор, пока не будут установлены новые или пока release() не будет в них вызван.


Второй дополнительный шаг выполняет реальную проверку. Это делается через вызов метода validate() с префиксом, uri и PageData, которые соответствуют проверяемому экземпляру директивы taglib и PageData, представляющему эту страницу.


Последний дополнительный шаг вызывает метод release() в тэге проверщика, когда он уже больше не нужен.

Этот метод освобождает все ресурсы.


Наконец, после проверки всех классов проверщика библиотеки тэгов, классы TagExtraInfo для всех тэгов будут проверяться вызовом их метода isValid. Порядок вызова этого метода не определён.

JSP.10.5.1 TagLibraryInfo


Синтаксис


public abstract class TagLibraryInfo


Описание


Это информация времени трансляции, ассоциированная с директивой taglib и её TLD-файлом. Большая часть информации получается непосредственно из TLD, за исключением значений префикса и uri, используемых в директиве taglib.

JSP.10.5.1.16 Поля


protected java.lang.String info

protected java.lang.String jspversion

protected java.lang.String prefix

protected java.lang.String shortname

protected TagInfo[] tags

protected java.lang.String tlibversion

protected java.lang.String uri

protected java.lang.String urn


JSP.10.5.1.17 Конструкторы


protected TagLibraryInfo(java.lang.String prefix, java.lang.String uri)


Конструктор. Будут вызываться конструкторы для TagInfo и TagAttributeInfo после разбора TLD-файла.


Параметры:


prefix
- префикс, используемый директивой taglib

uri - URI, используемый директивой taglib

JSP.10.5.1.18 Методы


public java.lang.String getInfoString()

  Информация (документация) для данного TLD.


public java.lang.String getPrefixString()

  Префикс, назначенный этой taglib из директивы <%taglib.


public java.lang.String getReliableURN()

  "Надёжное" URN, указанное в TLD. Может использоваться утилитами авторизации в качестве глобального идентификатора (атрибут uri) при создании директивы taglib для данной библиотеки.


public java.lang.String getRequiredVersion()

  Строка, описывающая требуемую версию JSP-контейнера.


public java.lang.String getShortName()

  Предпочтительное краткое имя (префикс), как указано в TLD. Может использоваться утилитами авторизации в качестве предпочтительного префикса при создании директивы include для данной библиотеки.


public TagInfo getTag(java.lang.String shortname)

  Получает TagInfo для данного имени тэга, просматривая все тэги в данной библиотеке тэгов.


Параметры:


shortname
- Краткое имя (не префикс) тэга.


public TagInfo[] getTags()
  Массив, описывающий тэги, определённые в данной библиотеке.


public java.lang.String getURI()

  Значение атрибута uri из директивы <%@ taglib для данной библиотеки.

JSP.10.5.2 TagInfo


Синтаксис

public class TagInfo


Описание


Информация Tag для тэга в Библиотеке Тэгов; этот класс инстанциируется из файла TLD/Дескриптора Библиотеки Тэгов и доступна только во время трансляции.

JSP.10.5.2.19 Поля
 

public static final java.lang.String BODY_CONTENT_EMPTY
 static-константа для getBodyContent(), если он пустой.


public static final java.lang.String BODY_CONTENT_JSP

 static-константа для getBodyContent(), если это JSP.


public static final java.lang.String BODY_CONTENT_TAG_DEPENDENT

 static-константа для getBodyContent(), если это зависит от Tag.


JSP.10.5.2.20 Конструкторы


public TagInfo(java.lang.String tagName, java.lang.String tagClassName, java.lang.String bodycontent, java.lang.String infoString, TagLibraryInfo taglib, TagExtraInfo tagExtraInfo, TagAttributeInfo[] attributeInfo)


Конструктор для TagInfo из данных в формате JSP 1.1 для TLD. Этот класс инстанциируется только из кода TagLibrary по запросу из некоторого кода JSP, разбирающего TLD (Tag Library Descriptor). Заметьте, что, поскольку TagLibibraryInfo отражает информацию TLD и директивы taglib, экземпляр TagInfo зависит от директивы taglib. Возможно это ошибка дизайна, которая может быть зафиксирована в будущем.


Параметры:


tagName
- имя того тэга.

tagClassName - имя класса обработчика тэга.

bodycontent - информация о теле содержимого этих тэгов.

infoString - строковая информация (optional) для данного тэга.

taglib - экземпляр библиотеки тэгов, содержащей их.

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

attributeInfo - массив данных AttributeInfo из дескриптора. Может быть null.


public TagInfo(java.lang.String tagName, java.lang.String tagClassName, java.lang.String bodycontent, java.lang.String infoString, TagLibraryInfo taglib, TagExtraInfo tagExtraInfo, TagAttributeInfo[] attributeInfo, java.lang.String displayName, java.lang.String smallIcon, java.lang.String largeIcon, TagVariableInfo[] tvi)


Конструктор для TagInfo из данных в формате JSP 1.2 для TLD. Этот класс инстанциируется только из кода TagLibrary по запросу из некоторого кода JSP, разбирающего TLD. Заметьте, что, поскольку TagLibibraryInfo отражает информацию TLD и директивы taglib, экземпляр TagInfo зависит от директивы taglib. Возможно это ошибка дизайна, которая может быть зафиксирована в будущем.


Параметры:


tagName
- имя того тэга.

tagClassName - имя класса обработчика тэга.

bodycontent - информация о теле содержимого этих тэгов.

infoString - строковая информация (optional) для данного тэга.

taglib - экземпляр библиотеки тэгов, содержащей их.

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

attributeInfo - массив данных AttributeInfo из дескриптора. Может быть null.

displayName - краткое имя для отображения утилитами.

smallIcon - путь к маленькой иконке, отображаемой утилитами.

largeIcon - путь к большой иконке, отображаемой утилитами.

tagVariableInfo - массив TagVariableInfo (или null).


JSP.10.5.2.21 Методы


public TagAttributeInfo[] getAttributes()


Информация атрибута (в TLD) в этом тэге. Возвращается массив, описывающий атрибуты данного тэга, как указано в TLD. Возврат null означает отсутствие атрибутов.


Возвращает: массив TagAttributeInfo для данного тэга.


public java.lang.String getBodyContent()


Информация bodycontent для данного тэга.


Возвращает: строку содержимого тела.


public java.lang.String getDisplayName()


Получает displayName.


Возвращает: Краткое имя для вывода утилитами.


public java.lang.String getInfoString()


Информационная строка для тэга.


Возвращает: информационную строку.


public java.lang.String getLargeIcon()


Получает путь к большой иконке.


Возвращает: путь к большой иконке, отображаемой утилитами.


public java.lang.String getSmallIcon()


Получает путь к маленькой иконке.


Возвращает: путь к маленькой иконке, отображаемой утилитами.


public java.lang.String getTagClassName()


Имя класса, предоставляющего обработчик для данного тэга.


Возвращает: имя класса обработчика тэга.


public TagExtraInfo getTagExtraInfo()


Экземпляр (если имеется) для дополнительной информации тэга.


Возвращает: экземпляр TagExtraInfo, если имеется.


public TagLibraryInfo getTagLibrary()


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


Возвращает: экземпляр библиотеки тэгов, к которому мы принадлежим.


public java.lang.String getTagName()


Имя тэга.


Возвращает: (краткое) имя тэга.


public TagVariableInfo[] getTagVariableInfos()


Получает объекты TagVariableInfo, ассоциированные с этим TagInfo.


Возвращает: объект TagVariableInfo, ассоциированный с этим объектом.


public VariableInfo[] getVariableInfo(TagData data)


Информация об объектах скриптинга, созданных этим тэгом на этапе прогона/runtime. Это удобный метод в ассоциированном классе TagExtraInfo. По умолчанию null, если тэг не имеет атрибута "id", иначе - {"id", Object}


Параметры:


data
- TagData, описывающие данную акцию.


Возвращает: массив элементов VariableInfo.


public booleanisValid(TagData data)


Проверка атрибутов на этапе трансляции. Это удобный метод в ассоциированном классе TagExtraInfo.


Параметры:


data
- экземпляр TagData времени трансляции.


Возвращает: верны ли данные.


public void setTagExtraInfo(TagExtraInfo tei)


Набор экземпляров для дополнительной информации тэга.


Параметры:


tei - экземпляр TagExtraInfo.


public void setTagLibrary(TagLibraryInfo tl)


Устанавливает свойство TagLibraryInfo. Заметьте, что элемент TagLibraryInfo зависит не просто от информации TLD, но также и от специфики используемого экземпляра taglib. Это означает, что некоторая работа должна быть проделана для конструирования и инициализации объектов TagLib. Если использовать аккуратно, этот setter поможет исключить необходимость создания новых элементов TagInfo для каждой директивы taglib.


Параметры:


tl
- назначаемый TagLibraryInfo.


public java.lang.String toString()


Строго для целей отладки ...


Переопределяет: java.lang.Object.toString() в классе java.lang.Object

JSP.10.5.3 TagAttributeInfo


Синтаксис
 

public class TagAttributeInfo


Описание


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

JSP.10.5.3.22 Поля
 

public static final java.lang.String ID


"id"
окружается, чтобы стать ID. Реально это не даёт преимущества, поскольку IDREF не обрабатываются раздельно.

JSP.10.5.3.23 Конструкторы


public TagAttributeInfo(java.lang.String name, boolean required, java.lang.String type, boolean reqTime)


Конструктор для TagAttributeInfo. Этот класс инстанциируется только из кода TagLibrary по запросу из некоторого JSP-кода, разбирающего TLD.


Параметры:


name
- имя атрибута.

required - необходим ли атрибут в экземплярах тэга.

type - имя типа атрибута.

reqTime - содержит ли данный атрибут Attribute времени запроса.


JSP.10.5.3.24 Методы


public booleancanBeRequestTime()


Может ли данный атрибут содержать значение времени запроса.


Возвращает: может ли данный атрибут содержать значение времени запроса.


public static TagAttributeInfo getIdAttribute(TagAttributeInfo[] a)


Удобный static-метод, проходящий по массиву объектов TagAttributeInfo и ищущий "id".


Параметры:


a - массив TagAttributeInfo.


Возвращает: ссылку на TagAttributeInfo с именем "id".


public java.lang.String getName()


Имя этого атрибута.


Возвращает: имя атрибута.


public java.lang.String getTypeName()


Тип (как String) этого атрибута.


Возвращает: тип атрибута.


public booleanisRequired()


Необходим ли данный атрибут.


Возвращает: необходим ли данный атрибут.


public java.lang.String toString()


Переопределяет: java.lang.Object.toString() в классе java.lang.Object

JSP.10.5.4 PageData


Синтаксис


public abstract class PageData


Описание


Информация времени трансляции о JSP-странице. Информация соответствует XML-просмотру JSP-страницы.

Объекты этого типа генерируются JSP-транслятором, например, при передаче экземпляру TagLibraryValidator.

JSP.10.5.4.25 Конструкторы


public PageData()

JSP.10.5.4.26 Методы
 

public abstract java.io.InputStream getInputStream()

Возвращает поток ввода в XML-просмотре JSP-страницы. Вызывает XML-просмотр JSP-страницы, который содержит развёрнутые директивы include.


Возвращает: поток ввода документа.

JSP.10.5.5 TagLibraryValidator


Синтаксис


public abstract class TagLibraryValidator


Описание


Класс проверщика этапа трансляции для JSP-страницы. Проверщик оперирует документом XML, ассоциированным с JSP-страницей. TLD-файл ассоциирует класс TagLibraryValidator и некоторые init-аргументы с библиотекой тэгов.

JSP-контейнер отвечает за размещение соответствующих объектов соответствующего подкласса через:

Экземпляр TagLibraryValidator может создавать вспомогательные объекты внутри для выполнения проверки (например, проверщик XSchema) и может использовать их для всех страниц в ходе данной трансляции.

JSP-контейнер не сериализует гарантированно вызовы метода validate(), и TagLibraryValidator'ы должны выполнять синхронизацию, которая может потребоваться.


JSP-контейнер может по выбору поддерживать атрибут jsp:id для предоставления качественной проверки ошибок. Если такая поддержка имеется, контейнер будет отслеживать JSP-страницы, передаваемые контейнеру, и будет назначать каждому элементу уникальный "id", который передаётся как значение атрибута jsp:id. Каждый элемент XML, доступный в XML-просмотре, будет расширен этим атрибутом.

TagLibraryValidator
может затем использовать этот атрибут в одном или более объектах ValidationMessage. Контейнер тогда, в свою очередь, может использовать эти значения для предоставления более точной информации о местонахождении ошибки.

JSP.10.5.5.27 Конструкторы
 

public TagLibraryValidator()

JSP.10.5.5.28 Методы


public java.util.Map getInitParameters()


Получает данные init-параметров как неизменяемую Map/Карту. Имена параметров это ключи, а значения параметров - это значения.


Возвращает: параметры init как неизменяемую карту.


public void release()


Высвобождает любые данные, хранимые этим экземпляром, с целью проверки.


public void setInitParameters(java.util.Map map
)

Устанавливает данные init в TLD для этого проверщика. Имена параметров это ключи, а значения параметров - это значения.


Параметры:


initMap
- карта, описывающая параметры init.


public ValidationMessage[] validate(java.lang.String prefix, java.lang.String uri, PageData page)


Проверяет JSP-страницу. Будет вызван однократно на каждую директиву в JSP-странице. Этот метод возвратит null, если страница верна/valid; иначе метод должен возвратить массив объектов ValidationMessage. Массив нулевой длины также интерпретируется как отсутствие ошибок.


Параметры:


prefix
- значение аргумента prefix в директиве.

uri - значение аргумента uri в директиве.

thePage - JspData-объект страницы.

Возвращает: null-объект, или массив нулевой длины при отсутствии ошибок, или массив объектов ValidationMessages.

JSP.10.5.6 ValidationMessage


Синтаксис


public class ValidationMessage


Описание


Сообщение о проверке из TagLibraryValidator. JSP-может (по выбору) поддерживать атрибут jsp:id для предоставления качественной проверки ошибок. Если такая поддержка имеется, контейнер будет отслеживать JSP-страницы, передаваемые контейнеру, и будет назначать каждому элементу уникальный "id", который передаётся как значение атрибута jsp:id. Каждый элемент XML, доступный в XML-просмотре, будет расширен этим атрибутом. TagLibraryValidator может затем использовать этот атрибут в одном или более объектах ValidationMessage. Контейнер тогда, в свою очередь, может использовать эти значения для предоставления более точной информации о местонахождении ошибки.

JSP.10.5.6.29 Конструкторы


public ValidationMessage(java.lang.String id, java.lang.String message)


Создаёт ValidationMessage. String сообщения должна быть не-null. Значение id может быть null, если сообщение не специфично для XML-элемента или если не были переданы никакие атрибуты jsp:id. Если не-null, значение id обязано быть значением атрибута jsp:id для PageData, передаваемым в метод validate().


Параметры:


id
- либо null, либо значение атрибута jsp:id.

message - локализованное сообщение о проверке.

JSP.10.5.6.30 Методы
 

public java.lang.String getId()

Получает jsp:id.
null означает, что нет доступной информации.


Возвращает: jsp:id-информацию.


public java.lang.String getMessage()


Получает локализованное сообщение о проверке.


Возвращает: сообщение о проверке.

JSP.10.5.7 TagExtraInfo


Синтаксис


public abstract class TagExtraInfo


Описание


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

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

JSP-транслятор отвечает за то, чтобы начальное значение, возвращаемое в вызове getTagInfo(), соответствовало объекту TagInfo транслируемого тэга. Если выполняется явный вызов setTagInfo(), тогда передаваемый объект будет возвращён в последующих вызовах getTagInfo().

Единственный способ повлиять на значение, возвращаемое методом getTagInfo(), - через вызов setTag-Info() и, следовательно, TagExtraInfo.setTagInfo() вызывается JSP-транслятором с объектом TagInfo, который соответствует транслируемому тэгу. Это должно происходить до любого вызова isValid()  и до любого вызова getVariableInfo().

JSP.10.5.7.31 Конструкторы

public TagExtraInfo()

JSP.10.5.7.32 Методы

public final TagInfo getTagInfo()

Получает TagInfo для этого класса.


Возвращает: экземпляр taginfo, расширяемый данным экземпляром.


public VariableInfo[] getVariableInfo(TagData data)


Информация о переменных скриптинга, определённых тэгом, ассоциированным с данным экземпляром TagExtraInfo. Атрибуты времени запроса указаны как таковые в параметре TagData.


Параметры:


data
- экземпляр TagData.


Возвращает: массив данных VariableInfo.


public boolean isValid(TagData data)


Проверка атрибутов на этапе трансляции. Атрибуты времени запроса указаны как таковые в параметре TagData.


Параметры:


data
- экземпляр TagData.


Возвращает: верен ли этот экземпляр тэга.


public final void setTagInfo(TagInfo tagInfo)


Устанавливает TagInfo для данного класса.


Параметры:


tagInfo
- TagInfo, расширяемая этим экземпляром.

JSP.10.5.8 TagData


Синтаксис


public class TagData implements java.lang.Cloneable


Все Реализованные Интерфейсы: java.lang.Cloneable


Описание


Информация (только времени трансляции) атрибута/значения для экземпляра тэга. TagData используется только в качестве аргумента методов isValid и getVariableInfo в TagExtraInfo, которые вызываются во время трансляции.

JSP.10.5.8.33 Поля


public static final java.lang.Object REQUEST_TIME_VALUE


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

JSP.10.5.8.34 Конструкторы


public TagData(java.util.Hashtable attrs)


Конструктор для TagData. Если Вы уже имеете атрибуты в хэш-таблице, используйте этот конструктор.


Параметры:


attrs
- хэш-таблица для получения из неё значений.


public TagData(java.lang.Object[][] atts)


Конструктор для TagData.


Типичный конструктор может быть таким:


static final Object[][] att = {{"connection", "conn0"},

{"id", "query0"}};

static final TagData td = new TagData(att);


Значения обязаны быть String, за исключением тех, которые содержат известные объекты REQUEST_TIME_VALUE.


Параметры: atts - статические атрибут и значения. Может быть null.

JSP.10.5.8.35 Методы


public java.lang.Object getAttribute(java.lang.String attName)


Значение атрибута. Содержит известный объект REQUEST_TIME_VALUE, если значение является значением этапа запроса. Возвращает null, если атрибут не установлен.


Возвращает: объект значения атрибута.


public java.util.Enumeration getAttributes()


Перечисляет атрибуты.


Возвращает: перечисление атрибутов в TagData.


public java.lang.String getAttributeString(java.lang.String attName)


Получает значение для данного атрибута.


Возвращает: строка значений атрибута.


public java.lang.String getId()


Значение атрибута id, если имеется.


Возвращает: значение атрибута id или null.


public void setAttribute(java.lang.String attName, java.lang.Object value)


Устанавливает значение атрибута.


Параметры:


attName
- имя атрибута.

value - значение.

JSP.10.5.9 VariableInfo


Синтаксис


public class VariableInfo


Описание


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

Переменные скриптинга, генерируемые специальной акцией, могут иметь значения области видимости page, request, session и application.

Имя класса (VariableInfo.getClassName) в возвращаемых объектах может использоваться для определения типов переменных скриптинга. В связи с этим специальная акция не может создавать переменную скриптинга примитивного/базового типа. Чтобы обойти это, используйте "boxed/боксовые" типы.

Имя класса может быть Полным Квалифицированным Именем Класса, или кратким именем класса.

Если предоставляется Полное Квалифицированное Имя Класса, оно должно ссылаться на класс, находящийся в CLASSPATH для Web-Приложения (см. спецификацию Servlet 2.3 - как правило это WEB-INF/lib и WEB-INF/classes). Невыполнение этого приводит к ошибке времени трансляции.

Если дано краткое имя класса в объектах VariableInfo, тогда имя класса обязано быть именем public-класса в контексте директив import страницы, на которой специальная акция появилась (будет проверяться, имеется ли словоблудие JLS для ссылки на него). Класс обязан также быть в CLASSPATH для Web-Приложения (см. спецификацию Servlet 2.3 - как правило это WEB-INF/lib и WEB-INF/classes). Невыполнение этого приводит к ошибке времени трансляции.

Использование Комментариев

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

Употребление полных квалифицированных имён в такой манере делает их использование относительно устойчивым к ошибкам конфигурации.

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


Протокол Синхронизации

Результатом вызова getVariableInfo является массив объектов VariableInfo. Каждый такой объект описывает переменную скриптинга, предоставляя её имя, тип, указывая, является ли переменная новой или нет, и какова её область видимости. Область видимости лучше видна на рисунке:
 


Спецификация JSP 1.2 определяет интерпретацию трёх значений:

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

Информация о Переменной в TLD

Информация переменной скриптинга может быть также непосредственно кодирована для большинства случаев в Tag Library Descriptor путём использования субэлемента <variable> элемента <tag>. См. спецификацию JSP.

JSP.10.5.9.36 Поля

public static final int AT_BEGIN
  Информация области видимости о том, что переменная скриптинга видна после начального тэга.


public static final int AT_END

  Информация области видимости о том, что переменная скриптинга видна после конечного тэга.


public static final int NESTED

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


JSP.10.5.9.37 Конструкторы


public VariableInfo(java.lang.String varName, java.lang.String className, boolean declare, int scope)


Конструктор. Эти объекты могут быть созданы (на этапе трансляции) экземплярами TagExtraInfo.


Параметры:


id
- имя переменной скриптинга.

className - имя переменной скриптинга (наверное, класса??).

declare - если true, это новая переменная (в некоторых языках это требует объявления).

scope - обозначение лексической области видимости переменной.

JSP.10.5.9.38 Методы


public java.lang.String getClassName()

public boolean getDeclare()

public int getScope()

public java.lang.String getVarName()

JSP.10.5.10 TagVariableInfo


Синтаксис


public class TagVariableInfo


Описание


Информация переменной для тэга в Библиотеке Тэгов. Этот класс инстанциируется из TLD-файла и доступен только во время трансляции. Этот объект должен быть неизменяемым.

Данная информация доступна только в формате JSP 1.2.

JSP.10.5.10.39 Конструкторы


public TagVariableInfo(java.lang.String nameGiven, java.lang.String nameFromAttribute, java.lang.String className, boolean declare, int scope)


Конструктор для TagVariableInfo.


Параметры:


nameGiven
- значение <name-given>

nameFromAttribute - значение <name-from-attribute>

className - значение <variable-class>

declare - значение <declare>

scope - значение <scope>

JSP.10.5.10.40 Методы


public java.lang.String getClassName()

Тело элемента <variable-class>.


Возвращает: имя класса переменной.


public booleangetDeclare()


Тело элемента <declare>.


Возвращает: объявляется переменная, или нет.


public java.lang.String getNameFromAttribute()


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


Возвращает: атрибут, чьё значение определяет имя переменной.


public java.lang.String getNameGiven()


Тело элемента <name-given>.


Возвращает: имя переменной как константу.


public int getScope()


Тело элемента <scope>.


Возвращает: область видимости для переменной.


Глава JSP.2

Синтаксис Ядра и Семантика


В этой главе описаны синтаксис ядра и семантика спецификации JavaServer Pages 1.2 (JSP 1.2).

JSP.2.1 Что такое Страница JSP?

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

JSP-страница определяет класс реализации JSP-страницы который реализует семантику JSP-страницы. Этот класс является подклассом Servlet'а (см. Главу JSP.8). Во время запроса, запрос, предназначенный для JSP-страницы, направляется объекту реализации JSP-страницы для обработки/процесинга.

HTTP является протоколом по умолчанию для запросов и ответов. Дополнительные протоколы запроса/ответа могут поддерживаться JSP-контейнерами (см. ниже). Объекты request и response по умолчанию имеют тип HttpServletRequest и HttpServletResponse, соответственно.

JSP.2.1.1 Web-Контейнеры и Web-Компоненты

JSP-контейнер это экземпляр системного уровня, предоставляющий обслуживание жизненного цикла и поддержку на этапе прогона для JSP-страниц Servlet-компонентов. Запросы, направляемые JSP-странице, направляются JSP-контейнером подходящему объекту реализации JSP-страницы. Термин web-контейнер является синонимом JSP-контейнера.

Web-компонент это сервлет или JSP-страница. Элемент servlet в дескрипторе публикации web.xml используется для описания обоих типов web-компонентов. Компоненты - JSP-страницы - определяются неявно в дескрипторе публикации через использование неявного отображения расширения  .jsp

JSP.2.1.2 XML-Документ для Страницы JSP

JSP-страницы имеют эквивалент - XML-документ. XML-просмотр JSP-страницы создан для фазы трансляции (см. ниже).

JSP-страница может быть написана сразу как XML-документ. Начиная с версии JSP 1.2, XML-документ может быть направлен JSP-контейнеру для процесинга.

Нельзя смешивать стандартный синтаксис и XML-синтаксис в одном файле-источнике. Однако JSP-страница любого синтаксиса может включать JSP-страницу любого синтаксиса через директиву.

JSP.2.1.3 Фазы Трансляции и Выполнения

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

Во время фазы трансляции контейнер локализует или создаёт класс реализации JSP-страницы, соответствующий данной JSP-странице. Этот процесс определяется семантикой JSP-страницы. Контейнер интерпретирует имеющиеся на этой странице стандартные директивы и акции и специальные акции, ссылающиеся на библиотеки тэгов. Библиотека тэгов может по выбору представлять метод проверки корректности использования на JSP-странице данной библиотеки.

JSP-контейнер гибко работает с деталями класса реализации JSP-страницы, что может использоваться для адресации вопросов quality-of-service/качества-сервиса.


В фазе выполнения JSP-контейнер направляет события объекту реализации JSP-страницы. Контейнер отвечает за инициацию объектов request и response и вызов подходящего объекта реализации JSP-страницы.

По окончании процессинга, объект response получается контейнером для соединения с клиентом.
Детали соглашения/контракта между классом реализации JSP-страницы и JSP-контейнером описаны в Главе JSP.8.


Трансляция JSP-страницы-источника в класс её реализации может произойти в любой момент между начальной публикацией JSP-страницы в JSP-контейнер и получением и процессингом запроса клиента для целевой JSP-страницы. В Разделе JSP.2.1.5 описывается выполнение фазы трансляции перед публикацией.

JSP.2.1.4 События на Страницах JSP

JSP-страница может отмечать обработку некоторых событий. В JSP 1.2 только события init и destroy могут быть описаны в JSP-странице.


Когда первый запрос направляется JSP-странице, метод jspInit(), если он имеется, будет вызван для подготовки страницы. Аналогично, JSP-контейнер может вызывать метод JSP jspDestroy() для переделки ресурсов, используемых JSP-страницей, в любой момент, когда запрос не обслуживается. Это такой же жизненный цикл, что и у сервлетов.

JSP.2.1.5 Компилирование Страниц JSP

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

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

Компиляция JSP-страницы в контексте web-приложения предоставляет разрешение спецификаций относительных URL в директивы include (и в другом месте), ссылок на taglib и акции времени трансляции, используемых в специальных акциях.


JSP-страница может также компилироваться во время публикации.
 

JSP.2.1.5.1 Упаковка Страницы JSP
 

Когда класс реализации JSP-страницы зависит от поддержки классов (в дополнение к классам JSP 1.2 и Servlet 2.3), классы поддержки включаются в упакованный WAR-файл (как определено в спецификации Servlet 2.3) для обеспечения переносимости по JSP-контейнерам.


В Приложении JSP.A есть два примера упаковки JSP-страниц в WAR'ы:

  1. JSP-страница, направляемая в своей исходной форме (вероятно, это самый распространённый случай).
  2. JSP-страница, оттранслированная в класс реализации плюс информация для публикации.

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

JSP.2.1.6 Отладка Страниц JSP

Раньше утилиты отладки не имели стандартного формата для передачи информации отображения исходного кода, позволяющей использовать отладчик одного производителя с JSP-контейнером другого. Спецификация с поддержкой отладки, преодолевшая эти ограничения, разрабатывается как JSR-045 процесса JCP 2.0 под названием "Debugging Support for Non-Java Languages/Поддержка Отладки для Не-Java-Языков".


Детали можно найти по адресу  http://jcp.org/jsr/detail/45.jsp

JSP.2.1.7 Соглашение по Именованию для Файлов JSP

JSP-страница упаковывается в один или более файлов, часто - как web-приложение, и направляется утилите типа JSP-контейнера, J2EE-контейнера или IDE. Полная JSP-страница может содержаться в одном файле. В других случаях основной файл содержит другие файлы, которые содержать полные JSP-страницы или включаемые фрагменты.

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

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


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

Мы рекомендуем (но не обязываем), чтобы:

JSP.2.2  Web-Приложения

Приложение web это коллекция ресурсов, которые доступны по указанным URL.

Web-приложение состоит из следующих компонентов:

Web-приложения описаны более детально в спецификации Servlet 2.3. Web-приложение содержит дескриптор публикации web.xml, содержащий информация о JSP-страницах, сервлетах и других ресурсах, используемых в этом web-приложении. Дескриптор публикации детально описан в спецификации Servlet 2.3.

JSP 1.2 требует, чтобы эти ресурсы были неявно/косвенно ассоциированы с, и доступны через, уникальный экземпляр ServletContext, доступный как неявный объект приложения (Раздел JSP.2.8).

Приложение, которому принадлежит JSP-страница, отражается в объекте application и влияет на семантику следующих элементов:

JSP 1.2 поддерживает переносимую упаковку и публикацию/deployment web-приложений через спецификацию Servlet 2.3. Спецификация JavaServer Pages наследует от спецификации Servlet концепцию приложений, ServletContext'ы, Sessions/Сессии, Requests/Запросы и Responses/Ответы.

JSP.2.2.1 Специфицирование Относительных URL

Элементы могут использовать спецификации относительных URL, называемые "URI-пути" в спецификации Servlet 2.3. Эти пути описаны в спецификации RFC 2396. Мы имеем в виду часть path данной спецификации, а не части scheme или authority.

Некоторые примеры:

Путь относительно контекста это путь, начинающийся со знака "/". Он интерпретируется относительно приложения, к которому принадлежит JSP-страница, то есть говорится, что её объект ServletContext предоставляет базовый контекстный URL.


Путь относительно страницы это путь, не начинающийся со знака "/". Он интерпретируется как относительный к текущей JSP-странице или текущему JSP-файлу, в зависимости от того, где путь используется:

для директивы include (Раздел JSP.2.10.3); когда путь используется в  атрибуте файла - интерпретация относительно JSP-файла;

для акции jsp:include (Раздел JSP.4.4), когда путь используется атрибуте страницы - интерпретация относительно JSP-страницы.

В обоих случаях текущая страница (или файл) обозначается некоторой частью пути, начинающейся с "/", который (путь) затем модифицируется новой спецификацией, производящей путь с начальным "/".

Новый путь интерпретируется через объект ServletContext. См. точную информацию об этой интерпретации в Разделе JSP.2.10.4.


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

JSP.2.3 Синтаксические Элементы Страницы JSP

В этом разделе описаны базовые синтаксические правила JSP-страниц.

JSP.2.3.1 Элементы и Шаблонные Данные

JSP-страница содержит элементы и шаблонные данные.

Элемент
является экземпляром типа элемента, известного JSP-контейнеру.

Шаблонные данные
это то, о чём JSP-танслятор ничего не знает.

Тип элемента описывает его синтаксис и семантику. Если элемент имеет атрибуты, тип описывает имена, верные типы атрибутов и их интерпретацию. Если элемент определяет объекты, семантика включает эти определяемые объекты и их типы.

JSP.2.3.2 Синтаксис Элемента

Имеются элементы трёх типов: директивы, элементы скриптинга и акции.

Директивы
 

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


Синтаксис элемента-директивы  <%@ директива...%>

Акции
 

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

Элементы action следуют синтаксису XML-элемента: они имеют начальный тэг, включающий имя элемента, и могут иметь атрибуты, необязательное тело/body и соответствующий конечный тэг, или они могут быть пустыми тэгами, возможно, с атрибутами:
 

<mytag attr1="значение атрибута"...>body</mytag>
 

и


<mytag attr1="значение атрибута".../>

<mytag attr1="значение атрибута" ...></mytag>
 

Элемент имеет тип элемента, описывающий имя его тэга, верные атрибуты и их семантику.

Мы обращаемся к типу по имени его тэга.


JSP-тэги чувствительны к регистру, как в XML и XHTML.


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

Элементы Скриптинга


Элементы Скриптинга являются связкой между шаблонным текстом и акциями.

Есть три типа элементов скриптинга: declarations\объявления, scriptlets\скриптлеты и expressions\выражения.


Объявления имеют синтаксис <%! ... %>

скриптлеты   <% ... %>

выражения     <%= ... %>

JSP.2.3.3 Начальный и Конечный Тэги

Элементы, имеющие разные начальный и конечный тэги (при наличии тела), обязаны иметь начало и конец в одном файле. Стартовый тэг не может быть в одном файле, когда конечный тэг находится в другом файле.
То же самое правило применяется к элементам с альтернативным синтаксисом. Например, скриптлет имеет синтаксис <% скриптлет %>. Открывающий <% и закрывающий %> символы обязаны находиться в одном и том же физическом файле.
Язык скриптинга может также вводить ограничения на размещение начальных и конечных тэгов для специфических конструкций скриптинга. Например, в Главе 6 демонстрируется, как блоки языка Java не могут разделять начальный и конечный тэг; см. детали в Разделе JSP.6.4.

JSP.2.3.4 Пустые Элементы

Следуя спецификации XML, элемент, описанный с использованием пустого тэга, не отличается от элемента. использующего начальный тэг, пустое тело и конечный тэг.
Вот примеры пустых тэгов:
 

<x:foo></x:foo>

<x:foo />

<x:foo/>

<x:foo><%-- любой комментарий --%></x:foo>
 

Далее - примеры непустых тэгов:
 

<foo> </foo>

<foo><%= выражение %></foo>

<foo><% скриптлет %></foo>

<foo><bar/></foo>

<foo><!-- комментарий --></foo>

JSP.2.3.5 Значения Атрибутов

Следуя спецификации XML, атрибуты всегда заключаются в кавычки. Одинарные или двойные кавычки могут использоваться для уменьшения необходимости ввода кавычек мнемониками; соглашения по кавычкам описаны в Разделе JSP.2.6. Есть два типа значений атрибутов: литералы и выражения времени запроса (Раздел JSP.2.13.1), но правила применения кавычек - одинаковы.

JSP.2.3.6 Правильные Имена Акций и Атрибутов

Имена акций обязаны следовать соглашению XML (т.е. обязаны быть NMTOKEN, как указано в спецификации XML 1.0). Имена атрибутов обязаны следовать соглашениям, описанным в спецификации JavaBeans.
Имена атрибутов, начинающиеся с jsp, _jsp, java или sun зарезервированы данной спецификацией.

JSP.2.3.7 Пробелы

В HTML и XML пробел обычно не является значащим, но есть исключения. Например, файл XML может начинаться символами <?xml, и, если это так, ведущих пробельных символов не должно быть.

Данная спецификация следует поведению пробелов, определённому в спецификации XML.

Пробел в теле текста документа не является значащим, но сохраняется.


Далее идут два фрагмента JSP с ассоциированным выводом.
Обратите внимание, что директивы не генерируют никаких данных и применяются глобально к JSP-странице.

Таблица 2.1: Пример 1 - Ввод
N Строки Исходный Текст
1 <?xml version="1.0" ?>
2 <%@ page buffer="8kb" %>
3 Здесь - остальная часть документа.


Результат:

Таблица 2.2: Пример 1 - Вывод
N Строки Текст на Выходе
1 <?xml version="1.0" ?>
2  
3 Здесь - остальная часть документа.


Следующие две таблицы - другой пример ввода и вывода:


Таблица 2.3: Пример 2 - Ввод
N Строки Исходный Текст
1 <% response.setContentType("....");
2 что-нибудь... %><?xml version="1.0" ?>
3 <%@ page buffer="8kb" %>
4 Здесь - остальная часть документа.


Результат:

Таблица 2.4: Пример 2 - Вывод
N Строки Текст на Выходе
1 <?xml version="1.0" ?>
2  
4 Здесь - остальная часть документа.

JSP.2.4  Обработка Ошибок

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

JSP.2.4.1 Ошибки Процесса Времени Трансляции

Трансляция JSP-страницы-источника в соответствующий класс реализации JSP-страницы JSP-контейнером может производиться в любой момент между начальной публикацией JSP-страницы в JSP-контейнер и получением и обработкой запроса клиентом целевой JSP-страницы.

Если трансляция возникает до получения клиентского запроса целевой JSP-страницы, обработка ошибок и уведомление зависят от реализации и не рассматриваются в данной спецификации. Фатальные ошибки трансляции должны в результате приводить к невозможности выполнения последующих клиентских запросов на трансляцию целевой страницы с соответствующей спецификацией ошибки: для протоколов HTTP будет возвращаться код ошибки 500 (Server Error/Ошибка Сервера).

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

В процессе обработки запросов клиентов ошибки могут возникать в теле класса реализации JSP-страницы или в каком-либо другом коде (языка Java или других языков программирования реализации), вызываемом из тела класса реализации JSP-страницы.

Возникающие ошибки этапа прогона обрабатываются в реализации страницы, используя механизм исключений языка программирования Java для сообщения вызывающему(-им) о нарушениях.


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


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


Нарушающее java.lang.Throwable, описывающее появляющуюся ошибку, хранится в экземпляре javax.ServletRequest клиентского запроса, использующего метод setAttribute(), использующего имя "javax.servlet.jsp.jspException".

Имена, начинающиеся с префиксов "java" и "javax", зарезервированы различными спецификациями платформы Java. Префикс "javax.servlet" зарезервирован и используется спецификациями Servlet и JSP.

Если атрибут errorPage директивы страницы именует URL, который ссылается на другую JSP и та JSP сигнализирует, что на странице имеется ошибка (установкой атрибута isErrorPage директивы страницы в true), тогда неявная переменная языка программирования "exception" этой страницы инициализируется ссылкой Throwable-нарушителя.

JSP.2.5 Комментарии

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

JSP.2.5.1 Генерирование Комментариев при Выводе Клиенту

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

<!-- комментарии ... -->
 

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

<!-- комментарии <%= выражение %> ещё комментарии ... -->

JSP.2.5.2 Комментарии JSP

JSP-комментарий имеет форму:
 

<%-- что-либо, кроме закрывающих символов --%> ... --%>


Содержимое тела комментария полностью игнорируется. Комментарии используются для документирования, а также для "закомментирования" некоторой части JSP-страницы.

Обратите внимание, что JSP-комментарии не вкладываются.


Альтернативным способом размещения "комментария" на JSP-странице является использование механизма комментария языка скриптинга. Например:
 

<% /** это комментарий ... **/ %>

JSP.2.6 Соглашения по Кавычкам
и Escape-Последовательностям

В JSP-страницах применяются следующие соглашения по кавычкам:

Кавычки в Элементах Скриптинга
 

Литерал %> закавычивается %\>

Кавычки в Шаблонном Тексте


Литерал <% закавычивается <\%

Закавычивание Атрибутов


Закавычивание выполняется независимо от того, является значение атрибута литералом или выражением атрибута этапа запроса. Закавычивание может использоваться в значениях атрибутов независимо от того, ограничены они одинарными или двойными кавычками. Это выполняется только так, как описано ниже:

Примеры
 

В следующей строке показаны неправильные значения атрибутов:

В следующей строке дан верный скриптлет, но с, возможно, неожиданным результатом. Результат будет "Joe said %\>", а не "Joe said %>":


В следующих строках - правильное закавычивание:

Представление XML


Соглашения по кавычкам отличаются от соглашений XML. См. Главу JSP.5.

JSP.2.7 Общая Семантика Страницы JSP

Класс реализации JSP-страницыопределяет отображение метода _jspService() из объекта request в объект response. Некоторые детали этой трансформации специфичны для используемого языка скриптинга (см. Главу JSP.6). Некоторые детали не зависят от языка и описаны в данной главе.

Содержимое JSP-страницы большей частью описывает данные, которые записываются в поток вывода ответа. (JSP-контейнер обычно посылает эти данные обратно клиенту.) Это описание базируется на объекте JspWriter, который выводится через неявный объект out (см. Раздел JSP.2.8.3, "Неявные Объекты).

Его значение варьируется:

JSP.2.8 Объекты

JSP-страница может создавать и модифицировать серверные объекты/server-side и получать к ним доступ.

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

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

Элементы скриптинга могут получать доступ к объектам непосредственно через переменную скриптинга.

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

JSP.2.8.1 Объекты и Переменные

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


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

Тип элемента указывает имя и тип таких переменных, хотя в деталях имя переменной может зависеть от Языка Скриптинга.

Язык скриптинга может также влиять на то, как происходит доступ к различным свойствам объекта. Например, в спецификации JavaBeans доступ к свойствам осуществляется через методы getter и setter, в то время как эти свойства доступны напрямую как переменные в языке JavaScript≥.

Точные правила видимости переменных зависят от языка скриптинга. В Главе JSP.2.1 определены правила для случая, когда атрибут language директивы page установлен в "java".

JSP.2.8.2 Объекты и Область Видимости

JSP-страница может создавать и/или получать доступ к Java-объектам при обработке запроса. Спецификация JSP указывает, что некоторые объекты создаются неявно, возможно, как результат директивы (см. Раздел JSP.2.8.3, "Неявные Объекты"). Другие объекты создаются явно через акции или непосредственно путём использования кода скрипта. Созданные объекты имеют атрибут scope, определяющий, где находится ссылка на объект и когда эта ссылка удаляется.

Созданные объекты могут также непосредственно видимы элементам скриптинга через переменные уровня скриптинга (см. Раздел JSP.2.8.3, "Неявные Объекты"). Каждая акция и объявление определяют, как часть своей семантики, какой объект они создают, с каким атрибутом scope и доступны ли они элементам скриптинга.


Объекты создаются внутри экземпляра JSP-страницы, которая отвечает объекту request.

Имеется несколько областей видимости:

Имя/name должно ссылаться на уникальный объект из всех точек в ходе выполнения, то есть все области видимости должны в действительности вести себя как единое пространство имён. Реализация JSP-контейнера может или может не форсировать это правило явно по соображениям производительности.

JSP.2.8.3 Неявные/Implicit Объекты

Авторы JSP-страниц имеют доступ к определённым неявным (неявно создаваемым) объектам, которые всегда доступны для использования в скриптлетах и выражениях через переменные скриптинга, которые объявляются неявно в начале страницы. Все языки скриптинга должны предоставлять доступ к этим объектам.

Неявные объекты доступны обработчикам тэгов через объект pageContext (см. ниже).

Каждый неявный объект имеет тип класса или интерфейса, определённый в основной технологии Java или в пакете Java Servlet API, как показано в Таблице JSP. 2-1.


Таблица JSP.2-1 Неявные Объекты, Доступные в JSP-страницах
Имя Переменной Тип Семантика & Области Видимости
request подтип, зависящий от протокола: javax.servlet.ServletRequest,
например:
javax.servlet.http.HttpServletRequest
Запрос, включающий вызов сервиса/службы.
Область видимости: request.
response подтип, зависящий от протокола: javax.servlet.ServletResponse,
например:
javax.servlet.http.HttpServletResponse
Ответ на запрос.
Область видимости: page.
pageContext javax.servlet.jsp.PageContext Контекст страницы для данной JSP-страницы.
Область видимости: page.
session javax.servlet.http.HttpSession Объект session, созданный для запрашивающего клиента (если клиент имеется).
Эта переменная верна только для протоколов Http.
Область видимости: session.
application javax.servlet.ServletContext Контекст сервлета, полученный из объекта конфигурации сервлета (как при вызове
getServletConfig().getContext())
Область видимости: application.
out javax.servlet.jsp.JspWriter Объект, записывающий в поток вывода.
Область видимости: page.
config javax.servlet.ServletConfig ServletConfig для данной JSP-страницы.
Область видимости: page.
page java.lang.Object Экземпляр класса реализации данной страницы, обрабатывающий текущий запрос.
Область видимости: page.

a. Если язык скриптинга - "java", тогда "page" является синонимом для "this" в теле/body страницы.
Кроме того, может быть получен доступ к неявному объекту exception на странице ошибок, как указано в Таблице JSP.2-2.

JSP.2.8.4 Объект pageContext

PageContext это объект, предоставляющий контекст для хранения ссылок на объекты, используемые страницей. Он инкапсулирует зависящие от реализации свойства и предоставляет нужные методы. Класс реализации JSP-страницы может использовать PageContext для прогона в неизменённом виде в любом подходящем JSP-контейнере, одновременно используя преимущества специфичных для реализации улучшений типа высокопроизводительного JspWriters. См. детали в Главе JSP.9.

Таблица JSP.2-2 Неявные Объекты, Доступные на Страницах Ошибок\Error Pages
Имя Переменной Тип Семантика & Область Видимости

exception

java.lang.Throwable Неотловленный Throwable, приводящий к вызову страницы информации об ошибках.
Область видимости: page.

Имена объектов с префиксами jsp, _jsp, jspx и _jspx, в любой комбинации нижнего и верхнего регистров, зарезервированы данной спецификацией JSP. См. в Разделе JSP.7.6.1 некоторые ненормативные соглашения для введения новых неявных объектов.

JSP.2.9 Семантика Шаблонного Текста

Семантика шаблонного (или неинтерпретированного) Текста очень проста: шаблонный текст передаётся текущему out\выводящему неявному объекту JspWriter после применения замен Раздела JSP.2.6, "Соглашения по Кавычкам и Escape-Последовательностям".

JSP.2.10 Директивы

Директивы являются сообщениями JSP-контейнеру.

Синтаксис директивы:


<%@ директива { атрибут="значение" }* %>


Могут иметься необязательные пробелы после "<%@" и перед "%>". Это синтаксис легко вводится и понятен, но он несовместим с XML. В Главе JSP.5 описано отображение директив в элементы XML.

Директивы не производят никакого вывода в текущий поток out. Есть три директивы: page и taglib описаны здесь, а директива include - в следующей главе.

JSP.2.10.1 Директива page

Директива page определяет количество свойств страницы и сообщает о них JSP-контейнеру.

Трансляционный модуль (JSP файл-источник и любые файлы, включённые директивой include) может содержать более одного экземпляра директивы page, все атрибуты будут применяться ко всему трансляционному модулю (т.е. директивы page не зависят от позиции). Однако должно быть только одно вхождение любого атрибута/значения, определённого этой директивой, в данном трансляционном модуле, исключая атрибут "import"; многократные использования этого атрибута накапливаются (с семантикой объединения упорядоченного набора/ordered set union). Другие такие множественные (пере)определения атрибута/значения приводят к фатальной ошибке трансляции. Пространство имён attribute/value зарезервировано для использования данной и последующими спецификациями JSP.

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

Примеры


Следующая директива предоставляет некоторую видимую пользователем информацию на данной JSP-странице:
 

<%@ page info="my latest JSP Example" %>
 

Следующая директива запрашивает отсутствие буферизации, указывает, что страница является "безопасным потоком"/thread safe и предоставляет страницу для сообщений об ошибке:
 

<%@ page buffer="none" isThreadSafe="yes" errorPage="/oops.jsp" %>
 

Следующая директива указывает, что язык скриптинга базируется на Java, что типы, объявленные в пакете com.myco, непосредственно доступны коду скриптинга и что должна использоваться буферизация в 16KB:
 

<%@ page language="java" import="com.myco.*" buffer="16kb" %>

Синтаксис
 

<%@ page список_атрибутов_директивы_page %>
 

список_атрибутов_директивы_page ::= { language="scriptingLanguage\языкСкриптинга"}

{ extends="className"}
{ import="importList"}
{ session="true|false" }
{ buffer="none|sizekb" }
{ autoFlush="true|false" }
{ isThreadSafe="true|false" }
{ info="info_text" }
{ errorPage="error_url" }
{ isErrorPage="true|false" }
{ contentType="ctinfo" }
{ pageEncoding="peinfo"

Далее дана детальная информация об атрибутах:

Таблица JSP.2-1
Атрибут Описание
language Определяет язык скриптинга, используемый в скриптлетах, скриптлетах выражений и объявлениях внутри тела трансляционного модуля (JSP-страница любые файлы, включённые с использованием последующей директивы include). В JSP 1.2 единственным определённым и необходимым для данного атрибута значением языка скриптинга является "java". Данная спецификация описывает семантику только для скриптов со значением атрибута языка "java". Если "java" является значением языка скриптинга, фрагменты исходного кода Java Programming Language, используемые внутри данного трансляционного модуля, должны соответствовать спецификации Java Programming Language Specification так, как описано в Главе JSP.6.
Все языки скриптинга обязаны предоставлять неявные объекты, которые автор JSP-страниц может использовать в объявлениях, скриптлетах и выражениях. Специфические объекты, которые могут использоваться, определены в Разделе JSP.2.8.3, "Неявные Объекты."
Все языки скриптинга обязаны поддерживать Java Runtime Environment (JRE)/Среду Java. Все языки скриптинга обязаны представлять объектную модель технологии Java окружению скрипта, особенно неявные переменные, свойства компонентов JavaBeans и публичные методы. Будущие версии спецификации JSP могут определять дополнительные значения атрибута language, и все такие значения резервируются.
Для директивы с атрибутом language не-"java" будет фатальной ошибкой появление после первого вычисленного элемента скриптинга.
extends Значением является полное квалифицированное имя класса языка программирования Java, которое именует суперкласс класса, к которому JSP-страница трансформируется (см. Главу JSP.8). Этот атрибут не должен использоваться без тщательного учёта ограничения им способности JSP-контейнера предоставлять специализированные суперклассы, которые могут улучшить качество службы представления. См. в Разделе JSP.7.6.1 альтернативный способ ввода объектов на JSP-страницу, не имеющий такого недостатка.
import Атрибут import описывает типы, которые доступны среде скриптинга. Значение - такое же, как для объявления import в языке программирования Java, т.е. список (разделённых запятыми) полных квалифицированных имён типов языка программирования Java, обозначающих этот тип, или имя пакета с последующей строкой ".*", обозначающей все публичные типы, объявленные в этом пакете. Список import должен будет импортироваться транслируемой реализацией транслируемой JSP-страницы и будет, таким образом, доступен среде скриптинга.
По умолчанию список импорта - java.lang.*, javax.servlet.*, javax.servlet.jsp.* и javax.servlet.http.*. В настоящее время это значение определено только тогда, когда значением директивы language является "java".
session Означает, что данная страница требует участия в (http) сессии. Если "true", тогда неявная переменная языка скрипта с названием "session" типа javax.servlet.http.HttpSession ссылается на текущую/новую сессию для этой страницы. Если "false" - тогда эта страница не участвует в сессии; неявная переменная "session" недоступна, и любая ссылка на неё в теле JSP-страницы является недопустимой и приводит к фатальной ошибке трансляции. По умолчанию "true".
buffer Специфицирует модель буферизации для начального "out" JspWriter для обработки содержимого вывода с этой страницы. Если "none", тогда буферизации нет и весь вывод записывается непосредственно в ServletResponse PrintWriter. Размер может специфицироваться только в килобайтах, и суффикс "kb" является мандатным (обязательным). Если размер буфера специфицирован, тогда вывод буферизуется с размером буфера не меньше специфицированного. В зависимости от значения атрибута "autoFlush", содержимое этого буфера автоматически очищается, или возникает исключение при появлении переполнения. По умолчанию буферизуется с размером буфера реализации не менее 8kb.
autoFlush Специфицирует, должен ли буферизованный вывод очищаться автоматически (значение "true"), когда буфер заполнен, или должно вызываться исключение/exception (значение "false"), означающее переполнение буфера.
По умолчанию "true".
Примечание: не допускается установка autoFlush в "false", если "buffer=none".
isThreadSafe Обозначает уровень потока, безопасно выполняемого на странице. Если "false" - тогда JSP-контейнер должен выполнять диспетчеризацию множественных внешних запросов клиентов, по одному за раз в порядке их поступления, реализации страницы для процессинга. Если "true", тогда JSP-контейнер может избрать одновременное направление странице  множественных внешних запросов клиентов. Авторы страниц, использующие "true", должны быть уверены, что осуществляется соответствующая синхронизация доступа к странице.
По умолчанию "true".
Заметьте, что, даже если атрибут isThreadSafe имеет значение "false", автор JSP-страницы должен иметь уверенность, что доступы к любым объектам раздельного использования/shared соответствующим образом синхронизированы. Объекты могут использоваться раздельно в ServletContext или в HttpSession.
info Определяет произвольную строку, которая внедряется в транслируемую страницу, которая затем может быть получена из реализации страницы методом Servlet.getServletInfo().
isErrorPage Указывает, предназначена ли текущая JSP-страница служить целевым URL для другой JSP-страницы как errorPage. Если "true", тогда неявная переменная языка скриптинга "exception" определяется и её значением является ссылка на нарушающий Throwable из исходной JSP-страницы, в случае ошибки.
Если "false" - неявная переменная "exception" недоступна, и любая ссылка на неё в теле JSP-страницы является недопустимой и приведёт к фатальной ошибке трансляции.
По умолчанию "false".
errorPage Определяет URL ресурса, которому любой объект(ы) Throwable языка программирования Java, вызываемый, но не отлавливаемый реализацией страницы, направляется для обработки ошибки. Спецификация предоставляемого URL выполняется так, как указано в Разделе JSP.2.2.1. Если URL именует другую JSP-страницу, тогда неявная переменная скрипта вызываемого исключения этой JSP-страницы содержит ссылку на начальный неотловленый Throwable. URL по умолчанию зависит от реализации.
Обратите внимание, что объект Throwable передаётся реализацией страницы, вызывающей исключение/throwing, реализации страницы ошибки, сохраняя ссылку на объект в обычном объекте ServletRequest путём использования метода setAttribute(), с именем "javax.servlet.jsp.jspException".
Примечание: если autoFlush=true, то, если содержимое начального Jsp-Writer было очищено для потока вывода ServletResponse, любая последующая попытка диспетчеризации неотловленного исключения из страницы-нарушителя странице errorPage может потерпеть неудачу. Если страница обработки ошибок указана также в дескрипторе web.xml, то сначала применяется JSP-страница обработки ошибок, а затем страница web.xml.
contentType

Определяет кодировку символов для JSP-страницы и для JSP-страницы - ответа и тип MIME для JSP-страницы - ответа. Значения могут иметь форму "TYPE" или "TYPE; charset=CHARSET" с необязательным пробелом после ";".
CHARSET, если имеется, обязан быть значением IANA для кодировки символов.
TYPE это MIME-тип: см. в регистре IANA используемые значения.
Для TYPE значение по умолчанию - "text/html"; значение по умолчанию для кодировки символов - ISO-8859-1.
См. в Главе 3 детальную информацию о кодировках символов.

pageEncoding Определяет кодировку символов для JSP-страницы. Значения имеют форму "CHARSET", который обязан быть IANA-значением для кодировки символов. Значение contentType для CHARSET используется по умолчанию, если имеется, в противном случае - ISO-8859-1. См. в Главе 3 детальную информацию о кодировках символов.

JSP.2.10.2 Директива taglib

Набор значащих тэгов, интерпретируемых JSP-контейнером, может быть расширен "tag library/библиотекой тэгов". Директива taglib на JSP-странице объявляет, что данная страница использует библиотеку тэгов, уникально идентифицирует библиотеку тэгов, используя URI, и ассоциирует префикс тэгов, который служит для отличения использования акций в этой библиотеке. Если реализация JSP-контейнера не может локализовать описание библиотеки тэгов, должна возникать фатальная ошибка трансляции. Фатальная ошибка трансляции возникнет также, если директива taglib появится после акций, использующих данный префикс.

Библиотека тэгов может включать метод проверки корректности использования JSP-страницей функциональности библиотеки тэгов. См. более конкретные детали в Главе JSP.7. Также см. замечания по реализации в Разделе JSP.7.2.3.

Примеры


В следующем примере библиотека тэгов вводится и становится доступной данной странице путём использования префикса super; никакие другие библиотеки тэгов не должны вводиться на данной странице, используя этот префикс. В данном конкретном случае мы принимаем, что библиотека тэгов включает тип элемента doMagic, который используется на странице.
 

<%@ taglib uri="http://www.mycorp/supertags" prefix="super" />

...

<super:doMagic>

...

</super:doMagic>

Синтаксис


<%@ taglib uri="tagLibraryURI" prefix="tagPrefix" %>
 

где атрибуты:
 

Таблица JSP.2-1
uri Спецификация абсолютного или относительного URI, который уникально идентифицирует дескриптор библиотеки тэгов, ассоциированной с данным префиксом.
URI используется для локализации описания библиотеки тэгов, как указано в Главе 7.
tagPrefix Определяет строку prefix в конструкции <prefix>:<tagname>, которая используется для отличения специальной акции, например, <myPrefix:myTag>.
Использование префиксов, начинающихся с jsp:, jspx:, java:, javax:, servlet:, sun: и sunw:, зарезервировано.
Префикс обязан следовать соглашению об именовании, специфицированному в спецификации пространств имён XML.
Пустые префиксы в данной версии спецификации не допускаются.

Фатальная ошибка трансляции возникнет, если транслятор JSP-страницы обнаруживает тэг с именем prefix: Name, использующий префикс, введённый директивой taglib, и если Name не распознаётся соответствующей библиотекой тэгов.

JSP.2.10.3 Директива include

Директива include используется для подстановки текста и/или кода в JSP-страницу на этапе трансляции.

Директива <%@ include file="спецификация относительного URL" %> вставляет текст специфицированного ресурса в .jsp-файл. Включённый файл является субъектом контроля доступа, доступного JSP-контейнеру. Атрибут file рассматривается в Разделе JSP.2.2.1. JSP-контейнер может включать механизм уведомления в случае изменения включённого файла, чтобы контейнер мог перекомпилировать эту JSP-страницу, однако спецификация JSP 1.2 не содержит способа указания JSP-контейнеру, что включённые файлы должны изменяться.

Примеры
 

В следующем примере запрашивается включение на этапе трансляции файла авторских прав/copyright.
Этот файл может содержать элементы, которые также будут обрабатываться:
 

<%@ include file="copyright.html" %>

Синтаксис
 

<%@ include file="спецификация относительного URL" %>

JSP.2.10.4 Включение Данных в Страницы JSP

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

Таблица JSP.2-1 Обобщение Механизмов include в спецификации JSP 1.2
1
Синтаксис Спецификация Объект Описание
Директива include - Время Трансляции
<%@ include file=... %> относительно файла статический/static Содержимое разбирается/parsed JSP-контейнером. JSP.2.10.3
Акция include - Время Запроса
<jsp:include page= /> относительно страницы статический и динамический Содержимое не разбирается; оно вставляется в этом месте. JSP.4.4

Колонка Спецификация описывает, какой тип спецификации является верным для данного элемента. Данная спецификация JSP требует специфицировать относительный URL. Ссылка разрешается сервером web/приложений, и выполняется отображение её URL. Директивы include интерпретируются относительно текущего JSP-файла; акции jsp:include интерпретируются относительно текущей JSP-страницы. Директива include относится к ресурсу вроде JSP-страницы как к статичному/static объекту; т.е. байты в JSP-странице включаются. Акция include относится к ресурсу вроде JSP-страницы как к динамическому/dynamic объекту; т.е. запрос направляется этому объекту, и результат процессинга включается .

JSP.2.11 Элементы Скриптинга/Сценариев

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

Есть три класса элементов скриптинга: declarations\объявления, scriptlets\скриптлеты и expressions\выражения. Язык скриптинга, используемый на данной странице, задаётся значением директивы language (см. Раздел JSP.2.10.1, "Директива page"). В JSP 1.2 единственным определённым значением является "java".

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

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

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

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

Все такие языки скриптинга обязаны поддерживать:

Точное определение семантики скриптинга, выполняемого с использованием элементов на базе языка Java, дано в Главе JSP.6.

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

Каждый элемент скриптинга имеет следующий синтаксис на базе "<%":
 

<%! это объявление %>
 

<% это скриптлет %>
 

<%= это выражение %>
 

Могут иметься необязательные пробелы после "<%!", "<%" и "<%=" и до "%>".


Эквивалентные данным элементам скриптинга элементы XML описаны в Разделе JSP.5.2.

JSP.2.11.1 Объявления

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

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

Примеры


Например, первое объявление здесь объявляет целое число, глобальное в пределах страницы.

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

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

<%! int i; %>
 

<%! int i = 0; %>
 

<%! public String f(int i) { if (i<3) return("..."); ... } %>

Синтаксис
 

<%! объявление(-я) %>

JSP.2.11.2 Скриптлеты

Скриптлеты могут содержать любые фрагменты кода, которые являются верными для языка скриптинга, специфицированного директивой language. Является ли фрагмент кода действующим, зависит от деталей языка скриптинга (см. Главу JSP.6).

Скриптлеты выполняются во время обработки запроса. Производят они вывод в поток вывода или нет, зависит от кода скриптлета.

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

Чтобы использовать последовательность символов %> как литеральные символы в скриптлете, вместо того , чтобы они оканчивали скриптлет, вводите их так %\>.

Примеры


Вот простой пример динамического изменения страницы, в зависимости от времени суток.
 

<% if (Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM) {%>
Good Morning
<% } else { %>
Good Afternoon
<% } %>
 

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


<% int i; i= 0; %>
Привет, значение i равно <% i++ %>

Синтаксис


<% скриптлет %>

JSP.2.11.3 Выражения

Элемент expression в JSP-странице является выражением языка скриптинга, которое вычисляется, а результат приводится к String. Результат затем посылается в текущий объект вывода JspWriter. Если результат выражения не может быть приведён к String, обязаны выполняться следующие действия:

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

Если приведение не обнаруживается в процессе трансляции, должно вызываться исключение ClassCastException/ОшибкаПриведенияКласса во время запроса.

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

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

Выражения вычисляются во время HTTP-процессинга.

Значение выражения конвертируется к String и вставляется в соответствующую позицию в .jsp-файл.

Примеры


Вставляется текущая дата:


<%= (new java.util.Date()).toLocaleString() %>

Синтаксис


<%= выражение %>

JSP.2.12 Акции

Акции могут воздействовать на текущий поток вывода и использовать, модифицировать и/или создавать объекты. Акции могут зависеть от деталей конкретного объекта request/запроса, получаемого JSP-страницей.
Данная спецификация JSP содержит некоторые акции, которые являются стандартными и обязаны реализовываться всеми соответствующими JSP-контейнерами; эти акции описываются в Главе 4.

Новые акции определяются в соответствии с механизмами, описанными в Главах 7 и 10, и вводятся с использованием директивы taglib.

Синтаксис элементов акций базируется на XML. Акции могут быть пустыми и непустыми.

JSP.2.13 Семантика Интерпретации Атрибута Тэга

Интерпретация всех акций начинается с вычисления значений, данных их атрибутам, слева направо и присвоения этих значений атрибутам. В этом процессе могут производиться конверсии; правила конверсии описаны в Разделе JSP.2.13.2.

Многие значения являются фиксированными 'значениями времени трансляции', но JSP 1.2 предоставляет также механизм описания этих значений, когда они вычисляются на этапе запроса, правила описаны в Разделе JSP.2.13.1.

JSP.2.13.1 Значения Атрибутов Времени Запроса

Значение атрибута в форме "<%= scriptlet_expr %>" или '<%= scriptlet_expr %>' обозначает значение атрибута времени запроса. Указываемое значение является значением включаемого скриптлета. Значения атрибутов времени запроса могут использоваться только в акциях и не могут использоваться в директивах. Если в тэге имеется более одного такого атрибута, выражения вычисляются слева направо.

Закавычивание выполняется так же, как и в других значениях атрибута (Раздел JSP.2.6). Таким способом могут обозначаться только значения атрибута (имя атрибута всегда является явно определённым именем).

Выражение обязано появляться само по себе (множественные выражений и смешивание выражений и строковых констант не допускаются).

Множественные операции обязаны выполняться внутри выражения.

Конверсия типов описана в Разделе JSP.2.13.2. По умолчанию все атрибуты имеют семантику времени трансляции страницы. Попытка специфицировать выражение скриптлета как значение атрибута, который (по умолчанию или нет) имеет семантику времени трансляции, является недопустимой и приводит к фатальной ошибке трансляции.

Тип элемента action указывает, будет ли данный атрибут принимать значения атрибута времени запроса.

Большинство атрибутов стандартных акций из Главы 4 имеют семантику времени трансляции страницы, но следующие атрибуты принимают выражения атрибутов времени запроса:

JSP.2.13.2 Соглашения о Типах

Мы описываем два случая конверсии типов:

JSP.2.13.2.1 Конверсия из Значений String


Значение строки может использоваться для описания значения типа не-String через конверсию. Возможна ли конверсия и, если да, какая она, зависит от типа назначения.


Значения String могут использоваться для присвоения значений типу, который имеет класс PropertyEditor, как указано в спецификации JavaBeans. Если это именно тот случай, используется метод setAs-Text(String).

Конверсия терпит неудачу, если метод вызывает исключение IllegalArgumentException.


Значения String могут также использоваться для присвоения типов, как указано в Таблице JSP.2-2. Применяется так конверсия, которая указана в таблице. Неудача конверсии ведёт к ошибке времени трансляции или времени запроса.

Таблица JSP.2-2 Конверсия из Строковых Значений в Тип Назначения
Тип Назначения Исходное Строковое Значение
Свойство Bean Использовать setAsText(string-literal)
boolean или Boolean Как указано в java.lang.Boolean.valueOf(String)
byte или Byte Как указано в java.lang.Byte.valueOf(String)
char или Character Как указано в String.charAt(0)
double или Double Как указано в java.lang.Double.valueOf(String)
int или Integer Как указано в java.lang.Integer.valueOf(String)
float или Float Как указано в java.lang.Float.valueOf(String)
long или Long Как указано в java.lang.Long.valueOf(String)
short или Short Как указано в java.lang.Short.valueOf(String)
Object Как если бы new String(string-literal)

Эти конверсии являются частью общего механизма, используемого для присвоения значений атрибутам акций: когда значение атрибута, который не является атрибутом времени запроса, присваивается данному атрибуту, используется описанная здесь конверсия, использующая тип атрибута как целевой тип. Тип каждого атрибута стандартных акций описан в данной спецификации, а типы атрибутов специальных/custom акций описаны в ассоциированном с ними Дескрипторе Библиотеки Тэгов/Tag Library Descriptor.

Конкретная акция может также определять дополнительные способы использования конверсии типа/значения.

В Разделе JSP.4.2 описан механизм, используемый для стандартной акции setProperty.

JSP.2.13.2.3 Конверсия из Выражений Времени Запроса


Выражения времени запроса могут назначаться свойству любого типа.

Автоматическая конверсия не выполняется.


Глава JSP.3

Вопросы Локализации


В этой Главе описаны требования по локализации в JavaServer Pages 1.2 (JSP 1.2).

JSP.3.1 Кодировка Символов Страницы

Поддержка платформой Java локализованного содержимого базируется на универсальном внутреннем представлении текста как символов Unicode 2.0 (ISO010646) и поддержке нескольких кодировок символов в Unicode.

Java Virtual Machine (JVM)/Виртуальная Машина Java обязана поддерживать кодировки Unicode и Latin-1, но большинство машин поддерживают гораздо больше кодировок. Кодировки символов, поддерживаемые JVM от Sun, описаны по адресу: http://java.sun.com/products/jdk/1.1/docs/guide/intl/encoding.doc.html


JSP-страница использует кодировку символов. Кодировка может быть описана явно атрибутом pageEncoding директивы page . По умолчанию кодировка выполняется по атрибуту contentType директивы page , если она имеется, или, в противном случае, устанавливается ISO-8859-1. ISO-8859-1 известна также как Latin-1.


Верные имена кодировок символов в JSP 1.2 - те же, что и имена IANA. Они описаны по адресу:

 

ftp://venera.isi.edu/in-notes/iana/assignments/character-sets
 

Атрибут pageEncoding должен использоваться только тогда, когда кодировка символов JSP-страницы организована так, что символы ASCII отображают сами себя. Директива, содержащая атрибут pageEncoding, должна появляться на JSP-странице как можно раньше.


JSP-контейнер может использовать какую-нибудь зависящую от реализации эвристику и/или структуру для определения ожидаемой кодировки JSP-страницы и проверки соответствия атрибута contentType.


JSP-контейнер вызовет ошибку времени трансляции, если запрошена неподдерживаемая кодировка символов.

JSP.3.2 Статический Тип Содержимого

Большинство JSP-страниц написаны так, чтобы отправлять ответ, используя специфические тип содержимого/content type и кодировку символов. JSP-страница может использовать атрибут contentType директивы page для обозначения типа содержимого, предоставляемого в ответ на запросы. Если используется таким образом, данная страница будет всегда предоставлять содержимое одного и того же типа. Если страница определяет, что ответ должен иметь другой тип содержимого, она должна делать это "раньше", определяя, какая иная JSP-страница или сервлет будет обрабатывать этот запрос, и направлять запрос другой JSP-странице или сервлету. Значение TYPE по умолчанию "text/html", а значение по умолчанию для кодировки символов - ISO-8859-1. Регистр имён типов содержимого хранится в IANA.

См.: ftp://venera.isi.edu/in-notes/iana/assignments/media-types/media-types

Атрибут contentType обязан использоваться только в том случае, если кодировка символов организована так, что символы ASCII отображают сами себя, как минимум до тех пор, пока атрибут contentType не будет найден. Директива, содержащая атрибут contentType, должна появляться на JSP-странице как можно раньше.

JSP.3.3 Динамический Тип Содержимого

Некоторые JSP-страницы созданы так, что они могут направлять содержимое, используя различные типы содержимого и кодировки символов, в зависимости от ввода времени запроса. Эти страницы могут быть организованы как специальные акции или скриптлеты, которые определяют тип содержимого ответа и предоставляют 'связку' с другим кодом, реально генерирующим содержимое ответа.

Динамическая установка типа содержимого основана на вызове response.setcontentType(). Этот метод может быть вызван, пока никакого содержимого не было выслано в поток ответа. Данные высылаются в поток ответа при очистках буфера буферизованных страниц или при обнаружении первого содержимого (избегая пробелов) небуферизованных страниц.


Пробел в страницах JSP вводится известным трюком синтаксиса JSP, но более управляем в  JSP-страницах с синтаксисом XML.

JSP.3.4 Передача Локализованного Содержимого

Спецификация JSP не предписывает определённого подхода к структурированию локализованного содержимого, поэтому возможны различные подходы.

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


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


Глава JSP.4

Стандартные Акции


В этой главе описаны стандартные акции JavaServer Pages 1.2 (JSP 1.2).

JSP.4.1 <jsp:useBean>

Акция jsp:useBean ассоциирует экземпляр объекта языка программирования Java, определённый в данной области видимости/scope и доступный с данным id через вновь объявленную переменную скриптинга с тем же id.

Акция jsp:useBean весьма гибка: её точная семантика зависит от заданных атрибутов. Базовая семантика пытается найти существующий объект, используя id и область видимости. Если объект не найден, будет сделана попытка создания этого объекта с использованием других атрибутов.

Можно использовать эту акцию также для задания локального имени объекту, определённому в другом месте, например, в другой JSP-странице или Сервлете. Это может быть выполнено с помощью атрибута типа без предоставления атрибутов class или beanName. Должен быть представлен как минимум тип или класс, и неверным будет предоставление и class, и beanName. Если тип и класс имеются, class обязан быть назначен типу (в понимании Java-платформы). Невозможность его назначить является ошибкой времени трансляции.

Атрибут beanName специфицирует имя Bean'а, как указано в спецификации JavaBeans. Оно используется в качестве аргумента для метода instantiate() класса java.beans.Beans. Оно обязано иметь форму "a.b.c" и может быть именем класса или ресурса в форме "a/b/c.ser", которое будет разрешено в текущем ClassLoader/ЗагрузчикеКлассов. Если это не так, будет вызвано исключение времени запроса, как указано в семантике instantiate(). Значением этого атрибута может быть выражение атрибута времени запроса.

Более детально о роли id и scope говорится далее.

Атрибут id

Пара атрибут/значение id="имя" является элементом jsp:useBean и имеет специальное значение для JSP-контейнера во время трансляции страницы при обработке запроса клиента.

Конкретно:

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


Заметьте, что это подразумевает, что синтаксис значения name обязан соответствовать синтаксическим правилам именования переменных языка скриптинга, используемого на этой странице.

В Главе JSP.6 детально рассматривается случай, когда атрибут language - "java".

Пример использования правил правил области видимости, только что упомянутых, дан здесь:
 

<% { // вводится новый блок %>

...

<jsp:useBean id="customer" class="com.myco.Customer" />

<%

/*

* тэг создаёт или получает ссылку на Customer Bean,

* ассоциирует её с именем "customer"

* в PageContext и объявляет переменную языка программирования Java

* с тем же именем, которое инициализировано для ссылки на объект

* в пределах видимости этого блока.

*/

%>

...

<%= customer.getName(); %>

...

<% } // закрывает блок %>

<%

// переменная customer находится сейчас вне области видимости ,

// но объект всё ещё действует (и доступ к нему осуществляется через PageContext)

%>

Атрибут   scope

Пара атрибут/значение scope="page|request|session|application" ассоциирована с (и модифицирует) поведением атрибута id, описанного выше (она (пара) имеет семантику и времени трансляции, и времени процессинга запроса клиента).

Конкретнее, она описывает пространство имён, предполагаемый жизненный цикл ссылки на объект, ассоциированной с name, и API, используемые для доступа к этой ассоциации, таким образом:

Таблица JSP.4-1
page Именованный объект, доступный из javax.Servlet.jsp.PageContext для данной страницы.
Эта ссылка должна быть уничтожена после выполнения текущего запроса телом страницы.
Не допускается изменение объекта экземпляра, ассоциированного таким образом, что его (объекта?) тип времени прогона/выполнения является поднабором типа текущего объекта, ассоциированного ранее.
request Именованный объект, доступный из объекта ServletRequest текущей страницы через использование метода getAttribute(name).
Эта ссылка должна быть уничтожена после выполнения текущего клиентского запроса.
Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, что его (объекта?) тип времени прогона/выполнения является поднабором(-ами) типа объекта, ассоциированного ранее таким же образом.
session Именованный объект, доступный из объекта HttpSession текущей страницы (который, в свою очередь, может быть получен из объекта ServletRequest) через использование методаgetAttribute(name).
Эта ссылка должна быть уничтожена после аннулирования текущей сессии.
Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, чтобы его новый тип времени прогона был поднабором(-ами) типа объекта, ассоциированного ранее.
Заметьте, что будет фатальной ошибкой трансляции попытка использовать область видимости сессии, когда JSP-страница, делающая эту попытку, объявляется через директиву <%@ page ... %> (см. далее) так, что она не участвует в сессии.
application Именованный объект, доступный из объекта ServletContext текущей страницы через использование метода getAttribute(name).
Эта ссылка должна быть уничтожена после использования ServletContext.
Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, чтобы его новый тип времени прогона был поднабором(-ами) типа объекта, ассоциированного ранее таким же образом.
Семантика


Акциями, выполняемыми в jsp:useBean, являются:

  1. Попытка локализовать объект на базе значениях атрибутов id и scope. Синхронно выполняется проверка пространства имён области видимости/scope для исключения недетерминистического поведения.
    Переменная языка скриптинга специфицированного типа (если задан) или class/класс (если type не задан) определяется с данным id в текущей лексической области видимости языка скриптинга.
  2. Если этот объект найден, значение переменной инициализируется ссылкой на локализованный объект, приведённый к специфицированному типу. Если приведение терпит неудачу, должно возникать исключение java.lang.ClassCastException . Это завершает работу данной акции jsp:useBean.
  3. Если элемент jsp:useBean имел непустое тело/body, он игнорируется. Это завершает работу данной акции jsp:useBean.
  4. Если объект не найден в специфицированной области видимости и не заданы ни class, ни beanName, должно возникать исключение java.lang.InstantiationException. Это завершает работу данной акции jsp:useBean.
  5. Если объект не найден в специфицированной области видимости и класс/class специфицировал имена неабстрактного класса, который определяет публичный/public безаргументный конструктор, тогда создаётся экземпляр этого класса.
    Ссылка на новый объект ассоциируется с переменной скриптинга и со специфицированным именем в специфицированной области видимости через использование подходящей области видимости, в зависимости от механизма ассоциирования (см. PageContext). После этого выполняется шаг 7.
    Если объект не найден и класс является абстрактным классом, интерфейсом или не определён public безаргументный/no-args конструктор, тогда должно возникать исключение java.lang.InstantiationException. Это завершает работу данной акции jsp:useBean.
  6. Если объект не найден в специфицированной области видимости и задано имя beanName, тогда метод instantiate() класса java.beans.Beans будет вызван с Class-Loader/Загрузчиком-Классов объекта Servlet и с beanName в качестве аргументов.
    Если метод выполнен успешно, новая ссылка на объект ассоциируется с переменной скриптинга и со специфицированным именем в специфицированной области видимости через использование подходящей области видимости, в зависимости от механизма ассоциирования (см. PageContext). После этого выполняется шаг 7.
  7. Если элемент jsp:useBean имеет непустое тело/body, оно обрабатывается, переменная инициализируется и становится доступной в области видимости тела. Текст внутри тела рассматривается как обычно. Любой шаблонный текст будет передан в поток вывода. Тэги скриптлетов и акций вычисляются.
    Обычно непустое тело используется для завершения инициализации созданного экземпляра. В этом случае тело, вероятно, будет содержать акции jsp:setProperty и скриптлеты, которые вычисляются. Это завершает работу данной акции jsp:useBean.
Примеры


В этом примере Bean с именем "connection" и типом "com.myco.myapp.Connection" доступен после выполнения акций в этом элементе, или потому что он уже создан и найден, или потому что он создан заново.
 

<jsp:useBean id="connection" class="com.myco.myapp.Connection" />
 

В следующем примере свойство timeout устанавливается в 33, если Bean был инстанциирован.
 

<jsp:useBean id="connection" class="com.myco.myapp.Connection">
      <jsp:setProperty name="connection" property="timeout" value="33">
</jsp:useBean
>
 

В последнем примере объект должен существовать в данной сессии. Если это так, ему присваивается локальное имя wombat типа WombatType. Может возникать исключение ClassCastException, если это объект неверного класса, а InstantiationException может возникать, если объект не определён.
 

<jsp:useBean id="wombat" type="my.WombatType" scope="session"/>

Синтаксис


Эта акция может иметь или не иметь тело/body. Если акция не имеет тела, она имеет форму:
 

<jsp:useBean id="name" scope="page|request|session|application" typeSpec />

typeSpec ::= class="className" |
class="className" type="typeName" |
type="typeName" class="className" |
beanName="beanName" type="typeName" |
type="typeName" beanName="beanName" |
type="typeName"

Если акция имеет тело, она имеет форму:
 

<jsp:useBean id="name" scope="page|request|session|application" typeSpec >
     body
</jsp:useBean>
 

В этом случае тело тело будет вызвано, если Bean, обозначаемый этой акцией, создаётся. Обычно body будет содержать тэги скриптлетов или jsp:setProperty, которые будут использоваться для модификации вновь созданного объекта, но содержимое тела не ограничивается.

Тэг <jsp:useBean> имеет следующие атрибуты:

Таблица JSP.4-1
id Имя, используемое для идентификации экземпляра объекта в пространстве имён специфицированной области видимости, а также имя переменной скриптинга, объявленное и инициализированное вместе со ссылкой на этот объект.
Специфицированное пространство имён чувствительно к регистру и должно соответствовать соглашениям текущего языка скриптинга по именованию переменных.
scope Область видимости/scope, в зоне которой ссылка доступна. Значение по умолчанию - page.
См. описание атрибута scope, определённого ранее здесь же.
class Полное квалифицированное имя класса, определяющего реализацию объекта.
Имя класса чувствительно к регистру.
Если атрибуты class и beanName не специфицированы, объект обязан быть представлен в данной области видимости.
beanName Имя для Bean, как предполагается методом instantiate() класса java.beans.Beans. Этот атрибут может принимать в качестве значения выражение атрибута времени запроса.
type Если специфицирован, определяет тип переменной скриптинга.
Это позволяет типу переменной скриптинга отличаться от (но соотноситься с) типа специфицированного класса реализации.
Тип должен быть самим классом, суперклассом этого класса, либо интерфейсом, реализованным специфицированным классом.
Объект, на который ссылаются, должен быть этого типа, иначе должно возникать исключение java.lang.ClassCastException во время запроса, когда делается попытка назначения объекта, на который ссылаются, переменной скриптинга.
Если не специфицировано, значение будет тем же, что и значение атрибута class.

JSP.4.2 <jsp:setProperty>

Акция jsp:setProperty устанавливает значения свойств в Bean'е. Атрибут name, обозначающий этот Bean, обязан быть определён до появления этой акции.

Имеются два варианта акции jsp:setProperty. Оба они устанавливают значение одного или более свойств в Bean на базе типа свойств. Обычно в Bean выполняется самоанализ с целью обнаружения существующих свойств, и, для каждого из них,  имени, простое оно или индексированное, его типа и методов setter и getter. Самоанализ также указывает, имеет ли тип данного свойства класс PropertyEditor.


Свойства в Bean могут быть установлены из одного или более параметров объекта request, из String-константы или из вычисленного выражения времени запроса. Простые и индексированные свойства могут быть установлены с использованием jsp:setProperty.

При установке из параметра объекта request применяется конвертация, описанная в Разделе JSP.2.13.2.1, использующая целевое свойство для определения целевого типа.

При присвоении из значения, заданного как String-константа, применяется конвертация, описанная в Разделе JSP.2.13.2.1, использующая целевое свойство для определения целевого типа.

При присвоении из значения, заданного как атрибут времени запроса, никакая конвертация типов не применяется, как указано в Разделе JSP.2.13.2.3.

При присвоении значений индексированным свойствам значение обязано быть массивом/array; к элементам применяются правила, описанные в предыдущем параграфе. Неудача конверсии приводит к ошибке времени трансляции или времени запроса.

Примеры


Следующие два элемента устанавливают значение из значений параметра request:
 

<jsp:setProperty name="request" property="*" />

<jsp:setProperty name="user" property="user" param="username" />
 

Следующие два элемента устанавливают свойство из значения:
 

<jsp:setProperty name="results" property="row" value="<%= i+1 %>" />

Синтаксис
 

<jsp:setProperty name="beanName" prop_expr />
prop_expr ::=
property="*" |
property="propertyName"|
property="propertyName" param="parameterName"|
property="propertyName" value="propertyValue"
propertyValue ::= string

 

Значение propertyValue может также быть значением атрибута времени запроса, как описано в Разделе JSP.2.13.1.
 

propertyValue ::= expr_scriptlet (См. синтаксис скриптлета выражения "<%= ... %>")


Элемент <jsp:setProperty> имеет следующие атрибуты:

Таблица JSP.4-2
name Имя экземпляра Bean'а, определённое элементом <jsp:useBean> или каким-либо другим элементом.
Экземпляр Bean'а обязан содержать свойство, которое Вы хотите установить.
Определяющий элемент обязан появиться до элемента <jsp:setProperty> в том же файле.
property Имя свойства Bean'а, значение которого Вы хотите установить.
Если Вы устанавливаете propertyName в *, тогда тэг будет выполнять итерацию поверх текущих параметров ServletRequest, подбирая совпадения имён параметров и типа(-ов) значений с именами свойств и типом(-ами) метода setter, устанавливая каждое совпавшее свойство в значение совпадающего параметра.
Если параметр имеет значение "", соответствующее свойство не модифицируется.
param Имя параметра запроса, значение которого Вы хотите дать свойству Bean'а. Имя параметра запроса приходит обычно от web-формы.
Если param опущен, принимается, что имя параметра запроса - то же самое, что и имя свойства Bean'а.
Если param не установлен в объекте Request или если он имеет значение "", элемент jsp:setProperty не оказывает влияния (a noop - шо цэ такэ?).
Акция может не иметь атрибутов param и value.
value

Значение, присваиваемое данному свойству.
Этот атрибут может принимать выражение атрибута времени запроса в качестве значения.
Акция может не иметь атрибутов param и value.

JSP.4.3 <jsp:getProperty>

Акция <jsp:getProperty> помещает значение свойства экземпляра Bean'а, конвертированное к String, в неявный объект вывода, из которого Вы можете отобразить значение в качестве вывода. Экземпляр Bean'а обязан быть определён так, как указано в атрибуте name до этой точки страницы (обычно посредством акции jsp:useBean).

Конверсия к String выполняется также, как в методах println(), т.е. метод toString() данного объекта применяется для экземпляров Object, а примитивные типы конвертируются напрямую.

Если объект не найден, вызывается исключение времени запроса.

Значение атрибута name в jsp:setProperty и jsp:getProperty будет ссылаться на объект, который получен из объекта PageContext с помощью его метода findAttribute().

Объект, именованный посредством name, обязан быть "представлен" JSP-процессору путём использования акции jsp:useBean или специальной акции с ассоциированным входом VariableInfo для данного имени.


Примечание
: из предыдущего параграфа следует, что объекты, хранимые, скажем, в сессии лицевым/front компонентом, не являются автоматически видимыми акциям jsp:set-Property и jsp:getProperty на данной странице, если только акция jsp:useBean или какая-нибудь другая не делает их видимыми.

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

Пример
 

<jsp:getProperty name="user" property="name" />

Синтаксис


<jsp:getProperty name="name" property="propertyName" />

Таблица JSP.4-3 Атрибуты
name Имя экземпляра объекта, из которого получено свойство.
property Именует получаемое свойство.

JSP.4.4 <jsp:include>

Элемент <jsp:include .../> предоставляется для включения статических и динамических ресурсов в тот же контекст, что и у текущей страницы. См. в Таблице JSP.2-1 резюме по облегчению включения.
Включение производится в текущее значение out/вывода. Этот ресурс специфицирован путём использования relativeURLspec/спецификации относительного URI, которая интерпретируется в контексте web-сервера (т.е. она отображается/mapped).

Атрибуты page акций jsp:include и jsp:forward интерпретируются относительно текущей JSP-страницы, поскольку атрибут file в директиве include интерпретируется относительно текущего JSP-файла. См. ниже примеры таких комбинаций.

Включаемая страница имеет доступ только к объекту JspWriter и не может устанавливать шапки/headers. Это предотвращает вызов методов, подобных setCookie(). Попытки вызова таких методов будут игнорироваться. Это ограничение эквивалентно ограничению, вводимому методом include() класса RequestDispatcher.

Акция jsp:include может иметь субэлементы jsp:param, которые могут предоставлять значения некоторым параметрам в запросе для использования в процессе включения.

Процессинг запроса продолжается вызовом JSP-страницы, после того как включение выполнено.

Атрибут flush управляет очисткой. Если он true, тогда, если вывод страницы буферизуется и атрибут flush получает значение 'true', буфет очищается до включения, в ином случае буфер не очищается. По умолчанию атрибут flush имеет значение 'false'.

Примеры
 

<jsp:include page="/templates/copyright.html"/>
 

Вышеприведённый пример - это простое включение объекта. Путь интерпретируется в контексте Web-Приложения. Это похоже на static/статичный объект, но он может также отображаться в, например, Servlet посредством web.xml.

Например, в качестве более сложного набора включений рассмотрим следующие 4 ситуации, построенные с использованием 4 JSP-файлов: A.jsp, C.jsp, dir/B.jsp и dir/C.jsp:

Синтаксис
 

<jsp:include page="urlSpec" flush="true|false"/>

и

<jsp:include page="urlSpec" flush="true|false">

{ <jsp:<code></code> .... /> }*

</jsp:include>
 

В первом примере синтаксиса выполняется включение на этапе запроса.

Во втором случае значения в субэлементах param используются для увеличения запроса с целью включения.


Верными атрибутами являются:

Таблица JSP.4-4
page Этот URL является относительным urlSpec, как указано в Разделе JSP.2.2.1.
Относительные пути интерпретируются относительно текущей JSP-страницы.
Принимает атрибут времени запроса value (который обязан вычисляться до String, которая является спецификацией относительного URL).
flush Необязательный булев атрибут. Если "true", буфер немедленно очищается. По умолчанию - "false".

JSP.4.5 <jsp:forward>

Элемент <jsp:forward page="urlSpec" /> позволяет направлять на этапе прогона текущий запрос статическому ресурсу - JSP-странице или Java-классу Servlet в том же контексте, что и текущая страница.
jsp:forward эффективно прерывает выполнение текущей страницы. Относительный urlSpec - как в Разделе JSP.2.2.1. Объект запроса будет настроен в соответствии со значением атрибута page.

Акция jsp:forward может иметь субэлементы jsp:param, которые могут предоставлять значения для некоторых параметров запроса, используемых для перенаправления.

Если вывод страницы буферизуется, то буфер очищается перед перенаправлением.
Если вывод страницы буферизуется и буфер был очищен, то попытка направить запрос вызовет исключение IllegalStateException.

Если вывод страницы не буферизовался и в него что-то было записано, то попытка направить запрос вызовет исключение IllegalStateException.

Примеры
 

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

<% String whereTo = "/templates/"+someValue; %>

<jsp:forward page='<%= whereTo %>' />

Синтаксис
 

<jsp:forward page="relativeURLspec" />

   и

<jsp:forward page="urlSpec">

     { <jsp:param .... /> }*

</jsp:forward>


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

Таблица JSP.4-5
page URL является относительным urlSpec, как указано в Разделе JSP.2.2.1.
Относительные пути интерпретируются относительно текущей JSP-страницы.

Принимает атрибут времени запроса value (который обязан вычисляться до String, которая является спецификацией относительного URL).

JSP.4.6 <jsp:param>

Элемент jsp:param используется для предоставления информации ключ/значение. Этот элемент используется в элементах jsp:include, jsp:forward  и jsp:params. Должна вызываться ошибка времени трансляции, если этот элемент используется в другом месте.

При выполнении jsp:include или jsp:forward, включаемая страница или перенаправляемая страница будет просматривать оригинал объекта запроса с оригинальными параметрами, дополненными новыми параметрами с новыми значениями, имеющими приоритет над существующими значениями, где это нужно.

Областью видимости новых параметров является вызов jsp:include или jsp:forward; т.е., в случае с jsp:include - новые параметры (и значения) не будут применяться после включения. Это то же поведение, что и при использовании методов include и forward в ServletRequest (см. Раздел 8.1.1 в спецификации Servlet 2.2).

Например, если запрос имеет параметр A=foo, и параметр A=bar специфицирован для перенаправления, направляемый запрос должен будет сдержать A=bar,foo. Обратите внимание, что новый param имеет приоритет.

JSP.4.6.1 Синтаксис
 

<jsp:param name="name" value="value" />
 

Эта акция имеет два мандатных/обязательных атрибута: name и value.
Name это имя параметра, а value, которое может быть выражением времени запроса, это его значение.

JSP.4.7 <jsp:plugin>

Акция plugin даёт автору JSP-страниц возможность генерировать HTML, содержащий соответствующие клиентскому браузеру конструкции (OBJECT или EMBED), которые приводят к загрузке компонента Java Plugin (если это необходимо) и последующему выполнению специфицированного компонента Applet или JavaBeans.

Тэг <jsp:plugin> замещается тэгом <object> или <embed> - как больше подходит для запрашивающего Пользовательского Агента (ПА) - и выводится в поток вывода ответа/response.

Атрибуты тэга <jsp:plugin> предоставляют данные конфигурации для представления элемента, как показано далее в таблице.

Элементы <jsp:param> это параметры компонентов Applet или JavaBeans.

Элемент <jsp:fallback> это содержимое, используемое клиентским браузером, если компонент plugin не может стартовать (из-за того, что OBJECT или EMBED не поддерживаются клиентским браузером, либо по каким-то другим причинам).

Если plugin может стартовать, но компонент Applet или JavaBeans не может быть найден или не может стартовать, то сообщение, специфическое для данного plugin, будет показано пользователю: вероятнее всего - всплывающее окно, содержащее ClassNotFoundException.


Реальный код plugin не должен быть связан с JSP-контейнером. Ссылка на место размещения plugin'а Sun  может использоваться вместо этого, хотя некоторые продавцы ПО предпочитают включать plugin для удобства пользователя.

Примеры
 

<jsp:plugin type=applet code="Molecule.class" codebase="/html" >

<jsp:params>

<jsp:param

name="molecule"

value="molecules/benzene.mol"/>

</jsp:params>

<jsp:fallback>

<p> unable to start plugin </p>

</jsp:fallback>

</jsp:plugin>

Синтаксис
 

<jsp:plugintype="bean|applet"

  code="objectCode"

  codebase="objectCodebase"

  { align="alignment" }

  { archive="archiveList" }

  { height="height" }

  { hspace="hspace" }

  { jreversion="jreversion" }

  { name="componentName" }

  { vspace="vspace" }

  { width="width" }

  { nspluginurl="url" }

  { iepluginurl="url" } >

  { <jsp:params>

  { <jsp:<code></code> name="paramName" value="paramValue" /> }+

</jsp:params> }

  { <jsp:fallback> arbitrary_text </jsp:fallback> }

</jsp:plugin>

Таблица JSP.4-1
type Идентифицирует тип компонента: Bean или Applet.
code Как определено в HTML.
codebase Как определено в HTML.
align Как определено в HTML.
archive Как определено в HTML.
height Как определено в HTML. Принимает значение выражения времени прогона программы.
hspace Как определено в HTML.
jreversion Идентифицирует номер версии JRE, необходимый компоненту для работы; по умолчанию: "1.2"
name Как определено в HTML.
vspace Как определено в HTML.
title Как определено в HTML.
width Как определено в HTML. Принимает значение выражения времени прогона программы.
nspluginurl URL, с которого JRE-plugin может быть загружен для использования в Netscape Navigator, по умолчанию - определяется реализацией.
iepluginurl URL, с которого JRE-plugin может быть загружен для использования в IE, по умолчанию - определяется реализацией.

JSP.4.8 <jsp:params>

Акция jsp:params является частью акции jsp:plugin и может появляться только как прямой потомок элемента <jsp:plugin>.

Использование элемента jsp:params в любом ином контексте должно приводит к ошибке времени трансляции.

Семантика и синтаксис jsp:params описаны в Разделе JSP.4.7.

JSP.4.9 <jsp:fallback>

Акция jsp:fallback является частью акции jsp:plugin и может появляться только как прямой потомок элемента <jsp:plugin>.

Использование элемента jsp:fallback в любом ином контексте должно приводит к ошибке времени трансляции.

Семантика и синтаксис jsp:fallback описаны в Разделе JSP.4.7.


Глава JSP.5

JSP-Документы


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

Эта глава также определяет отображение/mapping между JSP-страницей и XML-описанием этой страницы, её XML view\XML-просмотр. XML-просмотр определён для JSP-страниц, написанных на JSP с синтаксисом XML.

JSP.5.1 Использование Синтаксиса XML для Страниц JSP

Синтаксис XML для JSP-страниц может использоваться по-разному, с том числе:

Проверка JSP-страницы поддерживается в спецификации JSP 1.2 с помощью класса TagLibraryValidator, ассоциированного с библиотекой тэгов. Класс-проверщик работает с объектом PageData, который представляет XML-просмотр JSP-страницы (см., например, Раздел JSP.7.5.1.2).


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

JSP.5.2 Документы JSP

JSP-документ это XML-документ, "знающий" о пространстве имён. Пространства имён используются для идентификации основного синтаксиса и библиотек тэгов, используемых на странице, и все относящиеся к JSP пространства имён вводятся в корне/root документа XML.

Основной синтаксис/core syntax определяется с помощью своего собственного URI. Хотя в этой главе используется префикс jsp, верным является любой префикс, если используется корректный URI, идентифицирующий основной синтаксис.

JSP-документ использует то же расширение файла (.jsp), что и JSP-страница с синтаксисом JSP. Контейнер может различить их, поскольку JSP-документ является XML-документом с верхним элементом jsp:root, а jsp:root не может появляться на JSP-странице с синтаксисом JSP.

Многие элементы XML в JSP-документе соответствуют элементам языка JSP, но можно включать элементы XML, непосредственно описывающие шаблон. Эти элементы могут иметь квалифицированные имена (и, таким образом, находиться в пространстве имён) или являться неквалифицированными. 


JSP-страница с синтаксисом XML может использовать следующие элементы:

JSP.5.2.1 Модель Семантики

Модель семантики JSP-документа не изменилась по сравнению с моделью семантики JSP-страницы с синтаксисом JSP: JSP-страницы генерируют ответный поток символов из шаблонных данных и динамических элементов. Шаблонные данные могут быть описаны явно элементом jsp:text или неявно фрагментом XML.

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

Чтобы точнее показать процессинг пробелов, мы следуем структуре спецификации XSLT. Первым шагом обработки JSP-документа является идентификация узлов документа. При этом все текстуальные узлы, содержащие только пробелы, из документа удаляются; единственным исключением являются узлы элемента jsp:text, которые сохраняются дословно. Результирующие узлы интерпретируются так, как описано в последующих разделах. Шаблонные данные либо передаются непосредственно в ответ/response, либо опосредованно через (стандартные или специальные/custom) акции.

В соответствии со спецификацией XML (и спецификацией XSLT), пробельными символами являются #x20, #x9, #xD и #xA.

JSP.5.2.2 Элемент jsp:root

JSP-документ содержит элемент jsp:root в качестве корневого элемента. Элемент root содержит атрибут xmlns, который даёт возможность использовать стандартные элементы, определённые в спецификации JSP 1.2. Кроме того, root это место, где будут вставляться атрибуты пространства имён для директив taglib.

Все библиотеки тэгов, используемые в JSP-документе, представлены в элементе root с помощью дополнительных атрибутов xmlns.

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

<jsp:root
xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:prefix1="URI-для-taglib1"
xmlns:prefix2="URI-для-taglib2"... >
version="1.2">

JSP-страница

</jsp:root>
 

Атрибут xmlns специальной библиотеки тэгов в форме xml:префикс='uri' идентифицирует библиотеку тэгов через значение uri. Значение uri может иметь две формы, "uri" или "urn:jsptld:путь".

Если значение uri имеет форму "urn:jsptld:путь", тогда TLD определяется в соответствии с механизмом из Раздела JSP.7.3.2.

Если значение uri является обычным "uri", тогда путь определяется путём сравнения с указанным отображением в web.xml, расширенным с использованием  неявного отображения в упакованные библиотеки тэгов (Разделы JSP.7.3.3 и JSP.7.3.4), как указано в Разделе JSP.7.3.6.

JSP.5.2.3 Элемент jsp:directive.page

Элемент jsp:directive.page определяет несколько зависящих от страницы свойств и передаёт их JSP-контейнеру. Этот элемент обязан быть потомком элементаroot и появляться в начале JSP-документа.

Его синтаксис:
 

<jsp:directive.page список_атрибутов_директивы_page />
 

где список_атрибутов_директивы_page\page_directive_attr_list - такой, как описано в Разделе JSP.2.10.1.

Интерпретация элемента jsp:directive.page описана в Разделе JSP.2.10.1, а его областью видимости/scope является JSP-документ и любой фрагмент, включённый директивой include.

JSP.5.2.4 Элемент jsp:directive.include

Элемент jsp:directive.include используется для замещения текста и\или кода на этапе трансляции JSP-страницы. Этот элемент может появляться в любом месте JSP-документа.

Его синтаксис:
 

<jsp:directive.include file="relativeURLspec\спецификация относительного URL" />

 

Интерпретация элемента jsp:directive.include описана в Разделе JSP.2.10.3.

XML-просмотр JSP-страницы не содержит элементов jsp:directive.include, вместо этого включённый файл разворачивается непосредственно в этом месте. Это делается для упрощения проверки.

JSP.5.2.5 Элемент jsp:declaration

Элемент jsp:declaration используется для объявления конструкций языка скриптинга, которые доступны всем другим элементам скриптинга. Элемент jsp:declaration не имеет атрибутов, и его тело/body - это само объявление.

Его синтаксис:
 

<jsp:declaration> здесь идёт объявление </jsp:declaration>


Интерпретация элемента jsp:declaration описана в Разделе JSP.2.11.1.

JSP.5.2.6 Элемент jsp:scriptlet

Элемент jsp:scriptlet используется для описания акций, выполняемых в ответ на некоторый запрос. Скриптлеты являются фрагментами программы. Элемент jsp:scriptlet не имеет атрибутов, и его тело - это фрагмент программы, содержащий скриптлет.

Его синтаксис:


<jsp:scriptlet> здесь - фрагмент кода </jsp:scriptlet>


Интерпретация элемента jsp:scriptlet описана в Разделе JSP.2.11.2.

JSP.5.2.7 Элемент jsp:expression

Элемент jsp:expression используется для описания сложных выражений на языке скриптинга, вычисляемых на этапе ответа. Элемент jsp:expression не имеет атрибутов, и его тело - это выражение.

Его синтаксис:


<jsp:expression> здесь - выражение </jsp:expression>


Интерпретация элемента jsp:expression описана в Разделе JSP.2.11.3.

JSP.5.2.8 Элементы Стандартных и Специальных Акций

JSP-документ может использовать стандартные акции, описанные в Главе JSP.4. Поскольку синтаксис этих элементов уже базируется на XML, описания этой главы достаточно, за исключением того, что в шаблоне JSP-документа текст может быть описан элементом jsp:text, либо посредством элемента XML, который не является ни стандартной, ни специальной акцией (см. Раздел JSP.5.2.11).

Для полноты приведём элементы-акции:

Семантика и ограничения описаны в Главе JSP.4, а интерпретация элементов скриптинга - в Главе JSP.6.
Библиотеки тэгов вводят новые элементы атрибутам xmlns или элементом jsp:root, а их синтаксис и семантика описаны в Главе JSP.7.

JSP.5.2.9 Атрибуты Времени Запроса

Элемент акции, который может принимать атрибут времени запроса (Раздел JSP.2.13.1), принимает аргумент для этого атрибута в форме "%= text %" (пробелы вокруг text не нужны, и отметьте отсутствие  '<' и '>'). Text, после применения кавычек (как и в любом другом документе XML), является выражением, вычисляемым по правилам Раздела JSP.2.13.1.

JSP.5.2.10 Элемент jsp:text

Элемент jsp:text можно использовать для включения шаблонных данных в представление XML.
Элемент jsp:text не имеет атрибутов и может появляться в любом месте, где могут появляться шаблонные данные.

Его синтаксис:


<jsp:text> шаблонные данные </jsp:text>


При интерпретации элемента jsp:text, его содержимое передаётся текущему значению out/вывода. Это очень напоминает работу элемента xsl:text из XSLT.

JSP.5.2.11 Другие XML-Элементы

Синтаксис XML для JSP-страниц допускает также появление XML-элементов, которые не представляют ни стандартных, ни специальных акций, в любом месте, где может появляться jsp:text.


Интерпретация такого XML-элемента - это передача его текстуального представления текущему значению out после процессинга пробелов, описанного в Разделе JSP.5.2.1.


Как пример, если фрагмент JSP-документа таков:

Таблица 5.1: Пример 1 - Ввод
N Строки Исходный Текст
1 <hello><jsp:scriptlet>i=3;</jsp:scriptlet>
2 <hi>
3 <jsp:text> hi you all
4 </jsp:text><jsp:expression>i</jsp:expression>
5 </hi>
6 </hello>

то результат будет:

Таблица 5.2: Пример 1 - Вывод
N Строки Итоговый Текст
1 <hello> <hi> hi you all
2 3 </hi></hello>

Обратите внимание на работу с пробелами.

JSP.5.3 XML-Просмотр Страницы JSP

В этом разделе описан XML-просмотр/view JSP-страницы: отображение между JSP-страницей, написанной с синтаксисом XML или JSP, и XML-документом, описывающим её.

JSP.5.3.1 JSP-Документы

XML-просмотр JSP-страницы, написанной с синтаксисом XML, очень похож на оригинал JSP-страницы.
Выполняются только две трансформации:

JSP.5.3.2 Страницы JSP и Синтаксис JSP

XML-просмотр JSP-страницы, написанной с синтаксисом XML, определяется следующей трансформацией:

Обратите внимание, что XML-просмотр JSP-страницы не имеет информации DOCTYPE; см. Раздел JSP.5.4.


Краткий обзор трансформации дан в Таблице JSP.5-1:

Таблица JSP.5-1 Трансформации XML-Просмотра
Элемент JSP-страницы XML-просмотр
<%-- комментарий --%> удалён.
<%@ page ... %> <jsp:directive.page ... />. По выбору добавляется jsp:id.
<%@ taglib ... %> элемент jsp:root снабжается информацией пространства имён. По выбору добавляется jsp:id.
<%@ include ... %> развёртывается в этом месте.

<%! ... %> <jsp:declaration> .... </jsp:declaration>. По выбору добавляется jsp:id.
<% ... %> <jsp:scriptlet> ... </jsp:scriptlet>. По выбору добавляется jsp:id.
<%= ... %> <jsp:expression> ... </jsp:expression>. По выбору добавляется jsp:id.

Стандартная акция замещается синтаксисом XML уточняются выражения времени запроса; по выбору добавляется jsp:id)
Специальная акция как есть (уточняются выражения времени запроса; по выбору добавляется jsp:id)
Шаблон замещается элементом jsp:text. По выбору добавляется jsp:id.

Более детально:

JSP.5.3.3 Комментарии JSP

JSP-комментарии (в форме <%-- комментарий --%>) не передаются в XML-просмотр JSP-страницы.

JSP.5.3.4 Директива page

Директива page в форме:
 

<%@ page { атрибут="значение" }* %>
 

транслируется в элемент в форме:
 

<jsp:directive.page { атрибут="значение" }* />

JSP.5.3.5 Директива taglib

Директива taglib в форме:
 


<%@ taglib uri="uriValue\значениеURI" prefix="префикс" %>

транслируется в атрибут xmlns:prefix элемента root JSP-документа со значением. которое зависит от uriValue. Если uriValue является относительным путём, то используемое значение будет "urn:jsptld:uriValue"; иначе uriValue используется напрямую.

JSP.5.3.6 Директива include

Директива include в форме:


<%@ include file="value" %>


развёртывается в JSP-фрагмент, обозначенный value. Это сделано для того, чтобы дать возможность проверять страницу.

JSP.5.3.7 Объявления

Объявления транслируются в элемент jsp:declaration . Например, второй пример из Раздела JSP.2.11.1:


<%! public String f(int i) { if (i<3) return("..."); ... } %>


транслируется в:


<jsp:declaration> <![CDATA[ public String f(int i) { if (i<3) return("..."); } ]]> </jsp:declaration>


Альтернативно мы можем использовать &lt; и записать:


<jsp:declaration> public String f(int i) { if (i&lt;3) return("..."); } </jsp:declaration>

JSP.5.3.8 Скриптлеты

Скриптлеты транслируются в элементы jsp:scriptlet . В XML-документе, соответствующем JSP-страницам, директивы представлены с использованием следующего синтаксиса:
 

<jsp:scriptlet> здесь - фрагмент кода </jsp:scriptlet>

JSP.5.3.9 Выражения

В XML-документе, соответствующем JSP-страницам, директивы представлены с использованием элемента jsp:expression:


<jsp:expression> здесь - выражение </jsp:expression>

JSP.5.3.10 Стандартные и Специальные Акции

Синтаксис элементов стандартных и специальных акций базируется на XML. Необходимы трансформации в связи с соглашениями по кавычкам и с синтаксисом выражений атрибутов времени запроса.

JSP.5.3.11 Выражения Атрибутов Времени Запроса

Выражения атрибутов времени запроса/Request-time attribute expressions имеют форму "<%= expression %>".

Хотя этот синтаксис следует синтаксису, используемому в JSP-странице, он не является допустимым в XML.
Отображение XML для таких выражений - это значение в форме "%= выражение'%", где соглашение по кавычкам спецификации JSP конвертировано в соглашение по кавычкам XML.

JSP.5.3.12 Шаблонный Текст и Элементы XML

Весь текст, который не интерпретируется JSP-транслятором, конвертируется в тело/body элемента jsp:text. Как следствие, никакие XML-элементы в форме, описанной в Разделе JSP.5.2.11, не будут появляться в XML-просмотре JSP-странице, написанной с синтаксисом JSP.

JSP.5.3.13 Атрибут jsp:id

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


В JSP-контейнере, поддерживающем атрибут jsp:id, XML-просмотр любой JSP-страницы будет содержать дополнительный атрибут jsp:id во всех XML-элементах. Этому атрибуту даётся значение, уникальное среди всех элементов XML-просмотра. См. детали в Главе 10.

JSP.5.4 Проверка XML-Просмотра Страницы JSP

XML-просмотр JSP-страницы это документ, связанный с пространством имён, и он не может быть проверен относительно ОТД/DTD (Определение Типа Данных), за исключением лишь наиболее простых случаев.
Чтобы уменьшить конфликты и возможные нежелательные последствия, XML-просмотр JSP-страницы не будет включать DOCTYPE. Однако пока ОТД могут содержать некоторое значение в качестве документации, Приложение JSP.C содержит описания и DTD, и XSchema JSP-документов.

Есть несколько механизмов с участием пространства имён, которые могут использоваться для проверки XML-просмотра JSP-страниц. Самым популярным механизмом является язык XML Schema консорциума W3C, но подойдут также и другие, включая некоторые простейшие, которые, например, могут использовать только некоторые элементы, или, напротив, которые не используют их. Проверщик TagLibraryValidator для библиотеки тэгов разрешает инкапсуляцию этих сведений в библиотеке тэгов.

TagLibraryValidator
работает в XML-просмотре JSP-страницы. Если страница создана с синтаксисом JSP, этот просмотр не предоставляет никаких деталей о шаблонных данных (всё группируется внутри элементов jsp:text), но отдельные детали могут быть описаны при использовании JSP-документов. Аналогично, когда XSLT-трансформация применяется к JSP-документу, XML-фрагменты будут нормально видимы, в то время как содержимое элементов jsp:text - нет.

JSP.5.5 Примеры

В этом разделе представлены два примера JSP-документов. В первом дана JSP-страница с синтаксисом JSP и её отображение в синтаксис XML. Во втором - JSP-страница с синтаксисом XML, включающая XML-фрагменты.
 

JSP.5.5.1 Страница JSP и Соответствующий Ей JSP-Документ

Пример отображения между синтаксисом JSP и XML.

JSP-СТРАНИЦА С СИНТАКСИСОМ JSP:
 

<html>

<title>positiveTagLib</title>

<body>

<%@ taglib uri="http://java.apache.org/tomcat/examples-taglib" prefix="eg" %>

<%@ taglib uri="/tomcat/taglib" prefix="test" %>

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

<eg:test toBrowser="true" att1="Working">

Positive Test taglib directive </eg:test>

</body>

</html>

XML-ПРОСМОТР JSP-СТРАНИЦЫ:
 

<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"

xmlns:eg="http://java.apache.org/tomcat/examples-taglib"

xmlns:test="urn:jsptld:/tomcat/taglib"

xmlns:temp="urn:jsptld:/WEB-INF/tlds/my.tld"

version="1.2">

<jsp:text><![CDATA[<html>

<title>positiveTagLig</title>

<body>

]]></jsp:text>

<eg:test toBrowser="true" att1="Working>

<jsp:text>Positive test taglib directive</jsp:text>

</eg:test>

<jsp:text><![CDATA[

</body>

</html>

]]></jsp:text>

</jsp:root>

JSP.5.5.2 JSP-Документ

Это пример очень простого JSP-документа, содержащего некоторые шаблонные XML-элементы.


<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"

xmlns:mytags="prefix1-URL"

version="1.2">

<mytags:iterator count="4">

<foo> </foo>

</mytags:iterator>

</jsp:root>


Глава JSP.7

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


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

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

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

JSP.7.1 Введение

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


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


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

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


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


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

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

JSP.7.1.1 Цели

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

JSP.7.1.2 Обзор

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

Parsing\Разбор

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


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

Validation\Проверка

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

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

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

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

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

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

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

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

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


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

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


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

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

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

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

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

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

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

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

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

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


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


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

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


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

JSP.7.1.3.3Условия


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

JSP.7.1.3.4 Итерации
 

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

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


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

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


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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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


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


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


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

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

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


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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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


<taglib>
 

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


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


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


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

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

<!ATTLIST taglib id ID #IMPLIED>


<taglib-uri>


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


<!ELEMENT taglib-uri (#PCDATA)>

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


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

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


<taglib-location>


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

<!ELEMENT taglib-location (#PCDATA)>

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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


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


<taglib>

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

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

</taglib>
 

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

Нотация


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

JSP Tag Library 1.2//EN">


<taglib>


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


<!ATTLIST taglib

id

ID

#IMPLIED

xmlns

CDATA

#FIXED

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

>
 

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

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

<!ELEMENT taglib

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


<tlib-version>
 

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


Синтаксис:


<!ELEMENT tlib-version (#PCDATA)>

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


<jsp-version>


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


Синтаксис:
 

<!ELEMENT jsp-version (#PCDATA)>

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


<short-name>


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


Синтаксис:


<!ELEMENT short-name (#PCDATA)>

#PCDATA ::= NMTOKEN


<uri>


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


<!ELEMENT uri (#PCDATA)>


<description>


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


<!ELEMENT description (#PCDATA)>


<validator>


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


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

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

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


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


<validator-class>


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


<!ELEMENT validator-class (#PCDATA)>


<init-param>


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

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

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

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


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


<param-name>


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


<!ELEMENT param-name (#PCDATA)>


<param-value>


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


<!ELEMENT param-value (#PCDATA)>


<listener>


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


<!ELEMENT listener (listener-class)>


<listener-class>


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


<!ELEMENT listener-class (#PCDATA)>


<tag>


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


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


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


<!ATTLIST tag id ID #IMPLIED>


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

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

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

<!ELEMENT tag

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


<tag-class>


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


Синтаксис:


<!ELEMENT tag-class (#PCDATA)>

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


<tei-class>


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


Синтаксис:


<!ELEMENT tei-class (#PCDATA)>

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


<body-content>


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


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

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

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


Синтаксис:


<!ELEMENT body-content (#PCDATA)>

#PCDATA ::= tagdependent | JSP | empty.


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


<display-name>


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


Синтаксис:


<!ELEMENT display-name (#PCDATA)>


<large-icon>


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


Синтаксис:


<!ELEMENT large-icon (#PCDATA)>


<small-icon>


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


Синтаксис:


<!ELEMENT small-icon (#PCDATA)>


<variable>


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

 

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

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

Синтаксис:

 

<!ELEMENT variable

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


<name-given>


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


Синтаксис:


<!ELEMENT name-given (#PCDATA)>


<name-from-attribute>


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


Синтаксис:


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


<variable-class>


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


Синтаксис:


<!ELEMENT class (#PCDATA)>


<declare>


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


Синтаксис:


<!ELEMENT declare #PCDATA)>

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


<scope>


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


Синтаксис:


<!ELEMENT scope #PCDATA)>

#PCDATA ::= NESTED | AT_BEGIN | AT_END


<attribute>


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


<!ATTLIST attribute id ID#IMPLIED>
 

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

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

Синтаксис:


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


<name>


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


Синтаксис:


<!ELEMENT name (#PCDATA)>

#PCDATA ::= NMTOKEN


<required>


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


Синтаксис:


<!ELEMENT required (#PCDATA)>

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


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


<rtexprvalue>


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


Синтаксис:


<!ELEMENT rtexprvalue (#PCDATA)>

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


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


<type>


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

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


Синтаксис:

<!ELEMENT type (#PCDATA)>

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


Пример:


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


<example>


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


<!ELEMENT example (#PCDATA)>

JSP.7.5 Проверка

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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


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

<me:defineObjects />

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


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


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


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


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

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

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

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

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

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


Глава JSP.8

JSP-Контейнер


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

Протокол прекомпиляции (см. Раздел JSP.8.4) также представлен здесь.


Информация, представленная здесь, не зависит от Языка Скриптинга, используемого на JSP-странице.

Глава JSP.6 описывает информацию для случая, когда атрибут language директивы page установлен в "java".
 

Классы реализации JSP-страницы должны использовать классы JspFactory и PageContext для получения преимуществ платформозависимых реализаций.

JSP.8.1 Модель JSP-Страницы

JSP-страница представлена на этапе выполнения объектом реализации JSP-страницы и выполняется JSP-контейнером. Объект реализации JSP-страницы - это servlet/сервлет. JSP-контейнер направляет запросы от клиента объекту реализации JSP-страницы и ответы объекта реализации JSP-страницы - клиенту.


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

В JSP 1.2 только события init и destroy являются допустимыми событиями.

JSP.8.1.1 Протокол, Видимый Web-Сервером

JSP-контейнер локализует соответствующий экземпляр класса реализации JSP-страницы и направляет ему запросы, используя протокол Servlet. JSP-контейнеру может потребоваться создать такой класс динамически из исходной JSP-страницы до направления ей объектов request и response.


Класс Servlet определяет контракт между JSP-контейнером и классом реализации JSP-страницы.
Если используется протокол HTTP, контракт описывается классом HttpServlet. Большинство JSP-страниц используют протокол HTTP, но другие протоколы также разрешены  данной спецификацией.


JSP-контейнер автоматически делает несколько серверных/server-side объектов доступными объекту реализации JSP-страницы. См. Раздел JSP.2.8.3.

JSP.8.1.1.1 Протокол, Видимый Автором JSP-Страницы

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

Детальная информация об этом контракте дана в Главе JSP.6. Контракт описывает также, как автор 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-Контейнером.
JSP-Контейнер
JSP-Страница

На Рисунке J2EE.8.1 показаны включённые контракты. Теперь мы рассмотрим этот процесс более детально.

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.2.1 Контракты API

Контракт между JSP-контейнером и Java-классом, реализующим JSP-страницу, соответствует интерфейсу Servlet. См. детали в спецификации Servlet 2.3.


Ответственность за выполнение этого контракта лежит на реализации JSP-контейнера, если JSP-страница не использует атрибут extends директивы jsp.

Если атрибут extends директивы jsp используется, автор JSP-страниц обязан гарантировать, что суперкласс, заданный в атрибуте extends, поддерживает этот контракт.

Таблица JSP.8-1  Как JSP-Контейнер Обрабатывает JSP-Страницы
Комментарии Методы, вызываемые JSP-Контейнером
Метод может по выбору/optionally быть определён в JSP-странице.
Метод вызывается при инициализации JSP-страницы.
Если метод вызывается, доступны все методы сервлета, включая getServletConfig().
void jspInit()
Метод по выбору определяется в JSP-странице.
Метод вызывается при уничтожении страницы.
void jspDestroy()
Метод не может быть определён в JSP-странице.
JSP-контейнер автоматически генерирует этот метод, базируясь на содержимом JSP-страницы.
Метод вызывается при каждом клиентском запросе.
void
_jspService(<ServletRequestSubtype>, <ServletResponseSubtype>) throws IOException,
ServletException

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 (см. Раздел 2.10.1) в JSP-странице не используется, JSP-контейнер может генерировать любой класс, удовлетворяющий контракту, описанному в Таблице JSP.8-1, если он трансформирует JSP-страницу.
 

В следующих примерах Пример Кода 8.1 иллюстрирует общий/родовой HTTP-суперкласс, названный ExampleHttpSuper. В Примере Кода 8.2 показан подкласс, названный _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, генерируемый класс идентичен классу из Примера Кода 8.2, за исключением того, что имя этого класса это имя, специфицированное в атрибуте extends.


Контракт класса реализации JSP-страницы не изменяется. JSP-контейнер должен проверить (обычно через отражение/reflection), что предоставленный суперкласс:

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

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 в Главе JSP.9.


При включённой буферизации, Вы можете всё ещё использовать метод redirect скриптлета в файле .jsp, вызывая response.redirect(какой-то URL) напрямую.

JSP.8.4 Прекомпиляция

JSP-страница, использующая протокол HTTP, будет получать HTTP-запросы.

Контейнеры, соответствующие JSP 1.2, обязаны поддерживать простой протокол прекомпиляции, а также некоторые базовые зарезервированные имена параметров. Заметьте, что протокол прекомпиляции это понятие близкое, но не то же самое, что компиляция JSP-страницы в Servlet-класс (Приложение JSP.A).

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.9

Основной API


Эта глава описывает пакет javax.servlet.jsp. В главе имеется содержимое, сгенерированное автоматически из javadoc, внедрённых в Java-классы и интерфейсы. Это делает возможным создание единого авторизованного документа спецификации.


Пакет javax.servlet.jsp содержит несколько классов и интерфейсов, описывающих и определяющих контракты между классом реализации JSP-страницы и средой работы программы/runtime environment, предоставляемые экземпляру такого класса соответствующим JSP-контейнером.

JSP.9.1 Контракт Объекта Реализации JSP-Страницы

В разделе рассматривается базовый контракт между объектом реализации JSP-страницы и его контейнером. Главный контракт определяется классами JspPage и HttpJspPage. Класс JspFactory описывает механизм портативной инстанциации всех необходимых объектов прогона, а JspEngineInfo предоставляет базовую информацию о текущем JSP-контейнере.


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

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 и включается в интерфейс явно.


См. Также: JspPage



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/контекст страницы.


См. Также: PageContext .


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.2  Неявные Объекты

Объекты PageContext и JspWriter доступны по умолчанию в качестве неявных объектов.

JSP.9.2.1 PageContext

Синтаксис
 


public abstract class PageContext


Описание


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

Неявные объекты добавляют pageContext автоматически.


Класс PageContext является абстрактным классом, созданный как расширяемый для предоставления реализаций соответствующей средой запуска программ JSP-машины.

Экземпляр PageContext получается классом реализации JSP через вызов метода JspFactory.getPageContext() и освобождается через вызов JspFactory.releasePageContext().


Примеры использования PageContext, JspFactory и других классов в объекте реализацииJSP-страницы можно найти повсюду.


PageContext
облегчает работу автора страниц/компонентов и реализатора страниц, предоставляя:


Методы, Предназначенные для Кода, Генерируемого Контейнером
 

Некоторые методы предназначены для использования в коде, генерируемом контейнером, а не для кода, написанного авторами 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.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  Исключения

Класс JspException является базовым классом для всех JSP-исключений. JspTag-Exception используется механизмом исключения тэга.

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


Скриптинг


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


JSP-Контейнер


Основной API


API Развёртывания Тэгов


Упаковка JSP-страниц


ОТД и Схема для Синтаксиса XML


ОТД для TLD JSP 1.2


ОТД для TLD JSP 1.1


Приложение Е - Изменения.


Словарь


Оглавление


Приложение JSP.A

Упаковка (Архивирование)
JSP-Страниц


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


В первом примере JSP-страница публикуется в исходной форме. Это самый общий пример.


Во втором примере JSP-страница компилируется в Servlet, который использует только вызовы API Servlet 2.3 и JSP 1.2; Servlet затем упаковывается в WAR с таким дескриптором публикации, что он выглядит для любого клиента как оригинальная JSP-страница.


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

A.1 Простейшая JSP-Страница

Мы начинаем с простейшей JSP-страницы HelloWorld.jsp.
 

<%@ page info="Пример предварительно скомпилированной JSP" %>

<p>

Hello World

</p>

A.2 JSP-Страница, Упакованная как Источник/source в WAR-Файл

JSP-страница может быть упакована в WAR-файл простым помещением её в "/HelloWorld.jsp", где отображение расширения JSP-страницы по умолчанию будет её получать.

Web.xml тривиален:
 

<!DOCTYPE webapp

SYSTEM "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<webapp>

<session-config>

<session-timeout> 1 </session-timeout>

</session-config>

</webapp>

A.3 Сервлет/Servlet для Откомпилированной JSP-Страницы

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


JSP-страница компилируется в Сервлет с некоторым зависящим от реализации именем _jsp_HelloWorld_XXX_Impl. Servlet-код, зависящий только от API JSP 1.2 и Servlet 2.3, таков:
 

imports javax.servlet.*;

imports javax.servlet.http.*;

imports javax.servlet.jsp.*;

class _jsp_HelloWorld_XXX_Impl

extends_PlatformDependent_Jsp_Super_Impl {

public void _jspInit() {

// ...

}

public void jspDestroy() {

// ...

}

static JspFactory_factory= JspFactory.getDefaultFactory();

public void _jspService(HttpServletRequest request,

HttpServletResponse response)

throws IOException;

{

Object page= this;

HttpSessionsession= request.getSession();

ServletConfigconfig= getServletConfig();

ServletContextapplication = config.getServletContext();

PageContextpageContext

= _factory.getPageContext(this,

request,

response,

(String)NULL,

true,

JspWriter.DEFAULT_BUFFER,

true

);

JspWriterout= pageContext.getOut();

// контекст страницы создаёт начальный JspWriter "out"

try {

out.println("<p>");

out.println("Hello World");

out.println("</p>");

} catch (Exception e) {

pageContext.handlePageException(e);

} finally {

_factory.releasePageContext(pageContext);

}

}

}

A.4 Дескриптор Web-Приложения

Servlet начинает выглядеть как JSP-страница в следующем web.xml:
 

<!DOCTYPE webapp

SYSTEM "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<webapp>

<servlet>

<servlet-name> HelloWorld </servlet-name>

<servlet-class> _jsp_HelloWorld_XXX_Impl.class </servlet-class>

</servlet>

<servlet-mapping>

<servlet-name> HelloWorld </servlet-name>

<url-pattern> /HelloWorld.jsp </url-pattern>

</servlet-mapping>

<session-config>

<session-timeout> 1 </session-timeout>

</session-config>

</webapp>

A.5 WAR для Откомпилированной JSP-Страницы

Наконец, всё это упаковывается в WAR:
 

/WEB-INF/web.xml

/WEB-INF/classes/_jsp_HelloWorld_XXX_Impl.class


Заметьте, что, если класс Servlet, сгенерированный для JSP-страницы, зависел от некоторых классов поддержки, они также должны были быть включены в WAR.


На главную страницу
 

Спецификация
JavaServer Pages (JSP)

Версия: 1.2


Пожалуйста, направляйте комментарии по e-mail:  jsp-spec-comments@eng.sun.com


и переводчику: a_pyramidin@yahoo.com (Александр Пирамидин)



Понедельник, 27 августа, 2001 г.
Редактор: Eduardo Pelegrí-Llopart.

901 San Antonio Road
Palo Alto, CA 94303 USA
650 960-1300 факс: 650 969-9131


Статус: FCS


Релиз: 17 сентября 2001 г.

Copyright 2001 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, California 94303, U.S.A.
Все Права Зарезервированы.

ЛИЦЕНЗИЯ

Данная Спецификация защищена авторскими правами, и информация, приведённая здесь, может быть защищена одним или более патентами США, иностранными патентами или задействованными приложениями.

За исключением случаев, указанных в данной лицензии, никакая часть данной Спецификации не может воспроизводиться в любой форме и любым способом без наличия предварительного письменной авторизации Sun Microsystems, Inc. ("Sun") и её лицензоров, если имеются.

Любая часть данной Спецификации и описанной здесь информации управляется терминами и условиями данной лицензии и Export Control Guidelines, как установлено ранее в Terms of Use на сайте Sun.

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

Настоящим документом Sun предоставляет Вам лицензию на бесплатное, неисключительное пользование без права передачи (без права на сублицензию), с сохранением прав интеллектуальной собственности Sun, что является непременным условием использования данной Спецификации для внутренних целей дизайна и разработки Ваших Java-аплетов и приложений, предназначенных для работы на платформе Java, или для создания чисто рабочих реализаций данной Спецификации, которые:

(i) полную реализацию текущей версии Спецификации без подразделения или объединения её;
(ii) реализует весь интерфейс и функциональность данной Спецификации без подразделения или объединения её;
(iii) включают полную реализацию всех необязательных компонентов (как определено Спецификацией), которые Вы выбрали для реализации, без подразделения или объединения;
(iv) реализует все интерфейсы и функциональность таких необязательных компонентов без подразделения или объединения;
(v) не добавляют никаких дополнительных пакетов, классов или интерфейсов к пакетам "java.*" или "javax.*" или подпакетам или другим пакетам, определённым в данной Спецификации;
(vi) удовлетворяют всем требованиям тестирования, доступным от Sun, относящимся к самой последней версии данной Спецификации, опубликованной за шесть (6) месяцев до любого релиза реализации такой чисто рабочей реализации или обновления до неё;
(vii) не происходят от какого-либо кода-источника Sun или кодов двоичных материалов; и
(viii) не включает какого-либо первичного кода Sun или кодов двоичных материалов без отдельной соответствующей лицензии Sun. Данная Спецификация содержит информацию о правах собственности Sun и может использоваться только в соответствии с данной лицензией.

Действие данной лицензии оканчивается немедленно без предупреждения от Sun, если Вы не согласны с каким-либо из условий данной лицензии. После окончания или истечения срока действия данной лицензии Вы обязаны исключить использование или уничтожить имеющуюся у Вас Спецификацию.

ТОРГОВЫЕ МАРКИ

Никакие права названия или интересы торговых марок, сервисных марок или торговых имён Sun или лицензоров Sun не передаются по данному соглашению.

Sun, Sun Microsystems, логотип Sun, Java, логотип Java Coffee Cup, JSP и JavaServer Pages являются торговыми марками или зарегистрированными торговыми марками Sun Microsystems, Inc. в США и других странах.

ОГРАНИЧЕННАЯ ГАРАНТИЯ

ДАННАЯ СПЕЦИФИКАЦИЯ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ". SUN НЕ ДА╗Т НИКАКИХ ГАРАНТИЙ, ЯВНЫХ ИЛИ КОСВЕННЫХ (ВКЛЮЧАЯ - НО НЕ ОГРАНИЧИВАЯСЬ ИМИ - ГАРАНТИИ РЕАЛИЗУЕМОСТИ), СООТВЕТСТВИЯ ОПРЕДЕЛ╗ННОМУ НАЗНАЧЕНИЮ ИЛИ НЕНАРУШЕНИЯ УСЛОВИЙ, ЧТО СОДЕРЖИМОЕ ДАННОЙ СПЕЦИФИКАЦИИ ПОДХОДИТ ДЛЯ КАКИХ-ЛИБО ЦЕЛЕЙ ИЛИ ЧТО ЛЮБОЕ ИСПОЛЬЗОВАНИЕ ИЛИ РЕАЛИЗАЦИЯ ТАКОГО СОДЕРЖИМОГО НЕ БУДЕТ НАРУШАТЬ КАКИХ-ЛИБО ПАТЕНТОВ ТРЕТЬЕЙ СТОРОНЫ, АВТОРСКИХ ПРАВ, КОММЕРЧЕСКОЙ ТАЙНЫ ИЛИ ИНЫХ ПРАВ.
 

Данный документ не содержит каких-либо обязательств на реализацию или выпуск какой-либо части данной Спецификации в каком-либо продукте.


ДАННАЯ СПЕЦИФИКАЦИЯ МОЖЕТ СОДЕРЖАТЬ ТЕХНИЧЕСКИЕ НЕТОЧНОСТИ ИЛИ ТИПОГРАФСКИЕ ОШИБКИ. ИЗМЕНЕНИЯ ПЕРИОДИЧЕСКИ ДОБАВЛЯЮТСЯ К ИМЕЮЩЕЙСЯ ИНФОРМАЦИИ; ЭТИ ИЗМЕНЕНИЯ БУДУТ ВНЕДРЕНЫ В НОВЫЕ ВЕРСИИ ДАННОЙ СПЕЦИФИКАЦИИ, ЕСЛИ ОНИ (ВЕРСИИ) ПОЯВЯТСЯ. SUN МОЖЕТ В ЛЮБОЕ ВРЕМЯ ДЕЛАТЬ УЛУЧШЕНИЯ И/ИЛИ ВНОСИТЬ ИЗМЕНЕНИЯ В ПРОДУКТЫ И/ИЛИ ПРОГРАММЫ, ОПИСАННЫЕ В ДАННОЙ СПЕЦИФИКАЦИИ.

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

ОГРАНИЧЕНИЕ ОТВЕТСТВЕННОСТИ

В ДОПОЛНЕНИЕ К НЕ ЗАПРЕЩ╗ННОМУ ЗАКОНОМ, НИ ПРИ КАКИХ СОБЫТИЯХ SUN ИЛИ Е╗ ЛИЦЕНЗОРЫ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБОЙ УЩЕРБ, ВКЛЮЧАЯ, БЕЗ ОГРАНИЧЕНИЯ, УПУЩЕННУЮ ВЫГОДУ, ПОТЕРЮ ДАННЫХ ИЛИ ЗА ПРИЧИН╗ННЫЙ, КОСВЕННЫЙ, ПОСЛЕДУЮЩИЙ, СЛУЧАЙНЫЙ ИЛИ УМЫШЛЕННЫЙ ВРЕД, НАНЕС╗ННЫЙ КАКИМ-ЛИБО ОБРАЗОМ, ВНЕ ЗАВИСИМОСТИ ОТ ПРАВИЛ ОБ ОТВЕТСТВЕННОСТИ, ПРИЧИН╗ННЫЙ ИЛИ ОТНОСЯЩИЙСЯ К: ЛЮБОМУ ОБОРУДОВАНИЮ, ИСПОЛЬЗОВАНИЮ, МОДИФИЦИРОВАНИЮ ИЛИ ИНОМУ ИСПОЛЬЗОВАНИЮ ДАННОЙ СПЕЦИФИКАЦИИ, ДАЖЕ ЕСЛИ SUN И/ИЛИ Е╗ ЛИЦЕНЗОРЫ БЫЛИ УВЕДОМЛЕНЫ О ВОЗМОЖНОСТИ ТАКОГО УЩЕРБА/ВРЕДА.


Вы страхуете и защищаете Sun и её лицензоров от любых претензий, являющихся результатом:

(i) Вашего использования данной Спецификации;
(ii) использования или распространения Ваших Java-приложений, аплетов и/или чисто рабочих реализаций; и/или
(iii) любых претензий, которые могут явиться результатом несовместимости последующих версий или релизов любой Спецификации, использованной Вами, со Спецификацией, предоставленной Вам по данному соглашению.

ОГРАНИЧЕННЫЕ ПРАВА

Правительство США: Если данная Спецификация получена от имени или для Правительства США первичным контрактором или субконтрактором Правительства США (любого уровня), тогда права Правительства в области Программного Обеспечения и сопутствующей документации будут действовать так, как описано ранее в данной лицензии; это действует в соответствии с правилами от 48 C.F.R. 227.7201 до 227.7202-4 (для приобретений Департамента Обороны/Department of Defense (DoD)) и в соответствии с правилами 48 C.F.R. 2.101 и 12.212 (для приобретений не Департамента Обороны).

КУДА СООБЩИТЬ

Вы можете сообщить о какой-либо неоднозначности, неполноте или неточностях в связи с использованием Вами данной Спецификации ("Обратная Связь/Feedback"). В связи с тем, что Вы направляете Sun информацию Feedback, Вы, кроме того:

(i) согласны с тем, что эта информация предоставляется Вами на некоммерческой и неконфиденциальной основе, и
(ii) предоставляете Sun бессрочное, неисключительное, всемирно действующее, неотзываемое разрешение безвозмездно, с правом сублицензирования на несколько уровней сублицензирования, внедрять, публиковать и использовать без ограничений Feedback для любых целей, относящихся к данной Спецификации и её последующим версиям, реализациям, и утилитам тестирования.

Статус


Это спецификация JSP 1.2, разработанная группой экспертов JSR053 как часть процесса Java Community Process (детали - по адресу http://jcp.org/jsr/detail/53.jsp).

JSP.S.1  Процессы Сообщества Java

JCP создаёт спецификации, используя три сообщества: сообщество экспертов (the expert group),  participants\участники JCP и public\публика вообще.

Эксперты является авторами спецификаций, создавая проекты/drafts.

Проекты
проходят путь от экспертов, через участников, к публике, постепенно совершенствуясь в деталях, всегда возвращая комментарии обратно группе экспертов; final draft/окончательный проект отправляется для одобрения в Executive Committee\Исполнительный Комитет.

Лидер группы экспертов
отвечает за облегчение работы группы экспертов, авторизацию спецификации и за организацию reference implementation\справочной реализации и conformance test suite\блока тестирования на соответствие.

JSP.S.2   JCP и Эта Спецификация

JCP разработан как чрезвычайно гибкий процесс, так что каждая группа экспертов может адресовать требования специфического сообщества, обслуживаемого ею. Справочная реализация JSP 1.2 и Servlet 2.3 использует код, который разрабатывается как открытый проект-ресурс по соглашению с Apache Software Foundation.

Данная спецификация содержит главы, которые получены непосредственно из комментариев javadoc в классах API, но там, где имеются расхождения, данная спецификация имеет преимущество над комментариями javadoc.


Процесс JCP предоставляет механизм обновления спецификации в процессе поддержки через Erratas\Списки Ошибок. Если они имеются, эти списки имеют приоритет над данной спецификацией.


Приложения C и D являются нормативными; остальные приложения являются ненормативными.

 

Предисловие


Этот документ является спецификацией JavaServer Pagesтм 1.2 (JSP 1.2).


Данная Спецификация была разработана как часть процесса Java Community Process (JCP). Комментарии от Экспертов, Участников и Публики были рассмотрены, и все изменения были внесены в спецификацию, где это было необходимо.

JSP.P.1 Сравнение с JSP 1.1

JSP 1.2 расширяет Спецификацию JavaServer Pagesтм 1.1 (JSP 1.1) следующим образом:

JSP.P.2  Лицензирование Спецификации

Детали условий, по которым данный документ распространяется, даны в лицензии.

JSP.P.3  Для кого предназначен этот документ

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

JSP.P.4  Родственные Документы

Разработчики контейнеров JSP и авторы страниц JSP могут найти необходимую информацию также в следующих документах:

Таблица  JSP.P-1  Некоторые Родственные Web-Сайты
Домашняя страница JSP:  http://java.sun.com/products/jsp
Домашняя страница Servlet:  http://java.sun.com/products/servlet
Java 2 Platform, Standard Edition::  http://java.sun.com/products/jdk/1.3
Java 2 Platform, Enterprise Edition:  http://java.sun.com/j2ee
Домашняя страница XML на платформе Java:  http://java.sun.com/xml
Домашняя страница JavaBeans≥:  http://java.sun.com/beans
Домашняя страница XML на W3C:  http://www.w3.org/XML
Домашняя страница HTML на W3C:  http://www.w3.org/MarkUp
Домашняя страница XML.org:  http://www.xml.org

JSP.P.5  Немного Истории

Пионерами, выполнившими начальную работу по платформе Java, относящуюся к данной Спецификации, были: James Gosling, работавший над Web Server в Java в 1994/1995 гг. - основой сервлетов.

Расширенный проект был начат в 1996 г. Pavani Diwanji - ведущим инженером - и многими другими ключевыми участниками, перечисленными ниже. Результатом работы над этим проектом стал продукт Java Web Server компании Sun.

Некоторые проекты начались в 1999 г.. Группа экспертов по сервлетам во главе с James Davidson выпустила спецификации: Servlet 2.1 - в январе и Servlet 2.2 в декабре, а группа JSP во главе с Larry Cable и Eduardo Pelegri-Llopart выпустила JSP 1.0 в июне и JSP 1.1 - в декабре.

Год 2000 ознаменовался большим количеством разработок: многочисленные реализации контейнеров, утилит, книг и тренировочных материалов по JSP 1.1, Servlet 2.2 и платформе Java 2 Enterprise Edition. Интенсивно разрабатывались библиотеки тэгов и различные усовершенствования. Внедрение технологии JSP продолжилось в 2001 году по многим направлениям Web и сервиса JavaOne.

Проследить развитие печатной продукции весьма трудно; лучше всего это сделано на сайте  http://java.sun.com/products/jsp.

JSP.P.6  Благодарности

Успех Java Platform обусловлен деятельностью Java Community Process по её разработке. Этот процесс, вовлёкший в свою орбиту множество людей и корпораций, продвигает разработку высококачественных спецификаций эпохи Internet.


Хотя невозможно перечислить всех участвовавших в разработке этой версии Спецификации, мы хотели бы поблагодарить всех членов нашей экспертной группы. Мы использовали преимущества большой активной группы экспертов, без которой спецификации JSP не были бы созданы.


Мы хотим поблагодарить:

Alex Yiu, Alex Chaffee, Allan Scott, Amit Kishnani, Bill dehOra, Bjorn Carlson, Bob Foster, Chris Hansen, Clement Wong, Craig McClanahan, Dano Ferrin, Danny Coward, Dave Brown, Edwin Smith, Francios Jouaux, Frank Biederich, Govind Seshadri, Hans Bergsten, Howard Melman, James Strachan, Jason McGeee, Jason Hunter, Jeff Mischkinsky, Jon Rousseau, Julie Basu, Karl Avedal, Kevin Jones, Larry Cable, Larry Isaas, Magnus Rydin, Magnus Stenman, Mark Wallace, Miles Sabin, Misha Davidson, Murty Chintalapati, Nathan Abamson, Nic Ferrier, Olli Blackburn, Paul Bonfanti, Peter Petersen, Petr Jiricka, Pier Paolo Fumagalli, Pierre Delisle, Ramesh Mandava, Rod Magnuson, Sam Pullara, Satoshi Kikuchi, Scott Ferguson, Scott Snyder, Simeon Simeonov, Stephanie Bodoff, Stefano Mazzocchi, Tim Ampe, Tom Reilly, Vince Bonfanti.


Мы благодарим всё сообщество, разрабатывавшее пробные реализации, и продавцов, выпускавших утилиты авторизации и библиотеки тэгов.


Отдельно упомянем Scott Ferguson, Bob Foster, Stefano Mazzocchi и Ricardo Rocha и их работу по Главе 5. Bob Foster заслуживает благодарности за ОТД& XSchema, а сообщество Cocoon - за Cocoon & XSP. Наши благодарности Jess Holle за кропотливую работу над статьями в Главе JSP.3.


Мы хотим поблагодарить также всех авторов книг о JSP и создателей web-сайтов, отслеживавших и облегчавших работу по созданию сообщества JSP.


Редактор особо признателен участникам Java Platform Group, в особенности - James, Jon, Mala, Jeff, Connie и Graham.


Наконец, мы благодарим разработчиков программного обеспечения, web-авторов и членов группы public, прочитавших эту спецификацию, использовавших пробную реализацию и поделившихся своим опытом.

Благодаря вам, появилась технология JavaServerPages.
 


Оглавление


Статус
Предисловие

JSP.1 Обзор

JSP.2 Синтаксис Ядра и Семантика

JSP.3 Вопросы Локализации

JSP.4 Стандартные Акции

JSP.5 JSP-Документы

JSP.6 Скриптинг

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

JSP.8  JSP-Контейнер

JSP.9   Основной API

JSP.10  API  Развёртывания Тэгов

JSP.A Упаковка (Архивирование) JSP -Страниц

JSP.B  ОТД/DTD и Схема для Синтаксиса XML

JSP.C  ОТД для TagLibrary-Дескриптора, JSP 1.2

C.1 ОТД для Файлов TagLibrary-Дескриптора

JSP.D  ОТД для TagLibrary-Дескриптора, JSP 1.1

D.1 ОТД для Файлов TagLibrary-Дескриптора

JSP.E  Изменения

JSP.F  Словарь


Глава JSP.6

Скриптинг


В этой главе детально разбираются Элементы Скриптинга, когда значением директивы language является "java". Этот язык скриптинга базируется на языке программирования Java (как специфицировано в "The Java Language Specification"), но заметьте, что верная Java-программа не является верной JSP-страницей или её разделом.
 

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

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

JSP.6.1 Общая Структура

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

JSP.6.1.1 Верная Страница JSP

JSP-страница является таковой для Платформы Java, если, и только если, класс реализации JSP-страницы, определённый по Таблице JSP.6-1 (после применения всех директив include), вместе со всеми прочими классами, определёнными JSP-контейнером, является верной программой для данной Java-Платформы и если он передаёт методы проверки для всех библиотек тэгов, ассоциированных с этой JSP-страницей.

JSP.6.1.2 Зарезервированные Имена

Sun Microsystems резервирует для спецификаций JSP все имена, имеющие форму {_}jsp_* и {_}jspx_*, в любом сочетании верхнего и нижнего регистров.

Имена, имеющие такую форму и не определённые в данной спецификации, зарезервированы фирмой Sun для будущих расширений.

JSP.6.1.3 Гибкость Реализации

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

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

Таблица JSP.6-1  Структура Класса JavaProgramming
необязательное выражение импорта, как указано директивой jsp. import name1
SuperClass выбирается JSP-контейнером, либо автором JSP через использование директивы jsp. Имя класса (_jspXXX) зависит от реализации. class _jspXXX extends SuperClass
Начало тела/body класса реализации JSP-страницы. {
(1) Раздел Объявлений // объявления...
Подпись для генерируемого метода. public void _jspService(<ServletRequestSubtype>
request,
<ServletResponseSubtype> response)
 throws ServletException, IOException {
(2) Раздел Неявных/Implicit Объектов // код, определяющий и инициализирующий request, response, page, pageContext и т.п.
(3) Главный/Main Раздел // код, определяющий выражение отображения request/response метода _jspService
закрытие метода _jspService }
закрытие _jspXXX }

JSP.6.2 Раздел Объявлений

Раздел объявлений соответствует элементам объявлений. Содержимое этого раздела определяется путём конкатенации всех объявлений на странице в порядке их появления.

JSP.6.3 Раздел Инициализации

Этот раздел определяет и инициализирует неявные объекты, доступные JSP-странице. См. Раздел JSP.2.8.3, "Неявные Объекты.

JSP.6.4 Раздел Main/Главный

Этот раздел осуществляет главное отображение/mapping между объектами request и response.

Содержимое кодового сегмента 2 определяется скриптлетами, выражениями и текстовым телом JSP-страницы.

Элементы обрабатываются последовательно в порядке их появления на странице. Трансляция каждого из них определяется так, как показано ниже, и вставляется в данный раздел.

Трансляция зависит от типа элемента:

JSP.6.4.1 Шаблонные Данные

Шаблонные данные трансформируются в код, который будет размещать шаблонные данные в потоке, именованном неявной переменной out в процессе исполнения кода. Пробелы сохраняются.
 

Опуская подробности закавычивания и производительности, это соответствует оператору вида:

Оригинал Эквивалентный Текст
шаблон out.print(шаблон)

JSP.6.4.2 Скриптлеты

Скриптлет трансформируется во фрагмент кода вида:

Оригинал Эквивалентный Текст
<% фрагмент %> фрагмент

JSP.6.4.3 Выражения

Выражение трансформируется в оператор Java для вставки значения выражения (конвертированного, если необходимо, в java.lang.String), в поток, именованный неявной переменной out. Никакие дополнительные символы новой строки или пробелы не включаются.

Опуская подробности закавычивания и производительности, это соответствует оператору вида:

Оригинал Эквивалентный Текст
<%= выражение %> out.print(выражение)

JSP.6.4.4 Акции

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

Семантика типа акции определяет имена переменных (обычно имя атрибута id, если он имеется) и их тип.

Единственной стандартной акцией в спецификации JSP, которая определяет объекты, является акция jsp:usebean. Имя вводимой переменной это имя атрибута id, а тип - атрибута класса.

Оригинал Эквивалентный Текст

<x:tag>
  foo
</x:tag>

объявляются переменные AT_BEGIN
{
объявляются переменные NESTED
трансформации foo
}
объявляются переменные AT_END

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


Эта страница использует фрэймы,
но ваш браузер их не поддерживает.

Нажмите эту ссылку для перехода к оглавлению.


Глава JSP.1

Обзор


В этой главе даётся обзор технологии JavaServer Pages/Серверные Страницы Java.

JSP.1.1 Технология JavaServer Pagesтм

JavaServer Pages это технология Java 2 Platform, Enterprise Edition (J2EE) для создания приложений, генерирующих динамическое web-содержимое - HTML, DHTML, XHTML и XML. Технология JavaServer Pages даёт возможность легко создавать динамическое содержимое web-страниц, предельно мощное и гибкое.

JSP.1.1.1 Общие Понятия

Технология JavaServer Pages придаёт смысл текстуальной спецификации создания динамического response\ответа на request\запрос. Эта технология основывается на следующих понятиях:

JSP.1.1.2 Преимущества Технологии JavaServer Pages

Технология JavaServer Pages даёт следующие преимущества:

JSP.1.2 Базовые Понятия

В этом разделе рассмотрены базовые понятия, формально определённые далее в этой спецификации.

JSP.1.2.1 Что такое страница JSP?

JSP-страница это текстовый документ, описывающий процесс обработки запроса для создания ответа. Шаблонные данные смешиваются с динамическими акциями и воздвигаются на платформу Java 2 Platform.

JSP-технология поддерживает различные парадигмы авторизации динамического содержимого.

Ключевыми особенностями JavaServer Pages являются:

JSP.1.2.2 Web-Приложения

Концепция web-приложения унаследована от спецификации Servlet.

Web-приложение может состоять из следующих частей:

Спецификация JavaServer Pages унаследовала от спецификации Servlet понятия web-приложений, ServletContexts/КонтекстаСервлета, сессии, запросов и ответов. См. детали в спецификации Java Servlet 2.3.

JSP.1.2.3 Компоненты и Контейнеры

JSP-страницы и классы сервлетов вместе называются web-компонентами. JSP-страницы направляются Container\Контейнеру, который предоставляет сервис, указанный в JSP Component Contract\Контракте Компонента.

Это отделение компонента от контейнера даёт возможность многократного использования компонентов и возможностей, предоставляемых контейнером.

JSP.1.2.4 Этапы Трансляции и Выполнения

JSP-страницы являются текстуальными компонентами. Они проходят через две фазы: фазу трансляции и фазу запроса. Трансляция выполняется для страницы один раз. Фаза запроса выполняется один раз на один запрос.

JSP-страница транслируется для создания класса сервлета, класса реализации JSP-страницы, который инстанциируется во время запроса. Инстанциированный объект JSP-страницы обрабатывает запросы и создаёт ответы.

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

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

JSP.1.2.5 Роль в Платформе Java 2, Enterprise Edition

За некоторыми исключениями, интеграция JSP-страниц на платформу J2EE 1.3 наследуется из спецификации Servlet 2.3, поскольку трансляция превращает JSP-страницы в сервлеты.


Глава JSP.10

API Развёртывания Тэгов


В этой главе описываются обработчики тэгов и другие классы развёртывания тэгов, а также методы доступа к файлам Tag Library Descriptor/Дескриптора Библиотеки Тэгов. Это дополняет предыдущую главу  описанием формата файлов Tag Library Descriptor и их использование в директивах taglib.

Эта глава включает содержимое, сгенерированное автоматически из javadoc, внедрённых в реальные Java-классы и интерфейсы. Это позволяет создавать единый авторизованный документ-спецификацию.

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

Пустой тэг не имеет тела. Есть два эквивалентных синтаксиса, один - с отдельными начальным и конечным тэгами, другой - в котором начальный и конечный тэги скомбинированы в один тэг.

Следующие два пример идентичны:


<x:foo att="myObject" />

<x:foo att="myObject" ></foo>


Непустой тэг имеет начальный тэг, тело и конечный тэг.


Пример-прототип имеет форму:


<x:foo att="myObject" >

BODY

</x:foo/>


Спецификация JavaServer Pages(тм) (JSP) 1.2 предоставляет переносимый механизм для описания библиотек тэгов, включающий:


Данная глава разбита на три раздела:

Первый раздел представляет базовые классы обработчика тэга.
Во втором разделе описаны более сложные обработчики тэга, которым необходим доступ к обсчёту их тела.
Последний раздел посвящён вопросам этапа/времени трансляции.

JSP.10.1 Простые Обработчики Тэгов

Этот раздел вводит понятие обработчика тэга и описывает простейшие типы обработчика тэга.

Обработчик Тэга/Tag Handler

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

Обработчик тэга создаётся первоначально с использованием нулевого аргумента конструктора в соответствующем классе; метод java.beans.Beans.instantiate() не используется.

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

setter-метод используется для установки свойств, обнаруженных с помощью машины интроспекции JavaBeans.

Протокол, поддерживаемый обработчиком тэга, даёт возможность передавать параметры, обсчитывать и пересчитывать тело акции и получать доступ к объектам и другим обработчикам тэгов в JSP-странице.

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

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

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

Свойства

Обработчик тэга имеет несколько свойств.

Все обработчики тэгов имеют свойство pageContext для JSP-страницы, на которой находится тэг, и свойство parent для обработчика тэга ближайшей внешней/содержащей акции. Отдельные классы обработчика тэга могут иметь дополнительные свойства.

Все атрибуты специальной акции обязаны быть свойствами компонента JavaBeans, хотя некоторые свойства не могут экспонироваться в качестве атрибутов. Атрибуты, видимые JSP-транслятору, это в точности те атрибуты, которые перечислены в Дескрипторе Обработчика Тэга/(TLD).

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

setter-методы, которые должны использоваться при установке значения атрибуту специальной акции, определяются через использование интроспектора JavaBeans в классе обработчика тэга, а затем используется setter-метод, ассоциированный со свойством, имеющий то же самое имя, что и атрибут в запросе. Подразумевается (в спецификации JavaBeans - недостаточно чётко), что для каждого свойства имеется только один setter.

Неспецифицированные атрибуты/свойства не должны использоваться (через setter-метод).

После того как свойство установлено, оно считается постоянным, так что, если JSP-контейнер утверждает, что свойство уже установлено в данном экземпляре обработчика тэга, оно не должно устанавливаться ещё раз (дополнительно).

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

Обработчик Тэга как Объект, Обслуживаемый Контейнером

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

Эти ограничения на ссылки на объекты обработчика тэга и на модификацию свойств атрибутов дают JSP-контейнеру относительную свободу для эффективного обслуживания объектов обработчика тэга для достижения различных целей. Например, контейнер может реализовывать различные стратегии пулинга/pooling (создания пула) для минимизации затрат на создание, или может осуществлять установку свойств для уменьшения затрат, когда обработчик тэга находится внутри другого повторяющегося/iterative тэга.

Соглашения

Обработчик тэга реализует акцию; JSP-контейнер обязан выдерживать конверсии типов, описанные в Разделе 2.13.2, при присвоении значений атрибутам акции.

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

Пустая акция не имеет тела; она может использовать один или два синтаксиса: <foo/> или <foo></foo>. Поскольку пустые акции не имеют тела, методы, имеющие отношение к работе с телом, не вызываются.

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

Непустая акция имеет тело.

Интерфейс Tag

Обработчик тэга, который "не хочет" обрабатывать своё тело, может просто реализовывать интерфейс Tag. Обработчик тэга может "не хотеть" обрабатывать своё тело, если это пустой тэг, или из-за того, что тело просто "передаётся (дальше)/passed through".

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

Метод doStartTag() вызывается при обнаружении начального тэга, и его return-значение указывает, должно ли тело/body (если имеется) быть пропущено, или вычислено и передано текущему потоку response.

Метод doEndTag() вызывается при обнаружении конечного тэга; его return-значение указывает, должно ли продолжаться обсчитывание оставшейся части страницы, или нет.
Если в процессе обсчёта тела тэга обнаружено исключение, метод doEndTag не будет выполняться. См. в тэге TryCatchFinally методы, которые гарантированно выполняются.

Интерфейс IterationTag

Интерфейс IterationTag используется для повторяющихся вычислений тела специальной акции.

Этот интерфейс имеет единственный метод - doAfterBody(), который вызывается после каждого вычисления тела для определения необходимости дальнейших вычислений.

Повторение вычисления запрашивается значением 2, которое в JSP 1.1 определено как BodyTag.EVAL_BODY_TAG. Это константное значение сохранено в JSP 1.2 (для полной обратной совместимости), но, для улучшения ясности кода, имеется и новое имя: IterationTag.EVAL_BODY_AGAIN.
Для остановки итерации возвращаемое значение должно быть 0, то есть Tag.SKIP_BODY.

Базовый Класс TagSupport

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

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 обработчик тэга доступен для последующих вызовов (и предполагается, что сохраняет свои свойства).


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


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


После того как все вызовы обработчика тэга выполнены, в нём вызывается метод 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.

JSP.10.1.2 IterationTag


Синтаксис


public interface IterationTag extends Tag


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


Все Суперинтерфейсы: Tag


Все Известные Реализующие Классы: TagSupport


Описание


Интерфейс IterationTag расширяет интерфейс Tag через определение одного дополнительного метода, управляющего повторными вычислениями его тела.

Обработчик тэга, реализующий IterationTag, рассматривается как обработчик, реализующий Tag через методы doStartTag() и doEndTag(). IterationTag предоставляет новый метод: doAfterBody().


Метод doAfterBody() вызывается после каждого цикла итерации - вычисления тела для управления последующими вычислениями тела.

Если doAfterBody() возвращает IterationTag.EVAL_BODY_AGAIN, тогда тело снова будет вычисляться.
Если doAfterBody() возвращает Tag.SKIP_BODY, тогда тело будет пропущено и вместо него будет обсчитываться doEndTag().


Свойства


Новых свойств, в дополнение к уже имеющимся в Tag, нет.


Методы


Имеется один новый метод: doAfterBody().


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


Жизненный цикл показан на диаграмме переноса. Исключения, вызываемые в процессе обсчёта doStartTag(), BODY и doAfterBody(), прерывают последовательность выполнения и помещаются на верх стэка, если только обработчик тэга не реализует интерфейс TryCatchFinally; см. детали об этом интерфейсе.
 


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


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


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

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

JSP.10.1.2.3 Поля


public static final int EVAL_BODY_AGAIN


Запрашивает повторение обсчёта некоторого тела/body. Возвращается методом doAfterBody. Для совместимости с JSP 1.1 значение должно тщательно подбираться, чтобы быть тем же самым, что и в, теперь не рекомендуемом, BodyTag.EVAL_BODY_TAG.

JSP.10.1.2.4 Методы


public int doAfterBody()


Осуществляет (пере)обсчёт тела. Этот метод вызывается объектом реализации JSP-страницы после каждого обсчёта тела в объекте BodyEvaluation. Этот метод не вызывается, если нет обсчёта тела/body.


Если doAfterBody возвращает EVAL_BODY_AGAIN, происходит новый обсчёт тела (с последующим вызовом doAfterBody). Если doAfterBody возвращает SKIP_BODY, обсчёт тела больше не производится, значение out восстанавливается через использование метода popBody в pageContext, а затем вызывается doEndTag.

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


Возвращает: нужно ли проводить дополнительные обсчёты тела/body.


Вызывает: JspException

JSP.10.1.3 TryCatchFinally


Синтаксис


public interface TryCatchFinally


Описание


Интерфейс, в дополнение к Tag, IterationTag или BodyTag, для обработчика тэга, которому нужны дополнительные возможности для обслуживания ресурсов. Этот интерфейс предоставляет два новых метода: doCatch(Throwable) и doFinally().


Прототип вызова таков:


h = get a Tag(); // получает обработчика тэга, возможно из пула
h.setPageContext(pc); // инициализируется
h.setParent(null);
h.setFoo("foo");

// протокол вызова тэга; см. Tag.java

try {
doStartTag()...
....
doEndTag()...
}catch (Throwable t){
// реагирует на условие исключения
h.doCatch(t);
} finally {
// восстанавливает инварианты данных и освобождает вызванные ресурсы
h.doFinally();
}

... другие вызовы, возможно, с новыми setter'ами

...

h.release(); // освобождает долгосрочные ресурсы

JSP.10.1.3.5 Методы


public void doCatch(java.lang.Throwable t)


Вызывается, если возникает Throwable при обсчёте BODY внутри тэга, или любым из следующих методов: Tag.doStartTag(), Tag.doEndTag(), Iteration-Tag.doAfterBody() и BodyTag.doInitBody().


Этот метод вызывается, если Throwable возникает в одном из setter-методов.


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


Этот метод предназначен для использования в ответ на исключительное условие.


Параметры:


t
- Навигация вызываемого исключения по этому тэгу.


Вызывает: Throwable


public void doFinally()


Вызывается во всех случаях после doEndTag() для всех классов, реализующих Tag, IterationTag или BodyTag. Этот метод вызывается, даже если в BODY тэга возникло исключение, или в любом из следующих методов:

Tag.doStartTag(), Tag.doEndTag(), IterationTag.doAfterBody() и Body-Tag.doInitBody().


Этот метод не вызывается, если Throwable возникает в одном из setter-методов.

Этот метод не должен вызывать Exception.

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

JSP.10.1.4 TagSupport


Синтаксис
 

public class TagSupport implements IterationTag, java.io.Serializable


Прямые Известные Подклассы: BodyTagSupport


Все Реализованные Интерфейсы: IterationTag, java.io.Serializable, Tag


Описание


Базовый класс для определения новых обработчиков тэгов, реализующих Tag.


Класс TagSupport является служебным классом, предназначенным для использования в качестве базового класса для новых обработчиков тэгов. Класс TagSupport реализует интерфейсы Tag и IterationTag и добавляет дополнительные удобные методы, включая getter-методы для свойств в Tag. TagSupport имеет один static-метод, который включён для облегчения координации между кооперирующимися тэгами.


Многие обработчики тэгов будут расширять TagSupport и переопределять только некоторые методы.

JSP.10.1.4.6 Поля
 

protected java.lang.String id


protected PageContext pageContext

JSP.10.1.4.7 Конструкторы


public TagSupport()


Конструктор по умолчанию, все классы должны определять только public-конструктор с той же подписью и вызывать конструктор суперкласса. Этот конструктор вызывается кодом, генерируемым JSP-транслятором.

JSP.10.1.4.8 Методы
 

public int doAfterBody()


Процессинг по умолчанию для тела/body.


Возвращает: SKIP_BODY


Вызывает: JspException


См. также: public int doAfterBody()


public int doEndTag()


Процессинг по умолчанию конечного тэга, возвращающий EVAL_PAGE.


Вызывает: JspException


См. также: public int doEndTag()


public int doStartTag()


Процессинг по умолчанию начального тэга, возвращающий SKIP_BODY.


Вызывает:JspException


См. также: public int doStartTag()


public static final Tag findAncestorWithClass(Tag from, java.lang.Class klass)


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

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


Если автор библиотеки тэгов предоставляет информацию о рассматриваемом типе обработчика тэга, клиентский программный код должен быть приспособлен к этому ограничению. Точнее, Class, переданный в findAncestorWithClass, должен иметь подтип рассматриваемого типа.


Параметры:


from
- Экземпляр, с которого начинать просмотр.

klass - Совпадающий подкласс Tag'а или интерфейс.

public java.lang.String getId() - Значение атрибута id этого тэга; или null.

public Tag getParent() - Ближайший экземпляр Tag'а, заключающий в себе данный экземпляр тэга.


См. также: public Tag getParent()


public java.lang.Object getValue(java.lang.String k)


Получает значение, ассоциированное с ключом/key.


Параметры:

k - Строка-ключ.


public java.util.Enumeration getValues()


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


public void release()


Освобождает статус.


См. также: public void release()


public void removeValue(java.lang.String k)


Удаляет значение, ассоциированное с ключом.


Параметры:


k
- строка-ключ.


public void setId(java.lang.String id)


Устанавливает атрибут id для данного тэга.


Параметры:


id
- String для id.


public void setPageContext(PageContext pageContext)


Устанавливает контекст страницы.


Параметры:


pageContenxt
- PageContext.


См. также: public void setPageContext(PageContext pc)


public void setParent(Tag t)


Устанавливает вкладывающий тэг для данного тэга.


Параметры:


t
- родительский Tag.


См. также: public void setParent(Tag t)


public void setValue(java.lang.String k, java.lang.Object o)


Ассоциирует значение со String-ключом.


Параметры:


k
- String-ключ.

o - Ассоциируемое значение.

JSP.10.2 Обработчики Тэгов, которые хотят получить Доступ к Содержимому своего Body/Тела

Вычисление тела передаётся в объект bodyContent, который затем становится доступным обработчикам тэгов, реализующим интерфейс BodyTag. Класс BodyTag-Support даёт базовый класс, упрощающий написание этих обработчиков. Если обработчик Tag хочет иметь доступ к содержимому его тела, то он обязан реализовывать интерфейс BodyTag. Этот интерфейс расширяет IterationTag, предоставляя два дополнительных метода setBodyContent(bodyContent) и doInitBody() и ссылаясь на объект типа bodyContent.

bodyContent
это подкласс JspWriter'а, имеющий несколько дополнительных методов для конвертации его содержимого в String, вставки этого содержимого в другой JspWriter, получения Reader в его содержимое и очистки содержимого. Его семантика гарантирует, что размер буфера никогда не будет превышен.

Реализация JSP-страницы создаст bodyContent, если метод doStartTag() возвращает EVAL_BODY_BUFFERED. Этот объект будет передан методу doInitBody(); затем тело тэга будет обсчитано, и в ходе этого вычисления out будет привязан к bodyContent, только что переданному обработчику BodyTag .

Затем doAfterBody() будет обсчитан. Если этот метод вернёт SKIP_BODY, больше никаких вычислений тела выполнено не будет; если метод вернёт EVAL_BODY_AGAIN, тогда тело будет обсчитано, а doAfterBody() будет вызван вновь.

Содержимое экземпляра bodyContent остаётся доступным, пока не будет вызван его ассоциированный метод doEndBody().


Обычно bodyContent используется для извлечения его содержимого в String и последующего использования этой String в качестве значения для некоторой операции. Другой обычный способ использования - взять его содержимое и поместить его в поток вывода/out Stream, который был верным/действующим/valid в момент обнаружения тэга (который доступен из объекта PageContext, переданного обработчику в setPageContext).
 

JSP.10.2.1 bodyContent


Синтаксис


public abstract class bodyContent extends JspWriter


Описание


Инкапсулирует вычисление/обсчёт тела акции так, что доступен обработчику тэга. bodyContent является подклассом JspWriter'а.


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

bodyContent
имеет методы конвертации своего содержимого в String, для чтения его содержимого, и для очистки/clear своего содержимого.

Размер буфера объекта bodyContent не ограничен. Объект bodyContent не может быть в режиме autoFlush.

Невозможно вызвать flush в объекте bodyContent, так как отсутствует фоновый/backing поток.

Экземпляры bodyContent'а создаются через вызов методов pushBody и popBody класса PageContext.

bodyContent
заключён внутри другого JspWriter'а (возможно, другого объекта bodyContent), следуя структуре их ассоциированных акций.

bodyContent
становится доступным BodyTag'у через вызов setBodyContent().

Обработчик тэга может использовать этот объект до момента вызова doEndTag().

JSP.10.2.1.9 Конструкторы


protected bodyContent(JspWriter e)


Protected-конструктор. Несвязанный буфер, без autoflushing/автооочистки.

JSP.10.2.1.10 Методы
 

public void clearBody()


Очищает body без вызова исключений.


public void flush()


Переопределённый таким образом flush() не допускается. Нельзя зачищать bodyContent, поскольку позади него отсутствует фоновый/backing поток.


Переопределяет: public abstract void flush() в классе JspWriter


Вызывает: IOException


public JspWriter getEnclosingWriter()


Получает содержащий JspWriter.


Возвращает: содержащий JspWriter, переданный на этапе конструирования.


public abstract java.io.Reader getReader()


Возвращает: значение данного bodyContent как Reader.


public abstract java.lang.String getString()


Возвращает: значение данного bodyContent как String.


public abstract void writeOut(java.io.Writer out)


Записывает содержимое данного bodyContent в Writer. Подклассы могут оптимизировать общие патэрны вызова.


Параметры:


out
- writer, в который помещается содержимое вычисления этого body.


Вызывает: IOException

JSP.10.2.2 BodyTag


Синтаксис


public interface BodyTag extends IterationTag


Все Суперинтерфейсы: IterationTag, Tag


Все Известные Реализующие Классы: BodyTagSupport


Описание


Интерфейс BodyTag расширяет IterationTag путём определения дополнительных методов, позволяющих обработчику тэга манипулировать содержимым, обсчитывая его тела.

Обработчик тэга отвечает за обработку содержимого body. Например, обработчик тэга может взять содержимое тела, конвертировать его в String путём использования метода bodyContent.getString и его последующего использования. Либо обработчик тэга может взять тело содержимого и записать его в содержащий JspWriter, используя метод bodyContent.writeOut.


Обработчик тэга, реализующий BodyTag, рассматривается как обработчик, реализующий IterationTag, за исключением того, что метод doStartTag может возвратить SKIP_BODY, EVAL_BODY_INCLUDE или EVAL_BODY_BUFFERED.


Если возвращено EVAL_BODY_INCLUDE, вычисление проводится как в IterationTag.


Если возвращено EVAL_BODY_BUFFERED, будет создан объект bodyContent (в коде, генерируемом JSP-компилятором) для захвата вычисления тела.


Код, генерируемый JSP-компилятором, получает объект bodyContent через вызов метода pushBody из текущего pageContext, который дополнительно даёт эффект сохранения предыдущего значения out. Компилятор страницы возвращает этот объект через вызов метода popBody класса PageContext; этот вызов также восстанавливает значение out.


Этот интерфейс предоставляет одно новое свойство с setter-методом и новый метод акции.


Свойства


Имеется новое свойство: bodyContent, для получения объекта bodyContent, где объект реализации JSP-страницы будет размещать вычисление/обсчёт (и повторный обсчёт, если нужно) тела.

setter
-метод (setBodyContent) будет вызван только в том случае, если doStartTag() возвратит EVAL_BODY_BUFFERED.


Методы


В дополнение к setter-методу свойства bodyContent есть новый метод акции: doInitBody(), который вызывается сразу после setBodyContent() и до обсчёта тела. Этот метод вызывается только в том случае, если doStartTag() возвращает EVAL_BODY_BUFFERED.


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


Детали жизненного цикла даны ниже на диаграмме переноса. Исключения, вызываемые в процессе вычислений doStartTag(), setBodyContent(), doInit-Body(), BODY, doAfterBody(), прерывают выполнение и помещаются на верх стэка, если только обработчик тэга не реализует интерфейс TryCatchFinally; см. детали об этом интерфейсе.
 


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


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

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

Если возвращено EVAL_BODY_INCLUDE, setBodyContent() не вызывается, doInitBody() не вызывается, тело обсчитывается и "передаётся" текущему out, затем вызывается doAfterBody() и, после 0 или более итераций, вызывается doEndTag().


Если возвращено EVAL_BODY_BUFFERED, setBodyContent() вызывается, doInit-Body() вызывается, тело обсчитывается, вызывается doAfterBody() и, после 0 или более итераций, вызывается doEndTag().

JSP.10.2.2.11 Поля


public static final int EVAL_BODY_BUFFERED


Запрашивается создание нового буфера, bodyContent, в котором происходит обсчёт тела данного тэга.

Возвращается из doStartTag, если класс реализует BodyTag.

Неверным является значение doStartTag, если класс не реализует BodyTag.


public static final int EVAL_BODY_TAG


Не рекомендуется. Так как Java JSP API 1.2 использует BodyTag.EVAL_BODY_BUFFERED или IterationTag.EVAL_BODY_AGAIN.


Не рекомендуемая для использования константа, которая имеет то же значение, что и EVAL_BODY_BUFFERED и EVAL_BODY_AGAIN. Помечена как не рекомендуемая с целью продвижения этих двух различных терминов, которые являются более описательными.

JSP.10.2.2.12 Методы


public void doInitBody()


Подготавливает обсчёт/вычисление тела/body. Этот метод вызывается объектом реализации JSP-страницы после setBodyContent и до первого вычисления тела. Этот метод не вызывается для пустых тэгов или непустых тэгов, чей метод doStartTag() возвращает SKIP_BODY или EVAL_BODY_INCLUDE.

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


Вызывает:JspException


public void setBodyContent(bodyContent b)


Устанавливает свойство bodyContent. Этот метод вызывается объектом реализации JSP-страницы максимум один раз на один вызов акции. Этот метод будет вызван до doInitBody. Этот метод не будет вызван для пустых тэгов и для непустых тэгов, чей метод doStartTag() возвращает SKIP_BODY или EVAL_BODY_INCLUDE.
Если setBodyContent вызывается, значение неявного объекта out уже было изменено в объекте pageContext. Передаваемый объект bodyContent не будет содержать данных, но может использоваться повторно (и очищаться) после некоторого предыдущего вызова.

Объект bodyContent доступен с соответствующим содержимым, пока не вызван метод doEndTag, после чего он может быть использован повторно.


Параметры:


b - bodyContent

JSP.10.2.3 BodyTagSupport


Синтаксис


public class BodyTagSupport extends TagSupport implements BodyTag


Все Реализованные Интерфейсы: BodyTag, IterationTag, java.io.Serializable, Tag


Описание


Базовый класс для определения обработчиков тэгов, реализующих BodyTag.

Класс BodyTagSupport реализует интерфейс BodyTag и добавляет несколько удобных методов, включая getter-методы для свойства bodyContent и методы для получения предыдущего out JspWriter.

Многие обработчики тэгов будут расширять BodyTagSupport и переопределять только несколько методов.

JSP.10.2.3.13 Поля


protected bodyContent bodyContent

JSP.10.2.3.14 Конструкторы


public BodyTagSupport()


Конструктор по умолчанию, все подклассы должны определить public-конструктор с той же подписью и вызвать конструктор суперкласса. Этот конструктор вызывается кодом, генерируемым JSP-транслятором.

JSP.10.2.3.15 Методы

public int doAfterBody()


После вычисления/обсчёта тела: не выполнять повторного обсчёта и продолжать разбор страницы. С данными bodyContent по умолчанию ничего не делается (если они имеются).


Переопределяет: public int doAfterBody() в классе TagSupport


Возвращает: SKIP_BODY


Вызывает: JspException


public int doEndTag()


Процессинг по умолчанию конечного тэга, возвращающий EVAL_PAGE.


Переопределяет: public int doEndTag() в классе TagSupport


Возвращает: EVAL_PAGE


Вызывает: JspException


public void doInitBody()


Подготавливает обсчёт/вычисление тела/body сразу перед первым вычислением тела: нет акции.


Вызывает: JspException


public int doStartTag()


Процессинг по умолчанию начального тэга, возвращающий


Переопределяет: public int doStartTag() в классе TagSupport.


Возвращает: EVAL_BODY_BUFFERED;


Вызывает:JspException


public bodyContent getBodyContent()


Получает текущий bodyContent.


Возвращает: содержимое тела.


public JspWriter getPreviousOut()


Получает окружающий out JspWriter.


Возвращает: содержащий JspWriter, из bodyContent.


public void release()


Освобождает статус.


Переопределяет: public void release() в классе TagSupport.


public void setBodyContent(bodyContent b)


Подготавливает для обсчёта тела: прячет bodyContent.


Параметры: b - bodyContent

JSP.10.3 Пример Работы с Аннотированным Обработчиком Тэга

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

Есть и другие стратегии, которым можно следовать.

В данном примере мы принимаем, что x:iterate это тег итерации, а x:doit и x:foobar - простые тэги. Мы также принимаем, что x:iterate и x:foobar реализуют интерфейс TryCatchFinally, а x:doit - не реализует его.


<x:iterate src="foo">
  <x:doit att1="one" att2="<%=1 +1 %>"/>
  <x:foobar />
  <x:doit att1="one" att2="<%=2 +2 %>"/>
</x:iterate>
<x:doit att1="one" att2="<%=3 +3 %>"/>


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


boolean b1, b2;
IterationTag i; // для x:iterate
Tag d; // для x:doit
Tag d; // для x:foobar
page: // лэйбл для конца страницы...
// инициализируется тэг итерации
i = get tag from pool or new();
i.setPageContext(pc);
i.setParent(null);
i.setSrc("foo");
// x:iterate implements TryCatchFinally
try {
    if ((b1 = i.doStartTag()) == EVAL_BODY_INCLUDE) {
         // инициализируется тэг doit
         // код выводится из цикла для показа
         d = get tag from pool or new();
         d.setPageContext(pc);
         d.setParent(i);
         d.setAtt1("one");
    loop:
      while (1) do {
      // Игнорирую символы новой строки...
      // два вызова, сплавленные вместе
      // первый вызов x:doit
      d.setAtt2(1+1);
      if ((b2 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
          // ничего
      } else if (b2 != SKIP_BODY) {
         // Q? ошибка протокола ...
      }
      if ((b2 = d.doEndTag()) == SKIP_PAGE) {
           break page; // выполняется им.
      } else if (b2 != EVAL_PAGE) {
           // Q? ошибка протокола
      }

// вызов x:foobar
      f = get tag from pool or new();
      f.setPageContext(pc);
      f.setParent(i);
      // x:foobar implements TryCatchFinally
      try {
         if ((b2 = f.doStartTag()) == EVAL_BODY_INCLUDE) {
             // ничего
         } else if (b2 != SKIP_BODY) {
            // Q? ошибка протокола
         }
         if ((b2 = f.doEndTag()) == SKIP_PAGE) {
             break page; // выполняется им.
         } else if (b2 != EVAL_PAGE) {
            // Q? ошибка протокола
         }
} catch (Throwable t) {
         f.doCatch(t); // отловлено, может быть повторно отловлено!
} finally {
         f.doFinally();
}
// помещает f обратно в пул

// второй вызов x:doit
d.setAtt2(2+2);
if ((b2 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
    // ничего
} else if (b2 != SKIP_BODY) {
   // Q? ошибка протокола
}
if ((b2 = d.doEndTag()) == SKIP_PAGE) {
    break page; // выполняется им.
} else if (b2 != EVAL_PAGE) {
   // Q? ошибка протокола
}
if ((b2 = i.doAfterBody()) == EVAL_BODY_AGAIN) {
   break loop;
} else if (b2 != SKIP_BODY) {
   // Q? ошибка протокола
}

// цикл
}
} else if (b1 != SKIP_BODY) {
// Q? ошибка протокола
}

// конец IteratorTag ...
if ((b1 = i.doEndTag()) == SKIP_PAGE) {
   break page; // выполняется им.
} else if (b1 != EVAL_PAGE) {
   // Q? ошибка протокола
}

// третий вызов
// этот обработчик тэга может быть повторно использован из предыдущего.
d = get tag from pool or new();
d.setPageContext(pc);
d.setParent(null);
d.setAtt1("one");
d.setAtt2(3+3);
if ((b1 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
   // ничего
} else if (b1 != SKIP_BODY) {
   // Q? ошибка протокола
}
if ((b1 = d.doEndTag()) == SKIP_PAGE) {
   break page; // выполняется им.
} else if (b1 != EVAL_PAGE) {
   // Q? ошибка протокола
}
}catch (Throwable t){
i.doCatch(t); // отловлено, может быть повторно отловлено!
} finally {
i.doFinally();
}

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

Акции могут кооперироваться с другими акциями и с кодом скриптинга разными способами.

PageContext


Часто две акции в JSP-странице нужно скооперировать: когда, возможно, одна акция создаёт серверный объект, доступ к которому осуществляет вторая акция. Один из механизмов реализации этого - дать объекту имя внутри JSP-страницы; первая акция создаст объект и ассоциирует имя с ним, а вторая акция будет использовать это имя для запроса объекта.

Например, в следующем JSP-фрагменте акция foo может создать серверный объект и дать ему имя "myObject". Затем акция bar может получить доступ к этому серверному объекту и выполнить какое-нибудь действие.


<x:foo id="myObject" />

<x:bar ref="myObjet" />


В JSP-реализации отображение "имя"->значение хранится в неявном объекте pageContext. Этот объект передаётся по кругу через экземпляры обработчика Tag так, что он (объект) может использоваться для передачи информации: всё, что необходимо, это знать имя, под которым информация хранится в pageContext.


Стэк Времени Прогона/Runtime Stack

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


<foo>

<bar/>

</foo>


Эта функциональность поддерживается через BodyTagSupport.findAncestorWithClass(Tag, Class), который использует ссылку на родительский тэг, сохраняемую каждым экземпляром Tag, что эффективно представляет стэк выполнения времени/этапа прогона.

JSP.10.5 Классы Времени Трансляции

Следующие классы используются на этапе трансляции.


Tag
-отображение, Tag-имя

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

На этапе выполнения реализация JSP-страницы будет использовать доступный экземпляр Tag с соответствующими установками свойств, а затем следовать протоколу, описанному интерфейсами Tag, IterationTag, BodyTag и TryCatchFinally. Реализация гарантирует, что все экземпляры обработчика тэга инициализируются и высвобождаются, но реализация может принимать, что предыдущие установки сохраняются обработчиком тэга, чтобы уменьшить затраты на этапе прогона.


Переменные Скриптинга

JSP поддерживает переменные скриптинга, которые могут объявляться внутри одного скриптлета и использоваться в другом. JSP-акции также можно использовать для определения переменных скриптинга, чтобы использовать их затем в элементах скриптинга или в других акциях. Это особенно применимо в некоторых случаях; например, стандартная акция jsp:useBean может определять объект, который позднее используется через переменную скриптинга.

В некоторых случаях информация переменных скриптинга может быть описана непосредственно в TLD, используя элементы. Особый случай - типичная итерация атрибута &quotid". В других случаях логика, определяющая определение экземпляром акции переменной скриптинга, может быть довольно сложной, и имя класса TagExtraInfo используется вместо данного в TLD. Метод getVariableInfo этого класса используется во время трансляции для получения информации о каждой переменной, которая будет создана во время запроса, когда данная акция выполняется. Метод передаётся в TagDat-экземпляр, содержащий значения атрибутов времени трансляции.

Проверка/Validation

TLD-файл содержит несколько частей информации, которая используется для проверки синтаксиса на этапе трансляции. Он содержит также два расширяемых механизма проверки: класс TagLibraryValidator может использоваться для проверки всей JSP-страницы, а класс TagExtraInfo может использоваться для проверки специфической акции. В некоторых случаях дополнительная проверка на этапе запроса будет выполняться динамически внутри методов в экземпляре Tag. Если обнаружена ошибка, может быть вызван экземпляр JspTagException. Если ошибка не выловлена, этот объект будет вызывать механизм errorpage JSP.


TagLibraryValidator
является дополнением к спецификации JSP 1.2 и заканчивается очень открыто, будучи значительно более мощным, чем механизм TagExtraInfo. JSP-страница представляется через объект PageData, который абстрагирует XML-просмотр JSP-страницы. Экземпляр PageData будет предоставлять InputStream (только для чтения) в странице. Последующие спецификации могут добавить другие просмотры страницы (DOM, SAX, JDOM являются кандидатами). В настоящее время эти просмотры могут генерироваться из InputStream и, возможно, кэшироваться для повышения производительности (вызов просмотра страницы делается "только для чтения").

JSP-контейнер может по выбору поддерживать атрибут jsp:id для более качественной проверки ошибок. Если атрибут поддерживается, контейнер будет отслеживать JSP-страницы по мере передачи контейнеру и назначать каждому элементу уникальный идентификатор "id", который передаётся как значение атрибута jsp:id. Каждый XML-элемент, доступный в XML-просмотре, будет расширен этим атрибутом. TagLibraryValidator может затем использовать этот атрибут в одном или более объектах ValidationMessage. Затем контейнер, в свою очередь, может использовать эти значения для предоставления более точной информации о местонахождении ошибки.


Детали Проверки


Более детально, проверка выполняется так:


Во-первых, JSP-страница разбирается с использованием информации в TLD. На этом этапе проверяются атрибуты - мандатные и по выбору/optional.


Во-вторых, для всех директив taglib страницы, в лексическом порядке их появления, вызывается класс их ассоциированного проверщика (если имеется). Это вызывает выполнение нескольких дополнительных шагов.

Первый шаг выполняется для получения инициализированного экземпляра проверщика путём, либо:

Имя класса - такое, какое указано в элементе <validator-class>, а Map, переданный в setInitParameters() - такой, как описано в элементе <init-params>. Предполагается, что все классы TagLibraryValidator сохраняют свои initParameters до тех пор, пока не будут установлены новые или пока release() не будет в них вызван.


Второй дополнительный шаг выполняет реальную проверку. Это делается через вызов метода validate() с префиксом, uri и PageData, которые соответствуют проверяемому экземпляру директивы taglib и PageData, представляющему эту страницу.


Последний дополнительный шаг вызывает метод release() в тэге проверщика, когда он уже больше не нужен.

Этот метод освобождает все ресурсы.


Наконец, после проверки всех классов проверщика библиотеки тэгов, классы TagExtraInfo для всех тэгов будут проверяться вызовом их метода isValid. Порядок вызова этого метода не определён.

JSP.10.5.1 TagLibraryInfo


Синтаксис


public abstract class TagLibraryInfo


Описание


Это информация времени трансляции, ассоциированная с директивой taglib и её TLD-файлом. Большая часть информации получается непосредственно из TLD, за исключением значений префикса и uri, используемых в директиве taglib.

JSP.10.5.1.16 Поля


protected java.lang.String info

protected java.lang.String jspversion

protected java.lang.String prefix

protected java.lang.String shortname

protected TagInfo[] tags

protected java.lang.String tlibversion

protected java.lang.String uri

protected java.lang.String urn


JSP.10.5.1.17 Конструкторы


protected TagLibraryInfo(java.lang.String prefix, java.lang.String uri)


Конструктор. Будут вызываться конструкторы для TagInfo и TagAttributeInfo после разбора TLD-файла.


Параметры:


prefix
- префикс, используемый директивой taglib

uri - URI, используемый директивой taglib

JSP.10.5.1.18 Методы


public java.lang.String getInfoString()

  Информация (документация) для данного TLD.


public java.lang.String getPrefixString()

  Префикс, назначенный этой taglib из директивы <%taglib.


public java.lang.String getReliableURN()

  "Надёжное" URN, указанное в TLD. Может использоваться утилитами авторизации в качестве глобального идентификатора (атрибут uri) при создании директивы taglib для данной библиотеки.


public java.lang.String getRequiredVersion()

  Строка, описывающая требуемую версию JSP-контейнера.


public java.lang.String getShortName()

  Предпочтительное краткое имя (префикс), как указано в TLD. Может использоваться утилитами авторизации в качестве предпочтительного префикса при создании директивы include для данной библиотеки.


public TagInfo getTag(java.lang.String shortname)

  Получает TagInfo для данного имени тэга, просматривая все тэги в данной библиотеке тэгов.


Параметры:


shortname
- Краткое имя (не префикс) тэга.


public TagInfo[] getTags()
  Массив, описывающий тэги, определённые в данной библиотеке.


public java.lang.String getURI()

  Значение атрибута uri из директивы <%@ taglib для данной библиотеки.

JSP.10.5.2 TagInfo


Синтаксис

public class TagInfo


Описание


Информация Tag для тэга в Библиотеке Тэгов; этот класс инстанциируется из файла TLD/Дескриптора Библиотеки Тэгов и доступна только во время трансляции.

JSP.10.5.2.19 Поля
 

public static final java.lang.String BODY_CONTENT_EMPTY
 static-константа для getBodyContent(), если он пустой.


public static final java.lang.String BODY_CONTENT_JSP

 static-константа для getBodyContent(), если это JSP.


public static final java.lang.String BODY_CONTENT_TAG_DEPENDENT

 static-константа для getBodyContent(), если это зависит от Tag.


JSP.10.5.2.20 Конструкторы


public TagInfo(java.lang.String tagName, java.lang.String tagClassName, java.lang.String bodycontent, java.lang.String infoString, TagLibraryInfo taglib, TagExtraInfo tagExtraInfo, TagAttributeInfo[] attributeInfo)


Конструктор для TagInfo из данных в формате JSP 1.1 для TLD. Этот класс инстанциируется только из кода TagLibrary по запросу из некоторого кода JSP, разбирающего TLD (Tag Library Descriptor). Заметьте, что, поскольку TagLibibraryInfo отражает информацию TLD и директивы taglib, экземпляр TagInfo зависит от директивы taglib. Возможно это ошибка дизайна, которая может быть зафиксирована в будущем.


Параметры:


tagName
- имя того тэга.

tagClassName - имя класса обработчика тэга.

bodycontent - информация о теле содержимого этих тэгов.

infoString - строковая информация (optional) для данного тэга.

taglib - экземпляр библиотеки тэгов, содержащей их.

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

attributeInfo - массив данных AttributeInfo из дескриптора. Может быть null.


public TagInfo(java.lang.String tagName, java.lang.String tagClassName, java.lang.String bodycontent, java.lang.String infoString, TagLibraryInfo taglib, TagExtraInfo tagExtraInfo, TagAttributeInfo[] attributeInfo, java.lang.String displayName, java.lang.String smallIcon, java.lang.String largeIcon, TagVariableInfo[] tvi)


Конструктор для TagInfo из данных в формате JSP 1.2 для TLD. Этот класс инстанциируется только из кода TagLibrary по запросу из некоторого кода JSP, разбирающего TLD. Заметьте, что, поскольку TagLibibraryInfo отражает информацию TLD и директивы taglib, экземпляр TagInfo зависит от директивы taglib. Возможно это ошибка дизайна, которая может быть зафиксирована в будущем.


Параметры:


tagName
- имя того тэга.

tagClassName - имя класса обработчика тэга.

bodycontent - информация о теле содержимого этих тэгов.

infoString - строковая информация (optional) для данного тэга.

taglib - экземпляр библиотеки тэгов, содержащей их.

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

attributeInfo - массив данных AttributeInfo из дескриптора. Может быть null.

displayName - краткое имя для отображения утилитами.

smallIcon - путь к маленькой иконке, отображаемой утилитами.

largeIcon - путь к большой иконке, отображаемой утилитами.

tagVariableInfo - массив TagVariableInfo (или null).


JSP.10.5.2.21 Методы


public TagAttributeInfo[] getAttributes()


Информация атрибута (в TLD) в этом тэге. Возвращается массив, описывающий атрибуты данного тэга, как указано в TLD. Возврат null означает отсутствие атрибутов.


Возвращает: массив TagAttributeInfo для данного тэга.


public java.lang.String getBodyContent()


Информация bodycontent для данного тэга.


Возвращает: строку содержимого тела.


public java.lang.String getDisplayName()


Получает displayName.


Возвращает: Краткое имя для вывода утилитами.


public java.lang.String getInfoString()


Информационная строка для тэга.


Возвращает: информационную строку.


public java.lang.String getLargeIcon()


Получает путь к большой иконке.


Возвращает: путь к большой иконке, отображаемой утилитами.


public java.lang.String getSmallIcon()


Получает путь к маленькой иконке.


Возвращает: путь к маленькой иконке, отображаемой утилитами.


public java.lang.String getTagClassName()


Имя класса, предоставляющего обработчик для данного тэга.


Возвращает: имя класса обработчика тэга.


public TagExtraInfo getTagExtraInfo()


Экземпляр (если имеется) для дополнительной информации тэга.


Возвращает: экземпляр TagExtraInfo, если имеется.


public TagLibraryInfo getTagLibrary()


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


Возвращает: экземпляр библиотеки тэгов, к которому мы принадлежим.


public java.lang.String getTagName()


Имя тэга.


Возвращает: (краткое) имя тэга.


public TagVariableInfo[] getTagVariableInfos()


Получает объекты TagVariableInfo, ассоциированные с этим TagInfo.


Возвращает: объект TagVariableInfo, ассоциированный с этим объектом.


public VariableInfo[] getVariableInfo(TagData data)


Информация об объектах скриптинга, созданных этим тэгом на этапе прогона/runtime. Это удобный метод в ассоциированном классе TagExtraInfo. По умолчанию null, если тэг не имеет атрибута "id", иначе - {"id", Object}


Параметры:


data
- TagData, описывающие данную акцию.


Возвращает: массив элементов VariableInfo.


public booleanisValid(TagData data)


Проверка атрибутов на этапе трансляции. Это удобный метод в ассоциированном классе TagExtraInfo.


Параметры:


data
- экземпляр TagData времени трансляции.


Возвращает: верны ли данные.


public void setTagExtraInfo(TagExtraInfo tei)


Набор экземпляров для дополнительной информации тэга.


Параметры:


tei - экземпляр TagExtraInfo.


public void setTagLibrary(TagLibraryInfo tl)


Устанавливает свойство TagLibraryInfo. Заметьте, что элемент TagLibraryInfo зависит не просто от информации TLD, но также и от специфики используемого экземпляра taglib. Это означает, что некоторая работа должна быть проделана для конструирования и инициализации объектов TagLib. Если использовать аккуратно, этот setter поможет исключить необходимость создания новых элементов TagInfo для каждой директивы taglib.


Параметры:


tl
- назначаемый TagLibraryInfo.


public java.lang.String toString()


Строго для целей отладки ...


Переопределяет: java.lang.Object.toString() в классе java.lang.Object

JSP.10.5.3 TagAttributeInfo


Синтаксис
 

public class TagAttributeInfo


Описание


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

JSP.10.5.3.22 Поля
 

public static final java.lang.String ID


"id"
окружается, чтобы стать ID. Реально это не даёт преимущества, поскольку IDREF не обрабатываются раздельно.

JSP.10.5.3.23 Конструкторы


public TagAttributeInfo(java.lang.String name, boolean required, java.lang.String type, boolean reqTime)


Конструктор для TagAttributeInfo. Этот класс инстанциируется только из кода TagLibrary по запросу из некоторого JSP-кода, разбирающего TLD.


Параметры:


name
- имя атрибута.

required - необходим ли атрибут в экземплярах тэга.

type - имя типа атрибута.

reqTime - содержит ли данный атрибут Attribute времени запроса.


JSP.10.5.3.24 Методы


public booleancanBeRequestTime()


Может ли данный атрибут содержать значение времени запроса.


Возвращает: может ли данный атрибут содержать значение времени запроса.


public static TagAttributeInfo getIdAttribute(TagAttributeInfo[] a)


Удобный static-метод, проходящий по массиву объектов TagAttributeInfo и ищущий "id".


Параметры:


a - массив TagAttributeInfo.


Возвращает: ссылку на TagAttributeInfo с именем "id".


public java.lang.String getName()


Имя этого атрибута.


Возвращает: имя атрибута.


public java.lang.String getTypeName()


Тип (как String) этого атрибута.


Возвращает: тип атрибута.


public booleanisRequired()


Необходим ли данный атрибут.


Возвращает: необходим ли данный атрибут.


public java.lang.String toString()


Переопределяет: java.lang.Object.toString() в классе java.lang.Object

JSP.10.5.4 PageData


Синтаксис


public abstract class PageData


Описание


Информация времени трансляции о JSP-странице. Информация соответствует XML-просмотру JSP-страницы.

Объекты этого типа генерируются JSP-транслятором, например, при передаче экземпляру TagLibraryValidator.

JSP.10.5.4.25 Конструкторы


public PageData()

JSP.10.5.4.26 Методы
 

public abstract java.io.InputStream getInputStream()

Возвращает поток ввода в XML-просмотре JSP-страницы. Вызывает XML-просмотр JSP-страницы, который содержит развёрнутые директивы include.


Возвращает: поток ввода документа.

JSP.10.5.5 TagLibraryValidator


Синтаксис


public abstract class TagLibraryValidator


Описание


Класс проверщика этапа трансляции для JSP-страницы. Проверщик оперирует документом XML, ассоциированным с JSP-страницей. TLD-файл ассоциирует класс TagLibraryValidator и некоторые init-аргументы с библиотекой тэгов.

JSP-контейнер отвечает за размещение соответствующих объектов соответствующего подкласса через:

Экземпляр TagLibraryValidator может создавать вспомогательные объекты внутри для выполнения проверки (например, проверщик XSchema) и может использовать их для всех страниц в ходе данной трансляции.

JSP-контейнер не сериализует гарантированно вызовы метода validate(), и TagLibraryValidator'ы должны выполнять синхронизацию, которая может потребоваться.


JSP-контейнер может по выбору поддерживать атрибут jsp:id для предоставления качественной проверки ошибок. Если такая поддержка имеется, контейнер будет отслеживать JSP-страницы, передаваемые контейнеру, и будет назначать каждому элементу уникальный "id", который передаётся как значение атрибута jsp:id. Каждый элемент XML, доступный в XML-просмотре, будет расширен этим атрибутом.

TagLibraryValidator
может затем использовать этот атрибут в одном или более объектах ValidationMessage. Контейнер тогда, в свою очередь, может использовать эти значения для предоставления более точной информации о местонахождении ошибки.

JSP.10.5.5.27 Конструкторы
 

public TagLibraryValidator()

JSP.10.5.5.28 Методы


public java.util.Map getInitParameters()


Получает данные init-параметров как неизменяемую Map/Карту. Имена параметров это ключи, а значения параметров - это значения.


Возвращает: параметры init как неизменяемую карту.


public void release()


Высвобождает любые данные, хранимые этим экземпляром, с целью проверки.


public void setInitParameters(java.util.Map map
)

Устанавливает данные init в TLD для этого проверщика. Имена параметров это ключи, а значения параметров - это значения.


Параметры:


initMap
- карта, описывающая параметры init.


public ValidationMessage[] validate(java.lang.String prefix, java.lang.String uri, PageData page)


Проверяет JSP-страницу. Будет вызван однократно на каждую директиву в JSP-странице. Этот метод возвратит null, если страница верна/valid; иначе метод должен возвратить массив объектов ValidationMessage. Массив нулевой длины также интерпретируется как отсутствие ошибок.


Параметры:


prefix
- значение аргумента prefix в директиве.

uri - значение аргумента uri в директиве.

thePage - JspData-объект страницы.

Возвращает: null-объект, или массив нулевой длины при отсутствии ошибок, или массив объектов ValidationMessages.

JSP.10.5.6 ValidationMessage


Синтаксис


public class ValidationMessage


Описание


Сообщение о проверке из TagLibraryValidator. JSP-может (по выбору) поддерживать атрибут jsp:id для предоставления качественной проверки ошибок. Если такая поддержка имеется, контейнер будет отслеживать JSP-страницы, передаваемые контейнеру, и будет назначать каждому элементу уникальный "id", который передаётся как значение атрибута jsp:id. Каждый элемент XML, доступный в XML-просмотре, будет расширен этим атрибутом. TagLibraryValidator может затем использовать этот атрибут в одном или более объектах ValidationMessage. Контейнер тогда, в свою очередь, может использовать эти значения для предоставления более точной информации о местонахождении ошибки.

JSP.10.5.6.29 Конструкторы


public ValidationMessage(java.lang.String id, java.lang.String message)


Создаёт ValidationMessage. String сообщения должна быть не-null. Значение id может быть null, если сообщение не специфично для XML-элемента или если не были переданы никакие атрибуты jsp:id. Если не-null, значение id обязано быть значением атрибута jsp:id для PageData, передаваемым в метод validate().


Параметры:


id
- либо null, либо значение атрибута jsp:id.

message - локализованное сообщение о проверке.

JSP.10.5.6.30 Методы
 

public java.lang.String getId()

Получает jsp:id.
null означает, что нет доступной информации.


Возвращает: jsp:id-информацию.


public java.lang.String getMessage()


Получает локализованное сообщение о проверке.


Возвращает: сообщение о проверке.

JSP.10.5.7 TagExtraInfo


Синтаксис


public abstract class TagExtraInfo


Описание


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

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

JSP-транслятор отвечает за то, чтобы начальное значение, возвращаемое в вызове getTagInfo(), соответствовало объекту TagInfo транслируемого тэга. Если выполняется явный вызов setTagInfo(), тогда передаваемый объект будет возвращён в последующих вызовах getTagInfo().

Единственный способ повлиять на значение, возвращаемое методом getTagInfo(), - через вызов setTag-Info() и, следовательно, TagExtraInfo.setTagInfo() вызывается JSP-транслятором с объектом TagInfo, который соответствует транслируемому тэгу. Это должно происходить до любого вызова isValid()  и до любого вызова getVariableInfo().

JSP.10.5.7.31 Конструкторы

public TagExtraInfo()

JSP.10.5.7.32 Методы

public final TagInfo getTagInfo()

Получает TagInfo для этого класса.


Возвращает: экземпляр taginfo, расширяемый данным экземпляром.


public VariableInfo[] getVariableInfo(TagData data)


Информация о переменных скриптинга, определённых тэгом, ассоциированным с данным экземпляром TagExtraInfo. Атрибуты времени запроса указаны как таковые в параметре TagData.


Параметры:


data
- экземпляр TagData.


Возвращает: массив данных VariableInfo.


public boolean isValid(TagData data)


Проверка атрибутов на этапе трансляции. Атрибуты времени запроса указаны как таковые в параметре TagData.


Параметры:


data
- экземпляр TagData.


Возвращает: верен ли этот экземпляр тэга.


public final void setTagInfo(TagInfo tagInfo)


Устанавливает TagInfo для данного класса.


Параметры:


tagInfo
- TagInfo, расширяемая этим экземпляром.

JSP.10.5.8 TagData


Синтаксис


public class TagData implements java.lang.Cloneable


Все Реализованные Интерфейсы: java.lang.Cloneable


Описание


Информация (только времени трансляции) атрибута/значения для экземпляра тэга. TagData используется только в качестве аргумента методов isValid и getVariableInfo в TagExtraInfo, которые вызываются во время трансляции.

JSP.10.5.8.33 Поля


public static final java.lang.Object REQUEST_TIME_VALUE


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

JSP.10.5.8.34 Конструкторы


public TagData(java.util.Hashtable attrs)


Конструктор для TagData. Если Вы уже имеете атрибуты в хэш-таблице, используйте этот конструктор.


Параметры:


attrs
- хэш-таблица для получения из неё значений.


public TagData(java.lang.Object[][] atts)


Конструктор для TagData.


Типичный конструктор может быть таким:


static final Object[][] att = {{"connection", "conn0"},

{"id", "query0"}};

static final TagData td = new TagData(att);


Значения обязаны быть String, за исключением тех, которые содержат известные объекты REQUEST_TIME_VALUE.


Параметры: atts - статические атрибут и значения. Может быть null.

JSP.10.5.8.35 Методы


public java.lang.Object getAttribute(java.lang.String attName)


Значение атрибута. Содержит известный объект REQUEST_TIME_VALUE, если значение является значением этапа запроса. Возвращает null, если атрибут не установлен.


Возвращает: объект значения атрибута.


public java.util.Enumeration getAttributes()


Перечисляет атрибуты.


Возвращает: перечисление атрибутов в TagData.


public java.lang.String getAttributeString(java.lang.String attName)


Получает значение для данного атрибута.


Возвращает: строка значений атрибута.


public java.lang.String getId()


Значение атрибута id, если имеется.


Возвращает: значение атрибута id или null.


public void setAttribute(java.lang.String attName, java.lang.Object value)


Устанавливает значение атрибута.


Параметры:


attName
- имя атрибута.

value - значение.

JSP.10.5.9 VariableInfo


Синтаксис


public class VariableInfo


Описание


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

Переменные скриптинга, генерируемые специальной акцией, могут иметь значения области видимости page, request, session и application.

Имя класса (VariableInfo.getClassName) в возвращаемых объектах может использоваться для определения типов переменных скриптинга. В связи с этим специальная акция не может создавать переменную скриптинга примитивного/базового типа. Чтобы обойти это, используйте "boxed/боксовые" типы.

Имя класса может быть Полным Квалифицированным Именем Класса, или кратким именем класса.

Если предоставляется Полное Квалифицированное Имя Класса, оно должно ссылаться на класс, находящийся в CLASSPATH для Web-Приложения (см. спецификацию Servlet 2.3 - как правило это WEB-INF/lib и WEB-INF/classes). Невыполнение этого приводит к ошибке времени трансляции.

Если дано краткое имя класса в объектах VariableInfo, тогда имя класса обязано быть именем public-класса в контексте директив import страницы, на которой специальная акция появилась (будет проверяться, имеется ли словоблудие JLS для ссылки на него). Класс обязан также быть в CLASSPATH для Web-Приложения (см. спецификацию Servlet 2.3 - как правило это WEB-INF/lib и WEB-INF/classes). Невыполнение этого приводит к ошибке времени трансляции.

Использование Комментариев

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

Употребление полных квалифицированных имён в такой манере делает их использование относительно устойчивым к ошибкам конфигурации.

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


Протокол Синхронизации

Результатом вызова getVariableInfo является массив объектов VariableInfo. Каждый такой объект описывает переменную скриптинга, предоставляя её имя, тип, указывая, является ли переменная новой или нет, и какова её область видимости. Область видимости лучше видна на рисунке:
 


Спецификация JSP 1.2 определяет интерпретацию трёх значений:

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

Информация о Переменной в TLD

Информация переменной скриптинга может быть также непосредственно кодирована для большинства случаев в Tag Library Descriptor путём использования субэлемента <variable> элемента <tag>. См. спецификацию JSP.

JSP.10.5.9.36 Поля

public static final int AT_BEGIN
  Информация области видимости о том, что переменная скриптинга видна после начального тэга.


public static final int AT_END

  Информация области видимости о том, что переменная скриптинга видна после конечного тэга.


public static final int NESTED

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


JSP.10.5.9.37 Конструкторы


public VariableInfo(java.lang.String varName, java.lang.String className, boolean declare, int scope)


Конструктор. Эти объекты могут быть созданы (на этапе трансляции) экземплярами TagExtraInfo.


Параметры:


id
- имя переменной скриптинга.

className - имя переменной скриптинга (наверное, класса??).

declare - если true, это новая переменная (в некоторых языках это требует объявления).

scope - обозначение лексической области видимости переменной.

JSP.10.5.9.38 Методы


public java.lang.String getClassName()

public boolean getDeclare()

public int getScope()

public java.lang.String getVarName()

JSP.10.5.10 TagVariableInfo


Синтаксис


public class TagVariableInfo


Описание


Информация переменной для тэга в Библиотеке Тэгов. Этот класс инстанциируется из TLD-файла и доступен только во время трансляции. Этот объект должен быть неизменяемым.

Данная информация доступна только в формате JSP 1.2.

JSP.10.5.10.39 Конструкторы


public TagVariableInfo(java.lang.String nameGiven, java.lang.String nameFromAttribute, java.lang.String className, boolean declare, int scope)


Конструктор для TagVariableInfo.


Параметры:


nameGiven
- значение <name-given>

nameFromAttribute - значение <name-from-attribute>

className - значение <variable-class>

declare - значение <declare>

scope - значение <scope>

JSP.10.5.10.40 Методы


public java.lang.String getClassName()

Тело элемента <variable-class>.


Возвращает: имя класса переменной.


public booleangetDeclare()


Тело элемента <declare>.


Возвращает: объявляется переменная, или нет.


public java.lang.String getNameFromAttribute()


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


Возвращает: атрибут, чьё значение определяет имя переменной.


public java.lang.String getNameGiven()


Тело элемента <name-given>.


Возвращает: имя переменной как константу.


public int getScope()


Тело элемента <scope>.


Возвращает: область видимости для переменной.


Глава JSP.2

Синтаксис Ядра и Семантика


В этой главе описаны синтаксис ядра и семантика спецификации JavaServer Pages 1.2 (JSP 1.2).

JSP.2.1 Что такое Страница JSP?

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

JSP-страница определяет класс реализации JSP-страницы который реализует семантику JSP-страницы. Этот класс является подклассом Servlet'а (см. Главу JSP.8). Во время запроса, запрос, предназначенный для JSP-страницы, направляется объекту реализации JSP-страницы для обработки/процесинга.

HTTP является протоколом по умолчанию для запросов и ответов. Дополнительные протоколы запроса/ответа могут поддерживаться JSP-контейнерами (см. ниже). Объекты request и response по умолчанию имеют тип HttpServletRequest и HttpServletResponse, соответственно.

JSP.2.1.1 Web-Контейнеры и Web-Компоненты

JSP-контейнер это экземпляр системного уровня, предоставляющий обслуживание жизненного цикла и поддержку на этапе прогона для JSP-страниц Servlet-компонентов. Запросы, направляемые JSP-странице, направляются JSP-контейнером подходящему объекту реализации JSP-страницы. Термин web-контейнер является синонимом JSP-контейнера.

Web-компонент это сервлет или JSP-страница. Элемент servlet в дескрипторе публикации web.xml используется для описания обоих типов web-компонентов. Компоненты - JSP-страницы - определяются неявно в дескрипторе публикации через использование неявного отображения расширения  .jsp

JSP.2.1.2 XML-Документ для Страницы JSP

JSP-страницы имеют эквивалент - XML-документ. XML-просмотр JSP-страницы создан для фазы трансляции (см. ниже).

JSP-страница может быть написана сразу как XML-документ. Начиная с версии JSP 1.2, XML-документ может быть направлен JSP-контейнеру для процесинга.

Нельзя смешивать стандартный синтаксис и XML-синтаксис в одном файле-источнике. Однако JSP-страница любого синтаксиса может включать JSP-страницу любого синтаксиса через директиву.

JSP.2.1.3 Фазы Трансляции и Выполнения

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

Во время фазы трансляции контейнер локализует или создаёт класс реализации JSP-страницы, соответствующий данной JSP-странице. Этот процесс определяется семантикой JSP-страницы. Контейнер интерпретирует имеющиеся на этой странице стандартные директивы и акции и специальные акции, ссылающиеся на библиотеки тэгов. Библиотека тэгов может по выбору представлять метод проверки корректности использования на JSP-странице данной библиотеки.

JSP-контейнер гибко работает с деталями класса реализации JSP-страницы, что может использоваться для адресации вопросов quality-of-service/качества-сервиса.


В фазе выполнения JSP-контейнер направляет события объекту реализации JSP-страницы. Контейнер отвечает за инициацию объектов request и response и вызов подходящего объекта реализации JSP-страницы.

По окончании процессинга, объект response получается контейнером для соединения с клиентом.
Детали соглашения/контракта между классом реализации JSP-страницы и JSP-контейнером описаны в Главе JSP.8.


Трансляция JSP-страницы-источника в класс её реализации может произойти в любой момент между начальной публикацией JSP-страницы в JSP-контейнер и получением и процессингом запроса клиента для целевой JSP-страницы. В Разделе JSP.2.1.5 описывается выполнение фазы трансляции перед публикацией.

JSP.2.1.4 События на Страницах JSP

JSP-страница может отмечать обработку некоторых событий. В JSP 1.2 только события init и destroy могут быть описаны в JSP-странице.


Когда первый запрос направляется JSP-странице, метод jspInit(), если он имеется, будет вызван для подготовки страницы. Аналогично, JSP-контейнер может вызывать метод JSP jspDestroy() для переделки ресурсов, используемых JSP-страницей, в любой момент, когда запрос не обслуживается. Это такой же жизненный цикл, что и у сервлетов.

JSP.2.1.5 Компилирование Страниц JSP

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

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

Компиляция JSP-страницы в контексте web-приложения предоставляет разрешение спецификаций относительных URL в директивы include (и в другом месте), ссылок на taglib и акции времени трансляции, используемых в специальных акциях.


JSP-страница может также компилироваться во время публикации.
 

JSP.2.1.5.1 Упаковка Страницы JSP
 

Когда класс реализации JSP-страницы зависит от поддержки классов (в дополнение к классам JSP 1.2 и Servlet 2.3), классы поддержки включаются в упакованный WAR-файл (как определено в спецификации Servlet 2.3) для обеспечения переносимости по JSP-контейнерам.


В Приложении JSP.A есть два примера упаковки JSP-страниц в WAR'ы:

  1. JSP-страница, направляемая в своей исходной форме (вероятно, это самый распространённый случай).
  2. JSP-страница, оттранслированная в класс реализации плюс информация для публикации.

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

JSP.2.1.6 Отладка Страниц JSP

Раньше утилиты отладки не имели стандартного формата для передачи информации отображения исходного кода, позволяющей использовать отладчик одного производителя с JSP-контейнером другого. Спецификация с поддержкой отладки, преодолевшая эти ограничения, разрабатывается как JSR-045 процесса JCP 2.0 под названием "Debugging Support for Non-Java Languages/Поддержка Отладки для Не-Java-Языков".


Детали можно найти по адресу  http://jcp.org/jsr/detail/45.jsp

JSP.2.1.7 Соглашение по Именованию для Файлов JSP

JSP-страница упаковывается в один или более файлов, часто - как web-приложение, и направляется утилите типа JSP-контейнера, J2EE-контейнера или IDE. Полная JSP-страница может содержаться в одном файле. В других случаях основной файл содержит другие файлы, которые содержать полные JSP-страницы или включаемые фрагменты.

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

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


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

Мы рекомендуем (но не обязываем), чтобы:

JSP.2.2  Web-Приложения

Приложение web это коллекция ресурсов, которые доступны по указанным URL.

Web-приложение состоит из следующих компонентов:

Web-приложения описаны более детально в спецификации Servlet 2.3. Web-приложение содержит дескриптор публикации web.xml, содержащий информация о JSP-страницах, сервлетах и других ресурсах, используемых в этом web-приложении. Дескриптор публикации детально описан в спецификации Servlet 2.3.

JSP 1.2 требует, чтобы эти ресурсы были неявно/косвенно ассоциированы с, и доступны через, уникальный экземпляр ServletContext, доступный как неявный объект приложения (Раздел JSP.2.8).

Приложение, которому принадлежит JSP-страница, отражается в объекте application и влияет на семантику следующих элементов:

JSP 1.2 поддерживает переносимую упаковку и публикацию/deployment web-приложений через спецификацию Servlet 2.3. Спецификация JavaServer Pages наследует от спецификации Servlet концепцию приложений, ServletContext'ы, Sessions/Сессии, Requests/Запросы и Responses/Ответы.

JSP.2.2.1 Специфицирование Относительных URL

Элементы могут использовать спецификации относительных URL, называемые "URI-пути" в спецификации Servlet 2.3. Эти пути описаны в спецификации RFC 2396. Мы имеем в виду часть path данной спецификации, а не части scheme или authority.

Некоторые примеры:

Путь относительно контекста это путь, начинающийся со знака "/". Он интерпретируется относительно приложения, к которому принадлежит JSP-страница, то есть говорится, что её объект ServletContext предоставляет базовый контекстный URL.


Путь относительно страницы это путь, не начинающийся со знака "/". Он интерпретируется как относительный к текущей JSP-странице или текущему JSP-файлу, в зависимости от того, где путь используется:

для директивы include (Раздел JSP.2.10.3); когда путь используется в  атрибуте файла - интерпретация относительно JSP-файла;

для акции jsp:include (Раздел JSP.4.4), когда путь используется атрибуте страницы - интерпретация относительно JSP-страницы.

В обоих случаях текущая страница (или файл) обозначается некоторой частью пути, начинающейся с "/", который (путь) затем модифицируется новой спецификацией, производящей путь с начальным "/".

Новый путь интерпретируется через объект ServletContext. См. точную информацию об этой интерпретации в Разделе JSP.2.10.4.


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

JSP.2.3 Синтаксические Элементы Страницы JSP

В этом разделе описаны базовые синтаксические правила JSP-страниц.

JSP.2.3.1 Элементы и Шаблонные Данные

JSP-страница содержит элементы и шаблонные данные.

Элемент
является экземпляром типа элемента, известного JSP-контейнеру.

Шаблонные данные
это то, о чём JSP-танслятор ничего не знает.

Тип элемента описывает его синтаксис и семантику. Если элемент имеет атрибуты, тип описывает имена, верные типы атрибутов и их интерпретацию. Если элемент определяет объекты, семантика включает эти определяемые объекты и их типы.

JSP.2.3.2 Синтаксис Элемента

Имеются элементы трёх типов: директивы, элементы скриптинга и акции.

Директивы
 

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


Синтаксис элемента-директивы  <%@ директива...%>

Акции
 

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

Элементы action следуют синтаксису XML-элемента: они имеют начальный тэг, включающий имя элемента, и могут иметь атрибуты, необязательное тело/body и соответствующий конечный тэг, или они могут быть пустыми тэгами, возможно, с атрибутами:
 

<mytag attr1="значение атрибута"...>body</mytag>
 

и


<mytag attr1="значение атрибута".../>

<mytag attr1="значение атрибута" ...></mytag>
 

Элемент имеет тип элемента, описывающий имя его тэга, верные атрибуты и их семантику.

Мы обращаемся к типу по имени его тэга.


JSP-тэги чувствительны к регистру, как в XML и XHTML.


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

Элементы Скриптинга


Элементы Скриптинга являются связкой между шаблонным текстом и акциями.

Есть три типа элементов скриптинга: declarations\объявления, scriptlets\скриптлеты и expressions\выражения.


Объявления имеют синтаксис <%! ... %>

скриптлеты   <% ... %>

выражения     <%= ... %>

JSP.2.3.3 Начальный и Конечный Тэги

Элементы, имеющие разные начальный и конечный тэги (при наличии тела), обязаны иметь начало и конец в одном файле. Стартовый тэг не может быть в одном файле, когда конечный тэг находится в другом файле.
То же самое правило применяется к элементам с альтернативным синтаксисом. Например, скриптлет имеет синтаксис <% скриптлет %>. Открывающий <% и закрывающий %> символы обязаны находиться в одном и том же физическом файле.
Язык скриптинга может также вводить ограничения на размещение начальных и конечных тэгов для специфических конструкций скриптинга. Например, в Главе 6 демонстрируется, как блоки языка Java не могут разделять начальный и конечный тэг; см. детали в Разделе JSP.6.4.

JSP.2.3.4 Пустые Элементы

Следуя спецификации XML, элемент, описанный с использованием пустого тэга, не отличается от элемента. использующего начальный тэг, пустое тело и конечный тэг.
Вот примеры пустых тэгов:
 

<x:foo></x:foo>

<x:foo />

<x:foo/>

<x:foo><%-- любой комментарий --%></x:foo>
 

Далее - примеры непустых тэгов:
 

<foo> </foo>

<foo><%= выражение %></foo>

<foo><% скриптлет %></foo>

<foo><bar/></foo>

<foo><!-- комментарий --></foo>

JSP.2.3.5 Значения Атрибутов

Следуя спецификации XML, атрибуты всегда заключаются в кавычки. Одинарные или двойные кавычки могут использоваться для уменьшения необходимости ввода кавычек мнемониками; соглашения по кавычкам описаны в Разделе JSP.2.6. Есть два типа значений атрибутов: литералы и выражения времени запроса (Раздел JSP.2.13.1), но правила применения кавычек - одинаковы.

JSP.2.3.6 Правильные Имена Акций и Атрибутов

Имена акций обязаны следовать соглашению XML (т.е. обязаны быть NMTOKEN, как указано в спецификации XML 1.0). Имена атрибутов обязаны следовать соглашениям, описанным в спецификации JavaBeans.
Имена атрибутов, начинающиеся с jsp, _jsp, java или sun зарезервированы данной спецификацией.

JSP.2.3.7 Пробелы

В HTML и XML пробел обычно не является значащим, но есть исключения. Например, файл XML может начинаться символами <?xml, и, если это так, ведущих пробельных символов не должно быть.

Данная спецификация следует поведению пробелов, определённому в спецификации XML.

Пробел в теле текста документа не является значащим, но сохраняется.


Далее идут два фрагмента JSP с ассоциированным выводом.
Обратите внимание, что директивы не генерируют никаких данных и применяются глобально к JSP-странице.

Таблица 2.1: Пример 1 - Ввод
N Строки Исходный Текст
1 <?xml version="1.0" ?>
2 <%@ page buffer="8kb" %>
3 Здесь - остальная часть документа.


Результат:

Таблица 2.2: Пример 1 - Вывод
N Строки Текст на Выходе
1 <?xml version="1.0" ?>
2  
3 Здесь - остальная часть документа.


Следующие две таблицы - другой пример ввода и вывода:


Таблица 2.3: Пример 2 - Ввод
N Строки Исходный Текст
1 <% response.setContentType("....");
2 что-нибудь... %><?xml version="1.0" ?>
3 <%@ page buffer="8kb" %>
4 Здесь - остальная часть документа.


Результат:

Таблица 2.4: Пример 2 - Вывод
N Строки Текст на Выходе
1 <?xml version="1.0" ?>
2  
4 Здесь - остальная часть документа.

JSP.2.4  Обработка Ошибок

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

JSP.2.4.1 Ошибки Процесса Времени Трансляции

Трансляция JSP-страницы-источника в соответствующий класс реализации JSP-страницы JSP-контейнером может производиться в любой момент между начальной публикацией JSP-страницы в JSP-контейнер и получением и обработкой запроса клиентом целевой JSP-страницы.

Если трансляция возникает до получения клиентского запроса целевой JSP-страницы, обработка ошибок и уведомление зависят от реализации и не рассматриваются в данной спецификации. Фатальные ошибки трансляции должны в результате приводить к невозможности выполнения последующих клиентских запросов на трансляцию целевой страницы с соответствующей спецификацией ошибки: для протоколов HTTP будет возвращаться код ошибки 500 (Server Error/Ошибка Сервера).

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

В процессе обработки запросов клиентов ошибки могут возникать в теле класса реализации JSP-страницы или в каком-либо другом коде (языка Java или других языков программирования реализации), вызываемом из тела класса реализации JSP-страницы.

Возникающие ошибки этапа прогона обрабатываются в реализации страницы, используя механизм исключений языка программирования Java для сообщения вызывающему(-им) о нарушениях.


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


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


Нарушающее java.lang.Throwable, описывающее появляющуюся ошибку, хранится в экземпляре javax.ServletRequest клиентского запроса, использующего метод setAttribute(), использующего имя "javax.servlet.jsp.jspException".

Имена, начинающиеся с префиксов "java" и "javax", зарезервированы различными спецификациями платформы Java. Префикс "javax.servlet" зарезервирован и используется спецификациями Servlet и JSP.

Если атрибут errorPage директивы страницы именует URL, который ссылается на другую JSP и та JSP сигнализирует, что на странице имеется ошибка (установкой атрибута isErrorPage директивы страницы в true), тогда неявная переменная языка программирования "exception" этой страницы инициализируется ссылкой Throwable-нарушителя.

JSP.2.5 Комментарии

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

JSP.2.5.1 Генерирование Комментариев при Выводе Клиенту

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

<!-- комментарии ... -->
 

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

<!-- комментарии <%= выражение %> ещё комментарии ... -->

JSP.2.5.2 Комментарии JSP

JSP-комментарий имеет форму:
 

<%-- что-либо, кроме закрывающих символов --%> ... --%>


Содержимое тела комментария полностью игнорируется. Комментарии используются для документирования, а также для "закомментирования" некоторой части JSP-страницы.

Обратите внимание, что JSP-комментарии не вкладываются.


Альтернативным способом размещения "комментария" на JSP-странице является использование механизма комментария языка скриптинга. Например:
 

<% /** это комментарий ... **/ %>

JSP.2.6 Соглашения по Кавычкам
и Escape-Последовательностям

В JSP-страницах применяются следующие соглашения по кавычкам:

Кавычки в Элементах Скриптинга
 

Литерал %> закавычивается %\>

Кавычки в Шаблонном Тексте


Литерал <% закавычивается <\%

Закавычивание Атрибутов


Закавычивание выполняется независимо от того, является значение атрибута литералом или выражением атрибута этапа запроса. Закавычивание может использоваться в значениях атрибутов независимо от того, ограничены они одинарными или двойными кавычками. Это выполняется только так, как описано ниже:

Примеры
 

В следующей строке показаны неправильные значения атрибутов:

В следующей строке дан верный скриптлет, но с, возможно, неожиданным результатом. Результат будет "Joe said %\>", а не "Joe said %>":


В следующих строках - правильное закавычивание:

Представление XML


Соглашения по кавычкам отличаются от соглашений XML. См. Главу JSP.5.

JSP.2.7 Общая Семантика Страницы JSP

Класс реализации JSP-страницыопределяет отображение метода _jspService() из объекта request в объект response. Некоторые детали этой трансформации специфичны для используемого языка скриптинга (см. Главу JSP.6). Некоторые детали не зависят от языка и описаны в данной главе.

Содержимое JSP-страницы большей частью описывает данные, которые записываются в поток вывода ответа. (JSP-контейнер обычно посылает эти данные обратно клиенту.) Это описание базируется на объекте JspWriter, который выводится через неявный объект out (см. Раздел JSP.2.8.3, "Неявные Объекты).

Его значение варьируется:

JSP.2.8 Объекты

JSP-страница может создавать и модифицировать серверные объекты/server-side и получать к ним доступ.

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

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

Элементы скриптинга могут получать доступ к объектам непосредственно через переменную скриптинга.

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

JSP.2.8.1 Объекты и Переменные

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


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

Тип элемента указывает имя и тип таких переменных, хотя в деталях имя переменной может зависеть от Языка Скриптинга.

Язык скриптинга может также влиять на то, как происходит доступ к различным свойствам объекта. Например, в спецификации JavaBeans доступ к свойствам осуществляется через методы getter и setter, в то время как эти свойства доступны напрямую как переменные в языке JavaScript≥.

Точные правила видимости переменных зависят от языка скриптинга. В Главе JSP.2.1 определены правила для случая, когда атрибут language директивы page установлен в "java".

JSP.2.8.2 Объекты и Область Видимости

JSP-страница может создавать и/или получать доступ к Java-объектам при обработке запроса. Спецификация JSP указывает, что некоторые объекты создаются неявно, возможно, как результат директивы (см. Раздел JSP.2.8.3, "Неявные Объекты"). Другие объекты создаются явно через акции или непосредственно путём использования кода скрипта. Созданные объекты имеют атрибут scope, определяющий, где находится ссылка на объект и когда эта ссылка удаляется.

Созданные объекты могут также непосредственно видимы элементам скриптинга через переменные уровня скриптинга (см. Раздел JSP.2.8.3, "Неявные Объекты"). Каждая акция и объявление определяют, как часть своей семантики, какой объект они создают, с каким атрибутом scope и доступны ли они элементам скриптинга.


Объекты создаются внутри экземпляра JSP-страницы, которая отвечает объекту request.

Имеется несколько областей видимости:

Имя/name должно ссылаться на уникальный объект из всех точек в ходе выполнения, то есть все области видимости должны в действительности вести себя как единое пространство имён. Реализация JSP-контейнера может или может не форсировать это правило явно по соображениям производительности.

JSP.2.8.3 Неявные/Implicit Объекты

Авторы JSP-страниц имеют доступ к определённым неявным (неявно создаваемым) объектам, которые всегда доступны для использования в скриптлетах и выражениях через переменные скриптинга, которые объявляются неявно в начале страницы. Все языки скриптинга должны предоставлять доступ к этим объектам.

Неявные объекты доступны обработчикам тэгов через объект pageContext (см. ниже).

Каждый неявный объект имеет тип класса или интерфейса, определённый в основной технологии Java или в пакете Java Servlet API, как показано в Таблице JSP. 2-1.


Таблица JSP.2-1 Неявные Объекты, Доступные в JSP-страницах
Имя Переменной Тип Семантика & Области Видимости
request подтип, зависящий от протокола: javax.servlet.ServletRequest,
например:
javax.servlet.http.HttpServletRequest
Запрос, включающий вызов сервиса/службы.
Область видимости: request.
response подтип, зависящий от протокола: javax.servlet.ServletResponse,
например:
javax.servlet.http.HttpServletResponse
Ответ на запрос.
Область видимости: page.
pageContext javax.servlet.jsp.PageContext Контекст страницы для данной JSP-страницы.
Область видимости: page.
session javax.servlet.http.HttpSession Объект session, созданный для запрашивающего клиента (если клиент имеется).
Эта переменная верна только для протоколов Http.
Область видимости: session.
application javax.servlet.ServletContext Контекст сервлета, полученный из объекта конфигурации сервлета (как при вызове
getServletConfig().getContext())
Область видимости: application.
out javax.servlet.jsp.JspWriter Объект, записывающий в поток вывода.
Область видимости: page.
config javax.servlet.ServletConfig ServletConfig для данной JSP-страницы.
Область видимости: page.
page java.lang.Object Экземпляр класса реализации данной страницы, обрабатывающий текущий запрос.
Область видимости: page.

a. Если язык скриптинга - "java", тогда "page" является синонимом для "this" в теле/body страницы.
Кроме того, может быть получен доступ к неявному объекту exception на странице ошибок, как указано в Таблице JSP.2-2.

JSP.2.8.4 Объект pageContext

PageContext это объект, предоставляющий контекст для хранения ссылок на объекты, используемые страницей. Он инкапсулирует зависящие от реализации свойства и предоставляет нужные методы. Класс реализации JSP-страницы может использовать PageContext для прогона в неизменённом виде в любом подходящем JSP-контейнере, одновременно используя преимущества специфичных для реализации улучшений типа высокопроизводительного JspWriters. См. детали в Главе JSP.9.

Таблица JSP.2-2 Неявные Объекты, Доступные на Страницах Ошибок\Error Pages
Имя Переменной Тип Семантика & Область Видимости

exception

java.lang.Throwable Неотловленный Throwable, приводящий к вызову страницы информации об ошибках.
Область видимости: page.

Имена объектов с префиксами jsp, _jsp, jspx и _jspx, в любой комбинации нижнего и верхнего регистров, зарезервированы данной спецификацией JSP. См. в Разделе JSP.7.6.1 некоторые ненормативные соглашения для введения новых неявных объектов.

JSP.2.9 Семантика Шаблонного Текста

Семантика шаблонного (или неинтерпретированного) Текста очень проста: шаблонный текст передаётся текущему out\выводящему неявному объекту JspWriter после применения замен Раздела JSP.2.6, "Соглашения по Кавычкам и Escape-Последовательностям".

JSP.2.10 Директивы

Директивы являются сообщениями JSP-контейнеру.

Синтаксис директивы:


<%@ директива { атрибут="значение" }* %>


Могут иметься необязательные пробелы после "<%@" и перед "%>". Это синтаксис легко вводится и понятен, но он несовместим с XML. В Главе JSP.5 описано отображение директив в элементы XML.

Директивы не производят никакого вывода в текущий поток out. Есть три директивы: page и taglib описаны здесь, а директива include - в следующей главе.

JSP.2.10.1 Директива page

Директива page определяет количество свойств страницы и сообщает о них JSP-контейнеру.

Трансляционный модуль (JSP файл-источник и любые файлы, включённые директивой include) может содержать более одного экземпляра директивы page, все атрибуты будут применяться ко всему трансляционному модулю (т.е. директивы page не зависят от позиции). Однако должно быть только одно вхождение любого атрибута/значения, определённого этой директивой, в данном трансляционном модуле, исключая атрибут "import"; многократные использования этого атрибута накапливаются (с семантикой объединения упорядоченного набора/ordered set union). Другие такие множественные (пере)определения атрибута/значения приводят к фатальной ошибке трансляции. Пространство имён attribute/value зарезервировано для использования данной и последующими спецификациями JSP.

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

Примеры


Следующая директива предоставляет некоторую видимую пользователем информацию на данной JSP-странице:
 

<%@ page info="my latest JSP Example" %>
 

Следующая директива запрашивает отсутствие буферизации, указывает, что страница является "безопасным потоком"/thread safe и предоставляет страницу для сообщений об ошибке:
 

<%@ page buffer="none" isThreadSafe="yes" errorPage="/oops.jsp" %>
 

Следующая директива указывает, что язык скриптинга базируется на Java, что типы, объявленные в пакете com.myco, непосредственно доступны коду скриптинга и что должна использоваться буферизация в 16KB:
 

<%@ page language="java" import="com.myco.*" buffer="16kb" %>

Синтаксис
 

<%@ page список_атрибутов_директивы_page %>
 

список_атрибутов_директивы_page ::= { language="scriptingLanguage\языкСкриптинга"}

{ extends="className"}
{ import="importList"}
{ session="true|false" }
{ buffer="none|sizekb" }
{ autoFlush="true|false" }
{ isThreadSafe="true|false" }
{ info="info_text" }
{ errorPage="error_url" }
{ isErrorPage="true|false" }
{ contentType="ctinfo" }
{ pageEncoding="peinfo"

Далее дана детальная информация об атрибутах:

Таблица JSP.2-1
Атрибут Описание
language Определяет язык скриптинга, используемый в скриптлетах, скриптлетах выражений и объявлениях внутри тела трансляционного модуля (JSP-страница любые файлы, включённые с использованием последующей директивы include). В JSP 1.2 единственным определённым и необходимым для данного атрибута значением языка скриптинга является "java". Данная спецификация описывает семантику только для скриптов со значением атрибута языка "java". Если "java" является значением языка скриптинга, фрагменты исходного кода Java Programming Language, используемые внутри данного трансляционного модуля, должны соответствовать спецификации Java Programming Language Specification так, как описано в Главе JSP.6.
Все языки скриптинга обязаны предоставлять неявные объекты, которые автор JSP-страниц может использовать в объявлениях, скриптлетах и выражениях. Специфические объекты, которые могут использоваться, определены в Разделе JSP.2.8.3, "Неявные Объекты."
Все языки скриптинга обязаны поддерживать Java Runtime Environment (JRE)/Среду Java. Все языки скриптинга обязаны представлять объектную модель технологии Java окружению скрипта, особенно неявные переменные, свойства компонентов JavaBeans и публичные методы. Будущие версии спецификации JSP могут определять дополнительные значения атрибута language, и все такие значения резервируются.
Для директивы с атрибутом language не-"java" будет фатальной ошибкой появление после первого вычисленного элемента скриптинга.
extends Значением является полное квалифицированное имя класса языка программирования Java, которое именует суперкласс класса, к которому JSP-страница трансформируется (см. Главу JSP.8). Этот атрибут не должен использоваться без тщательного учёта ограничения им способности JSP-контейнера предоставлять специализированные суперклассы, которые могут улучшить качество службы представления. См. в Разделе JSP.7.6.1 альтернативный способ ввода объектов на JSP-страницу, не имеющий такого недостатка.
import Атрибут import описывает типы, которые доступны среде скриптинга. Значение - такое же, как для объявления import в языке программирования Java, т.е. список (разделённых запятыми) полных квалифицированных имён типов языка программирования Java, обозначающих этот тип, или имя пакета с последующей строкой ".*", обозначающей все публичные типы, объявленные в этом пакете. Список import должен будет импортироваться транслируемой реализацией транслируемой JSP-страницы и будет, таким образом, доступен среде скриптинга.
По умолчанию список импорта - java.lang.*, javax.servlet.*, javax.servlet.jsp.* и javax.servlet.http.*. В настоящее время это значение определено только тогда, когда значением директивы language является "java".
session Означает, что данная страница требует участия в (http) сессии. Если "true", тогда неявная переменная языка скрипта с названием "session" типа javax.servlet.http.HttpSession ссылается на текущую/новую сессию для этой страницы. Если "false" - тогда эта страница не участвует в сессии; неявная переменная "session" недоступна, и любая ссылка на неё в теле JSP-страницы является недопустимой и приводит к фатальной ошибке трансляции. По умолчанию "true".
buffer Специфицирует модель буферизации для начального "out" JspWriter для обработки содержимого вывода с этой страницы. Если "none", тогда буферизации нет и весь вывод записывается непосредственно в ServletResponse PrintWriter. Размер может специфицироваться только в килобайтах, и суффикс "kb" является мандатным (обязательным). Если размер буфера специфицирован, тогда вывод буферизуется с размером буфера не меньше специфицированного. В зависимости от значения атрибута "autoFlush", содержимое этого буфера автоматически очищается, или возникает исключение при появлении переполнения. По умолчанию буферизуется с размером буфера реализации не менее 8kb.
autoFlush Специфицирует, должен ли буферизованный вывод очищаться автоматически (значение "true"), когда буфер заполнен, или должно вызываться исключение/exception (значение "false"), означающее переполнение буфера.
По умолчанию "true".
Примечание: не допускается установка autoFlush в "false", если "buffer=none".
isThreadSafe Обозначает уровень потока, безопасно выполняемого на странице. Если "false" - тогда JSP-контейнер должен выполнять диспетчеризацию множественных внешних запросов клиентов, по одному за раз в порядке их поступления, реализации страницы для процессинга. Если "true", тогда JSP-контейнер может избрать одновременное направление странице  множественных внешних запросов клиентов. Авторы страниц, использующие "true", должны быть уверены, что осуществляется соответствующая синхронизация доступа к странице.
По умолчанию "true".
Заметьте, что, даже если атрибут isThreadSafe имеет значение "false", автор JSP-страницы должен иметь уверенность, что доступы к любым объектам раздельного использования/shared соответствующим образом синхронизированы. Объекты могут использоваться раздельно в ServletContext или в HttpSession.
info Определяет произвольную строку, которая внедряется в транслируемую страницу, которая затем может быть получена из реализации страницы методом Servlet.getServletInfo().
isErrorPage Указывает, предназначена ли текущая JSP-страница служить целевым URL для другой JSP-страницы как errorPage. Если "true", тогда неявная переменная языка скриптинга "exception" определяется и её значением является ссылка на нарушающий Throwable из исходной JSP-страницы, в случае ошибки.
Если "false" - неявная переменная "exception" недоступна, и любая ссылка на неё в теле JSP-страницы является недопустимой и приведёт к фатальной ошибке трансляции.
По умолчанию "false".
errorPage Определяет URL ресурса, которому любой объект(ы) Throwable языка программирования Java, вызываемый, но не отлавливаемый реализацией страницы, направляется для обработки ошибки. Спецификация предоставляемого URL выполняется так, как указано в Разделе JSP.2.2.1. Если URL именует другую JSP-страницу, тогда неявная переменная скрипта вызываемого исключения этой JSP-страницы содержит ссылку на начальный неотловленый Throwable. URL по умолчанию зависит от реализации.
Обратите внимание, что объект Throwable передаётся реализацией страницы, вызывающей исключение/throwing, реализации страницы ошибки, сохраняя ссылку на объект в обычном объекте ServletRequest путём использования метода setAttribute(), с именем "javax.servlet.jsp.jspException".
Примечание: если autoFlush=true, то, если содержимое начального Jsp-Writer было очищено для потока вывода ServletResponse, любая последующая попытка диспетчеризации неотловленного исключения из страницы-нарушителя странице errorPage может потерпеть неудачу. Если страница обработки ошибок указана также в дескрипторе web.xml, то сначала применяется JSP-страница обработки ошибок, а затем страница web.xml.
contentType

Определяет кодировку символов для JSP-страницы и для JSP-страницы - ответа и тип MIME для JSP-страницы - ответа. Значения могут иметь форму "TYPE" или "TYPE; charset=CHARSET" с необязательным пробелом после ";".
CHARSET, если имеется, обязан быть значением IANA для кодировки символов.
TYPE это MIME-тип: см. в регистре IANA используемые значения.
Для TYPE значение по умолчанию - "text/html"; значение по умолчанию для кодировки символов - ISO-8859-1.
См. в Главе 3 детальную информацию о кодировках символов.

pageEncoding Определяет кодировку символов для JSP-страницы. Значения имеют форму "CHARSET", который обязан быть IANA-значением для кодировки символов. Значение contentType для CHARSET используется по умолчанию, если имеется, в противном случае - ISO-8859-1. См. в Главе 3 детальную информацию о кодировках символов.

JSP.2.10.2 Директива taglib

Набор значащих тэгов, интерпретируемых JSP-контейнером, может быть расширен "tag library/библиотекой тэгов". Директива taglib на JSP-странице объявляет, что данная страница использует библиотеку тэгов, уникально идентифицирует библиотеку тэгов, используя URI, и ассоциирует префикс тэгов, который служит для отличения использования акций в этой библиотеке. Если реализация JSP-контейнера не может локализовать описание библиотеки тэгов, должна возникать фатальная ошибка трансляции. Фатальная ошибка трансляции возникнет также, если директива taglib появится после акций, использующих данный префикс.

Библиотека тэгов может включать метод проверки корректности использования JSP-страницей функциональности библиотеки тэгов. См. более конкретные детали в Главе JSP.7. Также см. замечания по реализации в Разделе JSP.7.2.3.

Примеры


В следующем примере библиотека тэгов вводится и становится доступной данной странице путём использования префикса super; никакие другие библиотеки тэгов не должны вводиться на данной странице, используя этот префикс. В данном конкретном случае мы принимаем, что библиотека тэгов включает тип элемента doMagic, который используется на странице.
 

<%@ taglib uri="http://www.mycorp/supertags" prefix="super" />

...

<super:doMagic>

...

</super:doMagic>

Синтаксис


<%@ taglib uri="tagLibraryURI" prefix="tagPrefix" %>
 

где атрибуты:
 

Таблица JSP.2-1
uri Спецификация абсолютного или относительного URI, который уникально идентифицирует дескриптор библиотеки тэгов, ассоциированной с данным префиксом.
URI используется для локализации описания библиотеки тэгов, как указано в Главе 7.
tagPrefix Определяет строку prefix в конструкции <prefix>:<tagname>, которая используется для отличения специальной акции, например, <myPrefix:myTag>.
Использование префиксов, начинающихся с jsp:, jspx:, java:, javax:, servlet:, sun: и sunw:, зарезервировано.
Префикс обязан следовать соглашению об именовании, специфицированному в спецификации пространств имён XML.
Пустые префиксы в данной версии спецификации не допускаются.

Фатальная ошибка трансляции возникнет, если транслятор JSP-страницы обнаруживает тэг с именем prefix: Name, использующий префикс, введённый директивой taglib, и если Name не распознаётся соответствующей библиотекой тэгов.

JSP.2.10.3 Директива include

Директива include используется для подстановки текста и/или кода в JSP-страницу на этапе трансляции.

Директива <%@ include file="спецификация относительного URL" %> вставляет текст специфицированного ресурса в .jsp-файл. Включённый файл является субъектом контроля доступа, доступного JSP-контейнеру. Атрибут file рассматривается в Разделе JSP.2.2.1. JSP-контейнер может включать механизм уведомления в случае изменения включённого файла, чтобы контейнер мог перекомпилировать эту JSP-страницу, однако спецификация JSP 1.2 не содержит способа указания JSP-контейнеру, что включённые файлы должны изменяться.

Примеры
 

В следующем примере запрашивается включение на этапе трансляции файла авторских прав/copyright.
Этот файл может содержать элементы, которые также будут обрабатываться:
 

<%@ include file="copyright.html" %>

Синтаксис
 

<%@ include file="спецификация относительного URL" %>

JSP.2.10.4 Включение Данных в Страницы JSP

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

Таблица JSP.2-1 Обобщение Механизмов include в спецификации JSP 1.2
1
Синтаксис Спецификация Объект Описание
Директива include - Время Трансляции
<%@ include file=... %> относительно файла статический/static Содержимое разбирается/parsed JSP-контейнером. JSP.2.10.3
Акция include - Время Запроса
<jsp:include page= /> относительно страницы статический и динамический Содержимое не разбирается; оно вставляется в этом месте. JSP.4.4

Колонка Спецификация описывает, какой тип спецификации является верным для данного элемента. Данная спецификация JSP требует специфицировать относительный URL. Ссылка разрешается сервером web/приложений, и выполняется отображение её URL. Директивы include интерпретируются относительно текущего JSP-файла; акции jsp:include интерпретируются относительно текущей JSP-страницы. Директива include относится к ресурсу вроде JSP-страницы как к статичному/static объекту; т.е. байты в JSP-странице включаются. Акция include относится к ресурсу вроде JSP-страницы как к динамическому/dynamic объекту; т.е. запрос направляется этому объекту, и результат процессинга включается .

JSP.2.11 Элементы Скриптинга/Сценариев

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

Есть три класса элементов скриптинга: declarations\объявления, scriptlets\скриптлеты и expressions\выражения. Язык скриптинга, используемый на данной странице, задаётся значением директивы language (см. Раздел JSP.2.10.1, "Директива page"). В JSP 1.2 единственным определённым значением является "java".

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

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

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

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

Все такие языки скриптинга обязаны поддерживать:

Точное определение семантики скриптинга, выполняемого с использованием элементов на базе языка Java, дано в Главе JSP.6.

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

Каждый элемент скриптинга имеет следующий синтаксис на базе "<%":
 

<%! это объявление %>
 

<% это скриптлет %>
 

<%= это выражение %>
 

Могут иметься необязательные пробелы после "<%!", "<%" и "<%=" и до "%>".


Эквивалентные данным элементам скриптинга элементы XML описаны в Разделе JSP.5.2.

JSP.2.11.1 Объявления

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

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

Примеры


Например, первое объявление здесь объявляет целое число, глобальное в пределах страницы.

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

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

<%! int i; %>
 

<%! int i = 0; %>
 

<%! public String f(int i) { if (i<3) return("..."); ... } %>

Синтаксис
 

<%! объявление(-я) %>

JSP.2.11.2 Скриптлеты

Скриптлеты могут содержать любые фрагменты кода, которые являются верными для языка скриптинга, специфицированного директивой language. Является ли фрагмент кода действующим, зависит от деталей языка скриптинга (см. Главу JSP.6).

Скриптлеты выполняются во время обработки запроса. Производят они вывод в поток вывода или нет, зависит от кода скриптлета.

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

Чтобы использовать последовательность символов %> как литеральные символы в скриптлете, вместо того , чтобы они оканчивали скриптлет, вводите их так %\>.

Примеры


Вот простой пример динамического изменения страницы, в зависимости от времени суток.
 

<% if (Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM) {%>
Good Morning
<% } else { %>
Good Afternoon
<% } %>
 

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


<% int i; i= 0; %>
Привет, значение i равно <% i++ %>

Синтаксис


<% скриптлет %>

JSP.2.11.3 Выражения

Элемент expression в JSP-странице является выражением языка скриптинга, которое вычисляется, а результат приводится к String. Результат затем посылается в текущий объект вывода JspWriter. Если результат выражения не может быть приведён к String, обязаны выполняться следующие действия:

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

Если приведение не обнаруживается в процессе трансляции, должно вызываться исключение ClassCastException/ОшибкаПриведенияКласса во время запроса.

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

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

Выражения вычисляются во время HTTP-процессинга.

Значение выражения конвертируется к String и вставляется в соответствующую позицию в .jsp-файл.

Примеры


Вставляется текущая дата:


<%= (new java.util.Date()).toLocaleString() %>

Синтаксис


<%= выражение %>

JSP.2.12 Акции

Акции могут воздействовать на текущий поток вывода и использовать, модифицировать и/или создавать объекты. Акции могут зависеть от деталей конкретного объекта request/запроса, получаемого JSP-страницей.
Данная спецификация JSP содержит некоторые акции, которые являются стандартными и обязаны реализовываться всеми соответствующими JSP-контейнерами; эти акции описываются в Главе 4.

Новые акции определяются в соответствии с механизмами, описанными в Главах 7 и 10, и вводятся с использованием директивы taglib.

Синтаксис элементов акций базируется на XML. Акции могут быть пустыми и непустыми.

JSP.2.13 Семантика Интерпретации Атрибута Тэга

Интерпретация всех акций начинается с вычисления значений, данных их атрибутам, слева направо и присвоения этих значений атрибутам. В этом процессе могут производиться конверсии; правила конверсии описаны в Разделе JSP.2.13.2.

Многие значения являются фиксированными 'значениями времени трансляции', но JSP 1.2 предоставляет также механизм описания этих значений, когда они вычисляются на этапе запроса, правила описаны в Разделе JSP.2.13.1.

JSP.2.13.1 Значения Атрибутов Времени Запроса

Значение атрибута в форме "<%= scriptlet_expr %>" или '<%= scriptlet_expr %>' обозначает значение атрибута времени запроса. Указываемое значение является значением включаемого скриптлета. Значения атрибутов времени запроса могут использоваться только в акциях и не могут использоваться в директивах. Если в тэге имеется более одного такого атрибута, выражения вычисляются слева направо.

Закавычивание выполняется так же, как и в других значениях атрибута (Раздел JSP.2.6). Таким способом могут обозначаться только значения атрибута (имя атрибута всегда является явно определённым именем).

Выражение обязано появляться само по себе (множественные выражений и смешивание выражений и строковых констант не допускаются).

Множественные операции обязаны выполняться внутри выражения.

Конверсия типов описана в Разделе JSP.2.13.2. По умолчанию все атрибуты имеют семантику времени трансляции страницы. Попытка специфицировать выражение скриптлета как значение атрибута, который (по умолчанию или нет) имеет семантику времени трансляции, является недопустимой и приводит к фатальной ошибке трансляции.

Тип элемента action указывает, будет ли данный атрибут принимать значения атрибута времени запроса.

Большинство атрибутов стандартных акций из Главы 4 имеют семантику времени трансляции страницы, но следующие атрибуты принимают выражения атрибутов времени запроса:

JSP.2.13.2 Соглашения о Типах

Мы описываем два случая конверсии типов:

JSP.2.13.2.1 Конверсия из Значений String


Значение строки может использоваться для описания значения типа не-String через конверсию. Возможна ли конверсия и, если да, какая она, зависит от типа назначения.


Значения String могут использоваться для присвоения значений типу, который имеет класс PropertyEditor, как указано в спецификации JavaBeans. Если это именно тот случай, используется метод setAs-Text(String).

Конверсия терпит неудачу, если метод вызывает исключение IllegalArgumentException.


Значения String могут также использоваться для присвоения типов, как указано в Таблице JSP.2-2. Применяется так конверсия, которая указана в таблице. Неудача конверсии ведёт к ошибке времени трансляции или времени запроса.

Таблица JSP.2-2 Конверсия из Строковых Значений в Тип Назначения
Тип Назначения Исходное Строковое Значение
Свойство Bean Использовать setAsText(string-literal)
boolean или Boolean Как указано в java.lang.Boolean.valueOf(String)
byte или Byte Как указано в java.lang.Byte.valueOf(String)
char или Character Как указано в String.charAt(0)
double или Double Как указано в java.lang.Double.valueOf(String)
int или Integer Как указано в java.lang.Integer.valueOf(String)
float или Float Как указано в java.lang.Float.valueOf(String)
long или Long Как указано в java.lang.Long.valueOf(String)
short или Short Как указано в java.lang.Short.valueOf(String)
Object Как если бы new String(string-literal)

Эти конверсии являются частью общего механизма, используемого для присвоения значений атрибутам акций: когда значение атрибута, который не является атрибутом времени запроса, присваивается данному атрибуту, используется описанная здесь конверсия, использующая тип атрибута как целевой тип. Тип каждого атрибута стандартных акций описан в данной спецификации, а типы атрибутов специальных/custom акций описаны в ассоциированном с ними Дескрипторе Библиотеки Тэгов/Tag Library Descriptor.

Конкретная акция может также определять дополнительные способы использования конверсии типа/значения.

В Разделе JSP.4.2 описан механизм, используемый для стандартной акции setProperty.

JSP.2.13.2.3 Конверсия из Выражений Времени Запроса


Выражения времени запроса могут назначаться свойству любого типа.

Автоматическая конверсия не выполняется.


Глава JSP.3

Вопросы Локализации


В этой Главе описаны требования по локализации в JavaServer Pages 1.2 (JSP 1.2).

JSP.3.1 Кодировка Символов Страницы

Поддержка платформой Java локализованного содержимого базируется на универсальном внутреннем представлении текста как символов Unicode 2.0 (ISO010646) и поддержке нескольких кодировок символов в Unicode.

Java Virtual Machine (JVM)/Виртуальная Машина Java обязана поддерживать кодировки Unicode и Latin-1, но большинство машин поддерживают гораздо больше кодировок. Кодировки символов, поддерживаемые JVM от Sun, описаны по адресу: http://java.sun.com/products/jdk/1.1/docs/guide/intl/encoding.doc.html


JSP-страница использует кодировку символов. Кодировка может быть описана явно атрибутом pageEncoding директивы page . По умолчанию кодировка выполняется по атрибуту contentType директивы page , если она имеется, или, в противном случае, устанавливается ISO-8859-1. ISO-8859-1 известна также как Latin-1.


Верные имена кодировок символов в JSP 1.2 - те же, что и имена IANA. Они описаны по адресу:

 

ftp://venera.isi.edu/in-notes/iana/assignments/character-sets
 

Атрибут pageEncoding должен использоваться только тогда, когда кодировка символов JSP-страницы организована так, что символы ASCII отображают сами себя. Директива, содержащая атрибут pageEncoding, должна появляться на JSP-странице как можно раньше.


JSP-контейнер может использовать какую-нибудь зависящую от реализации эвристику и/или структуру для определения ожидаемой кодировки JSP-страницы и проверки соответствия атрибута contentType.


JSP-контейнер вызовет ошибку времени трансляции, если запрошена неподдерживаемая кодировка символов.

JSP.3.2 Статический Тип Содержимого

Большинство JSP-страниц написаны так, чтобы отправлять ответ, используя специфические тип содержимого/content type и кодировку символов. JSP-страница может использовать атрибут contentType директивы page для обозначения типа содержимого, предоставляемого в ответ на запросы. Если используется таким образом, данная страница будет всегда предоставлять содержимое одного и того же типа. Если страница определяет, что ответ должен иметь другой тип содержимого, она должна делать это "раньше", определяя, какая иная JSP-страница или сервлет будет обрабатывать этот запрос, и направлять запрос другой JSP-странице или сервлету. Значение TYPE по умолчанию "text/html", а значение по умолчанию для кодировки символов - ISO-8859-1. Регистр имён типов содержимого хранится в IANA.

См.: ftp://venera.isi.edu/in-notes/iana/assignments/media-types/media-types

Атрибут contentType обязан использоваться только в том случае, если кодировка символов организована так, что символы ASCII отображают сами себя, как минимум до тех пор, пока атрибут contentType не будет найден. Директива, содержащая атрибут contentType, должна появляться на JSP-странице как можно раньше.

JSP.3.3 Динамический Тип Содержимого

Некоторые JSP-страницы созданы так, что они могут направлять содержимое, используя различные типы содержимого и кодировки символов, в зависимости от ввода времени запроса. Эти страницы могут быть организованы как специальные акции или скриптлеты, которые определяют тип содержимого ответа и предоставляют 'связку' с другим кодом, реально генерирующим содержимое ответа.

Динамическая установка типа содержимого основана на вызове response.setcontentType(). Этот метод может быть вызван, пока никакого содержимого не было выслано в поток ответа. Данные высылаются в поток ответа при очистках буфера буферизованных страниц или при обнаружении первого содержимого (избегая пробелов) небуферизованных страниц.


Пробел в страницах JSP вводится известным трюком синтаксиса JSP, но более управляем в  JSP-страницах с синтаксисом XML.

JSP.3.4 Передача Локализованного Содержимого

Спецификация JSP не предписывает определённого подхода к структурированию локализованного содержимого, поэтому возможны различные подходы.

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


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


Глава JSP.4

Стандартные Акции


В этой главе описаны стандартные акции JavaServer Pages 1.2 (JSP 1.2).

JSP.4.1 <jsp:useBean>

Акция jsp:useBean ассоциирует экземпляр объекта языка программирования Java, определённый в данной области видимости/scope и доступный с данным id через вновь объявленную переменную скриптинга с тем же id.

Акция jsp:useBean весьма гибка: её точная семантика зависит от заданных атрибутов. Базовая семантика пытается найти существующий объект, используя id и область видимости. Если объект не найден, будет сделана попытка создания этого объекта с использованием других атрибутов.

Можно использовать эту акцию также для задания локального имени объекту, определённому в другом месте, например, в другой JSP-странице или Сервлете. Это может быть выполнено с помощью атрибута типа без предоставления атрибутов class или beanName. Должен быть представлен как минимум тип или класс, и неверным будет предоставление и class, и beanName. Если тип и класс имеются, class обязан быть назначен типу (в понимании Java-платформы). Невозможность его назначить является ошибкой времени трансляции.

Атрибут beanName специфицирует имя Bean'а, как указано в спецификации JavaBeans. Оно используется в качестве аргумента для метода instantiate() класса java.beans.Beans. Оно обязано иметь форму "a.b.c" и может быть именем класса или ресурса в форме "a/b/c.ser", которое будет разрешено в текущем ClassLoader/ЗагрузчикеКлассов. Если это не так, будет вызвано исключение времени запроса, как указано в семантике instantiate(). Значением этого атрибута может быть выражение атрибута времени запроса.

Более детально о роли id и scope говорится далее.

Атрибут id

Пара атрибут/значение id="имя" является элементом jsp:useBean и имеет специальное значение для JSP-контейнера во время трансляции страницы при обработке запроса клиента.

Конкретно:

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


Заметьте, что это подразумевает, что синтаксис значения name обязан соответствовать синтаксическим правилам именования переменных языка скриптинга, используемого на этой странице.

В Главе JSP.6 детально рассматривается случай, когда атрибут language - "java".

Пример использования правил правил области видимости, только что упомянутых, дан здесь:
 

<% { // вводится новый блок %>

...

<jsp:useBean id="customer" class="com.myco.Customer" />

<%

/*

* тэг создаёт или получает ссылку на Customer Bean,

* ассоциирует её с именем "customer"

* в PageContext и объявляет переменную языка программирования Java

* с тем же именем, которое инициализировано для ссылки на объект

* в пределах видимости этого блока.

*/

%>

...

<%= customer.getName(); %>

...

<% } // закрывает блок %>

<%

// переменная customer находится сейчас вне области видимости ,

// но объект всё ещё действует (и доступ к нему осуществляется через PageContext)

%>

Атрибут   scope

Пара атрибут/значение scope="page|request|session|application" ассоциирована с (и модифицирует) поведением атрибута id, описанного выше (она (пара) имеет семантику и времени трансляции, и времени процессинга запроса клиента).

Конкретнее, она описывает пространство имён, предполагаемый жизненный цикл ссылки на объект, ассоциированной с name, и API, используемые для доступа к этой ассоциации, таким образом:

Таблица JSP.4-1
page Именованный объект, доступный из javax.Servlet.jsp.PageContext для данной страницы.
Эта ссылка должна быть уничтожена после выполнения текущего запроса телом страницы.
Не допускается изменение объекта экземпляра, ассоциированного таким образом, что его (объекта?) тип времени прогона/выполнения является поднабором типа текущего объекта, ассоциированного ранее.
request Именованный объект, доступный из объекта ServletRequest текущей страницы через использование метода getAttribute(name).
Эта ссылка должна быть уничтожена после выполнения текущего клиентского запроса.
Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, что его (объекта?) тип времени прогона/выполнения является поднабором(-ами) типа объекта, ассоциированного ранее таким же образом.
session Именованный объект, доступный из объекта HttpSession текущей страницы (который, в свою очередь, может быть получен из объекта ServletRequest) через использование методаgetAttribute(name).
Эта ссылка должна быть уничтожена после аннулирования текущей сессии.
Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, чтобы его новый тип времени прогона был поднабором(-ами) типа объекта, ассоциированного ранее.
Заметьте, что будет фатальной ошибкой трансляции попытка использовать область видимости сессии, когда JSP-страница, делающая эту попытку, объявляется через директиву <%@ page ... %> (см. далее) так, что она не участвует в сессии.
application Именованный объект, доступный из объекта ServletContext текущей страницы через использование метода getAttribute(name).
Эта ссылка должна быть уничтожена после использования ServletContext.
Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, чтобы его новый тип времени прогона был поднабором(-ами) типа объекта, ассоциированного ранее таким же образом.
Семантика


Акциями, выполняемыми в jsp:useBean, являются:

  1. Попытка локализовать объект на базе значениях атрибутов id и scope. Синхронно выполняется проверка пространства имён области видимости/scope для исключения недетерминистического поведения.
    Переменная языка скриптинга специфицированного типа (если задан) или class/класс (если type не задан) определяется с данным id в текущей лексической области видимости языка скриптинга.
  2. Если этот объект найден, значение переменной инициализируется ссылкой на локализованный объект, приведённый к специфицированному типу. Если приведение терпит неудачу, должно возникать исключение java.lang.ClassCastException . Это завершает работу данной акции jsp:useBean.
  3. Если элемент jsp:useBean имел непустое тело/body, он игнорируется. Это завершает работу данной акции jsp:useBean.
  4. Если объект не найден в специфицированной области видимости и не заданы ни class, ни beanName, должно возникать исключение java.lang.InstantiationException. Это завершает работу данной акции jsp:useBean.
  5. Если объект не найден в специфицированной области видимости и класс/class специфицировал имена неабстрактного класса, который определяет публичный/public безаргументный конструктор, тогда создаётся экземпляр этого класса.
    Ссылка на новый объект ассоциируется с переменной скриптинга и со специфицированным именем в специфицированной области видимости через использование подходящей области видимости, в зависимости от механизма ассоциирования (см. PageContext). После этого выполняется шаг 7.
    Если объект не найден и класс является абстрактным классом, интерфейсом или не определён public безаргументный/no-args конструктор, тогда должно возникать исключение java.lang.InstantiationException. Это завершает работу данной акции jsp:useBean.
  6. Если объект не найден в специфицированной области видимости и задано имя beanName, тогда метод instantiate() класса java.beans.Beans будет вызван с Class-Loader/Загрузчиком-Классов объекта Servlet и с beanName в качестве аргументов.
    Если метод выполнен успешно, новая ссылка на объект ассоциируется с переменной скриптинга и со специфицированным именем в специфицированной области видимости через использование подходящей области видимости, в зависимости от механизма ассоциирования (см. PageContext). После этого выполняется шаг 7.
  7. Если элемент jsp:useBean имеет непустое тело/body, оно обрабатывается, переменная инициализируется и становится доступной в области видимости тела. Текст внутри тела рассматривается как обычно. Любой шаблонный текст будет передан в поток вывода. Тэги скриптлетов и акций вычисляются.
    Обычно непустое тело используется для завершения инициализации созданного экземпляра. В этом случае тело, вероятно, будет содержать акции jsp:setProperty и скриптлеты, которые вычисляются. Это завершает работу данной акции jsp:useBean.
Примеры


В этом примере Bean с именем "connection" и типом "com.myco.myapp.Connection" доступен после выполнения акций в этом элементе, или потому что он уже создан и найден, или потому что он создан заново.
 

<jsp:useBean id="connection" class="com.myco.myapp.Connection" />
 

В следующем примере свойство timeout устанавливается в 33, если Bean был инстанциирован.
 

<jsp:useBean id="connection" class="com.myco.myapp.Connection">
      <jsp:setProperty name="connection" property="timeout" value="33">
</jsp:useBean
>
 

В последнем примере объект должен существовать в данной сессии. Если это так, ему присваивается локальное имя wombat типа WombatType. Может возникать исключение ClassCastException, если это объект неверного класса, а InstantiationException может возникать, если объект не определён.
 

<jsp:useBean id="wombat" type="my.WombatType" scope="session"/>

Синтаксис


Эта акция может иметь или не иметь тело/body. Если акция не имеет тела, она имеет форму:
 

<jsp:useBean id="name" scope="page|request|session|application" typeSpec />

typeSpec ::= class="className" |
class="className" type="typeName" |
type="typeName" class="className" |
beanName="beanName" type="typeName" |
type="typeName" beanName="beanName" |
type="typeName"

Если акция имеет тело, она имеет форму:
 

<jsp:useBean id="name" scope="page|request|session|application" typeSpec >
     body
</jsp:useBean>
 

В этом случае тело тело будет вызвано, если Bean, обозначаемый этой акцией, создаётся. Обычно body будет содержать тэги скриптлетов или jsp:setProperty, которые будут использоваться для модификации вновь созданного объекта, но содержимое тела не ограничивается.

Тэг <jsp:useBean> имеет следующие атрибуты:

Таблица JSP.4-1
id Имя, используемое для идентификации экземпляра объекта в пространстве имён специфицированной области видимости, а также имя переменной скриптинга, объявленное и инициализированное вместе со ссылкой на этот объект.
Специфицированное пространство имён чувствительно к регистру и должно соответствовать соглашениям текущего языка скриптинга по именованию переменных.
scope Область видимости/scope, в зоне которой ссылка доступна. Значение по умолчанию - page.
См. описание атрибута scope, определённого ранее здесь же.
class Полное квалифицированное имя класса, определяющего реализацию объекта.
Имя класса чувствительно к регистру.
Если атрибуты class и beanName не специфицированы, объект обязан быть представлен в данной области видимости.
beanName Имя для Bean, как предполагается методом instantiate() класса java.beans.Beans. Этот атрибут может принимать в качестве значения выражение атрибута времени запроса.
type Если специфицирован, определяет тип переменной скриптинга.
Это позволяет типу переменной скриптинга отличаться от (но соотноситься с) типа специфицированного класса реализации.
Тип должен быть самим классом, суперклассом этого класса, либо интерфейсом, реализованным специфицированным классом.
Объект, на который ссылаются, должен быть этого типа, иначе должно возникать исключение java.lang.ClassCastException во время запроса, когда делается попытка назначения объекта, на который ссылаются, переменной скриптинга.
Если не специфицировано, значение будет тем же, что и значение атрибута class.

JSP.4.2 <jsp:setProperty>

Акция jsp:setProperty устанавливает значения свойств в Bean'е. Атрибут name, обозначающий этот Bean, обязан быть определён до появления этой акции.

Имеются два варианта акции jsp:setProperty. Оба они устанавливают значение одного или более свойств в Bean на базе типа свойств. Обычно в Bean выполняется самоанализ с целью обнаружения существующих свойств, и, для каждого из них,  имени, простое оно или индексированное, его типа и методов setter и getter. Самоанализ также указывает, имеет ли тип данного свойства класс PropertyEditor.


Свойства в Bean могут быть установлены из одного или более параметров объекта request, из String-константы или из вычисленного выражения времени запроса. Простые и индексированные свойства могут быть установлены с использованием jsp:setProperty.

При установке из параметра объекта request применяется конвертация, описанная в Разделе JSP.2.13.2.1, использующая целевое свойство для определения целевого типа.

При присвоении из значения, заданного как String-константа, применяется конвертация, описанная в Разделе JSP.2.13.2.1, использующая целевое свойство для определения целевого типа.

При присвоении из значения, заданного как атрибут времени запроса, никакая конвертация типов не применяется, как указано в Разделе JSP.2.13.2.3.

При присвоении значений индексированным свойствам значение обязано быть массивом/array; к элементам применяются правила, описанные в предыдущем параграфе. Неудача конверсии приводит к ошибке времени трансляции или времени запроса.

Примеры


Следующие два элемента устанавливают значение из значений параметра request:
 

<jsp:setProperty name="request" property="*" />

<jsp:setProperty name="user" property="user" param="username" />
 

Следующие два элемента устанавливают свойство из значения:
 

<jsp:setProperty name="results" property="row" value="<%= i+1 %>" />

Синтаксис
 

<jsp:setProperty name="beanName" prop_expr />
prop_expr ::=
property="*" |
property="propertyName"|
property="propertyName" param="parameterName"|
property="propertyName" value="propertyValue"
propertyValue ::= string

 

Значение propertyValue может также быть значением атрибута времени запроса, как описано в Разделе JSP.2.13.1.
 

propertyValue ::= expr_scriptlet (См. синтаксис скриптлета выражения "<%= ... %>")


Элемент <jsp:setProperty> имеет следующие атрибуты:

Таблица JSP.4-2
name Имя экземпляра Bean'а, определённое элементом <jsp:useBean> или каким-либо другим элементом.
Экземпляр Bean'а обязан содержать свойство, которое Вы хотите установить.
Определяющий элемент обязан появиться до элемента <jsp:setProperty> в том же файле.
property Имя свойства Bean'а, значение которого Вы хотите установить.
Если Вы устанавливаете propertyName в *, тогда тэг будет выполнять итерацию поверх текущих параметров ServletRequest, подбирая совпадения имён параметров и типа(-ов) значений с именами свойств и типом(-ами) метода setter, устанавливая каждое совпавшее свойство в значение совпадающего параметра.
Если параметр имеет значение "", соответствующее свойство не модифицируется.
param Имя параметра запроса, значение которого Вы хотите дать свойству Bean'а. Имя параметра запроса приходит обычно от web-формы.
Если param опущен, принимается, что имя параметра запроса - то же самое, что и имя свойства Bean'а.
Если param не установлен в объекте Request или если он имеет значение "", элемент jsp:setProperty не оказывает влияния (a noop - шо цэ такэ?).
Акция может не иметь атрибутов param и value.
value

Значение, присваиваемое данному свойству.
Этот атрибут может принимать выражение атрибута времени запроса в качестве значения.
Акция может не иметь атрибутов param и value.

JSP.4.3 <jsp:getProperty>

Акция <jsp:getProperty> помещает значение свойства экземпляра Bean'а, конвертированное к String, в неявный объект вывода, из которого Вы можете отобразить значение в качестве вывода. Экземпляр Bean'а обязан быть определён так, как указано в атрибуте name до этой точки страницы (обычно посредством акции jsp:useBean).

Конверсия к String выполняется также, как в методах println(), т.е. метод toString() данного объекта применяется для экземпляров Object, а примитивные типы конвертируются напрямую.

Если объект не найден, вызывается исключение времени запроса.

Значение атрибута name в jsp:setProperty и jsp:getProperty будет ссылаться на объект, который получен из объекта PageContext с помощью его метода findAttribute().

Объект, именованный посредством name, обязан быть "представлен" JSP-процессору путём использования акции jsp:useBean или специальной акции с ассоциированным входом VariableInfo для данного имени.


Примечание
: из предыдущего параграфа следует, что объекты, хранимые, скажем, в сессии лицевым/front компонентом, не являются автоматически видимыми акциям jsp:set-Property и jsp:getProperty на данной странице, если только акция jsp:useBean или какая-нибудь другая не делает их видимыми.

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

Пример
 

<jsp:getProperty name="user" property="name" />

Синтаксис


<jsp:getProperty name="name" property="propertyName" />

Таблица JSP.4-3 Атрибуты
name Имя экземпляра объекта, из которого получено свойство.
property Именует получаемое свойство.

JSP.4.4 <jsp:include>

Элемент <jsp:include .../> предоставляется для включения статических и динамических ресурсов в тот же контекст, что и у текущей страницы. См. в Таблице JSP.2-1 резюме по облегчению включения.
Включение производится в текущее значение out/вывода. Этот ресурс специфицирован путём использования relativeURLspec/спецификации относительного URI, которая интерпретируется в контексте web-сервера (т.е. она отображается/mapped).

Атрибуты page акций jsp:include и jsp:forward интерпретируются относительно текущей JSP-страницы, поскольку атрибут file в директиве include интерпретируется относительно текущего JSP-файла. См. ниже примеры таких комбинаций.

Включаемая страница имеет доступ только к объекту JspWriter и не может устанавливать шапки/headers. Это предотвращает вызов методов, подобных setCookie(). Попытки вызова таких методов будут игнорироваться. Это ограничение эквивалентно ограничению, вводимому методом include() класса RequestDispatcher.

Акция jsp:include может иметь субэлементы jsp:param, которые могут предоставлять значения некоторым параметрам в запросе для использования в процессе включения.

Процессинг запроса продолжается вызовом JSP-страницы, после того как включение выполнено.

Атрибут flush управляет очисткой. Если он true, тогда, если вывод страницы буферизуется и атрибут flush получает значение 'true', буфет очищается до включения, в ином случае буфер не очищается. По умолчанию атрибут flush имеет значение 'false'.

Примеры
 

<jsp:include page="/templates/copyright.html"/>
 

Вышеприведённый пример - это простое включение объекта. Путь интерпретируется в контексте Web-Приложения. Это похоже на static/статичный объект, но он может также отображаться в, например, Servlet посредством web.xml.

Например, в качестве более сложного набора включений рассмотрим следующие 4 ситуации, построенные с использованием 4 JSP-файлов: A.jsp, C.jsp, dir/B.jsp и dir/C.jsp:

Синтаксис
 

<jsp:include page="urlSpec" flush="true|false"/>

и

<jsp:include page="urlSpec" flush="true|false">

{ <jsp:<code></code> .... /> }*

</jsp:include>
 

В первом примере синтаксиса выполняется включение на этапе запроса.

Во втором случае значения в субэлементах param используются для увеличения запроса с целью включения.


Верными атрибутами являются:

Таблица JSP.4-4
page Этот URL является относительным urlSpec, как указано в Разделе JSP.2.2.1.
Относительные пути интерпретируются относительно текущей JSP-страницы.
Принимает атрибут времени запроса value (который обязан вычисляться до String, которая является спецификацией относительного URL).
flush Необязательный булев атрибут. Если "true", буфер немедленно очищается. По умолчанию - "false".

JSP.4.5 <jsp:forward>

Элемент <jsp:forward page="urlSpec" /> позволяет направлять на этапе прогона текущий запрос статическому ресурсу - JSP-странице или Java-классу Servlet в том же контексте, что и текущая страница.
jsp:forward эффективно прерывает выполнение текущей страницы. Относительный urlSpec - как в Разделе JSP.2.2.1. Объект запроса будет настроен в соответствии со значением атрибута page.

Акция jsp:forward может иметь субэлементы jsp:param, которые могут предоставлять значения для некоторых параметров запроса, используемых для перенаправления.

Если вывод страницы буферизуется, то буфер очищается перед перенаправлением.
Если вывод страницы буферизуется и буфер был очищен, то попытка направить запрос вызовет исключение IllegalStateException.

Если вывод страницы не буферизовался и в него что-то было записано, то попытка направить запрос вызовет исключение IllegalStateException.

Примеры
 

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

<% String whereTo = "/templates/"+someValue; %>

<jsp:forward page='<%= whereTo %>' />

Синтаксис
 

<jsp:forward page="relativeURLspec" />

   и

<jsp:forward page="urlSpec">

     { <jsp:param .... /> }*

</jsp:forward>


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

Таблица JSP.4-5
page URL является относительным urlSpec, как указано в Разделе JSP.2.2.1.
Относительные пути интерпретируются относительно текущей JSP-страницы.

Принимает атрибут времени запроса value (который обязан вычисляться до String, которая является спецификацией относительного URL).

JSP.4.6 <jsp:param>

Элемент jsp:param используется для предоставления информации ключ/значение. Этот элемент используется в элементах jsp:include, jsp:forward  и jsp:params. Должна вызываться ошибка времени трансляции, если этот элемент используется в другом месте.

При выполнении jsp:include или jsp:forward, включаемая страница или перенаправляемая страница будет просматривать оригинал объекта запроса с оригинальными параметрами, дополненными новыми параметрами с новыми значениями, имеющими приоритет над существующими значениями, где это нужно.

Областью видимости новых параметров является вызов jsp:include или jsp:forward; т.е., в случае с jsp:include - новые параметры (и значения) не будут применяться после включения. Это то же поведение, что и при использовании методов include и forward в ServletRequest (см. Раздел 8.1.1 в спецификации Servlet 2.2).

Например, если запрос имеет параметр A=foo, и параметр A=bar специфицирован для перенаправления, направляемый запрос должен будет сдержать A=bar,foo. Обратите внимание, что новый param имеет приоритет.

JSP.4.6.1 Синтаксис
 

<jsp:param name="name" value="value" />
 

Эта акция имеет два мандатных/обязательных атрибута: name и value.
Name это имя параметра, а value, которое может быть выражением времени запроса, это его значение.

JSP.4.7 <jsp:plugin>

Акция plugin даёт автору JSP-страниц возможность генерировать HTML, содержащий соответствующие клиентскому браузеру конструкции (OBJECT или EMBED), которые приводят к загрузке компонента Java Plugin (если это необходимо) и последующему выполнению специфицированного компонента Applet или JavaBeans.

Тэг <jsp:plugin> замещается тэгом <object> или <embed> - как больше подходит для запрашивающего Пользовательского Агента (ПА) - и выводится в поток вывода ответа/response.

Атрибуты тэга <jsp:plugin> предоставляют данные конфигурации для представления элемента, как показано далее в таблице.

Элементы <jsp:param> это параметры компонентов Applet или JavaBeans.

Элемент <jsp:fallback> это содержимое, используемое клиентским браузером, если компонент plugin не может стартовать (из-за того, что OBJECT или EMBED не поддерживаются клиентским браузером, либо по каким-то другим причинам).

Если plugin может стартовать, но компонент Applet или JavaBeans не может быть найден или не может стартовать, то сообщение, специфическое для данного plugin, будет показано пользователю: вероятнее всего - всплывающее окно, содержащее ClassNotFoundException.


Реальный код plugin не должен быть связан с JSP-контейнером. Ссылка на место размещения plugin'а Sun  может использоваться вместо этого, хотя некоторые продавцы ПО предпочитают включать plugin для удобства пользователя.

Примеры
 

<jsp:plugin type=applet code="Molecule.class" codebase="/html" >

<jsp:params>

<jsp:param

name="molecule"

value="molecules/benzene.mol"/>

</jsp:params>

<jsp:fallback>

<p> unable to start plugin </p>

</jsp:fallback>

</jsp:plugin>

Синтаксис
 

<jsp:plugintype="bean|applet"

  code="objectCode"

  codebase="objectCodebase"

  { align="alignment" }

  { archive="archiveList" }

  { height="height" }

  { hspace="hspace" }

  { jreversion="jreversion" }

  { name="componentName" }

  { vspace="vspace" }

  { width="width" }

  { nspluginurl="url" }

  { iepluginurl="url" } >

  { <jsp:params>

  { <jsp:<code></code> name="paramName" value="paramValue" /> }+

</jsp:params> }

  { <jsp:fallback> arbitrary_text </jsp:fallback> }

</jsp:plugin>

Таблица JSP.4-1
type Идентифицирует тип компонента: Bean или Applet.
code Как определено в HTML.
codebase Как определено в HTML.
align Как определено в HTML.
archive Как определено в HTML.
height Как определено в HTML. Принимает значение выражения времени прогона программы.
hspace Как определено в HTML.
jreversion Идентифицирует номер версии JRE, необходимый компоненту для работы; по умолчанию: "1.2"
name Как определено в HTML.
vspace Как определено в HTML.
title Как определено в HTML.
width Как определено в HTML. Принимает значение выражения времени прогона программы.
nspluginurl URL, с которого JRE-plugin может быть загружен для использования в Netscape Navigator, по умолчанию - определяется реализацией.
iepluginurl URL, с которого JRE-plugin может быть загружен для использования в IE, по умолчанию - определяется реализацией.

JSP.4.8 <jsp:params>

Акция jsp:params является частью акции jsp:plugin и может появляться только как прямой потомок элемента <jsp:plugin>.

Использование элемента jsp:params в любом ином контексте должно приводит к ошибке времени трансляции.

Семантика и синтаксис jsp:params описаны в Разделе JSP.4.7.

JSP.4.9 <jsp:fallback>

Акция jsp:fallback является частью акции jsp:plugin и может появляться только как прямой потомок элемента <jsp:plugin>.

Использование элемента jsp:fallback в любом ином контексте должно приводит к ошибке времени трансляции.

Семантика и синтаксис jsp:fallback описаны в Разделе JSP.4.7.


Глава JSP.5

JSP-Документы


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

Эта глава также определяет отображение/mapping между JSP-страницей и XML-описанием этой страницы, её XML view\XML-просмотр. XML-просмотр определён для JSP-страниц, написанных на JSP с синтаксисом XML.

JSP.5.1 Использование Синтаксиса XML для Страниц JSP

Синтаксис XML для JSP-страниц может использоваться по-разному, с том числе:

Проверка JSP-страницы поддерживается в спецификации JSP 1.2 с помощью класса TagLibraryValidator, ассоциированного с библиотекой тэгов. Класс-проверщик работает с объектом PageData, который представляет XML-просмотр JSP-страницы (см., например, Раздел JSP.7.5.1.2).


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

JSP.5.2 Документы JSP

JSP-документ это XML-документ, "знающий" о пространстве имён. Пространства имён используются для идентификации основного синтаксиса и библиотек тэгов, используемых на странице, и все относящиеся к JSP пространства имён вводятся в корне/root документа XML.

Основной синтаксис/core syntax определяется с помощью своего собственного URI. Хотя в этой главе используется префикс jsp, верным является любой префикс, если используется корректный URI, идентифицирующий основной синтаксис.

JSP-документ использует то же расширение файла (.jsp), что и JSP-страница с синтаксисом JSP. Контейнер может различить их, поскольку JSP-документ является XML-документом с верхним элементом jsp:root, а jsp:root не может появляться на JSP-странице с синтаксисом JSP.

Многие элементы XML в JSP-документе соответствуют элементам языка JSP, но можно включать элементы XML, непосредственно описывающие шаблон. Эти элементы могут иметь квалифицированные имена (и, таким образом, находиться в пространстве имён) или являться неквалифицированными. 


JSP-страница с синтаксисом XML может использовать следующие элементы:

JSP.5.2.1 Модель Семантики

Модель семантики JSP-документа не изменилась по сравнению с моделью семантики JSP-страницы с синтаксисом JSP: JSP-страницы генерируют ответный поток символов из шаблонных данных и динамических элементов. Шаблонные данные могут быть описаны явно элементом jsp:text или неявно фрагментом XML.

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

Чтобы точнее показать процессинг пробелов, мы следуем структуре спецификации XSLT. Первым шагом обработки JSP-документа является идентификация узлов документа. При этом все текстуальные узлы, содержащие только пробелы, из документа удаляются; единственным исключением являются узлы элемента jsp:text, которые сохраняются дословно. Результирующие узлы интерпретируются так, как описано в последующих разделах. Шаблонные данные либо передаются непосредственно в ответ/response, либо опосредованно через (стандартные или специальные/custom) акции.

В соответствии со спецификацией XML (и спецификацией XSLT), пробельными символами являются #x20, #x9, #xD и #xA.

JSP.5.2.2 Элемент jsp:root

JSP-документ содержит элемент jsp:root в качестве корневого элемента. Элемент root содержит атрибут xmlns, который даёт возможность использовать стандартные элементы, определённые в спецификации JSP 1.2. Кроме того, root это место, где будут вставляться атрибуты пространства имён для директив taglib.

Все библиотеки тэгов, используемые в JSP-документе, представлены в элементе root с помощью дополнительных атрибутов xmlns.

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

<jsp:root
xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:prefix1="URI-для-taglib1"
xmlns:prefix2="URI-для-taglib2"... >
version="1.2">

JSP-страница

</jsp:root>
 

Атрибут xmlns специальной библиотеки тэгов в форме xml:префикс='uri' идентифицирует библиотеку тэгов через значение uri. Значение uri может иметь две формы, "uri" или "urn:jsptld:путь".

Если значение uri имеет форму "urn:jsptld:путь", тогда TLD определяется в соответствии с механизмом из Раздела JSP.7.3.2.

Если значение uri является обычным "uri", тогда путь определяется путём сравнения с указанным отображением в web.xml, расширенным с использованием  неявного отображения в упакованные библиотеки тэгов (Разделы JSP.7.3.3 и JSP.7.3.4), как указано в Разделе JSP.7.3.6.

JSP.5.2.3 Элемент jsp:directive.page

Элемент jsp:directive.page определяет несколько зависящих от страницы свойств и передаёт их JSP-контейнеру. Этот элемент обязан быть потомком элементаroot и появляться в начале JSP-документа.

Его синтаксис:
 

<jsp:directive.page список_атрибутов_директивы_page />
 

где список_атрибутов_директивы_page\page_directive_attr_list - такой, как описано в Разделе JSP.2.10.1.

Интерпретация элемента jsp:directive.page описана в Разделе JSP.2.10.1, а его областью видимости/scope является JSP-документ и любой фрагмент, включённый директивой include.

JSP.5.2.4 Элемент jsp:directive.include

Элемент jsp:directive.include используется для замещения текста и\или кода на этапе трансляции JSP-страницы. Этот элемент может появляться в любом месте JSP-документа.

Его синтаксис:
 

<jsp:directive.include file="relativeURLspec\спецификация относительного URL" />

 

Интерпретация элемента jsp:directive.include описана в Разделе JSP.2.10.3.

XML-просмотр JSP-страницы не содержит элементов jsp:directive.include, вместо этого включённый файл разворачивается непосредственно в этом месте. Это делается для упрощения проверки.

JSP.5.2.5 Элемент jsp:declaration

Элемент jsp:declaration используется для объявления конструкций языка скриптинга, которые доступны всем другим элементам скриптинга. Элемент jsp:declaration не имеет атрибутов, и его тело/body - это само объявление.

Его синтаксис:
 

<jsp:declaration> здесь идёт объявление </jsp:declaration>


Интерпретация элемента jsp:declaration описана в Разделе JSP.2.11.1.

JSP.5.2.6 Элемент jsp:scriptlet

Элемент jsp:scriptlet используется для описания акций, выполняемых в ответ на некоторый запрос. Скриптлеты являются фрагментами программы. Элемент jsp:scriptlet не имеет атрибутов, и его тело - это фрагмент программы, содержащий скриптлет.

Его синтаксис:


<jsp:scriptlet> здесь - фрагмент кода </jsp:scriptlet>


Интерпретация элемента jsp:scriptlet описана в Разделе JSP.2.11.2.

JSP.5.2.7 Элемент jsp:expression

Элемент jsp:expression используется для описания сложных выражений на языке скриптинга, вычисляемых на этапе ответа. Элемент jsp:expression не имеет атрибутов, и его тело - это выражение.

Его синтаксис:


<jsp:expression> здесь - выражение </jsp:expression>


Интерпретация элемента jsp:expression описана в Разделе JSP.2.11.3.

JSP.5.2.8 Элементы Стандартных и Специальных Акций

JSP-документ может использовать стандартные акции, описанные в Главе JSP.4. Поскольку синтаксис этих элементов уже базируется на XML, описания этой главы достаточно, за исключением того, что в шаблоне JSP-документа текст может быть описан элементом jsp:text, либо посредством элемента XML, который не является ни стандартной, ни специальной акцией (см. Раздел JSP.5.2.11).

Для полноты приведём элементы-акции:

Семантика и ограничения описаны в Главе JSP.4, а интерпретация элементов скриптинга - в Главе JSP.6.
Библиотеки тэгов вводят новые элементы атрибутам xmlns или элементом jsp:root, а их синтаксис и семантика описаны в Главе JSP.7.

JSP.5.2.9 Атрибуты Времени Запроса

Элемент акции, который может принимать атрибут времени запроса (Раздел JSP.2.13.1), принимает аргумент для этого атрибута в форме "%= text %" (пробелы вокруг text не нужны, и отметьте отсутствие  '<' и '>'). Text, после применения кавычек (как и в любом другом документе XML), является выражением, вычисляемым по правилам Раздела JSP.2.13.1.

JSP.5.2.10 Элемент jsp:text

Элемент jsp:text можно использовать для включения шаблонных данных в представление XML.
Элемент jsp:text не имеет атрибутов и может появляться в любом месте, где могут появляться шаблонные данные.

Его синтаксис:


<jsp:text> шаблонные данные </jsp:text>


При интерпретации элемента jsp:text, его содержимое передаётся текущему значению out/вывода. Это очень напоминает работу элемента xsl:text из XSLT.

JSP.5.2.11 Другие XML-Элементы

Синтаксис XML для JSP-страниц допускает также появление XML-элементов, которые не представляют ни стандартных, ни специальных акций, в любом месте, где может появляться jsp:text.


Интерпретация такого XML-элемента - это передача его текстуального представления текущему значению out после процессинга пробелов, описанного в Разделе JSP.5.2.1.


Как пример, если фрагмент JSP-документа таков:

Таблица 5.1: Пример 1 - Ввод
N Строки Исходный Текст
1 <hello><jsp:scriptlet>i=3;</jsp:scriptlet>
2 <hi>
3 <jsp:text> hi you all
4 </jsp:text><jsp:expression>i</jsp:expression>
5 </hi>
6 </hello>

то результат будет:

Таблица 5.2: Пример 1 - Вывод
N Строки Итоговый Текст
1 <hello> <hi> hi you all
2 3 </hi></hello>

Обратите внимание на работу с пробелами.

JSP.5.3 XML-Просмотр Страницы JSP

В этом разделе описан XML-просмотр/view JSP-страницы: отображение между JSP-страницей, написанной с синтаксисом XML или JSP, и XML-документом, описывающим её.

JSP.5.3.1 JSP-Документы

XML-просмотр JSP-страницы, написанной с синтаксисом XML, очень похож на оригинал JSP-страницы.
Выполняются только две трансформации:

JSP.5.3.2 Страницы JSP и Синтаксис JSP

XML-просмотр JSP-страницы, написанной с синтаксисом XML, определяется следующей трансформацией:

Обратите внимание, что XML-просмотр JSP-страницы не имеет информации DOCTYPE; см. Раздел JSP.5.4.


Краткий обзор трансформации дан в Таблице JSP.5-1:

Таблица JSP.5-1 Трансформации XML-Просмотра
Элемент JSP-страницы XML-просмотр
<%-- комментарий --%> удалён.
<%@ page ... %> <jsp:directive.page ... />. По выбору добавляется jsp:id.
<%@ taglib ... %> элемент jsp:root снабжается информацией пространства имён. По выбору добавляется jsp:id.
<%@ include ... %> развёртывается в этом месте.

<%! ... %> <jsp:declaration> .... </jsp:declaration>. По выбору добавляется jsp:id.
<% ... %> <jsp:scriptlet> ... </jsp:scriptlet>. По выбору добавляется jsp:id.
<%= ... %> <jsp:expression> ... </jsp:expression>. По выбору добавляется jsp:id.

Стандартная акция замещается синтаксисом XML уточняются выражения времени запроса; по выбору добавляется jsp:id)
Специальная акция как есть (уточняются выражения времени запроса; по выбору добавляется jsp:id)
Шаблон замещается элементом jsp:text. По выбору добавляется jsp:id.

Более детально:

JSP.5.3.3 Комментарии JSP

JSP-комментарии (в форме <%-- комментарий --%>) не передаются в XML-просмотр JSP-страницы.

JSP.5.3.4 Директива page

Директива page в форме:
 

<%@ page { атрибут="значение" }* %>
 

транслируется в элемент в форме:
 

<jsp:directive.page { атрибут="значение" }* />

JSP.5.3.5 Директива taglib

Директива taglib в форме:
 


<%@ taglib uri="uriValue\значениеURI" prefix="префикс" %>

транслируется в атрибут xmlns:prefix элемента root JSP-документа со значением. которое зависит от uriValue. Если uriValue является относительным путём, то используемое значение будет "urn:jsptld:uriValue"; иначе uriValue используется напрямую.

JSP.5.3.6 Директива include

Директива include в форме:


<%@ include file="value" %>


развёртывается в JSP-фрагмент, обозначенный value. Это сделано для того, чтобы дать возможность проверять страницу.

JSP.5.3.7 Объявления

Объявления транслируются в элемент jsp:declaration . Например, второй пример из Раздела JSP.2.11.1:


<%! public String f(int i) { if (i<3) return("..."); ... } %>


транслируется в:


<jsp:declaration> <![CDATA[ public String f(int i) { if (i<3) return("..."); } ]]> </jsp:declaration>


Альтернативно мы можем использовать &lt; и записать:


<jsp:declaration> public String f(int i) { if (i&lt;3) return("..."); } </jsp:declaration>

JSP.5.3.8 Скриптлеты

Скриптлеты транслируются в элементы jsp:scriptlet . В XML-документе, соответствующем JSP-страницам, директивы представлены с использованием следующего синтаксиса:
 

<jsp:scriptlet> здесь - фрагмент кода </jsp:scriptlet>

JSP.5.3.9 Выражения

В XML-документе, соответствующем JSP-страницам, директивы представлены с использованием элемента jsp:expression:


<jsp:expression> здесь - выражение </jsp:expression>

JSP.5.3.10 Стандартные и Специальные Акции

Синтаксис элементов стандартных и специальных акций базируется на XML. Необходимы трансформации в связи с соглашениями по кавычкам и с синтаксисом выражений атрибутов времени запроса.

JSP.5.3.11 Выражения Атрибутов Времени Запроса

Выражения атрибутов времени запроса/Request-time attribute expressions имеют форму "<%= expression %>".

Хотя этот синтаксис следует синтаксису, используемому в JSP-странице, он не является допустимым в XML.
Отображение XML для таких выражений - это значение в форме "%= выражение'%", где соглашение по кавычкам спецификации JSP конвертировано в соглашение по кавычкам XML.

JSP.5.3.12 Шаблонный Текст и Элементы XML

Весь текст, который не интерпретируется JSP-транслятором, конвертируется в тело/body элемента jsp:text. Как следствие, никакие XML-элементы в форме, описанной в Разделе JSP.5.2.11, не будут появляться в XML-просмотре JSP-странице, написанной с синтаксисом JSP.

JSP.5.3.13 Атрибут jsp:id

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


В JSP-контейнере, поддерживающем атрибут jsp:id, XML-просмотр любой JSP-страницы будет содержать дополнительный атрибут jsp:id во всех XML-элементах. Этому атрибуту даётся значение, уникальное среди всех элементов XML-просмотра. См. детали в Главе 10.

JSP.5.4 Проверка XML-Просмотра Страницы JSP

XML-просмотр JSP-страницы это документ, связанный с пространством имён, и он не может быть проверен относительно ОТД/DTD (Определение Типа Данных), за исключением лишь наиболее простых случаев.
Чтобы уменьшить конфликты и возможные нежелательные последствия, XML-просмотр JSP-страницы не будет включать DOCTYPE. Однако пока ОТД могут содержать некоторое значение в качестве документации, Приложение JSP.C содержит описания и DTD, и XSchema JSP-документов.

Есть несколько механизмов с участием пространства имён, которые могут использоваться для проверки XML-просмотра JSP-страниц. Самым популярным механизмом является язык XML Schema консорциума W3C, но подойдут также и другие, включая некоторые простейшие, которые, например, могут использовать только некоторые элементы, или, напротив, которые не используют их. Проверщик TagLibraryValidator для библиотеки тэгов разрешает инкапсуляцию этих сведений в библиотеке тэгов.

TagLibraryValidator
работает в XML-просмотре JSP-страницы. Если страница создана с синтаксисом JSP, этот просмотр не предоставляет никаких деталей о шаблонных данных (всё группируется внутри элементов jsp:text), но отдельные детали могут быть описаны при использовании JSP-документов. Аналогично, когда XSLT-трансформация применяется к JSP-документу, XML-фрагменты будут нормально видимы, в то время как содержимое элементов jsp:text - нет.

JSP.5.5 Примеры

В этом разделе представлены два примера JSP-документов. В первом дана JSP-страница с синтаксисом JSP и её отображение в синтаксис XML. Во втором - JSP-страница с синтаксисом XML, включающая XML-фрагменты.
 

JSP.5.5.1 Страница JSP и Соответствующий Ей JSP-Документ

Пример отображения между синтаксисом JSP и XML.

JSP-СТРАНИЦА С СИНТАКСИСОМ JSP:
 

<html>

<title>positiveTagLib</title>

<body>

<%@ taglib uri="http://java.apache.org/tomcat/examples-taglib" prefix="eg" %>

<%@ taglib uri="/tomcat/taglib" prefix="test" %>

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

<eg:test toBrowser="true" att1="Working">

Positive Test taglib directive </eg:test>

</body>

</html>

XML-ПРОСМОТР JSP-СТРАНИЦЫ:
 

<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"

xmlns:eg="http://java.apache.org/tomcat/examples-taglib"

xmlns:test="urn:jsptld:/tomcat/taglib"

xmlns:temp="urn:jsptld:/WEB-INF/tlds/my.tld"

version="1.2">

<jsp:text><![CDATA[<html>

<title>positiveTagLig</title>

<body>

]]></jsp:text>

<eg:test toBrowser="true" att1="Working>

<jsp:text>Positive test taglib directive</jsp:text>

</eg:test>

<jsp:text><![CDATA[

</body>

</html>

]]></jsp:text>

</jsp:root>

JSP.5.5.2 JSP-Документ

Это пример очень простого JSP-документа, содержащего некоторые шаблонные XML-элементы.


<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"

xmlns:mytags="prefix1-URL"

version="1.2">

<mytags:iterator count="4">

<foo> </foo>

</mytags:iterator>

</jsp:root>


Глава JSP.6

Скриптинг


В этой главе детально разбираются Элементы Скриптинга, когда значением директивы language является "java". Этот язык скриптинга базируется на языке программирования Java (как специфицировано в "The Java Language Specification"), но заметьте, что верная Java-программа не является верной JSP-страницей или её разделом.
 

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

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

JSP.6.1 Общая Структура

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

JSP.6.1.1 Верная Страница JSP

JSP-страница является таковой для Платформы Java, если, и только если, класс реализации JSP-страницы, определённый по Таблице JSP.6-1 (после применения всех директив include), вместе со всеми прочими классами, определёнными JSP-контейнером, является верной программой для данной Java-Платформы и если он передаёт методы проверки для всех библиотек тэгов, ассоциированных с этой JSP-страницей.

JSP.6.1.2 Зарезервированные Имена

Sun Microsystems резервирует для спецификаций JSP все имена, имеющие форму {_}jsp_* и {_}jspx_*, в любом сочетании верхнего и нижнего регистров.

Имена, имеющие такую форму и не определённые в данной спецификации, зарезервированы фирмой Sun для будущих расширений.

JSP.6.1.3 Гибкость Реализации

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

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

Таблица JSP.6-1  Структура Класса JavaProgramming
необязательное выражение импорта, как указано директивой jsp. import name1
SuperClass выбирается JSP-контейнером, либо автором JSP через использование директивы jsp. Имя класса (_jspXXX) зависит от реализации. class _jspXXX extends SuperClass
Начало тела/body класса реализации JSP-страницы. {
(1) Раздел Объявлений // объявления...
Подпись для генерируемого метода. public void _jspService(<ServletRequestSubtype>
request,
<ServletResponseSubtype> response)
 throws ServletException, IOException {
(2) Раздел Неявных/Implicit Объектов // код, определяющий и инициализирующий request, response, page, pageContext и т.п.
(3) Главный/Main Раздел // код, определяющий выражение отображения request/response метода _jspService
закрытие метода _jspService }
закрытие _jspXXX }

JSP.6.2 Раздел Объявлений

Раздел объявлений соответствует элементам объявлений. Содержимое этого раздела определяется путём конкатенации всех объявлений на странице в порядке их появления.

JSP.6.3 Раздел Инициализации

Этот раздел определяет и инициализирует неявные объекты, доступные JSP-странице. См. Раздел JSP.2.8.3, "Неявные Объекты.

JSP.6.4 Раздел Main/Главный

Этот раздел осуществляет главное отображение/mapping между объектами request и response.

Содержимое кодового сегмента 2 определяется скриптлетами, выражениями и текстовым телом JSP-страницы.

Элементы обрабатываются последовательно в порядке их появления на странице. Трансляция каждого из них определяется так, как показано ниже, и вставляется в данный раздел.

Трансляция зависит от типа элемента:

JSP.6.4.1 Шаблонные Данные

Шаблонные данные трансформируются в код, который будет размещать шаблонные данные в потоке, именованном неявной переменной out в процессе исполнения кода. Пробелы сохраняются.
 

Опуская подробности закавычивания и производительности, это соответствует оператору вида:

Оригинал Эквивалентный Текст
шаблон out.print(шаблон)

JSP.6.4.2 Скриптлеты

Скриптлет трансформируется во фрагмент кода вида:

Оригинал Эквивалентный Текст
<% фрагмент %> фрагмент

JSP.6.4.3 Выражения

Выражение трансформируется в оператор Java для вставки значения выражения (конвертированного, если необходимо, в java.lang.String), в поток, именованный неявной переменной out. Никакие дополнительные символы новой строки или пробелы не включаются.

Опуская подробности закавычивания и производительности, это соответствует оператору вида:

Оригинал Эквивалентный Текст
<%= выражение %> out.print(выражение)

JSP.6.4.4 Акции

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

Семантика типа акции определяет имена переменных (обычно имя атрибута id, если он имеется) и их тип.

Единственной стандартной акцией в спецификации JSP, которая определяет объекты, является акция jsp:usebean. Имя вводимой переменной это имя атрибута id, а тип - атрибута класса.

Оригинал Эквивалентный Текст

<x:tag>
  foo
</x:tag>

объявляются переменные AT_BEGIN
{
объявляются переменные NESTED
трансформации foo
}
объявляются переменные AT_END

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


Глава JSP.7

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


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

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

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

JSP.7.1 Введение

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


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


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

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


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


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

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

JSP.7.1.1 Цели

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

JSP.7.1.2 Обзор

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

Parsing\Разбор

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


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

Validation\Проверка

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

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

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

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

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

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

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

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

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


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

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


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

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

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

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

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

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

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

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

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

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


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


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

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


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

JSP.7.1.3.3Условия


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

JSP.7.1.3.4 Итерации
 

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

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


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

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


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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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


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


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


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

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

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


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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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


<taglib>
 

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


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


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


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

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

<!ATTLIST taglib id ID #IMPLIED>


<taglib-uri>


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


<!ELEMENT taglib-uri (#PCDATA)>

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


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

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


<taglib-location>


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

<!ELEMENT taglib-location (#PCDATA)>

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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


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


<taglib>

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

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

</taglib>
 

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

Нотация


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

JSP Tag Library 1.2//EN">


<taglib>


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


<!ATTLIST taglib

id

ID

#IMPLIED

xmlns

CDATA

#FIXED

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

>
 

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

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

<!ELEMENT taglib

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


<tlib-version>
 

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


Синтаксис:


<!ELEMENT tlib-version (#PCDATA)>

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


<jsp-version>


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


Синтаксис:
 

<!ELEMENT jsp-version (#PCDATA)>

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


<short-name>


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


Синтаксис:


<!ELEMENT short-name (#PCDATA)>

#PCDATA ::= NMTOKEN


<uri>


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


<!ELEMENT uri (#PCDATA)>


<description>


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


<!ELEMENT description (#PCDATA)>


<validator>


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


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

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

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


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


<validator-class>


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


<!ELEMENT validator-class (#PCDATA)>


<init-param>


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

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

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

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


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


<param-name>


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


<!ELEMENT param-name (#PCDATA)>


<param-value>


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


<!ELEMENT param-value (#PCDATA)>


<listener>


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


<!ELEMENT listener (listener-class)>


<listener-class>


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


<!ELEMENT listener-class (#PCDATA)>


<tag>


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


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


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


<!ATTLIST tag id ID #IMPLIED>


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

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

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

<!ELEMENT tag

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


<tag-class>


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


Синтаксис:


<!ELEMENT tag-class (#PCDATA)>

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


<tei-class>


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


Синтаксис:


<!ELEMENT tei-class (#PCDATA)>

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


<body-content>


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


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

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

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


Синтаксис:


<!ELEMENT body-content (#PCDATA)>

#PCDATA ::= tagdependent | JSP | empty.


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


<display-name>


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


Синтаксис:


<!ELEMENT display-name (#PCDATA)>


<large-icon>


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


Синтаксис:


<!ELEMENT large-icon (#PCDATA)>


<small-icon>


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


Синтаксис:


<!ELEMENT small-icon (#PCDATA)>


<variable>


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

 

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

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

Синтаксис:

 

<!ELEMENT variable

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


<name-given>


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


Синтаксис:


<!ELEMENT name-given (#PCDATA)>


<name-from-attribute>


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


Синтаксис:


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


<variable-class>


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


Синтаксис:


<!ELEMENT class (#PCDATA)>


<declare>


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


Синтаксис:


<!ELEMENT declare #PCDATA)>

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


<scope>


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


Синтаксис:


<!ELEMENT scope #PCDATA)>

#PCDATA ::= NESTED | AT_BEGIN | AT_END


<attribute>


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


<!ATTLIST attribute id ID#IMPLIED>
 

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

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

Синтаксис:


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


<name>


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


Синтаксис:


<!ELEMENT name (#PCDATA)>

#PCDATA ::= NMTOKEN


<required>


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


Синтаксис:


<!ELEMENT required (#PCDATA)>

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


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


<rtexprvalue>


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


Синтаксис:


<!ELEMENT rtexprvalue (#PCDATA)>

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


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


<type>


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

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


Синтаксис:

<!ELEMENT type (#PCDATA)>

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


Пример:


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


<example>


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


<!ELEMENT example (#PCDATA)>

JSP.7.5 Проверка

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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


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

<me:defineObjects />

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


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


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


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


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

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

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

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

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

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


Глава JSP.8

JSP-Контейнер


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

Протокол прекомпиляции (см. Раздел JSP.8.4) также представлен здесь.


Информация, представленная здесь, не зависит от Языка Скриптинга, используемого на JSP-странице.

Глава JSP.6 описывает информацию для случая, когда атрибут language директивы page установлен в "java".
 

Классы реализации JSP-страницы должны использовать классы JspFactory и PageContext для получения преимуществ платформозависимых реализаций.

JSP.8.1 Модель JSP-Страницы

JSP-страница представлена на этапе выполнения объектом реализации JSP-страницы и выполняется JSP-контейнером. Объект реализации JSP-страницы - это servlet/сервлет. JSP-контейнер направляет запросы от клиента объекту реализации JSP-страницы и ответы объекта реализации JSP-страницы - клиенту.


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

В JSP 1.2 только события init и destroy являются допустимыми событиями.

JSP.8.1.1 Протокол, Видимый Web-Сервером

JSP-контейнер локализует соответствующий экземпляр класса реализации JSP-страницы и направляет ему запросы, используя протокол Servlet. JSP-контейнеру может потребоваться создать такой класс динамически из исходной JSP-страницы до направления ей объектов request и response.


Класс Servlet определяет контракт между JSP-контейнером и классом реализации JSP-страницы.
Если используется протокол HTTP, контракт описывается классом HttpServlet. Большинство JSP-страниц используют протокол HTTP, но другие протоколы также разрешены  данной спецификацией.


JSP-контейнер автоматически делает несколько серверных/server-side объектов доступными объекту реализации JSP-страницы. См. Раздел JSP.2.8.3.

JSP.8.1.1.1 Протокол, Видимый Автором JSP-Страницы

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

Детальная информация об этом контракте дана в Главе JSP.6. Контракт описывает также, как автор 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-Контейнером.
JSP-Контейнер
JSP-Страница

На Рисунке J2EE.8.1 показаны включённые контракты. Теперь мы рассмотрим этот процесс более детально.

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.2.1 Контракты API

Контракт между JSP-контейнером и Java-классом, реализующим JSP-страницу, соответствует интерфейсу Servlet. См. детали в спецификации Servlet 2.3.


Ответственность за выполнение этого контракта лежит на реализации JSP-контейнера, если JSP-страница не использует атрибут extends директивы jsp.

Если атрибут extends директивы jsp используется, автор JSP-страниц обязан гарантировать, что суперкласс, заданный в атрибуте extends, поддерживает этот контракт.

Таблица JSP.8-1  Как JSP-Контейнер Обрабатывает JSP-Страницы
Комментарии Методы, вызываемые JSP-Контейнером
Метод может по выбору/optionally быть определён в JSP-странице.
Метод вызывается при инициализации JSP-страницы.
Если метод вызывается, доступны все методы сервлета, включая getServletConfig().
void jspInit()
Метод по выбору определяется в JSP-странице.
Метод вызывается при уничтожении страницы.
void jspDestroy()
Метод не может быть определён в JSP-странице.
JSP-контейнер автоматически генерирует этот метод, базируясь на содержимом JSP-страницы.
Метод вызывается при каждом клиентском запросе.
void
_jspService(<ServletRequestSubtype>, <ServletResponseSubtype>) throws IOException,
ServletException

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 (см. Раздел 2.10.1) в JSP-странице не используется, JSP-контейнер может генерировать любой класс, удовлетворяющий контракту, описанному в Таблице JSP.8-1, если он трансформирует JSP-страницу.
 

В следующих примерах Пример Кода 8.1 иллюстрирует общий/родовой HTTP-суперкласс, названный ExampleHttpSuper. В Примере Кода 8.2 показан подкласс, названный _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, генерируемый класс идентичен классу из Примера Кода 8.2, за исключением того, что имя этого класса это имя, специфицированное в атрибуте extends.


Контракт класса реализации JSP-страницы не изменяется. JSP-контейнер должен проверить (обычно через отражение/reflection), что предоставленный суперкласс:

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

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 в Главе JSP.9.


При включённой буферизации, Вы можете всё ещё использовать метод redirect скриптлета в файле .jsp, вызывая response.redirect(какой-то URL) напрямую.

JSP.8.4 Прекомпиляция

JSP-страница, использующая протокол HTTP, будет получать HTTP-запросы.

Контейнеры, соответствующие JSP 1.2, обязаны поддерживать простой протокол прекомпиляции, а также некоторые базовые зарезервированные имена параметров. Заметьте, что протокол прекомпиляции это понятие близкое, но не то же самое, что компиляция JSP-страницы в Servlet-класс (Приложение JSP.A).

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.9

Основной API


Эта глава описывает пакет javax.servlet.jsp. В главе имеется содержимое, сгенерированное автоматически из javadoc, внедрённых в Java-классы и интерфейсы. Это делает возможным создание единого авторизованного документа спецификации.


Пакет javax.servlet.jsp содержит несколько классов и интерфейсов, описывающих и определяющих контракты между классом реализации JSP-страницы и средой работы программы/runtime environment, предоставляемые экземпляру такого класса соответствующим JSP-контейнером.

JSP.9.1 Контракт Объекта Реализации JSP-Страницы

В разделе рассматривается базовый контракт между объектом реализации JSP-страницы и его контейнером. Главный контракт определяется классами JspPage и HttpJspPage. Класс JspFactory описывает механизм портативной инстанциации всех необходимых объектов прогона, а JspEngineInfo предоставляет базовую информацию о текущем JSP-контейнере.


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

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 и включается в интерфейс явно.


См. Также: JspPage



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/контекст страницы.


См. Также: PageContext .


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.2  Неявные Объекты

Объекты PageContext и JspWriter доступны по умолчанию в качестве неявных объектов.

JSP.9.2.1 PageContext

Синтаксис
 


public abstract class PageContext


Описание


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

Неявные объекты добавляют pageContext автоматически.


Класс PageContext является абстрактным классом, созданный как расширяемый для предоставления реализаций соответствующей средой запуска программ JSP-машины.

Экземпляр PageContext получается классом реализации JSP через вызов метода JspFactory.getPageContext() и освобождается через вызов JspFactory.releasePageContext().


Примеры использования PageContext, JspFactory и других классов в объекте реализацииJSP-страницы можно найти повсюду.


PageContext
облегчает работу автора страниц/компонентов и реализатора страниц, предоставляя:


Методы, Предназначенные для Кода, Генерируемого Контейнером
 

Некоторые методы предназначены для использования в коде, генерируемом контейнером, а не для кода, написанного авторами 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.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  Исключения

Класс JspException является базовым классом для всех JSP-исключений. JspTag-Exception используется механизмом исключения тэга.

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)

Конструктор с сообщением...