Пожалуйста, направляйте комментарии по 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).
JCP создаёт спецификации, используя три сообщества:
сообщество экспертов (the expert group),
participants\участники JCP и public\публика вообще.
Эксперты является авторами спецификаций, создавая проекты/drafts.
Проекты проходят путь от экспертов, через участников, к публике,
постепенно совершенствуясь в деталях, всегда возвращая комментарии обратно
группе экспертов; final draft/окончательный проект отправляется для
одобрения в Executive Committee\Исполнительный Комитет.
Лидер группы экспертов отвечает за
облегчение работы группы экспертов, авторизацию спецификации и за организацию reference
implementation\справочной реализации и conformance test suite\блока тестирования на соответствие.
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 1.2 расширяет Спецификацию JavaServer Pagesтм 1.1 (JSP 1.1) следующим образом:
Детали условий, по которым данный документ распространяется, даны в лицензии.
Этот документ является авторизованной спецификацией
JSP 1.2. Он предназначен для предоставления требований к реализациям процессинга JSP
и поддерживается web-контейнерами в web-серверах и серверами приложений.
Он не является справочником пользователя. Мы ожидаем появления других
документов, предназначенных для различных категорий читателей.
Разработчики контейнеров JSP и авторы страниц JSP могут найти необходимую информацию также в следующих документах:
Домашняя страница 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 |
Пионерами, выполнившими начальную работу по платформе 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.
Успех 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.
Это приложение содержит ОТД и XSchema для JSP-страниц с синтаксисом XML.
Это приложение не является нормативным.
Как указано в Разделе JSP.5.4, ОТД не является хорошим описанием, пригодным для
проверки документа, использующего пространства имён, типа JSP-страницы с
синтаксисом XML, но то, что многие читатели знакомы с ним, делает, тем не менее, возможным её использование.
Далее идут ОТД для 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>
Далее идёт описание, использующее 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]*%?">
<!ENTITY AsciiName "[A-Za-z0-9_-]*">
<!ENTITY ValidContentType
"&AsciiName;/&AsciiName;(;&WS;(charset=)?&AsciiName;)?">
<!ENTITY ValidPageEncoding "&AsciiName;/&AsciiName;">
<!ENTITY Buffer "[0-9]+kb">
<!ENTITY RTexpr "%=.*%">
]>
<!--Соответствует 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>
В этом приложении содержится ОТД/DTD для дескриптора библиотеки тэгов (TLD) с использованием JSP 1.2.
Все JSP 1.2-контейнеры должны принимать такой TLD.
Это то же самое ОТД, что и "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd", исключая некоторые изменения форматирования текста для извлечения комментариев и для того, чтобы сделать его более читабельным.
Это ОТД, описывающее файл 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>
В этом приложении содержится DTD/ОТД (Определение Типа Данных) для Дескриптора Библиотеки Тэгов (TLD) с использованием JSP 1.1.
Все JSP 1.2-контейнеры должны принимать такие TLD.
Это то же самое ОТД, что и "http://java.sun.com/dtd/web-jsptaglibrary_1_1.dtd",
исключая некоторые изменения форматирования для извлечения комментариев, чтобы
сделать их более читабельными.
Следующее ОТД описывает файл 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>
В этом приложении перечислены изменения в Спецификации JavaServer Pages.
Это приложение является ненормативным.
Это окончательная версия, одобренная JCP Executive Comittee; документ был обновлён для того, чтобы отразить этот статус. Все полосы изменений/change bars были переустановлены.
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).
height
& width
стали rtexprs
. Был затронут
Раздел JSP.4.7.short
и Short
и
откорректирована конверсия для char
и
Character
в Таблице JSP.2-2.doStartTag()
для Tag, IterationTag
и BodyTag. PFD2 некорректно указывал, что "emtpy/пустые" тэги могут
возвращать только SKIP_BODY
; корректное утверждение: тэги, чьё body-content - "empty"
,
могут возвращать только SKIP_BODY
.Мандатные интерпретации атрибута
"id"
в Разделе JSP 2.13.3 (что id
представляет уникальные id
в
пределах страницы)
и атрибута "scope"
в Разделе JSP 2.13.4 (касающиеся области видимости
вводимого значения) не форсировались большинством (возможно, всеми?)
контейнерами и были несовместимы с распространённой практикой разработки
библиотек специальных тэгов. Именно эти разделы интерпретировались как
локализованные утверждения о стандартной акции jsp:useBean
. Это было сделано
недвусмысленным, и эти разделы были перемещены в Главу
4, что отразить данные изменения. Были изменены Разделы JSP.2.13.3 и JSP.2.13.4
и Глава 4.
afresh
через вызовы new()
, но это требует произнесения/spelling, как только вводится
пулинг/pooling обработчика тэга. Это разъяснение действует для Раздела
JSP.10.1.Несколько разъяснений к Главе 5.
<?xml ... ?>
не требуется (как указано в XML spec).Разъяснено, что автор библиотеки тэгов может указать в комментариях, что
обработчик тэга может показывать на этапе прогона только некоторый поднабор
информации, описанной через класс реализации обработчика тэга. Это применяется
для специализированных реализаций известных библиотек тэгов, таких как
стандартная библиотека тэгов JSP. Это разъяснение повлияло на описание элемента tag
в Разделе JSP.7.4 и на описание Tag.setParent()
и
TagSupport.findAncestorWithClass()
. Удалён последний параграф в Разделе JSP.7.3.9;
у нас нет в планах удалять хорошо известный URI-механизм.
В целом "прочищено" описание вычисления отображения taglib
между URI и путём
ресурса TLD; предыдущая версия была дебильной.
Разъяснено правильное использование и роль блок-конструкций в скриптлетах и вложенных акциях. Это незначительно изменило Разделы JSP.2.3.3, JSP.6.4, JSP.6.4.4 и JSP.10.5.9.
errorPages
должны быть JSP-страницами, они
могут также быть static-объектами. Изменена Таблица JSP.2-1.include
и для акций jsp:include
и jsp:forward
. Изменены Разделы JSP.2.2.1, JSP.2.10.4, JSP.4.4
и JSP.4.5<type>
в <attribute>
в файле TLD должен соответствовать ему же в свойстве
лежащего в его основе компонента JavaBean.ClassLoader.getResource()
при получении данных от класса TagLi-braryValidator
.Change bars/полосы изменений используются в почти всех главах для обозначения изменений между PFD 1b и PFD 2. Исключение - главы 9 и 10, которые автоматически генерируются из Java-источников и не имеют полос изменений. Большинство изменений - семантические, но некоторые из них - редакторские поправки.
Дескриптор Библиотеки Тэгов/Tag Library Descriptor (TLD)
был расширен описательной информацией для пользователей библиотеки тэгов.
Конкретнее, TLD можно теперь непосредственно вставить (например, используя
таблицу стилей XSLT) в документ конечного пользователя. Был добавлен новый
элемент <example>
в качестве необязательного субэлемента в <tag>
.
Существующий элемент <description>
был сделан верным необязательным
субэлементом в <variable>
, <attribute>
и в
<validator>
.
Были изменены Раздел JSP.7.4 и Приложение JSP.C. ОТД TLD 1, и Схемы/Schemas также были изменены.
Этот механизм, используемый для предоставления в TLD информации о версии, был изменён.
В PFD версия кодировалась в пространстве имён. В PFD2 не предполагается изменять
пространство имён, если только это не изменения несовместимости, и версия
кодируется в элементе <jsp-version>
, который теперь является мандатным.
Новый URI для пространства имён:
"http://java.sun.com/JSP/TagLibraryDescriptor".
Были изменены Глава JSP.7 и Приложение JSP.C.
Object
Теперь можно назначать строковые литералы атрибуту, определённому как имеющий
тип Object
, а также свойству типа Object
. Все верные конвертации типов описаны в
Разделе JSP.2.13.2 и используются по ссылке в семантике <jsp:setProperty>
.
Мы дали разъяснение по верным именам для префиксов, используемых в директивах taglib
,
именам элементов, используемых в акциях, и именам атрибутов.
В спецификации JSP 1.1 различаются пустые/empty и непустые/non-empty акции, хотя лучше было бы дать описание. К сожалению, эскиз/проект JSP 1.2 PFD1 не улучшил это описание. Этот проект улучшил описание, указав точнее, какие методы при этом вызываются. Были изменены Главы 2, 7 и 10.
flush
в директиве include
в
Разделе JSP.5.2.4.jsp:cdata
изменено на
jsp:text
, поскольку его семантика очень похожа на элемент text
в XSLT.jsp:root
.DOCTYPE
.include
в XML-просмотре страницы JSP.xmlns
для директив taglib
,
и исправлено Приложение JSP.B.Мы разъяснили также несколько других несоответствий и ошибок.
DOCTYPE
необходим и каково его значение. Значение не изменилось.flush
акции include
, в Разделе JSP.4.4.<jsp:param>
может появляться только
внутри <jsp:forward>
, <jsp:in-clude>
и <jsp:params>
.<jsp:params>
и
<jsp:fallback>
могут появляться только внутри <jsp:plugin>
.doStartTag()
в обработчиках
тэгов, которые (обраб.) реализуют интерфейс BodyTag
. Корректными значениями
являются SKIP_BODY
,
EVAL_BODY_INCLUDE
и EVAL_BODY_BUFFER
. В Разделе это теперь указывается.PFD 1b является наброском, имеющим в основном изменения форматирования и минимум
редакционных поправок. Этот проект показан только для того, чтобы легче было
коррелировать изменения между последними и более ранними проектами.
Полосы изменений используются для обозначения изменений от PFD 1 к PFD 1b.
Следующие изменения появились после версии Public Draft 1 в версии
Proposed Final Draft
спецификации JSP 1.2.
resetCustomAttributes()
.JspException
для поддержки rootCause
(параллельно с ServletException
).PageContext.handleException(Throwable)
.TryCatchFinally
для лучшего контроля над
исключениями в обработчиках тэгов.pageEncoding
добавлен к директиве page.TagValidatorInfo
.top
и included
в JSP.java.beans.Beans.instantiate()
.<uri>
в TLD это URL на что-либо.
TagLibraryValidator
.response.getWriter()
.include
перемещена обратно в Главу JSP.2.javax.servlet.jsp.tagext.PageInfo
переименован в javax.servlet.jsp.tagext.Page-Data
(для соответствия существующему TagData
).TagLibraryInformation
в TLD путём
добавления нового элемента <validator>
,
переименования <validatorclass>
в <validator-class>
, для
соответствия, и добавления
<init-param>
как в дескрипторе Servlet web.xml.TagLibraryInfo
.
Добавлены String-аргументы prefix
и uri
в метод validate()
.<tag-class>
,
<tei-class>
, <tlib-version
, <jsp-version>
, <short-name>
и <body-content>
. <info>
был переименован в <description>
.Следующие изменения появились между JSP 1.1 и JSP 1.2 Public Draft 1.
Мы создали новый ненормативный документ "Using JSP Technology/Использование Технологии JSP". Этот документ ещё обновляется до JSP 1.2 и Servlet 2.3. Мы переместили в этот документ следующее:
jsp:include
может теперь указывать "flush='false'".PropertyEditor.setAsText()
может теперь использоваться для конвертации из
строкового литерального значения атрибута.ValidatorClass
и JspPage
- для проверки относительно библиотек
тэгов.IteratorTag
- для поддержки итерации без BodyContent
.
Добавлены две новые константы
(EVAL_BODY_BUFFERED
и EVAL_BODY_AGAIN
), чтобы легче документировать работу
протокола тэга; они были разработаны так, чтобы старые обработчики тэгов
продолжали работать без изменений, но использовать старое имя для константы -
EVAL_BODY_TAG
- теперь не рекомендуется.TagExtraInfo
в самых обычных ситуациях.resetCustomAttributes()
добавлен к интерфейсу Tag.JSP 1.2 базируется на Servlet 2.3, точнее: JSP 1.2 базируется на платформе Java 2.
Спецификация JSP 1.1 создана на основе спецификации JSP 1.0. Следующие изменения были внесены между окончательным вариантом спецификации JSP 1.0 и окончательны вариантом спецификации JSP 1.1.
uri
в директивах taglib
.flush
является теперь мандатным атрибутом в jsp:include
, и единственным
верным значением является "true".jsp:include
и jsp:forward
.pushBody()
и popBody()
добавлены к PageContext
.JspException
и JspTagException
.jsp:plugin
больше не может быть реализован простой посылкой содержимого jsp:fallback
клиенту.Данное приложение является справочником по главным концепциям данной спецификации.
Данное приложение является ненормативным.
taglib
.request
, response
, pageContext
, session
, application
,
out, config, page и exception."java"
. Синтаксически скриптлет ограничивается
символами <% и %>.Tag
или BodyTag
и являющийся представлением специальной акции на этапе прогона.Tag
или BodyTag
и
являющийся представлением специальной акции на этапе прогона.request
и обновляет объект response
. Класс реализации страницы может использовать
сервис, предоставляемый JSP-контейнером, включая API Servlet'а и API JSP.request
и обновляет объект response
.root
Web-приложения и, в среде J2EE, отображение безопасности и ресурсов.В этой главе даётся обзор технологии JavaServer Pages/Серверные Страницы Java.
JavaServer Pages≥ это технология Java≥ 2 Platform, Enterprise Edition (J2EE) для создания приложений, генерирующих динамическое web-содержимое - HTML, DHTML, XHTML и XML. Технология JavaServer Pages даёт возможность легко создавать динамическое содержимое web-страниц, предельно мощное и гибкое.
За некоторыми исключениями, интеграция JSP-страниц на платформу J2EE 1.3 наследуется из спецификации Servlet 2.3, поскольку трансляция превращает JSP-страницы в сервлеты.
В этой главе описываются обработчики тэгов и другие классы развёртывания тэгов,
а также методы доступа к файлам 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
предоставляет переносимый механизм для описания библиотек тэгов, включающий:
Tag Library Descriptor (TLD)/Дескриптор Библиотеки Тэгов (ДБТ)
Несколько классов обработчика тэга, определяющих поведение времени запроса
Несколько классов, определяющих поведение времени трансляции
Дополнительные ресурсы, используемые этими классами
Данная глава разбита на три раздела:
Первый раздел представляет базовые классы обработчика тэга.
Во втором разделе описаны более сложные обработчики тэга, которым необходим доступ к обсчёту их тела.
Последний раздел посвящён вопросам этапа/времени трансляции.
Этот раздел вводит понятие обработчика тэга и описывает простейшие типы обработчика тэга.
Обработчик тэга это объект времени выполнения, обслуживаемый контейнером,
обсчитывающий специальные акции в процессе выполнения
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
.
Tag
Синтаксис
public interface Tag
Все Известные Субинтерфейсы: BodyTag
, IterationTag
Описание
Это интерфейс простого обработчика тэга, который не хочет манипулировать своим содержимым.
Интерфейс Tag
определяет базовый протокол между обработчиком Tag
и классом реализации
JSP-страницы. Он определяет жизненный цикл и методы, вызываемые начальным и конечным тэгами.
Свойства
Интерфейс Tag
специфицирует
setter
и getter
-методы для основных свойств pageContext
и parent
.
Объект реализации JSP-страницы вызывает setPageContext
и setParent
в этом порядке до вызова
doStartTag
() или doEndTag
().
Методы
Есть две основные акции: doStartTag
и doEndTag
. После того как все соответствующие свойства
инициализированы, методы doStartTag
и doEndTag
могут быть вызваны обработчиком тэга. Между этими
вызовами принимается, что обработчик тэга имеет состояние, которое обязано
сохраняться. После вызова doEndTag
обработчик тэга доступен для последующих
вызовов (и предполагается, что сохраняет свои свойства).
Жизненный цикл
Детали жизненного цикла описываются ниже диаграммой перехода, со следующими комментариями:
[1] Этот переход предназначен для выпуска долгоживущих данных. Не даётся никаких гарантий долговечности свойств.
[2] Этот перенос происходит, если, и только если, тэг заканчивается нормально без вызова исключения.
[3] Заметьте, что, поскольку нет никаких гарантий статуса свойств, тэг, имеющий установленными какие-либо свойства по выбору/optional, может быть использован повторно, только если эти свойства устанавливаются в новое (известное) значение. Это значит, что обработчики тэгов могут использоваться только с тем же "AttSet" (набором установленных атрибутов).
Просмотрите интерфейс TryCatchFinally
на предмет дополнительных деталей
относительно обработки исключений и обслуживания ресурсов.
После того как все вызовы обработчика тэга выполнены, в нём вызывается метод release
.
После вызова метода release
, принимается, что все свойства, включая parent
и pageContext
, устанавливаются в неспецифицированное значение/unspecified
.
Компилятор страницы гарантирует, что release()
будет вызван в обработчике Tag
, до того как обработчик будет
освобождён для GC.
Пустые и Непустые Акции
Если файл TagLibraryDescriptor указывает, что акция обязана всегда быть пустой
акцией, через <body-content>
- "empty", тогда метод doStartTag
()
обязан возвращать SKIP_BODY
. В ином случае, метод doStartTag
() может вернуть SKIP_BODY
или
EVAL_BODY_INCLUDE
.
Если возвращён SKIP_BODY
, тело, если имеется, не обсчитывается.
Если возвращён EVAL_BODY_INCLUDE
, тело обсчитывается и "передаётся" текущему out
/выводу.
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
.
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_BUFFEREDBodyTag
.
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
.
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()
.
public static final int EVAL_BODY_AGAIN
Запрашивает повторение обсчёта некоторого тела/body.
Возвращается методом doAfterBody
. Для совместимости с JSP 1.1 значение должно
тщательно подбираться, чтобы быть тем же самым, что и в, теперь не рекомендуемом,
BodyTag.EVAL_BODY_TAG
.
public int doAfterBody()
Осуществляет (пере)обсчёт тела. Этот метод вызывается объектом реализации JSP-страницы
после каждого обсчёта тела в объекте BodyEvaluation
. Этот метод не вызывается, если нет обсчёта тела/body.
Если doAfterBody
возвращает
EVAL_BODY_AGAIN
, происходит новый обсчёт тела (с последующим вызовом doAfterBody
).
Если doAfterBody
возвращает SKIP_BODY
, обсчёт тела больше не производится, значение out
восстанавливается через использование метода popBody
в pageContext
, а затем
вызывается doEndTag
.
Повторные вызовы метода могут приводить к различным акциям, поскольку могли быть
произведены какие-то изменения разделяемого статуса, или из-за внешнего вычисления.
JSP-контейнер будет ресинхронизировать любые значения переменных, которые
обозначены в TagExtraInfo
, после вызова doAfterBody()
.
Возвращает: нужно ли проводить дополнительные обсчёты тела/body.
Вызывает: JspException
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(); // освобождает долгосрочные ресурсы
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
.
Этот метод предназначен для обслуживания целостности данных при вызове и акций обслуживания ресурсов.
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
и переопределять только некоторые методы.
protected java.lang.String id
protected PageContext pageContext
public TagSupport()
Конструктор по умолчанию, все классы должны определять только public-конструктор
с той же подписью и вызывать конструктор суперкласса. Этот конструктор
вызывается кодом, генерируемым JSP-транслятором.
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
для данного тэга.
Параметры:
-
idString
для id
.
public void setPageContext(PageContext pageContext)
Устанавливает контекст страницы.
Параметры:
-
pageContenxtPageContext
.
См. также:
public void setPageContext(PageContext pc)
public void setParent(Tag t)
Устанавливает вкладывающий тэг для данного тэга.
Параметры:
- родительский
tTag
.
См. также: public void setParent(Tag t)
public void setValue(java.lang.String k, java.lang.Object o)
Ассоциирует значение со String
-ключом.
Параметры:
-
kString
-ключ.
o
- Ассоциируемое значение.
Вычисление тела передаётся в объект
bodyContent
, который затем становится доступным обработчикам тэгов, реализующим интерфейс
BodyTag
. Класс
BodyTag-Support
даёт базовый класс, упрощающий написание этих обработчиков.
Если обработчик Tag
хочет иметь доступ к содержимому его тела, то он обязан
реализовывать интерфейс BodyTag
. Этот интерфейс расширяет IterationTag
, предоставляя два дополнительных метода
setBodyContent(bodyContent)
и
doInitBody()
и ссылаясь на объект типа bodyContent
.
это подкласс
bodyContentJspWriter
'а, имеющий
несколько дополнительных методов для конвертации его содержимого в 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)
.
bodyContent
Синтаксис
public abstract class bodyContent extends JspWriter
Описание
Инкапсулирует вычисление/обсчёт тела акции так, что доступен обработчику тэга. bodyContent
является подклассом JspWriter
'а.
Обратите внимание, что содержимое
bodyContent
'а является результатом вычисления, поэтому
оно не будет содержать акций и т.п., кроме результата своих вызовов.
имеет методы конвертации своего содержимого в
bodyContentString
, для чтения его
содержимого, и для очистки/clear своего содержимого.
Размер буфера объекта bodyContent
не ограничен. Объект bodyContent
не может быть
в режиме autoFlush
.
Невозможно вызвать flush
в объекте bodyContent
, так как
отсутствует фоновый/backing поток.
Экземпляры bodyContent
'а создаются через вызов методов pushBody
и popBody
класса PageContext
.
заключён внутри другого
bodyContentJspWriter
'а (возможно, другого объекта
bodyContent
), следуя структуре их ассоциированных акций.
становится доступным
bodyContentBodyTag
'у через вызов setBodyContent()
.
Обработчик тэга может использовать этот объект до момента вызова doEndTag()
.
protected bodyContent(JspWriter e)
Protected-конструктор. Несвязанный буфер, без autoflushing/автооочистки.
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
. Подклассы могут оптимизировать общие патэрны вызова.
Параметры:
- writer, в который помещается содержимое вычисления этого body.
out
Вызывает: IOException
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-страницы будет размещать вычисление/обсчёт (и повторный обсчёт, если нужно) тела.
-метод (
settersetBodyContent
) будет вызван только в том случае, если 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()
.
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
. Помечена как не рекомендуемая
с целью продвижения этих двух различных терминов, которые являются более описательными.
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
BodyTagSupport
Синтаксис
public class BodyTagSupport extends TagSupport implements BodyTag
Все Реализованные Интерфейсы: BodyTag
, IterationTag
, java.io.Serializable
, Tag
Описание
Базовый класс для определения обработчиков тэгов, реализующих BodyTag
.
Класс BodyTagSupport
реализует интерфейс BodyTag
и добавляет несколько удобных
методов, включая getter
-методы для свойства bodyContent
и методы для получения предыдущего
out JspWriter
.
Многие обработчики тэгов будут расширять
BodyTagSupport
и переопределять только несколько методов.
protected bodyContent bodyContent
public BodyTagSupport()
Конструктор по умолчанию, все подклассы должны определить public-конструктор с
той же подписью и вызвать конструктор суперкласса. Этот конструктор вызывается
кодом, генерируемым JSP-транслятором.
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-контейнер может выбрать выполнение некоторого обслуживания обработчика тэга.
Есть и другие стратегии, которым можно следовать.
В данном примере мы принимаем, что 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();
}
Акции могут кооперироваться с другими акциями и с кодом скриптинга разными способами.
PageContext
Часто две акции в JSP-странице нужно скооперировать: когда, возможно, одна акция
создаёт серверный объект, доступ к которому осуществляет вторая акция. Один из
механизмов реализации этого - дать объекту имя внутри JSP-страницы; первая акция
создаст объект и ассоциирует имя с ним, а вторая акция будет использовать это
имя для запроса объекта.
Например, в следующем JSP-фрагменте акция
foo
может создать серверный объект и дать ему имя "myObject"
. Затем акция
bar
может получить доступ к этому серверному объекту и выполнить какое-нибудь действие.
<x:foo id="myObject" />
<x:bar ref="myObjet" />
В JSP-реализации отображение "имя"->значение хранится в неявном объекте pageContext
.
Этот объект передаётся по кругу через экземпляры обработчика Tag
так, что он
(объект) может использоваться для передачи информации: всё, что необходимо, это
знать имя, под которым информация хранится в pageContext
.
Альтернативой явной передаче информации через именованный объект является
неявная координация на базе синтаксической видимости.
Например, в следующем JSP-фрагменте акция
foo могла бы создать серверный объект; затем вложенная акция
bar могла бы получить доступ к этому серверному объекту.
Этот объект не именован внутри pageContext
: он может быть найден, поскольку конкретный элемент
foo
является ближайшим содержащим экземпляром известного типа элемента.
<foo>
<bar/>
</foo>
Эта функциональность поддерживается через
BodyTagSupport.findAncestorWithClass(Tag, Class)
,
который использует ссылку на родительский тэг, сохраняемую каждым экземпляром Tag
,
что эффективно представляет стэк выполнения времени/этапа прогона.
Следующие классы используются на этапе трансляции.
Tag
-отображение, Tag
-имяДиректива taglib
вводит библиотеку тэгов и ассоциирует с ней префикс. TLD,
ассоциированный с библиотекой, ассоциирует классы обработчика Tag
(плюс другая
информация) с именами тэгов. Эта информация используется для ассоциирования Tag
-класса,
префикса и имени с каждым элементом специальной акции, появляющимся на JSP-странице.
На этапе выполнения реализация JSP-страницы будет использовать доступный
экземпляр Tag
с соответствующими установками свойств, а затем следовать
протоколу, описанному интерфейсами Tag
,
IterationTag
, BodyTag
и TryCatchFinally
. Реализация гарантирует, что все
экземпляры обработчика тэга инициализируются и высвобождаются, но реализация
может принимать, что предыдущие установки сохраняются обработчиком тэга, чтобы уменьшить затраты на этапе прогона.
JSP поддерживает переменные скриптинга, которые могут объявляться внутри одного
скриптлета и использоваться в другом. JSP-акции также можно использовать для
определения переменных скриптинга, чтобы использовать их затем в элементах
скриптинга или в других акциях. Это особенно применимо в некоторых случаях;
например, стандартная акция jsp:useBean
может определять объект, который позднее используется через
переменную скриптинга.
В некоторых случаях информация переменных скриптинга может быть описана
непосредственно в TLD, используя элементы. Особый случай - типичная итерация
атрибута "id"
. В других случаях логика, определяющая определение экземпляром
акции переменной скриптинга, может быть довольно сложной, и имя класса
TagExtraInfo
используется вместо данного в TLD.
Метод getVariableInfo
этого класса используется во время трансляции для получения
информации о каждой переменной, которая будет создана во время запроса, когда
данная акция выполняется. Метод передаётся в
TagDat
-экземпляр, содержащий значения атрибутов времени трансляции.
TLD-файл содержит несколько частей информации, которая используется для проверки
синтаксиса на этапе трансляции. Он содержит также два расширяемых механизма проверки: класс
TagLibraryValidator
может использоваться для проверки всей JSP-страницы, а класс
TagExtraInfo
может использоваться для проверки специфической акции. В некоторых
случаях дополнительная проверка на этапе запроса будет выполняться динамически
внутри методов в экземпляре Tag
. Если обнаружена ошибка, может быть вызван
экземпляр JspTagException
. Если ошибка не выловлена, этот объект будет
вызывать механизм errorpage JSP.
является дополнением к спецификации JSP 1.2 и заканчивается
очень открыто, будучи значительно более мощным, чем механизм
TagLibraryValidatorTagExtraInfo
.
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
страницы, в лексическом порядке их появления,
вызывается класс их ассоциированного проверщика (если имеется). Это вызывает
выполнение нескольких дополнительных шагов.
Первый шаг выполняется для получения инициализированного экземпляра проверщика путём, либо:
конструирования нового экземпляра и вызова в нём setInitParameters()
, либо
получения существующего объекта, который не используется, вызова в нём
и вызова следом в нём же release
()setInitParameters()
, либо
локализации существующего объекта, который не используется, в котором
необходимый setInitParameters()
уже вызван.
Имя класса - такое, какое указано в элементе <validator-class>
, а Map
,
переданный в setInitParameters()
- такой, как описано в элементе <init-params>
. Предполагается, что все
классы TagLibraryValidator
сохраняют свои initParameters
до тех пор, пока не будут
установлены новые или пока
не будет в них вызван.release
()
Второй дополнительный шаг выполняет реальную проверку. Это делается через вызов
метода validate()
с префиксом, uri
и PageData
, которые соответствуют
проверяемому экземпляру директивы taglib
и PageData
, представляющему эту страницу.
Последний дополнительный шаг вызывает метод
в тэге проверщика, когда он уже больше не нужен.
release
()
Этот метод освобождает все ресурсы.
Наконец,
после проверки всех классов проверщика библиотеки тэгов, классы TagExtraInfo
для
всех тэгов будут проверяться вызовом их метода isValid
. Порядок вызова этого метода не определён.
TagLibraryInfo
Синтаксис
public abstract class TagLibraryInfo
Описание
Это информация времени трансляции, ассоциированная с директивой taglib
и её
TLD-файлом. Большая часть информации получается непосредственно из TLD, за
исключением значений префикса и uri
, используемых в директиве taglib.
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
protected TagLibraryInfo(java.lang.String prefix, java.lang.String uri)
Конструктор. Будут вызываться конструкторы для TagInfo
и TagAttributeInfo
после разбора TLD-файла.
Параметры:
- префикс, используемый директивой
prefixtaglib
uri
- URI, используемый директивой taglib
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
для данной библиотеки.
TagInfo
Синтаксис
public class TagInfo
Описание
Информация Tag
для тэга в Библиотеке Тэгов; этот класс инстанциируется из файла TLD/Дескриптора Библиотеки Тэгов и доступна только во время трансляции.
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
.
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
- массив данных AttributeInf
o из дескриптора. Может быть 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
).
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}
Параметры:
-
dataTagData
, описывающие данную акцию.
Возвращает: массив элементов VariableInfo
.
public booleanisValid(TagData data)
Проверка атрибутов на этапе трансляции. Это удобный метод в
ассоциированном классе TagExtraInfo
.
Параметры:
- экземпляр
dataTagData
времени трансляции.
Возвращает: верны ли данные.
public void setTagExtraInfo(TagExtraInfo tei)
Набор экземпляров для дополнительной информации тэга.
Параметры:
tei
- экземпляр TagExtraInfo
.
public void setTagLibrary(TagLibraryInfo tl)
Устанавливает свойство TagLibraryInfo
.
Заметьте, что элемент TagLibraryInfo
зависит не просто от информации TLD, но
также и от специфики используемого экземпляра taglib
. Это означает, что
некоторая работа должна быть проделана для конструирования и инициализации
объектов TagLib
. Если использовать аккуратно, этот setter
поможет исключить
необходимость создания новых элементов TagInfo
для каждой директивы taglib
.
Параметры:
- назначаемый
tlTagLibraryInfo
.
public java.lang.String toString()
Строго для целей отладки ...
Переопределяет: java.lang.Object.toString()
в классе java.lang.Object
TagAttributeInfo
Синтаксис
public class TagAttributeInfo
Описание
Информация об атрибуте тэга, доступная во время трансляции. Этот класс инстанциируется из файла TLD.
Сюда включается только информация, необходимая для генерации кода. Друга
информация типа SCHEMA для проверки выводится в других местах.
public static final java.lang.String ID
окружается, чтобы стать
"id"ID
. Реально это не даёт преимущества, поскольку
IDREF
не обрабатываются раздельно.
public TagAttributeInfo(java.lang.String name, boolean required, java.lang.String type, boolean reqTime)
Конструктор для TagAttributeInfo
.
Этот класс инстанциируется только из кода TagLibrary
по запросу из
некоторого JSP-кода, разбирающего TLD.
Параметры:
- имя атрибута.
name
required
- необходим ли атрибут в экземплярах тэга.
type
- имя типа атрибута.
reqTime
- содержит ли данный атрибут Attribute
времени запроса.
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
PageData
Синтаксис
public abstract class PageData
Описание
Информация времени трансляции о
JSP-странице. Информация соответствует XML-просмотру JSP-страницы.
Объекты этого типа генерируются JSP-транслятором, например, при передаче экземпляру TagLibraryValidator
.
public PageData()
public abstract java.io.InputStream getInputStream()
Возвращает поток ввода в XML-просмотре JSP-страницы. Вызывает XML-просмотр JSP-страницы,
который содержит развёрнутые директивы include
.
Возвращает: поток ввода документа.
TagLibraryValidator
Синтаксис
public abstract class TagLibraryValidator
Описание
Класс проверщика этапа трансляции для JSP-страницы. Проверщик оперирует
документом XML, ассоциированным с JSP-страницей. TLD-файл ассоциирует класс
TagLibraryValidator
и некоторые init-аргументы с библиотекой тэгов.
JSP-контейнер отвечает за размещение соответствующих объектов соответствующего подкласса через:
новый экземпляр fresh
или через использование имеющегося экземпляра;
вызов метода setInitParams(Map)
в экземпляре после инициализации, метод
validate(String, String, PageData
) будет вызван там,
где первые два аргумента - это prefix
и uri
, используемые в директиве taglib
.
Экземпляр TagLibraryValidator
может создавать вспомогательные объекты внутри для
выполнения проверки (например, проверщик XSchema) и может использовать их для всех страниц в ходе данной трансляции.
JSP-контейнер не сериализует гарантированно вызовы метода validate()
,
и TagLibraryValidator
'ы должны выполнять синхронизацию, которая может потребоваться.
JSP-контейнер может по выбору поддерживать атрибут jsp:id
для предоставления
качественной проверки ошибок. Если такая поддержка имеется,
контейнер будет отслеживать JSP-страницы, передаваемые контейнеру, и будет
назначать каждому элементу уникальный "id"
, который передаётся как значение
атрибута jsp:id
. Каждый элемент XML, доступный в XML-просмотре, будет расширен этим атрибутом.
может затем использовать этот атрибут в
одном или более объектах
TagLibraryValidatorValidationMessage
. Контейнер тогда, в свою очередь, может использовать эти
значения для предоставления более точной информации о местонахождении ошибки.
public TagLibraryValidator()
public java.util.Map getInitParameters()
Получает данные init-параметров как неизменяемую Map/Карту. Имена параметров это ключи,
а значения параметров - это значения.
Возвращает: параметры init как неизменяемую карту.
public void release()
Высвобождает любые данные, хранимые этим экземпляром, с целью проверки.
)
public void setInitParameters(java.util.Map map
Устанавливает данные init
в TLD для этого проверщика. Имена параметров
это ключи, а значения параметров - это значения.
Параметры:
- карта, описывающая параметры
initMapinit
.
public ValidationMessage[] validate(java.lang.String prefix, java.lang.String uri, PageData page)
Проверяет JSP-страницу. Будет вызван однократно на каждую директиву в JSP-странице.
Этот метод возвратит null
, если страница верна/valid; иначе метод должен
возвратить массив объектов ValidationMessage
. Массив нулевой длины также
интерпретируется как отсутствие ошибок.
Параметры:
- значение аргумента
prefixprefix
в директиве.
uri
- значение аргумента uri
в директиве.
thePage
- JspData
-объект страницы.
Возвращает: null
-объект, или массив нулевой длины при отсутствии ошибок, или массив объектов
ValidationMessages
.
ValidationMessage
Синтаксис
public class ValidationMessage
Описание
Сообщение о проверке из TagLibraryValidator
. JSP-может (по выбору)
поддерживать атрибут jsp:id
для предоставления качественной проверки ошибок.
Если такая поддержка имеется, контейнер будет отслеживать JSP-страницы, передаваемые контейнеру, и будет
назначать каждому элементу уникальный "id", который передаётся как значение
атрибута jsp:id
. Каждый элемент XML, доступный в XML-просмотре, будет расширен
этим атрибутом. TagLibraryValidator
может затем использовать этот атрибут в
одном или более объектах ValidationMessage
. Контейнер тогда, в свою очередь, может использовать эти
значения для предоставления более точной информации о местонахождении ошибки.
public ValidationMessage(java.lang.String id, java.lang.String message)
Создаёт ValidationMessage
. String
сообщения должна быть не-null. Значение id
может быть null
, если сообщение не специфично для XML-элемента или если не были
переданы никакие атрибуты jsp:id
. Если не-null, значение id
обязано быть
значением атрибута jsp:id
для PageData
, передаваемым в метод validate()
.
Параметры:
- либо
idnull
, либо значение атрибута jsp:id
.
message
- локализованное сообщение о проверке.
public java.lang.String getId()
Получает jsp:id
.
null
означает, что нет доступной информации.
Возвращает: jsp:id
-информацию.
public java.lang.String getMessage()
Получает локализованное сообщение о проверке.
Возвращает: сообщение о проверке.
TagExtraInfo
Синтаксис
public abstract class TagExtraInfo
Описание
Класс по выбору, предоставляемый автором библиотеки тэгов для описания
дополнительной информации времени трансляции, не указанной в TLD. Класс TagExtraInfo
упоминается в файле TLD.
Этот класс может использоваться:
для указания на то, что тэг определяет переменные скриптинга;
для выполнения проверки атрибутов тэга на этапе трансляции .
JSP-транслятор отвечает за то, чтобы начальное значение, возвращаемое в вызове getTagInfo()
,
соответствовало объекту TagInfo
транслируемого тэга.
Если выполняется явный вызов setTagInfo()
, тогда передаваемый объект будет
возвращён в последующих вызовах getTagInfo()
.
Единственный способ повлиять на значение, возвращаемое методом getTagInfo()
, -
через вызов setTag-Info()
и, следовательно, TagExtraInfo.setTagInfo()
вызывается JSP-транслятором с
объектом TagInfo
, который соответствует транслируемому тэгу. Это должно
происходить до любого вызова isValid()
и до любого вызова
getVariableInfo()
.
public TagExtraInfo()
public final TagInfo getTagInfo()
Получает TagInfo
для этого класса.
Возвращает: экземпляр taginfo
, расширяемый данным экземпляром.
public VariableInfo[] getVariableInfo(TagData data)
Информация о переменных скриптинга, определённых тэгом, ассоциированным с
данным экземпляром TagExtraInfo
. Атрибуты времени запроса указаны как таковые в параметре
TagData
.
Параметры:
- экземпляр
dataTagData
.
Возвращает: массив данных VariableInfo
.
public boolean
isValid(TagData data)
Проверка атрибутов на этапе трансляции. Атрибуты времени запроса указаны
как таковые в параметре TagData
.
Параметры:
- экземпляр
dataTagData
.
Возвращает: верен ли этот экземпляр тэга.
public final void setTagInfo(TagInfo tagInfo)
Устанавливает TagInfo
для данного класса.
Параметры:
-
tagInfoTagInfo
, расширяемая этим экземпляром.
TagData
Синтаксис
public class TagData implements java.lang.Cloneable
Все Реализованные Интерфейсы:
java.lang.Cloneable
Описание
Информация (только времени трансляции)
атрибута/значения для экземпляра тэга. TagData
используется только в качестве аргумента методов isValid
и getVariableInfo
в TagExtraInfo
, которые вызываются во время трансляции.
public static final java.lang.Object REQUEST_TIME_VALUE
Значение, отличное от атрибута, для указания, что его (атрибута) значение
является выражением времени запроса (которое ещё не доступно, поскольку
экземпляры TagData
используются на этапе трансляции).
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
.
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
- значение.
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 определяет интерпретацию трёх значений:
NESTED
, если переменная скриптинга доступна между начальным и конечным тэгами
акции, которая определяет её.
AT_BEGIN
, если переменная скриптинга доступна из начального тэга акции, которая
определяет её, до достижения предела видимости.
AT_END
, если переменная скриптинга доступна после конечного тэга акции, которая
определяет её, до достижения предела видимости.
Значение области видимости переменной предполагает, какие методы влияют на значение и, следовательно, где нужна синхронизация:
для NESTED
, после doInitBody
и
doAfterBody
для обработчика тэга, реализующего
BodyTag
, и после doStartTag
- в противном случае.
для AT_BEGIN
, после doInitBody
,
doAfterBody
и doEndTag
для обработчика тэга, реализующего BodyTag
, и
doStartTag
и doEndTag
- в противном случае.
для AT_END
, после метода doEndTag
.
Информация переменной скриптинга может быть также непосредственно кодирована для
большинства случаев в Tag Library Descriptor путём использования субэлемента <variable>
элемента <tag>
. См. спецификацию JSP.
public static final int AT_BEGIN
Информация области видимости о том, что переменная скриптинга видна после
начального тэга.
public static final int AT_END
Информация области видимости о том, что переменная скриптинга видна после конечного тэга.
public static final int NESTED
Информация области видимости о том, что переменная скриптинга видна
только между начальным/конечным тэгами.
public VariableInfo(java.lang.String varName, java.lang.String className, boolean declare, int scope)
Конструктор. Эти объекты могут быть созданы (на этапе трансляции) экземплярами TagExtraInfo
.
Параметры:
- имя переменной скриптинга.
id
className
- имя переменной скриптинга (наверное, класса??).
declare
- если true
, это новая переменная (в некоторых языках это требует объявления).
scope
- обозначение лексической области видимости переменной.
public java.lang.String getClassName()
public boolean getDeclare()
public int getScope()
public java.lang.String getVarName()
TagVariableInfo
Синтаксис
public class TagVariableInfo
Описание
Информация переменной для тэга в Библиотеке Тэгов. Этот класс инстанциируется из TLD-файла и доступен только во время трансляции. Этот объект должен быть неизменяемым.
Данная информация доступна только в формате JSP 1.2.
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>
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>
.
Возвращает: область видимости для переменной.
В этой главе описаны синтаксис ядра и семантика спецификации JavaServer Pages 1.2 (JSP 1.2).
JSP-страница это текстовый документ, который описывает, как создавать объект response
из объекта request для данного протокола. Процессинг JSP-страницы может
включать создание и/или использование других объектов.
JSP-страница определяет класс реализации JSP-страницы который реализует
семантику JSP-страницы. Этот класс является подклассом Servlet'а (см.
Главу JSP.8). Во время запроса, запрос, предназначенный для JSP-страницы,
направляется объекту реализации JSP-страницы для обработки/процесинга.
HTTP является протоколом по умолчанию для запросов и ответов. Дополнительные
протоколы запроса/ответа могут поддерживаться JSP-контейнерами (см. ниже).
Объекты request
и response
по умолчанию имеют тип HttpServletRequest
и
HttpServletResponse
, соответственно.
JSP-контейнер это экземпляр системного уровня, предоставляющий
обслуживание жизненного цикла и поддержку на этапе прогона для JSP-страниц Servlet-компонентов.
Запросы, направляемые JSP-странице, направляются JSP-контейнером подходящему
объекту реализации JSP-страницы. Термин web-контейнер
является синонимом JSP-контейнера.
Web-компонент это сервлет или JSP-страница. Элемент servlet
в дескрипторе публикации
web.xml используется для описания обоих типов web-компонентов. Компоненты - JSP-страницы
- определяются неявно в дескрипторе публикации через использование неявного
отображения расширения .jsp
JSP-страницы имеют эквивалент - XML-документ. XML-просмотр JSP-страницы создан для фазы трансляции
(см. ниже).
JSP-страница может быть написана сразу как XML-документ. Начиная с версии JSP
1.2, XML-документ может быть направлен JSP-контейнеру для процесинга.
Нельзя смешивать стандартный синтаксис и XML-синтаксис в одном файле-источнике.
Однако JSP-страница любого синтаксиса может включать JSP-страницу любого
синтаксиса через директиву.
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-страница может отмечать обработку некоторых событий. В JSP 1.2 только события init и destroy могут быть описаны в JSP-странице.
Когда первый запрос направляется JSP-странице, метод
jspInit()
, если он имеется,
будет вызван для подготовки страницы.
Аналогично, JSP-контейнер может вызывать метод JSP jspDestroy()
для переделки ресурсов, используемых JSP-страницей, в любой момент, когда запрос
не обслуживается. Это такой же жизненный цикл, что и у сервлетов.
JSP-страница может быть откомпилирована в свой класс реализации, плюс
информация публикации в процессе создания (JSP-страница может также
компилироваться в процессе публикации).
Таким способом утилиты авторизации JSP-страниц и библиотеки тэгов JSP могут
использоваться для создания сервлетов. Преимущества этого подхода таковы:
Компиляция JSP-страницы в контексте web-приложения предоставляет разрешение
спецификаций относительных URL в директивы include
(и в другом месте),
ссылок на taglib
и акции времени трансляции, используемых в специальных акциях.
JSP-страница может также компилироваться во время публикации.
Когда класс реализации JSP-страницы зависит от поддержки классов (в дополнение к классам JSP 1.2 и Servlet 2.3), классы поддержки включаются в упакованный WAR-файл (как определено в спецификации Servlet 2.3) для обеспечения переносимости по JSP-контейнерам.
В Приложении JSP.A есть два примера упаковки JSP-страниц в WAR'ы:
В информации для публикации указаны необходимые поддерживающие классы и отображение между путём оригинального URL в JSP-страницу и URL для класса реализации этой JSP-страницы.
Раньше утилиты отладки не имели стандартного формата для передачи информации отображения исходного кода, позволяющей использовать отладчик одного производителя с JSP-контейнером другого. Спецификация с поддержкой отладки, преодолевшая эти ограничения, разрабатывается как JSR-045 процесса JCP 2.0 под названием "Debugging Support for Non-Java Languages/Поддержка Отладки для Не-Java-Языков".
Детали можно найти по адресу
http://jcp.org/jsr/detail/45.jsp
JSP-страница упаковывается в один или более файлов, часто - как web-приложение,
и направляется утилите типа JSP-контейнера, J2EE-контейнера или IDE. Полная JSP-страница
может содержаться в одном файле. В других случаях основной файл содержит другие
файлы, которые содержать полные JSP-страницы или включаемые фрагменты.
Утилиты обычно требуют отделения файлов JSP-страницы от других файлов.
В некоторых случаях утилиты также требуют отделения файлов верхнего уровня/top JSP
от включаемых фрагментов. Например, если фрагмент может не быть правильной JSP-страницей
и может не компилироваться соответствующим образом.
Определение типа файла также часто практикуется на уровне документации и
обслуживания, как должно быть уже известно тем, кто работает с соглашениями ".c"
и ".h" языка C.
Спецификация Servlet 2.3 использует расширение ".jsp" для обозначения JSP-страницы,
но не дифференцирует основные JSP-файлы и включаемые фрагменты.
Мы рекомендуем (но не обязываем), чтобы:
Приложение web это коллекция ресурсов, которые доступны по указанным URL.
Web-приложение состоит из следующих компонентов:
Web-приложения описаны более детально в спецификации Servlet 2.3.
Web-приложение содержит дескриптор публикации
web.xml, содержащий информация о JSP-страницах,
сервлетах и других ресурсах, используемых в этом web-приложении. Дескриптор
публикации детально описан в спецификации Servlet 2.3.
JSP 1.2 требует, чтобы эти ресурсы были неявно/косвенно ассоциированы с, и доступны через, уникальный экземпляр
ServletContext
, доступный как неявный объект приложения (Раздел JSP.2.8).
Приложение, которому принадлежит JSP-страница, отражается в объекте
application
и влияет на семантику следующих элементов:
include
(Раздел JSP.2.10.3).jsp:include
(Раздел JSP.4.4).jsp:forward
(Раздел JSP.4.5).JSP 1.2 поддерживает переносимую упаковку и публикацию/deployment web-приложений через спецификацию Servlet 2.3. Спецификация JavaServer Pages наследует от спецификации Servlet концепцию приложений, ServletContext'ы, Sessions/Сессии, Requests/Запросы и Responses/Ответы.
Элементы могут использовать спецификации относительных 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-страниц.
JSP-страница содержит элементы и шаблонные данные.
Элемент является экземпляром типа элемента, известного JSP-контейнеру.
Шаблонные данные это то, о чём JSP-танслятор ничего не знает.
Тип элемента описывает его синтаксис и семантику. Если элемент имеет атрибуты, тип описывает имена, верные типы атрибутов и их интерпретацию. Если элемент определяет объекты, семантика включает эти определяемые объекты и их типы.
Имеются элементы трёх типов: директивы, элементы скриптинга и акции.
Директивы предоставляют глобальную информацию, которая концептуально верна, независимо от специфики запроса, полученного JSP-страницей. Директивы предоставляют информацию для фазы трансляции.
Синтаксис элемента-директивы
<%@ директива...%>
Акции предоставляют информацию для фазы обработки запроса. Интерпретация
акции может, и часто так и бывает, зависеть от специфики запроса,
полученного JSP-страницей.
Акции могут быть стандартными, то есть
определёнными этой спецификацией, или
custom/специальными, то есть предоставленными через посредство механизма
развёртывания переносимых тэгов.
Элементы action
следуют синтаксису XML-элемента: они имеют начальный тэг, включающий имя
элемента, и могут иметь атрибуты, необязательное тело/body и соответствующий
конечный тэг, или они могут быть пустыми тэгами, возможно, с атрибутами:
<mytag attr1="значение атрибута"...>body</mytag>
и
<mytag attr1="значение атрибута".../>
<mytag attr1="значение атрибута" ...></mytag>
Элемент имеет тип элемента, описывающий имя его тэга, верные атрибуты и их семантику.
Мы обращаемся к типу по имени его тэга.
JSP-тэги чувствительны к регистру, как в XML и XHTML.
Акция может создавать объекты и делать их доступными элементам скриптинга через
специфические для скриптинга переменные.
Элементы Скриптинга являются связкой между шаблонным текстом и акциями.
Есть три типа элементов скриптинга:
declarations\объявления, scriptlets\скриптлеты и expressions\выражения.
Объявления имеют синтаксис
<%! ... %>
скриптлеты
<% ... %>
выражения
<%= ... %>
Элементы, имеющие разные начальный и конечный тэги (при наличии тела), обязаны
иметь начало и конец в одном файле. Стартовый тэг не может быть в одном файле,
когда конечный тэг находится в другом файле.
То же самое правило применяется к элементам с альтернативным синтаксисом.
Например, скриптлет имеет синтаксис
<% скриптлет %>
.
Открывающий <%
и закрывающий %>
символы обязаны находиться в одном
и том же физическом файле.
Язык скриптинга может также вводить ограничения на размещение начальных и
конечных тэгов для специфических конструкций скриптинга. Например, в
Главе 6
демонстрируется, как блоки языка Java не могут разделять начальный и конечный
тэг; см. детали в Разделе JSP.6.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>
Следуя спецификации XML, атрибуты всегда заключаются в кавычки. Одинарные или двойные кавычки могут использоваться для уменьшения необходимости ввода кавычек мнемониками; соглашения по кавычкам описаны в Разделе JSP.2.6. Есть два типа значений атрибутов: литералы и выражения времени запроса (Раздел JSP.2.13.1), но правила применения кавычек - одинаковы.
Имена акций обязаны следовать соглашению XML (т.е. обязаны быть NMTOKEN
, как указано
в спецификации XML 1.0). Имена атрибутов обязаны следовать соглашениям, описанным в спецификации JavaBeans.
Имена атрибутов, начинающиеся с jsp,
_jsp, java или sun зарезервированы данной спецификацией.
В HTML и XML пробел обычно не является значащим, но есть исключения.
Например, файл XML может начинаться символами
<?xml
, и,
если это так, ведущих пробельных символов не должно быть.
Данная спецификация следует поведению пробелов, определённому в спецификации XML.
Пробел в теле текста документа не является значащим, но сохраняется.
Далее идут два фрагмента JSP с ассоциированным выводом.
Обратите внимание, что директивы не генерируют никаких данных и применяются глобально к
JSP-странице.
N Строки | Исходный Текст |
---|---|
1 |
<?xml version="1.0" ?>
|
2 | <%@ page buffer="8kb" %> |
3 | Здесь - остальная часть документа. |
Результат:
N Строки | Текст на Выходе |
---|---|
1 |
<?xml version="1.0" ?>
|
2 | |
3 | Здесь - остальная часть документа. |
Следующие две таблицы - другой пример ввода и вывода:
N Строки | Исходный Текст |
---|---|
1 |
<% response.setContentType("....");
|
2 | что-нибудь... %><?xml version="1.0" ?>
|
3 |
<%@ page buffer="8kb" %>
|
4 | Здесь - остальная часть документа. |
Результат:
N Строки | Текст на Выходе |
---|---|
1 |
<?xml version="1.0" ?>
|
2 | |
4 | Здесь - остальная часть документа. |
Ошибки могут появляться на этапах трансляции или запроса. В этом разделе описывается, как ошибки обрабатываются соответствующей реализацией.
Трансляция JSP-страницы-источника в соответствующий класс реализации JSP-страницы JSP-контейнером
может производиться в любой момент между начальной публикацией JSP-страницы в JSP-контейнер
и получением и обработкой запроса клиентом целевой JSP-страницы.
Если трансляция возникает до получения клиентского запроса целевой JSP-страницы,
обработка ошибок и уведомление зависят от реализации и не рассматриваются в
данной спецификации. Фатальные ошибки трансляции должны в результате приводить к
невозможности выполнения последующих клиентских запросов на трансляцию целевой
страницы с соответствующей спецификацией ошибки:
для протоколов HTTP будет возвращаться код ошибки 500 (Server Error/Ошибка Сервера).
В процессе обработки запросов клиентов ошибки могут возникать в теле класса
реализации 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-странице есть два типа комментариев:
комментарии к самой JSP-странице, документирующие действия страницы, и
комментарии, предназначенные для вывода в генерируемом документе, направляемом клиенту.
Для генерации комментариев, появляющихся в потоке вывода response
к
запрашивающему клиенту, используется следующий синтаксис комментариев HTML и XML:
<!-- комментарии
... -->
Такие комментарии рассматриваются JSP-контейнером как неизменяемый шаблонный
текст. Если генерируемый комментарий должен содержать динамические данные, это
может быть сделано посредством такого синтаксиса:
<!-- комментарии
<%= выражение %> ещё комментарии ... -->
JSP-комментарий имеет форму:
<%-- что-либо, кроме закрывающих символов --%> ... --%>
Содержимое тела комментария полностью игнорируется. Комментарии используются для
документирования, а также для
"закомментирования" некоторой части JSP-страницы.
Обратите внимание, что JSP-комментарии не вкладываются.
Альтернативным способом размещения "комментария" на JSP-странице является
использование механизма комментария языка скриптинга. Например:
<% /** это комментарий ... **/ %>
В JSP-страницах применяются следующие соглашения по кавычкам:
Литерал %>
закавычивается %\>
Литерал <%
закавычивается <\%
Закавычивание выполняется независимо от того, является значение атрибута
литералом или выражением атрибута этапа запроса. Закавычивание может
использоваться в значениях атрибутов независимо от того, ограничены они
одинарными или двойными кавычками. Это выполняется только так, как описано ниже:
\'
. Это необходимо делать внутри значения атрибута,
ограниченного одинарными кавычками.\"
. Это необходимо делать внутри значения атрибута,
ограниченного двойными кавычками.\\
%>
записывается %\>
<%
записывается <\%
В следующей строке показаны неправильные значения атрибутов:
<mytags:tag value="<%= "hi!" %>"
/>
В следующей строке дан верный скриптлет, но с, возможно, неожиданным результатом. Результат будет "Joe said %\>", а не "Joe said %>":
<%= "Joe said %\\>" %>
В следующих строках - правильное закавычивание:
<%= "Joe said %/>" %>
<%= "Joe said %\>" %>
<% String joes_statement = "hi!";
%>
<%= "Joe said \"" + joes_statement
+ "\"." %>
<x:tag value='<%="Joe said \\"" +
joes_statement + "\\"."%>'/>
<x:tag value='<%= "hi!" %>' />
<x:tag value="<%= \"hi!\" %>" />
<x:tag value='<%= \"name\" %>' />
<x:tag value="<%= \"Joe said
'hello'\" %>"/>
<x:tag value="<%= \"Joe said
\\\"hello\\\" \" %>"/>
<x:tag value="end expression
%\>"/>
<% String s="abc"; %>
<x:tag value="<%= s + \"def\" + \"jkl\"
+ 'm' + \'n\' %>" />
<x:tag value='<%= s + \"def\" + "jkl"
+ \'m\' + \'n\' %>' />
Соглашения по кавычкам отличаются от соглашений XML. См. Главу JSP.5.
Класс реализации JSP-страницыопределяет отображение метода _jspService()
из объекта request в объект response. Некоторые детали этой
трансформации специфичны для используемого языка скриптинга (см.
Главу JSP.6).
Некоторые детали не зависят от языка и описаны в данной главе.
Содержимое JSP-страницы большей частью описывает данные, которые записываются в
поток вывода ответа. (JSP-контейнер обычно посылает эти данные обратно клиенту.)
Это описание базируется на объекте JspWriter
, который выводится через неявный объект
out (см. Раздел JSP.2.8.3, "Неявные Объекты).
Его значение варьируется:
JspWriter
. Этот объект может отличаться
от объекта stream, возвращаемого от response.getWriter()
, и может рассматриваться
как вставляемый позднее в последнем, чтобы
реализовать буферизацию (см. Раздел JSP.2.10.1, "Директива page
").
Это - начальный объект out. Авторам JSP-страниц запрещено записывать
непосредственно в
PrintWriter
или OutputStream
, ассоциированные с
ServletResponse
.response.getWriter()
до тех пор, пока первая часть содержимого не будет
переслана клиенту. Здесь поднимаются вопросы использования JSP, включая использование JSP
как языка для 'склейки' акций, дающих бинарный контекст, или надёжного
перенаправления сервлету, или динамического изменения типа содержимого ответа
до генерации содержимого. См. Главу JSP.3.JspWriter
. То, какой это случай, зависит от деталей семантики акции. Обычно
содержимое этих временных потоков присоединяется к потоку, на который out
ссылался перед этим, и out последовательно переназначается для того,
чтобы ссылаться на предыдущий (внешний) поток. Такие вложенные потоки всегда
буферизуются и требуют явной очистки/flushing, чтобы выгрузить вкладывающие потоки и их содержимое.JspWriter
буферизуется, тогда, в зависимости от значения атрибута
autoFlush
директивы page
, содержимое этого буфера будет либо автоматически очищаться перед потоком
вывода ServletResponse
, чтобы избежать переполнения, либо должно вызываться
исключение, чтобы сигнализировать о переполнении буфера. Если начальный out-объект
JspWriter
не буферизуется, тогда содержимое, записанное в него, будет передано прямо в поток вывода
ServletResponse
.JSP-страница может создавать и модифицировать серверные объекты/server-side и
получать к ним доступ.
Объекты могут быть сделаны видимыми для акций и элементов
скриптинга. Объект имеет scope\область видимости, которая описывает,
какие экземпляры могут получать доступ к объекту.
Акции могут получать доступ к объекту, используя имя в объекте
PageContext
. Объект, видимый через переменную
скриптинга, имеет область видимости в пределах страницы.
Элементы скриптинга могут получать доступ к объектам непосредственно через
переменную скриптинга.
Некоторые неявные объекты видны через переменные скриптинга на любой
JSP-странице.
Объект может быть сделан доступным для кода в элементах скриптинга через переменную языка скриптинга.
Элемент может определять переменные скриптинга,
которые будут содержать, в процессе времени запроса, ссылку на объект, определённый этим элементом,
хотя могут существовать и другие ссылки, в зависимости от области видимости объекта.
Тип элемента указывает имя и тип таких переменных, хотя в деталях имя переменной
может зависеть от Языка Скриптинга.
Язык скриптинга может также влиять на то, как происходит доступ к различным
свойствам объекта. Например, в спецификации
JavaBeans доступ к свойствам осуществляется через методы
getter
и setter, в то время как эти свойства доступны напрямую как переменные в
языке JavaScript≥.
Точные правила видимости переменных зависят от языка скриптинга. В
Главе JSP.2.1
определены правила для случая, когда атрибут
language
директивы page
установлен в "java"
.
JSP-страница может создавать и/или получать доступ к Java-объектам при обработке
запроса. Спецификация JSP указывает, что некоторые объекты создаются неявно,
возможно, как результат директивы
(см. Раздел JSP.2.8.3, "Неявные Объекты"). Другие объекты создаются явно через
акции или непосредственно путём использования кода скрипта. Созданные объекты
имеют атрибут scope, определяющий, где находится ссылка на объект и когда
эта ссылка удаляется.
Созданные объекты могут также непосредственно видимы элементам скриптинга через
переменные уровня скриптинга (см. Раздел JSP.2.8.3, "Неявные Объекты").
Каждая акция и объявление определяют, как часть своей семантики, какой объект
они создают, с каким атрибутом scope
и доступны ли они элементам скриптинга.
Объекты создаются внутри экземпляра JSP-страницы, которая отвечает объекту request.
Имеется несколько областей видимости:
pageContext
.request
.session
из страницы, которая не находится в данной сессии (см.
Раздел
JSP.2.10.1, "Директива page"). Все ссылки на такой объект должны быть
разорваны после того, как ассоциированная сессия закончилась. Ссылки на
объекты с областью видимости session хранятся в объекте session
,
ассоциированном с активацией страницы.application
, ассоциированном с активацией страницы. Объект application
является
контекстом сервлета, получаемым из объекта конфигурации сервлета. Все ссылки
на этот объект должны быть разорваны, когда рабочая среда/runtime environment запрашивает ServletContext
.Имя/name должно ссылаться на уникальный объект из всех точек в ходе выполнения, то есть все области видимости должны в действительности вести себя как единое пространство имён. Реализация JSP-контейнера может или может не форсировать это правило явно по соображениям производительности.
Авторы JSP-страниц имеют доступ к определённым неявным (неявно создаваемым) объектам,
которые всегда доступны для использования в скриптлетах и выражениях через
переменные скриптинга, которые объявляются неявно в начале страницы. Все языки
скриптинга должны предоставлять доступ к этим объектам.
Неявные объекты доступны обработчикам тэгов через объект pageContext
(см. ниже).
Каждый неявный объект имеет тип класса или интерфейса, определённый в основной
технологии Java или в пакете Java Servlet API, как
показано в Таблице JSP. 2-1.
Имя Переменной | Тип | Семантика & Области Видимости |
---|---|---|
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.
pageContext
PageContext
это объект, предоставляющий контекст для хранения ссылок на объекты,
используемые страницей. Он инкапсулирует зависящие от реализации свойства и
предоставляет нужные методы. Класс реализации JSP-страницы может использовать
PageContext для прогона в неизменённом виде в любом подходящем JSP-контейнере,
одновременно используя преимущества специфичных для реализации улучшений типа
высокопроизводительного JspWriters
.
См. детали в Главе JSP.9.
Имя Переменной | Тип | Семантика & Область Видимости |
---|---|---|
|
java.lang.Throwable
|
Неотловленный Throwable ,
приводящий к вызову страницы информации об ошибках.Область видимости: page . |
Имена объектов с префиксами jsp, _jsp, jspx и _jspx, в любой комбинации нижнего и верхнего регистров, зарезервированы данной спецификацией JSP. См. в Разделе JSP.7.6.1 некоторые ненормативные соглашения для введения новых неявных объектов.
Семантика шаблонного (или неинтерпретированного) Текста очень проста:
шаблонный текст передаётся текущему out\выводящему неявному объекту
JspWriter
после применения замен Раздела JSP.2.6,
"Соглашения по Кавычкам и Escape-Последовательностям".
Директивы являются сообщениями JSP-контейнеру.
Синтаксис директивы:
<%@ директива {
атрибут="значение" }* %>
Могут иметься необязательные пробелы после "<%@" и перед "%>".
Это синтаксис легко вводится и понятен, но он несовместим с XML.
В Главе JSP.5 описано отображение директив в элементы XML.
Директивы не производят никакого вывода в текущий поток out.
Есть три директивы:
page
и taglib
описаны здесь, а директива include
- в следующей главе.
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"
Далее дана детальная информация об атрибутах:
Атрибут | Описание |
---|---|
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" с необязательным пробелом после ";". |
pageEncoding
|
Определяет кодировку символов для JSP-страницы.
Значения имеют форму "CHARSET", который обязан быть IANA-значением для кодировки символов.
Значение contentType для CHARSET используется по умолчанию, если
имеется, в противном случае - ISO-8859-1.
См. в Главе 3 детальную информацию о кодировках символов. |
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" %>
где атрибуты:
uri
|
Спецификация абсолютного или относительного URI, который
уникально идентифицирует дескриптор библиотеки тэгов, ассоциированной с данным префиксом. URI используется для локализации описания библиотеки тэгов, как указано в Главе 7. |
tagPrefix
|
Определяет строку prefix в конструкции
<prefix>:<tagname> , которая используется для отличения специальной
акции, например, <myPrefix:myTag> .Использование префиксов, начинающихся с jsp:, jspx:, java:, javax:, servlet:, sun: и sunw:, зарезервировано. Префикс обязан следовать соглашению об именовании, специфицированному в спецификации пространств имён XML. Пустые префиксы в данной версии спецификации не допускаются. |
Фатальная ошибка трансляции возникнет, если транслятор JSP-страницы обнаруживает
тэг с именем prefix: Name,
использующий префикс, введённый директивой taglib
,
и если Name не распознаётся соответствующей библиотекой тэгов.
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-страницы. Соответственно, спецификация JSP 1.2 имеет два механизма включения для различных задач. Обобщение их семантики дано в Таблице JSP.2-1.
include
в спецификации JSP 1.2Синтаксис | Спецификация | Объект | Описание | |
---|---|---|---|---|
Директива 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 объекту; т.е.
запрос направляется этому объекту, и результат процессинга включается .
Элементы скриптинга обычно используются
для манипулирования объектами и для выполнения вычислений, влияющих на генерируемое содержимое.
Есть три класса элементов скриптинга: 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-странице. Объявление должно быть декларативным
оператором или последовательность операторов, соответствующей синтаксису
специфицированного языка скриптинга.
Объявления не производят никакого вывода в текущий поток вывода.
Объявления инициализируются в момент инициализации JSP-страницы и становятся
доступными другим объявлениям, скриптлетам и выражениям.
Например, первое объявление здесь объявляет целое число, глобальное в пределах страницы.
Второе объявление делает то же самое и инициализирует число в нуль. Этот тип
инициализации должен выполняться осторожно при наличии нескольких запросов к
странице.
В третьем случае объявляется метод, глобальный в пределах страницы.
<%! int i; %>
<%! int i = 0;
%>
<%! public String f(int i) { if (i<3) return("..."); ... } %>
<%!
объявление(-я) %>
Скриптлеты могут содержать любые фрагменты кода, которые являются верными для
языка скриптинга, специфицированного директивой
language
. Является ли фрагмент кода действующим, зависит от деталей языка
скриптинга (см. Главу JSP.6).
Скриптлеты выполняются во время обработки запроса. Производят они вывод в поток
вывода или нет, зависит от кода скриптлета.
Скриптлеты могут иметь побочные эффекты,
модифицируя объекты, видимые для них.
Когда все фрагменты скриптлетов в данном трансляционном модуле комбинируются для появления на JSP-странице,
они обязаны давать в результате верный оператор или последовательность
операторов на специфицированном языке скриптинга.
Чтобы использовать последовательность символов
%> как литеральные символы в скриптлете, вместо того , чтобы они оканчивали
скриптлет, вводите их так %\>.
Вот простой пример динамического изменения страницы, в зависимости от времени суток.
<% if
(Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM) {%>
Good Morning
<% } else { %>
Good Afternoon
<% } %>
Скриптлет может также содержать объявление локальных переменных, например, следующий скриптлет просто объявляет и инициализирует целое число и затем отображает это число и увеличивает его.
<% int i; i= 0;
%>
Привет, значение
i равно <% i++ %>
<% скриптлет %>
Элемент expression
в JSP-странице является выражением языка скриптинга, которое
вычисляется, а результат приводится к String
.
Результат затем посылается в текущий объект вывода JspWriter
.
Если результат выражения не может быть приведён к String
, обязаны выполняться следующие действия:
Если проблема обнаружена на этапе трансляции, должна возникать ошибка времени трансляции.
Если приведение не обнаруживается в процессе трансляции, должно вызываться исключение
ClassCastException
/ОшибкаПриведенияКласса во время запроса.
Язык скриптинга может поддерживать побочные эффекты в выражениях, когда выражение вычисляется.
Выражения вычисляются слева направо на JSP-странице. Если выражения появляется в
более чем одном атрибуте времени выполнения, они должны вычисляться слева
направо в тэге. Выражение может изменять значение объекта out
, хотя это не всегда легко выполнимо.
Выражение обязано быть полным выражением языка скриптинга, на котором оно написано.
Выражения вычисляются во время HTTP-процессинга.
Значение выражения конвертируется к String и вставляется в соответствующую позицию в .jsp-файл.
Вставляется текущая дата:
<%= (new
java.util.Date()).toLocaleString() %>
<%= выражение
%>
Акции могут воздействовать на текущий поток вывода и использовать,
модифицировать и/или создавать объекты.
Акции могут зависеть от деталей конкретного объекта request/запроса, получаемого JSP-страницей.
Данная спецификация JSP содержит некоторые акции, которые являются
стандартными и обязаны реализовываться всеми соответствующими JSP-контейнерами;
эти акции описываются в Главе 4.
Новые акции определяются в соответствии с механизмами, описанными в Главах 7
и 10, и вводятся с использованием директивы taglib
.
Синтаксис элементов акций базируется на XML. Акции могут быть пустыми и непустыми.
Интерпретация всех акций начинается с вычисления значений, данных их атрибутам,
слева направо и присвоения этих значений атрибутам. В этом процессе могут
производиться конверсии; правила конверсии описаны в Разделе JSP.2.13.2.
Многие значения являются фиксированными 'значениями времени трансляции', но JSP 1.2
предоставляет также механизм описания этих значений, когда они вычисляются на
этапе запроса, правила описаны в Разделе JSP.2.13.1.
Значение атрибута в форме
"<%= scriptlet_expr %>"
или '<%= scriptlet_expr %>'
обозначает значение атрибута времени запроса.
Указываемое значение является значением включаемого скриптлета. Значения
атрибутов времени запроса могут использоваться только в акциях и не могут
использоваться в директивах. Если в тэге имеется более одного такого атрибута,
выражения вычисляются слева направо.
Закавычивание выполняется так же, как и в других значениях атрибута (Раздел JSP.2.6).
Таким способом могут обозначаться только значения атрибута (имя атрибута всегда
является явно определённым именем).
Выражение обязано появляться само по себе (множественные выражений и смешивание
выражений и строковых констант не допускаются).
Множественные операции обязаны выполняться внутри выражения.
Конверсия типов описана в Разделе JSP.2.13.2.
По умолчанию все атрибуты имеют семантику времени трансляции страницы. Попытка
специфицировать выражение скриптлета как значение атрибута, который (по
умолчанию или нет) имеет семантику времени трансляции, является недопустимой и
приводит к фатальной ошибке трансляции.
Тип элемента action
указывает, будет ли данный атрибут принимать значения атрибута времени запроса.
Большинство атрибутов стандартных акций из Главы 4 имеют семантику времени
трансляции страницы, но следующие атрибуты принимают выражения атрибутов времени
запроса:
jsp:setProperty
(Раздел JSP.4.2).beanName
в jsp:useBean
(Раздел JSP.4.1).page
в jsp:include
(Раздел JSP.4.4).page
в jsp:forward
(Раздел JSP.4.5).jsp:param
(Раздел JSP.4.6).height
и width
в jsp:plugin
(Раздел JSP.4.7).Мы описываем два случая конверсии типов:
String
Значение строки может использоваться для описания значения типа не-String через
конверсию. Возможна ли конверсия и, если да, какая она, зависит от типа назначения.
Значения String
могут использоваться для присвоения значений типу, который имеет класс
PropertyEditor
, как указано в спецификации JavaBeans. Если это именно тот случай,
используется метод setAs-Text(String)
.
Конверсия терпит неудачу, если метод вызывает исключение
IllegalArgumentException
.
Значения String
могут также использоваться для присвоения типов, как указано в Таблице 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
.
Выражения времени запроса могут назначаться свойству любого типа.
Автоматическая конверсия не выполняется.
В этой Главе описаны требования по локализации в JavaServer Pages 1.2 (JSP 1.2).
Поддержка платформой 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
директивы
, если она имеется, или, в противном случае, устанавливается
ISO-8859-1. ISO-8859-1 известна также как Latin-1.page
Верные имена кодировок символов в JSP 1.2 - те же, что и имена
IANA. Они описаны по адресу:
ftp://venera.isi.edu/in-notes/iana/assignments/character-sets
Атрибут
pageEncoding
должен использоваться только тогда, когда кодировка символов JSP-страницы
организована так, что символы
ASCII отображают сами себя. Директива, содержащая атрибут
pageEncoding
, должна появляться на JSP-странице как можно раньше.
JSP-контейнер может использовать какую-нибудь зависящую от реализации эвристику
и/или структуру для определения ожидаемой кодировки JSP-страницы и проверки
соответствия атрибута
contentType
.
JSP-контейнер вызовет ошибку времени трансляции, если запрошена неподдерживаемая
кодировка символов.
Большинство 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-страницы созданы так, что они могут направлять содержимое,
используя различные типы содержимого и кодировки символов, в зависимости от
ввода времени запроса. Эти страницы могут быть организованы как специальные
акции или скриптлеты, которые определяют тип содержимого ответа и предоставляют 'связку'
с другим кодом, реально генерирующим содержимое ответа.
Динамическая установка типа содержимого основана на вызове response.setcontentType
().
Этот метод может быть вызван, пока никакого содержимого не было выслано в поток
ответа. Данные высылаются в поток ответа при очистках буфера буферизованных
страниц или при обнаружении первого содержимого (избегая пробелов)
небуферизованных страниц.
Пробел в страницах JSP вводится известным трюком синтаксиса JSP, но более
управляем в JSP-страницах с синтаксисом XML.
Спецификация JSP не предписывает определённого подхода к структурированию
локализованного содержимого, поэтому возможны различные подходы.
Два обычных подхода заключаются в использовании шаблонной taglib
и помещения локализованных строк из хранилища ресурсов, либо в
использовании локализованных JSP-страниц. Каждый подход имеет свои преимущества
и недостатки. Некоторые пользователи используют трансформацию
JSP-документов для простого замещения элементов локализованными строками,
обрабатывая таким образом синтаксис JSP без снижения производительности на этапе
прогона. Сочетание этих трёх подходов также имеет определённый смысл.
Есть несколько подходов к наилучшему проведению локализации. Мы ожидаем
появления JSR-052,
стандартной библиотеки тэгов JSP, чтобы адресовать к ней некоторые из этих
вопросов.
В этой главе описаны стандартные акции JavaServer Pages 1.2 (JSP 1.2).
<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-контейнера
во время трансляции страницы при обработке запроса клиента.
Конкретно:
id
, найденные в том же самом трансляционном
модуле, приводят в фатальной ошибке времени трансляции.Это 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, используемые для доступа к этой ассоциации, таким образом:
page
|
Именованный объект, доступный из javax.
для данной страницы.Эта ссылка должна быть уничтожена после выполнения текущего запроса телом страницы. Не допускается изменение объекта экземпляра, ассоциированного таким образом, что его (объекта?) тип времени прогона/выполнения является поднабором типа текущего объекта, ассоциированного ранее. |
request
|
Именованный объект, доступный из объекта ServletRequest текущей страницы через использование
метода getAttribute(name) .Эта ссылка должна быть уничтожена после выполнения текущего клиентского запроса. Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, что его (объекта?) тип времени прогона/выполнения является поднабором(-ами) типа объекта, ассоциированного ранее таким же образом. |
session
|
Именованный
объект, доступный из объекта HttpSession текущей страницы
(который, в свою очередь, может быть получен из объекта ServletRequest )
через использование методаgetAttribute(name) .Эта ссылка должна быть уничтожена после аннулирования текущей сессии. Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, чтобы его новый тип времени прогона был поднабором(-ами) типа объекта, ассоциированного ранее. Заметьте, что будет фатальной ошибкой трансляции попытка использовать область видимости сессии, когда JSP-страница, делающая эту попытку, объявляется через директиву <%@ page ... %>
(см. далее) так, что она не участвует в сессии. |
application
|
Именованный объект, доступный из объекта ServletContext
текущей страницы через использование метода getAttribute(name) .Эта ссылка должна быть уничтожена после использования ServletContext .Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, чтобы его новый тип времени прогона был поднабором(-ами) типа объекта, ассоциированного ранее таким же образом. |
Акциями, выполняемыми в jsp:useBean
, являются:
id
и scope
.
Синхронно выполняется проверка пространства имён области
видимости/scope
для исключения недетерминистического поведения.class
/класс
(если type
не задан) определяется с данным
id
в текущей лексической области видимости языка скриптинга.java.lang.ClassCastException
. Это завершает работу данной акции
jsp:useBean
.jsp:useBean
имел непустое тело/body, он игнорируется. Это завершает работу
данной акции jsp:useBean
.class
,
ни beanName
, должно возникать исключение
java.lang.InstantiationException
. Это завершает работу данной
акции jsp:useBean
.class
специфицировал имена неабстрактного класса, который
определяет публичный/public безаргументный конструктор,
тогда создаётся экземпляр этого класса.PageContext
). После этого выполняется шаг 7.java.lang.InstantiationException
.
Это завершает работу данной акции jsp:useBean
.beanName
,
тогда метод instantiate()
класса java.beans.Beans
будет вызван с Class-Loader/Загрузчиком-Классов объекта Servlet
и с beanName
в
качестве аргументов.PageContext
). После этого выполняется шаг 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
>
имеет следующие атрибуты:
id
|
Имя, используемое для идентификации
экземпляра объекта в пространстве имён специфицированной области видимости, а
также имя переменной скриптинга, объявленное и инициализированное
вместе со ссылкой на этот объект. Специфицированное пространство имён чувствительно к регистру и должно соответствовать соглашениям текущего языка скриптинга по именованию переменных. |
scope
|
Область видимости/scope ,
в зоне которой ссылка доступна. Значение по умолчанию - page.См. описание атрибута scope ,
определённого ранее здесь же. |
class
|
Полное
квалифицированное имя класса, определяющего реализацию объекта. Имя класса чувствительно к регистру. Если атрибуты class и beanName
не специфицированы, объект обязан быть представлен в данной области видимости.
|
beanName
|
Имя для Bean, как предполагается методом instantiate()
класса java.beans.Beans . Этот атрибут может принимать в
качестве значения выражение атрибута времени запроса. |
type
|
Если специфицирован, определяет тип переменной скриптинга. Это позволяет типу переменной скриптинга отличаться от (но соотноситься с) типа специфицированного класса реализации. Тип должен быть самим классом, суперклассом этого класса, либо интерфейсом, реализованным специфицированным классом. Объект, на который ссылаются, должен быть этого типа, иначе должно возникать исключение java.lang. во время
запроса, когда делается попытка назначения объекта, на который ссылаются, переменной скриптинга.Если не специфицировано, значение будет тем же, что и значение атрибута class . |
<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>
имеет следующие атрибуты:
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
|
Значение, присваиваемое данному свойству. |
<jsp:getProperty>
Акция <
помещает значение свойства экземпляра
Bean'а, конвертированное к String, в неявный объект вывода, из которого Вы можете отобразить значение в качестве
вывода. Экземпляр Bean'а обязан быть определён так, как указано в атрибуте
jsp:getProperty
>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" />
name
|
Имя экземпляра объекта, из которого получено свойство. |
property
|
Именует получаемое свойство. |
<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:
<%@ include file="dir/B.jsp"%>
, а
dir/B.jsp говорит <%@ include file="C.jsp"%>
.<jsp:include page="dir/B.jsp"/>
, а dir/B.jsp говорит <jsp:include
page="C.jsp" />
.<%@ include file="dir/B.jsp"%>
, а dir/B.jsp говорит <jsp:include
page="C.jsp"/>
.
<jsp:include page="urlSpec" flush="true|false"/>
и
<jsp:include page="urlSpec" flush="true|false">
{ <jsp:<code></code> .... /> }*
</jsp:include>
В первом примере синтаксиса выполняется включение на этапе запроса.
Во втором случае значения в субэлементах param
используются для увеличения запроса с целью включения.
Верными атрибутами являются:
page
|
Этот URL является относительным urlSpec,
как указано в Разделе JSP.2.2.1. Относительные пути интерпретируются относительно текущей JSP-страницы. Принимает атрибут времени запроса value (который обязан вычисляться до String, которая является спецификацией относительного URL). |
flush
|
Необязательный булев атрибут. Если "true", буфер немедленно очищается. По умолчанию - "false". |
<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>
Этот тэг позволяет автору страницы осуществлять воздействие на процессинг
текущего запроса специфицированными атрибутами:
page
|
URL является относительным urlSpec, как указано в
Разделе JSP.2.2.1. Относительные пути интерпретируются относительно текущей JSP-страницы.
Принимает атрибут времени запроса |
<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:param name="name"
value="value" />
Эта акция имеет два мандатных/обязательных атрибута: name
и value
.
Name
это имя параметра, а
value
, которое может быть выражением времени запроса, это его
значение.
<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>
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:params>
Акция jsp:params
является частью акции jsp:plugin
и
может появляться только как прямой потомок элемента <jsp:plugin>
.
Использование элемента jsp:params
в любом ином контексте должно
приводит к ошибке времени трансляции.
Семантика и синтаксис jsp:params
описаны в Разделе JSP.4.7.
<jsp:fallback>
Акция jsp:fallback
является частью акции jsp:plugin
и
может появляться только как прямой потомок элемента <jsp:plugin>
.
Использование элемента jsp:fallback
в любом ином контексте должно
приводит к ошибке времени трансляции.
Семантика и синтаксис jsp:fallback
описаны в Разделе
JSP.4.7.
В этой главе определён синтаксис XML для JSP-страниц и интерпретация страниц, написанных с этим синтаксисом. Мы используем термин JSP-документ для обозначения JSP-страницы с синтаксисом XML.
Эта глава также определяет отображение/mapping между JSP-страницей и XML-описанием этой страницы, её XML view\XML-просмотр. XML-просмотр определён для JSP-страниц, написанных на JSP с синтаксисом XML.
Синтаксис XML для JSP-страниц может использоваться по-разному, с том числе:
Проверка JSP-страницы поддерживается в спецификации JSP 1.2 с помощью класса
TagLibraryValidator
, ассоциированного с библиотекой тэгов. Класс-проверщик
работает с объектом PageData
, который представляет XML-просмотр JSP-страницы (см.,
например, Раздел JSP.7.5.1.2).
JSP-страница с любым синтаксисом может подключать с помощью директивы JSP-страницу
с любым синтаксисом. Нельзя, однако, смешивать стандартный JSP-синтаксис и XML-синтаксис в одном исходном файле.
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:root
, который используется для ввода пространства имён для специальных тэгов страницы;jsp:text
, соответствующие шаблонным данным;Модель семантики JSP-документа не изменилась по сравнению с моделью семантики JSP-страницы
с синтаксисом JSP: JSP-страницы генерируют ответный поток символов из шаблонных
данных и динамических элементов. Шаблонные данные могут быть описаны явно
элементом jsp:text
или неявно фрагментом XML.
Динамические элементы являются элементами
скриптинга, стандартными акциями или специальными акциями. Элементы скриптинга
представляются как элементы XML, кроме выражений времени/этапа запроса,
которые представляются специальным синтаксисом атрибутов.
Чтобы точнее показать процессинг пробелов, мы следуем структуре спецификации
XSLT. Первым шагом обработки JSP-документа является идентификация узлов
документа. При этом все текстуальные узлы, содержащие только пробелы, из
документа удаляются; единственным исключением являются узлы элемента jsp:text
,
которые сохраняются дословно. Результирующие узлы интерпретируются так, как
описано в последующих разделах. Шаблонные данные либо передаются непосредственно
в ответ/response, либо опосредованно через (стандартные или специальные/custom) акции.
В соответствии со спецификацией XML (и спецификацией XSLT), пробельными символами являются #x20, #x9, #xD и #xA.
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: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: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:declaration
Элемент jsp:declaration
используется для объявления конструкций языка скриптинга,
которые доступны всем другим элементам скриптинга. Элемент
jsp:declaration
не имеет атрибутов, и его тело/body - это само объявление.
Его синтаксис:
<jsp:declaration> здесь идёт объявление </jsp:declaration>
Интерпретация элемента
jsp:declaration
описана в Разделе JSP.2.11.1.
jsp:scriptlet
Элемент jsp:scriptlet
используется для описания акций, выполняемых в ответ на некоторый
запрос. Скриптлеты являются фрагментами программы. Элемент
jsp:scriptlet
не имеет атрибутов, и его тело - это фрагмент программы, содержащий скриптлет.
Его синтаксис:
<jsp:scriptlet> здесь - фрагмент кода </jsp:scriptlet>
Интерпретация элемента jsp:scriptlet
описана в Разделе
JSP.2.11.2.
jsp:expression
Элемент jsp:expression
используется для описания сложных выражений на языке скриптинга,
вычисляемых на этапе ответа. Элемент jsp:expression
не имеет атрибутов, и его тело - это выражение.
Его синтаксис:
<jsp:expression>
здесь - выражение </jsp:expression>
Интерпретация элемента
jsp:expression
описана в Разделе JSP.2.11.3.
JSP-документ может использовать стандартные акции, описанные в
Главе JSP.4.
Поскольку синтаксис этих элементов уже базируется на XML, описания этой главы
достаточно, за исключением того, что в шаблоне JSP-документа текст может быть
описан элементом jsp:text
, либо посредством элемента XML, который не является ни
стандартной, ни специальной акцией (см. Раздел
JSP.5.2.11).
Для полноты приведём элементы-акции:
jsp:useBean
jsp:setProperty
jsp:getProperty
jsp:include
jsp:forward
jsp:param
jsp:params
jsp:plugin
jsp:text
Семантика и ограничения описаны в Главе JSP.4, а интерпретация элементов
скриптинга - в Главе JSP.6.
Библиотеки тэгов вводят новые элементы атрибутам
xmlns
или элементом
jsp:root
, а их синтаксис и семантика описаны в Главе JSP.7.
Элемент акции, который может принимать атрибут времени запроса (Раздел JSP.2.13.1), принимает аргумент для этого атрибута в форме "%= text %" (пробелы вокруг text не нужны, и отметьте отсутствие '<' и '>'). Text, после применения кавычек (как и в любом другом документе XML), является выражением, вычисляемым по правилам Раздела JSP.2.13.1.
jsp:text
Элемент jsp:text
можно использовать для включения шаблонных данных в представление XML.
Элемент jsp:text
не имеет атрибутов и может появляться в любом месте, где могут появляться шаблонные данные.
Его синтаксис:
<jsp:text
> шаблонные данные </jsp:text
>
При интерпретации элемента jsp:text
, его содержимое передаётся текущему значению out/вывода.
Это очень напоминает работу элемента xsl:text
из XSLT.
Синтаксис XML для JSP-страниц допускает также появление XML-элементов, которые
не представляют ни стандартных, ни специальных акций, в любом месте, где может появляться
jsp:text
.
Интерпретация такого XML-элемента - это передача его текстуального представления
текущему значению out после процессинга пробелов, описанного в Разделе JSP.5.2.1.
Как пример, если фрагмент JSP-документа таков:
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>
|
то результат будет:
N Строки | Итоговый Текст |
---|---|
1 |
<hello> <hi> hi you all
|
2 |
3 </hi></hello>
|
Обратите внимание на работу с пробелами.
В этом разделе описан XML-просмотр/view JSP-страницы: отображение между JSP-страницей, написанной с синтаксисом XML или JSP, и XML-документом, описывающим её.
XML-просмотр JSP-страницы, написанной с синтаксисом XML, очень похож на оригинал JSP-страницы.
Выполняются только две трансформации:
include
разворачиваются в JSP-фрагменты.jsp:id
, этот атрибут добавляется. См. Раздел JSP.5.3.13.XML-просмотр JSP-страницы, написанной с синтаксисом XML, определяется следующей трансформацией:
include
разворачиваются в JSP-фрагменты;jsp:root
добавляется в качестве корневого, с соответствующим атрибутом
xmlns:jsp
, и директива taglib
конвертируется в атрибуты xmlns:
элемента jsp:root
;jsp:text
для всего шаблонного текста;jsp:id
, этот атрибут добавляется. См.
Раздел JSP.5.3.13.Обратите внимание, что XML-просмотр JSP-страницы не имеет информации DOCTYPE; см. Раздел JSP.5.4.
Краткий обзор трансформации дан в Таблице JSP.5-1:
Элемент 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-комментарии (в форме
<%-- комментарий --%
>) не передаются в
XML-просмотр JSP-страницы.
page
Директива page
в форме:
<%@ page {
атрибут="значение" }* %>
транслируется в элемент в форме:
<jsp:directive.page { атрибут="значение" }* />
taglib
Директива taglib
в форме:
<%@ taglib uri="uriValue\значениеURI"
prefix="префикс" %>
транслируется в атрибут
xmlns:prefix
элемента root
JSP-документа со значением. которое зависит от uriValue.
Если uriValue является относительным путём, то используемое значение будет
"urn:jsptld:uriValue"; иначе uriValue используется напрямую.
include
Директива include
в форме:
<%@ include file="value" %>
развёртывается в JSP-фрагмент, обозначенный value. Это сделано для того,
чтобы дать возможность проверять страницу.
Объявления транслируются в элемент
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>
Альтернативно мы можем использовать < и записать:
<jsp:declaration> public String f(int i) { if (i<3) return("..."); }
</jsp:declaration>
Скриптлеты транслируются в элементы
jsp:scriptlet
. В XML-документе, соответствующем JSP-страницам, директивы
представлены с использованием следующего синтаксиса:
<jsp:scriptlet> здесь - фрагмент кода </jsp:scriptlet>
В XML-документе, соответствующем JSP-страницам, директивы представлены с
использованием элемента jsp:expression
:
<jsp:expression> здесь - выражение </jsp:expression>
Синтаксис элементов стандартных и специальных акций базируется на XML. Необходимы трансформации в связи с соглашениями по кавычкам и с синтаксисом выражений атрибутов времени запроса.
Выражения атрибутов времени запроса/Request-time attribute expressions имеют форму
"<%= expression %>"
.
Хотя этот синтаксис следует синтаксису, используемому в JSP-странице, он не
является допустимым в XML.
Отображение XML для таких выражений - это значение в форме
"%= выражение'%"
, где соглашение по кавычкам спецификации JSP конвертировано в соглашение по кавычкам XML.
Весь текст, который не интерпретируется JSP-транслятором, конвертируется в тело/body элемента
jsp:text
. Как следствие, никакие XML-элементы в форме, описанной в
Разделе JSP.5.2.11,
не будут появляться в XML-просмотре JSP-странице, написанной с синтаксисом JSP.
jsp:id
JSP-контейнер может, по выбору, поддерживать атрибут
jsp:id
. Этот атрибут может присутствовать только в XML-просмотре JSP-страницы и
может использоваться для повышения качества сообщений об ошибках времени трансляции.
Он вводится по выбору, и соответствующий JSP-контейнер может выбрать,
поддерживать его или нет.
В JSP-контейнере, поддерживающем атрибут
jsp:id
, XML-просмотр любой JSP-страницы будет содержать дополнительный атрибут
jsp:id
во всех XML-элементах. Этому атрибуту даётся значение, уникальное среди
всех элементов XML-просмотра. См. детали в Главе 10.
XML-просмотр JSP-страницы это документ, связанный с пространством имён, и он не
может быть проверен относительно ОТД/DTD (Определение Типа Данных), за
исключением лишь наиболее простых случаев.
Чтобы уменьшить конфликты и возможные нежелательные последствия, XML-просмотр JSP-страницы
не будет включать DOCTYPE. Однако пока ОТД могут содержать некоторое значение в
качестве документации,
Приложение JSP.C содержит описания и DTD, и XSchema JSP-документов.
Есть несколько механизмов с участием пространства имён, которые могут
использоваться для проверки XML-просмотра JSP-страниц. Самым популярным
механизмом является язык XML Schema консорциума W3C, но подойдут также и другие,
включая некоторые простейшие, которые, например, могут использовать только
некоторые элементы,
или, напротив, которые не используют их. Проверщик TagLibraryValidator
для
библиотеки тэгов разрешает инкапсуляцию этих сведений в библиотеке тэгов.
работает в XML-просмотре JSP-страницы. Если страница создана
с синтаксисом JSP, этот просмотр не предоставляет никаких деталей о шаблонных
данных
(всё группируется внутри элементов
TagLibraryValidatorjsp:text
), но отдельные детали могут быть
описаны при использовании JSP-документов. Аналогично, когда XSLT-трансформация
применяется к JSP-документу,
XML-фрагменты будут нормально видимы, в то время как содержимое элементов
jsp:text
- нет.
В этом разделе представлены два примера JSP-документов. В первом дана JSP-страница
с синтаксисом JSP и её отображение в синтаксис XML. Во втором - JSP-страница с
синтаксисом XML, включающая XML-фрагменты.
Пример отображения между синтаксисом JSP и XML.
<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>
<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-документа, содержащего некоторые шаблонные 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-страницу.
Сюда относятся поддержка переносимости, механизм проверки и поддержка утилит авторизации.
Здесь дан также концептуальный обзор библиотеки тэгов. Рассмотрен
Tag Library Descriptor/Дескриптор Библиотеки Тэгов и директива
taglib
. Детальное описание задействованных API даётся в
Главе JSP.10.
Библиотека Тэгов/Tag Library абстрагирует функциональность, используемую JSP-страницей, определяя специализированный (суб)язык, что делает возможным более естественно использовать эту функциональность в JSP-страницах.
Акции, вводимые Библиотекой Тэгов, могут использоваться авторами JSP-страниц явно
при авторизации - вручную, или неявно - через использование утилит авторизации.
Библиотеки Тэгов особенно применимы в утилитах авторизации, поскольку позволяют
сосредоточиться на главном, а параметры, указанные в экземпляре акции, сами
передают информацию утилите.
Акции, которые предоставляются из библиотеки тэгов, импортируются в JSP-страницу путём использования директивы
taglib
. Они доступны для использования на странице через префикс, заданный этой директивой.
Акции могут создавать новые объекты, которые могут
затем передаваться другим акциям или обрабатываться программно элементами скриптинга в JSP-странице.
Библиотеки тэгов являются переносимыми: они могут использоваться на любой JSP-странице
вне зависимости от того, какой язык скриптинга используется на этой странице.
Механизм развёртывания тэгов содержит информацию для:
Библиотека Тэгов описывается через Tag Library Descriptor ( TLD)/Дескриптор Библиотеки Тэгов, документ XML, рассматриваемый ниже.
Механизм расширения/развёртывания тэгов преследует следующие цели:
Процессинг/обработка JSP-страницы концептуально состоит из следующих этапов:
JSP-страницы могут авторизоваться с использованием двух различных синтаксисов: JSP- и XML-синтаксиса. Семантика и проверка страницы с синтаксисом JSP даётся со ссылкой на семантику и проверку эквивалентного документа с синтаксисом XML.
Первый этап - разбор JSP-страницы. Разбираемая страница разворачивается путём
выполнения директив include
. Информация из TLD используется на
данном этапе и включает идентификацию специальных тэгов так, что происходит
некоторая обработка директивами taglib
на JSP-странице.
Библиотеки Тэгов в XML-документе обрабатываются в порядке их появления на странице.
Каждая библиотека проверяется на наличие класса-проверщика/validator class. Если
он имеется, весь документ становится доступным её методу
validate()
как объект PageData
. Если JSP-контейнер поддерживает
jsp:id
, то эта информация может использоваться для предоставления информации оместонахождении ошибок.
Каждый специальный тэг в библиотеке проверяется на наличие класса
TagExtraInfo
. Если класс имеется, вызывается метод
isValid()
.
Далее документ XML обрабатывается для создания класса реализации JSP-страницы.
В ходе этого процесса могут создаваться переменные скриптинга.
Каждая
специальная акция будет предоставлять информацию о переменных, либо статично - в TLD,
либо более гибко - через использование метода getVariableInfo
класса TagExtraInfo
.
После того как класс реализации JSP-страницы ассоциирован с JSP-страницей, он будет рассматриваться как любой другой Servlet-класс: запросы будут направляться экземплярам этого класса. На этапе прогона экземпляры обработчиков будут создаваться, а их методы будут вызываться.
Семантика специфики специальной акции в библиотеке тэгов описывается через класс
обработчика тэга, который обычно инстанциируется на этапе прогона классом реализации 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
.
Tag
определяет базовые методы, необходимые всем обработчикам тэгов. Это методы setter
для инициализации обработчика тэга, в контексте данных и значений атрибутов акции, и методы
doStartTag()
и doEndTag()
.
IterationTag
является расширением
Tag
'а, предоставляя дополнительный метод doAfterBody()
, вызываемый для повторного обсчёта тела тэга.BodyTag
является расширением
IterationTag
'а с двумя новыми методами для обработчика тэга для манипулирования телом тэга:
setBodyContent()
передаёт буфер, объект BodyContent
, а
doInitBody()
даёт возможность обработки буфера до первого обсчёта тела в буфере.Использование интерфейсов упрощает создание обработчика тэга из существующего Java-объекта.
Имеются также два класса поддержки, которые могут использоваться в качестве базовых классов:
TagSupport
и BodyTagSupport
.
В JSP 1.2 имеется новый интерфейс, помогающий поддерживать целостность данных и
обслуживать ресурсы при возникновении исключительных ситуаций.
Интерфейс
TryCatchFinally
может добавляться в класс, реализующий любой интерфейс:
Tag
, IterationTag
или BodyTag
.
Библиотека тэгов может содержать классы, которые являются прослушивателями событий (см. спецификацию Servlet 2.3). Классы-прослушиватели перечисляются в дескрипторе библиотеки тэгов, и JSP-контейнер автоматически инстанциирует и регистрирует их. Контейнер нужен для размещения всех TLD-файлов (см. в Разделе JSP.7.3.1 детали об их идентификации), чтения их элементов-прослушивателей и рассмотрения прослушивателей событий как расширений этих же прослушивателей, перечисленных в web.xml. Порядок регистрации прослушивателей не определён, но они регистрируются до старта приложения.
В качестве примеров мы рассмотрим прототипы использования развёртывания тэгов, кратко остановившись на преимуществах этих механизмов.
Простейшая акция просто делает что-нибудь, возможно - с параметрами, для
модификации этого "что-нибудь" и улучшения использования.
Акция этого типа может быть реализована через обработчик тэга, который реализует
интерфейс Tag. Этот обработчик тэга должен использовать только метод
doStartTag()
, который вызывается при обнаружении начального/стартового тэга. Он
имеет доступ к атрибутам тэга и информации о статусе JSP-страницы. Эта
информация передаётся объекту
Tag через вызовы setter-метода, прежде чем будет вызван
doStartTag()
.
Поскольку часто встречаются простые акции с пустым телом, Tag Library
Descriptor может использоваться для указания на то, что данный тэг всегда предполагается как пустой.
Такая индикация позволяет лучше проверять ошибки на этапе трансляции и даёт код
более высокого качества в классе реализации JSP-страницы.
Другой набор простых акций требует, чтобы что-нибудь происходило, когда
обнаруживается начальный тэг и когда обнаруживается конечный тэг. Интерфейс Tag
может также использоваться для этих акций. Метод
doEndTag()
похож на метод
doStartTag()
, за исключением того, что он вызывается при обнаружении конечного
тэга акции. Результат вызова doEndTag
показывает, вычисляется ли оставшаяся часть страницы, или нет.
В некоторых случаях тело должно вызываться только при возникновении некоторого (возможно, сложного)
условия. И опять, этот тип акции поддерживается базовым интерфейсом
Tag
через использование return-значений метода doStartTag()
.
Для итераций необходим интерфейс IterationTag
. Метод
doAfterBody()
вызывается для определения необходимости повторного обсчёта тела.
Рассмотрим акцию, которая обсчитывает своё тело несколько раз, создавая поток
данных ответа. Для этого используется протокол IterationTag
.
Если результат повторной интерпретации будет в дальнейшем обрабатываться, по
каким-то соображениям, в том числе и просто может быть отброшен, то нам нужен
способ "отвлечь" вывод/output от повторных обсчётов.
Это выполняется путём создания объекта
BodyContent
и использования метода setBodyContent()
, который является частью интерфейса BodyTag
.
BodyTag
также предоставляет метод doInitBody()
, вызываемый после
setBodyContent()
и до первого обсчёта тела, что является удобным моментом для взаимодействия с телом/body.
Кооперирующиеся акции могут предлагать наилучший способ описания необходимой функциональности.
Например, одна акция может использоваться для описания информации, приводящей к
созданию серверного объекта, а другая может использовать этот объект где-либо
на этой странице. Эти акции могут кооперироваться явно через переменные
скриптинга: одна акция создаёт объект и даёт ему имя; другая ссылается на объект по имени.
Переменные скриптинга кратко обсуждаются далее.
Две акции могут также кооперироваться неявно. Гибкий и удобный механизм
кооперирования акций использует вложение структуры акций для описания области
видимости. В данной спецификации это поддерживается через предоставление
обработчика каждого тэга и обработчика тэга его родителя (если имеется) через
вызов метода setParent()
. Статический метод findAncestorWithClass
в
TagSupport
может затем использоваться для локализации обработчика тэга и, после
локализации, для выполнения операций в обработчике тэга.
Специальные акции могут создавать серверные объекты и делать их доступными
элементам скриптинга через создание или обновление переменных скриптинга.
Обработанные таким образом переменные являются частью семантики специальной
акции и находятся в зоне ответственности автора библиотеки тэгов.
Эта информация используется во время трансляции JSP-страницы и может быть
описана одним из двух способов: непосредственно в
TLD - для простых случаев, или через субклассы TagExtraInfo
.
Каждый механизм будет указывать имена и типы переменных скриптинга.
На этапе запроса обработчик тэга будет ассоциировать объекты с переменными
скриптинга через объект pageContext
.
Транслятор JSP-страницы отвечает за то, чтобы автоматически снабжать кодом,
необходимым для выполнения "синхронизации" между значениями pageObject
и переменными скриптинга.
Библиотека тэгов это коллекция акций, инкапсулирующая некоторую
функциональность, используемую в JSP-странице. Библиотека тэгов становиться
доступной JSP-странице через использование директивы
taglib
, которая идентифицирует эту библиотеку тэгов с помощью URI (Universal Resource Identifier/Универсальный
Идентификатор Ресурсов).
URI, идентифицирующий библиотеку тэгов, может быть любым верным URI, который
может использоваться для уникальной идентификации семантики библиотеки тэгов.
URI, идентифицирующий библиотеку тэгов, ассоциируется с файлом Tag Library
Description (TLD) и с классами обработчиков тэгов, как указано далее
в Разделе JSP.7.3.
Утилиты авторизацииJSP-страниц и JSP-контейнеры должны принимать библиотеку тэгов, упакованную в JAR-файл.
При поставке в JSP-контейнере применяются стандартные соглашения по JAR,
описанные в спецификации Servlet 2.3, включая
соглашения для зависимостей расширений.
Упакованные библиотеки тэгов обязаны иметь как минимум один файл дескриптора библиотеки тэгов.
Спецификация JSP 1.1 разрешала только один TLD, в META-INF/taglib.tld, а в
JSP 1.2 разрешены несколько библиотек тэгов. См. в Разделе JSP.7.3.1 об
идентификации TLD.
Библиотека тэгов содержит классы для инстанциации на этапе трансляции и классы
для инстанциации на этапе запроса. Первые содержат классы TagLibraryValidator
и
TagExtraInfo
. Вторые содержат классы обработчика тэгов и прослушивателя событий.
Применяются обычные соглашения по классам Java: как часть web-приложения они
обязаны находиться внутри либо JAR-файла в директории WEB-INF/lib, либо в директории WEB-INF/classes.
JAR, содержащий упакованные библиотеки тэгов, может быть сброшен в директорию WEB-INF/
lib, чтобы сделать его классы доступными на этапе запроса (а также на этапе
трансляции, см. Раздел JSP.7.3.7).
Отображение между URI и TLD объясняется далее.
Директива taglib
в JSP-страниц объявляет, что эта страница использует библиотеку тэгов,
уникально идентифицирует эту библиотеку через URI и ассоциирует префикс тэга с использованием акций библиотеки.
JSP-контейнер отображает URI, используемый в директиве taglib
, в Tag Library
Descriptor/Дескриптор Библиотеки Тэгов за два шага: сначала разрешает URI в путь
ресурса TLD, а затем получает TLD-объект из пути ресурса TLD.
Если JSP-контейнер не может локализовать путь ресурса TLD для данного URI,
должна происходить фатальная ошибка трансляции.
Аналогично, фатальной ошибкой трансляции является развёртывание/разрешение
значения атрибута uri
в два различных пути ресурса TLD.
Для директивы taglib
будет фатальной ошибкой, если она появится после акций,
использующих префикс, вводимый ею.
Дескриптор Библиотеки Тэгов/Tag Library Descriptor (TLD) это XML-документ,
который описывает библиотеку тэгов. TLD библиотеки тэгов используется JSP-контейнером
для интерпретации страниц, которые содержат директивы
taglib
, ссылающиеся на эту библиотеку тэгов. TLD используется также утилитами
авторизации/создания JSP-страниц, которые будут генерировать JSP-страницы,
использующие библиотеку, и авторами, делающими то же самое вручную.
TLD содержит документацию о библиотеке в целом и о каждом из её тэгов,
информацию о версии JSP-контейнера и о библиотеке и информацию о каждой акции, определённой в этой библиотеке тэгов.
TLD может именовать класс TagLibraryValidator
, который может проверять
соответствие JSP-страницы набору ограничений, ожидаемых этой библиотекой тэгов.
Каждой акции в библиотеке присваивается имя, класс её обработчика тэга,
информация о переменных скриптинга, создаваемых этой акцией, и информация об
атрибутах акции. Информация о переменных скриптинга может быть задана
непосредственно в TLD или через класс TagExtraInfo
.
Каждый верный атрибут содержит указания на то, является ли он мандатным, может
ли он принимать выражения времени запроса, и дополнительную информацию.
Файл TLD используется для предоставления информации о библиотеке тэгов. Он может
быть прочитан утилитами без инстанциации объектов или классов загрузчика.
Наш подход соответствует соглашениям в других технологиях J2EE.
ОТД для дескриптора библиотеки тэгов организовано так, что нужные элементы имеют
необязательный атрибут ID. Этот атрибут может использоваться другими
документами, типа документации продавца, для предоставления аннотаций по информации TLD.
Файл дескриптора библиотеки тэгов (ДБТ) именуется с использованием расширения ".tld", которое указывает, что это файл ДБТ.
Если размещены внутри файла JAR,
файлы ДБТ обязаны находиться в директории META-INF или в её субдиректории.
При размещении непосредственно в web-приложении файлы ДБТ обязаны всегда
находиться в директории WEB-INF или в одной из её субдиректорий.
Документ ОТД для ДБТ это
"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd".
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).
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.
Отображение taglib
, описанное в web.xml, расширяется за счёт новых вхождений,
извлекаемых из файлов TLD Web-Приложения.
Новые вхождения обсчитываются так:
<uri>
,
создаётся новый элемент <taglib>
с субэлементом
<taglib-uri>
, значением которого является значение элемента
<uri>
, и с субэлементом <taglib-location>
, указывающим на TLD-файл.<taglib>
содержит разные <taglib-uri>
для каждого отображения taglib
, он добавляется.
Этот механизм предоставляет автоматическое отображение URI в TLD, а также
поддержку нескольких TLD в одном JAR-пакете.
Обратите внимание, что эта функциональность не требует явного именования места
размещения TLD-файла, которого мог бы потребовать механизм типа протокола
jar:.
Заметьте также, что этот механизм не добавляет дублирующие вхождения.
Контейнер также может добавлять дополнительные вхождения к отображению taglib
.
Как и в предыдущем случае, входы добавляются только для тех URI, которые не
представлены в отображении. Концептуально эти вхождения соответствуют TLD,
описывающему эти библиотеки тэгов.
Эти неявные вхождения отображения соответствуют библиотекам, которые известны
контейнеру, который отвечает за предоставление их реализации, либо через
обработчики тэгов, либо через механизм, описанный в Разделе JSP.7.3.9.
Путь ресурса TLD может быть определён из атрибута uri
директивы
taglib
, как показано ниже. В последующем разъяснении "абсолютным URI" называется
такой, который начинается с названия протокола и имени хоста,
а "относительный URI" даётся так, как указано в Разделе
2.5.2, т.е. без протокола и имени хоста.
Все шаги описаны так, будто они выполнялись, но реализация может использовать
различные стратегии для получения того же результата.
Карта 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
следующим образом:
<taglib-location>
это относительный URI, начинающийся с "/", то
TAGLIB_LOCATION
является этим URI.<taglib-location>
это относительный URI, не начинающийся с "/", то
TAGLIB_LOCATION
является разрешением этого URI относительно
/WEB-INF/web.xml (результатом этого разрешения является относительный URI, начинающийся с "/").
Здесь показано, как разрешить директиву taglib
для вычисления пути ресурса TLD
на базе значения атрибута uri
директивы taglib
.
uri
является ABS_URI
,
абсолютным URI. Идёт поиск в карте taglib
вхождения, чей TAGLIB_URI
является
ABS_URI
.
Если он найден, соответствующее TAGLIB_LOCATION
является путём ресурса TLD. Если он не найден,
возникает ошибка трансляции.uri
является ROOT_REL_URI
,
относительным URI, начинающимся с "/".
Идёт поиск в карте taglib
вхождения, чей
TAGLIB_URI
является ROOT_REL_URI
.
Если он найден, соответствующее
TAGLIB_LOCATION
является путём ресурса TLD. Если он не найден, ROOT_REL_URI
является путём ресурса TLD.uri
является
NOROOT_REL_URI
,
относительным URI, не начинающимся с "/". Идёт поиск в карте taglib
вхождения,
чей TAGLIB_URI
является NOROOT_REL_URI
.
Если он найден, соответствующее
TAGLIB_LOCATION
является путём ресурса TLD. Если он не найден,
NOROOT_REL_URI
разрешается относительно текущей JSP-страницы, где появилась
директива; это значение (по определению, это спецификация относительного URI,
начинающегося с "/") является путём ресурса TLD.Явное отображение 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" %>
Набор классов, доступных во время трансляции, - тот же, что и для времени
прогона/runtime: классы основной платформы Java, в JSP-контейнере и в файлах
классов в WEB-INF/classes, в JAR-файлах в
WEB-INF/lib и, косвенно, классы, обозначенные через использование атрибута class-path
в файле-манифесте META-INF/MANIFEST этих JAR-файлов.
Как часть процесса ассемблирования 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-контейнер может "знать" некоторые URI и может предоставлять альтернативные
реализации для библиотек тэгов, описанных этими URI, но пользователь обязан
видеть поведение как таковое, описанное описанием требуемой, переносимой
библиотеки тэгов, указанной в URI.
JSP-контейнер обязан всегда использовать отображение, специфицированное для URI,
в дескрипторе публикации
web.xml, если он имеется.
Если публикатор хочет использовать платформозависимую реализацию хорошо
известного URI, отображение такого
URI должно быть удалено во время публикации.
В этом разделе описано ОТД (Определение Типа Данных), для 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-страницы должна соответствовать некоторым правилам проверки:
Проверка может выполняться на этапе трансляции или на этапе запроса. Обычно проверка на этапе трансляции даёт больше информации, и спецификация JSP 1.2 предоставляет очень гибкий механизм проверки на этапе трансляции.
Определённая проверка на этапе трансляции проводится в Tag Library Descriptor (TLD).
В некоторых случаях для предоставления поддержки этой информации необходимо наличие класса
TagExtraInfo
.
Tag Library Descriptor содержит базовую синтаксическую информацию. Атрибуты
описываются с включением его имени, являются ли они необязательными или
мандатными и принимают ли они выражения времени запроса. Кроме того, элемент
bodycontent
может использоваться для указания на то, что акция обязаны быть пустой.
Все ограничения, описанные в TLD, обязаны форсироваться. Автор библиотеки тэгов может принять как данное, что
экземпляр обработчика тэга соответствует акции, которая удовлетворяет всем
ограничениям, указанным в TLD.
Класс TagLibraryValidator
может быть указан в TLD библиотеки тэгов для запроса проверки этой JSP-страницы.
XML-просмотр JSP-страницы экспонируется через класс
PageData, и класс validator/проверщика может выполнять любую проверку, которую
автор библиотеки тэгов сочтёт необходимой.
JSP-контейнер может по выбору уникально идентифицировать все XML-элементы в
XML-просмотре JSP-страницы через атрибут
jsp:id
. этот атрибут может использоваться для предоставления большей информации о местонахождении ошибки.
механизм класса проверщика является новым для спецификации JSP 1.2.
может быть передан некоторым параметрам инициализации в TLD.
Это облегчает многократное использование классов проверщика. Мы ожидаем, что validator-классы
будут написаны на базе различных механизмов схемы XML
(DTDs, XSchema, Relaxx, других). Стандартные классы проверщика могут быть внедрены в последующих версиях
спецификации JSP, если когда-нибудь появится полный стандарт схемы.
TagLibraryValidator
TagExtraInfo
Дополнительная проверка на этапе трансляции может выполняться путём
использования метода isValid
класса TagExtraInfo
. Метод
isValid
вызывается на этапе трансляции и передаётся в экземпляр
Tag Dat в качестве его аргумента.
Механизм isValid
был первоначальным механизмом проверки, введённым в
JSP 1.1 вместе с механизмами Расширения Тэгов. Библиотеки тэгов, созданные для запуска в контейнерах JSP 1.2, должны
использовать механизм класса проверщика.
В некоторых случаях может динамически выполняться дополнительная проверка на
этапе запроса в методах обработчиков тэгов. Если обнаруживается ошибка, вызывается экземпляр
JspException
. Если ошибка не отловлена, этот объект вызовет механизм errorpage спецификации JSP.
Этот раздел не является нормативным, хотя отражает практику разработки.
Мы предлагаем придерживаться следующего стиля введения неявных объектов:
defineObjects
определяет необходимые объекты.JSP-страница может сделать эти объекты доступными так:
<%@ tablig
prefix="me" uri="......" %>
<me:defineObjects />
.... начинается использование объектов ....
Этот подход имеет то преимущество, что не требует новых механизмов и установления слишком явной зависимости.
В некоторых случаях доступность этих объектов может зависеть от реализации.
Например, они могут предоставлять доступ к некоторой функциональности, которая имеется
только в определённой реализации. Это может быть выполнено через проверку
классом расширения тэга на этапе прогона на предмет наличия некоторых свойств
данной реализации и вызова ошибки этапа прогона (это, конечно, не делает страницу ближе к J2EE).
Этот механизм, вместе с доступом к информации метаданных, позволяет продвигать новинки наряду со стандартом.
Примечание: если новая возможность добавлена к спецификации
JSP и продавец также предоставляет эту возможность через свой специфический
механизм, стандартным механизмом, как указано в спецификации JSP, будет "win".
Это значит, что механизмы, специфичные для продавца, могут постепенно перейти в
спецификацию, если докажут свою пригодность.
Если продавец хочет ассоциировать некоторую информацию, не описанную в текущей версии TLD, с некоторой библиотекой тэгов, он может сделать это, вставив информацию в контролируемый им документ, включив этот документ в часть WEB-INF JAR-файла там, где находится Tab Library/Библиотека Тэгов, и используя стандартные механизмы Servlet 2.2 для доступа к этой информации. Продавец может теперь использовать ID-механизмы для ссылки на элемент внутри TLD.
Библиотека тэгов может быть специализирована в ходе ассемблирования и публикации. Например,
библиотека тэгов, предоставляющая доступ к базам данных, может быть
специализирована информацией логина и пароля.
В web.xml в спецификации Servlet 2.2 нет подходящего места для специализированной
информации. Стандартизованный механизм, возможно, станет частью последующей
JSP-спцификации, но пока советуем авторам библиотек тэгов размещать такую
информацию в хорошо известном месте какого-нибудь ресурса в части
WEB-INF/ Web-Приложения давать к ней доступ через вызов getResource()
в ServletContext
.
В этой главе рассматриваются контракты между JSP-контейнером и JSP-страницей.
Протокол прекомпиляции (см. Раздел JSP.8.4) также представлен здесь.
Информация, представленная здесь, не зависит от Языка Скриптинга, используемого на JSP-странице.
Глава JSP.6 описывает информацию для случая, когда атрибут
language
директивы page
установлен в "java"
.
Классы реализации
JSP-страницы должны использовать классы JspFactory
и PageContext
для получения
преимуществ платформозависимых реализаций.
JSP-страница представлена на этапе выполнения объектом реализации JSP-страницы и выполняется JSP-контейнером. Объект реализации JSP-страницы - это servlet/сервлет. JSP-контейнер направляет запросы от клиента объекту реализации JSP-страницы и ответы объекта реализации JSP-страницы - клиенту.
JSP-страница описывает создание объекта response из объекта request
для данного протокола, возможно, создавая и/или используя в ходе этого процесса
некоторые другие объекты. JSP-страница может также указывать, как должны обрабатываться некоторые события.
В JSP 1.2 только события init и destroy являются допустимыми событиями.
JSP-контейнер локализует соответствующий экземпляр класса реализации
JSP-страницы и направляет ему запросы, используя протокол Servlet.
JSP-контейнеру может потребоваться создать такой класс динамически из исходной JSP-страницы до
направления ей объектов request
и response
.
Класс Servlet
определяет контракт между JSP-контейнером и классом реализации JSP-страницы.
Если используется протокол HTTP, контракт описывается классом
HttpServlet
. Большинство JSP-страниц используют протокол HTTP, но другие
протоколы также разрешены данной спецификацией.
JSP-контейнер автоматически делает несколько серверных/server-side объектов
доступными объекту реализации JSP-страницы. См. Раздел JSP.2.8.3.
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, в любом сочетании регистров.
HttpJspPage
Выполнению контракта между JSP-контейнером и автором JSP-страницы помогает
требование о том, что класс Servlet
, соответствующий JSP-странице, обязан
реализовывать интерфейс HttpJspPage
(или интерфейс JspPage
, если протокол - не HTTP).
JSP-Контейнер |
JSP-Страница |
---|---|
|
На Рисунке J2EE.8.1 показаны включённые контракты. Теперь мы рассмотрим этот процесс более детально.
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-контейнером и Java-классом, реализующим JSP-страницу, соответствует интерфейсу
Servlet
. См. детали в спецификации Servlet 2.3.
Ответственность за выполнение этого контракта лежит на реализации JSP-контейнера,
если JSP-страница не использует атрибут extends директивы jsp.
Если атрибут extends директивы jsp
используется, автор JSP-страниц обязан гарантировать, что суперкласс, заданный в
атрибуте extends
, поддерживает этот контракт.
Комментарии | Методы, вызываемые JSP-Контейнером |
---|---|
Метод может по выбору/optionally быть определён в JSP-странице. Метод вызывается при инициализации JSP-страницы. Если метод вызывается, доступны все методы сервлета, включая getServletConfig() . |
void jspInit()
|
Метод по выбору определяется в JSP-странице. Метод вызывается при уничтожении страницы. |
void jspDestroy()
|
Метод не может быть определён в JSP-странице. JSP-контейнер автоматически генерирует этот метод, базируясь на содержимом JSP-страницы. Метод вызывается при каждом клиентском запросе. |
void_jspService(<ServletRequestSubtype>, <ServletResponseSubtype>) throws
IOException, |
Как видно из Таблицы 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-протокола, как описано в этом разделе.
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()
.
Это значительно упрощает реализацию.
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;
}
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());
// далее идёт код из скриптлетов, выражений и статического текста.
}
}
extends
Если автор JSP-страниц использует extends
,
генерируемый класс идентичен классу из Примера Кода 8.2, за исключением того,
что имя этого класса это имя, специфицированное в атрибуте extends
.
Контракт класса реализации JSP-страницы не изменяется. JSP-контейнер должен
проверить (обычно через отражение/reflection), что предоставленный суперкласс:
HttpJspPage
, если протокол - HTTP, либо
JspPage
- в ином случае.Servlet
объявлены final
.service()
из Servlet API вызывает метод _jspService()
;
init(ServletConfig)
хранит конфигурацию,
даёт к ней доступ как к getServletConfig
, затем вызывает jspInit
;destroy
вызывает jspDestroy
.JSP-контейнер может выдавать фатальную ошибку трансляции, если обнаружит, что предоставленный суперкласс не удовлетворяет этим требованиям, но большинство JSP-контейнеров эту проверку не будут выполнять.
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-страница, использующая протокол HTTP, будет получать HTTP-запросы.
Контейнеры, соответствующие JSP 1.2, обязаны поддерживать простой протокол
прекомпиляции, а также некоторые базовые зарезервированные имена
параметров. Заметьте, что протокол прекомпиляции это понятие близкое, но не
то же самое, что компиляция JSP-страницы в Servlet-класс (Приложение JSP.A).
Все имена параметров запроса, начинающиеся с префикса "jsp"
,
зарезервированы спецификацией
JSP и не должны использоваться иначе, чем установлено данной спецификацией.
Все JSP-страницы должны игнорировать (и не зависеть от) параметры, начинающиеся
с "jsp_"
Запрос к 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).
Эта глава описывает пакет javax.servlet.jsp
. В главе имеется содержимое,
сгенерированное автоматически из javadoc, внедрённых в Java-классы и интерфейсы.
Это делает возможным создание единого авторизованного документа спецификации.
Пакет javax.servlet.jsp
содержит несколько классов и интерфейсов, описывающих и
определяющих контракты между классом реализации JSP-страницы и средой работы
программы/runtime environment, предоставляемые экземпляру такого класса соответствующим JSP-контейнером.
В разделе рассматривается базовый контракт между объектом реализации JSP-страницы
и его контейнером. Главный контракт определяется классами JspPage
и HttpJspPage
.
Класс JspFactory
описывает механизм портативной инстанциации всех необходимых объектов
прогона, а JspEngineInfo
предоставляет базовую информацию о текущем JSP-контейнере.
Ни один из классов, рассматриваемых здесь, не предназначен для использования
авторами JSP-страниц; пример использования этих классов имеется в данной главе.
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;
()
public void jspDestroy
Метод jspDestroy()
вызывается при уничтожении JSP-страницы. JSP-страница может
переопределять этот метод включением его определения в элемент declaration
. JSP-страница
должна переопределять метод destroy()
из Servlet'а.
public void jspInit()
Метод jspInit()
вызывается при инициализации JSP-страницы. Реализация JSP
(и класса, упоминаемого атрибутом
extends
, если имеется) отвечает за то, что с этой точки вызовы метода getServlet-Config()
будут возвращать требуемое значение. JSP-страница может переопределять этот
метод включением его определения в элемент declaration
. JSP-страница должна
переопределять метод init()
из Servlet'а.
HttpJspPage
Синтаксис
public interface HttpJspPage extends JspPage
Все Суперинтерфейсы: JspPage, javax.servlet.Servlet
Описание
Интерфейс HttpJspPage
описывает взаимодействие, которое Класс Реализации JSP-Страницы
обязан выполнять при использовании HTTP-протокола.
Поведение идентично поведению JspPage
, за исключением подписи метода
_jspService
, которая теперь выражается в системе типов Java и включается в интерфейс явно.
См. Также: JspPage
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
JspFactory
Синтаксис
public abstract class JspFactory
Описание
является абстрактным классом, определяющим несколько factory/"фабричных"-методов,
доступных JSP-странице на этапе прогона, для создания экземпляров различных
интерфейсов и классов, используемых для поддержки JSP-реализации.
JspFactory
Соответствующая реализация JSP Engine будет, в процессе своей инициализации,
инстанциировать зависящий от реализации подкласс этого класса сделает его
глобально доступным для использования классами реализации JSP
путём регистрации экземпляра, созданного этим классом, через static/статичный
метод setDefaultFactory()
.
Классы PageContext
и
JspEngineInfo
являются единственными зависящими от реализации классами, которые
могут создаваться из factory/фактории.
JspFactory-объекты не должны использоваться авторами JSP-страниц.
public JspFactory()
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 - PageContextgetPageContext()
public static synchronized void setDefaultFactory(JspFactory deflt)
Устанавливает факторию по умолчанию для данной реализации. Для любой principal (основной среды
работы?), кроме среды JSP Engine, недопустимо вызывать этот метод.
Параметры:
- реализация фактории по умолчанию.
default
JspEngineInfo
Синтаксис
public abstract class JspEngineInfo
Описание
это абстрактный класс, предоставляющий информацию о текущей
JSP-машине.
JspEngineInfo
public JspEngineInfo()
public abstract java.lang.String getSpecificationVersion()
Возвращает номер версии JSP-спецификации, поддерживаемой этой JSP-машиной.
Номера версии состоят из положительных целых чисел, разделённых точками ".", например, "2.0" или "1.2.3.4.5.6.7". Это позволяет использовать расширенную нумерацию для представления версий major, minor, micro и т.д.
Номер версии обязан начинаться с цифры.
Возвращает: версию спецификации, null
возвращается, если номер неизвестен.
Объекты PageContext
и
JspWriter
доступны по умолчанию в качестве неявных объектов.
PageContext
Синтаксис
public abstract class PageContext
Описание
Экземпляр PageContext
предоставляет доступ ко всем пространствам имён, ассоциированным с
JSP-страницей, предоставляет доступ к некоторым атрибутам страницы, а также слой поверх деталей реализации.
Неявные объекты добавляют pageContext
автоматически.
Класс PageContext
является абстрактным классом,
созданный как расширяемый для предоставления реализаций соответствующей средой запуска программ JSP-машины.
Экземпляр PageContext
получается классом реализации JSP через вызов метода
JspFactory.getPageContext()
и освобождается через вызов
JspFactory.releasePageContext()
.
Примеры использования PageContext
,
JspFactory
и других классов в объекте реализацииJSP-страницы можно найти повсюду.
облегчает работу автора страниц/компонентов и реализатора страниц, предоставляя:
PageContext
JspWriter
для вывода/outputpage
в среде скриптингаerrorpage
Некоторые методы предназначены для использования в коде, генерируемом контейнером, а не для кода, написанного авторами JSP-страниц или библиотек тэгов JSP.
Методы, поддерживающие lifecycle/жизненный цикл
- initialize()
и release()
Следующие методы делают возможным обслуживание вложенных JspWriter-потоков
через реализацию Tag Extensions/Расширений Тэгов: pushBody()
и popBody()
Некоторые методы предоставляют универсальный доступ к различным объектам,
представляющим области видимости/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()
.
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
не будет закрыта.
public PageContext()
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(...)
после вызова этого метода.
Параметры:
- специфицирует относительный путь URL к целевому ресурсу, как рассмотрено выше.
relativeUrlPath
Вызывает:
ServletException, IOException
IllegalArgumentException
- если URL целевого ресурса не может быть разрешён/высчитан.
IllegalStateException
- если
ServletResponse
не в том состоянии, чтобы выполнить forward/направление.
SecurityException
- если вызывающий не может получить доступ к целевому ресурсу.
public abstract java.lang.Object getAttribute(java.lang.String name)
Возвращает объект, ассоциированный с именем в области видимости страницы, или null
, если объект не найден.
Параметры:
- имя атрибута для получения.
name
Вызывает:
- если имя - null.
NullPointerException
IllegalArgumentException
- если область видимости неверна.
public abstract java.lang.Object getAttribute(java.lang.String name, int scope)
Возвращает объект, ассоциированный с именем в специфицированной области видимости, или null, если объект не найден.
Параметры:
- имя атрибута для установки.
name
- область видимости, с которой ассоциировать имя/объект.
scope
Вызывает:
- если имя -
NullPointerExceptionnull.
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
после этого вызова.
Параметры:
- обрабатываемый
tthrowable
.
Вызывает:
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.
Параметры:
- специфицирует относительный путь-URL
к включаемому целевому ресурсу.
relativeUrlPath
Вызывает:
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, ассоциированный с данным
servletPageContext
.
request
- текущий рассматриваемый запрос для данного Servlet
.
response
- текущий рассматриваемый ответ для данного Servlet
.
errorPageURL
- значение атрибута errorpage в директиве page, или null
.
needsSession
- значение атрибута session директивы page.
bufferSize
- значение атрибута buffer
директивы page
.
autoFlush
- значение атрибута autoflush
директивы page.
Вызывает:
- во время создания
IOExceptionJspWriter
.
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
- объект для ассоциирования с этим именем.
Вызывает:
- если
NullPointerExceptionname
или object
- null
.
public abstract void setAttribute(java.lang.String name, java.lang.Object o,
int scope)
Регистрирует имя и объект, специфицированные с семантикой соответствующей области видимости.
Параметры:
- имя устанавливаемого атрибута.
name
o
- объект для ассоциирования с этим именем.
scope
- область видимости, с которой ассоциируется name/object
.
Вызывает:
- если
NullPointerExceptionname
или object
- null
.
IllegalArgumentException
- если область видимости неверна.
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
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
.
protected JspWriter(int bufferSize, boolean autoFlush)
protected-конструктор.
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)
.
Параметры:
- печатаемый char.
c
Вызывает: java.io.IOException
public abstract void print(char[] s)
Печатает массив символов. Символы конвертируются в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются
точно в манере метода java.io.Writer.write(int)
.
Параметры:
- массив печатаемых chars.
s
Вызывает:
-если
NullPointerExceptions
- null
.
java.io.IOException
public abstract void print(double d)
Печатает число с плавающей точкой двойной точности. Строка, производимая
java.lang.String.valueOf(double)
, транслируется в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int)
.
Параметры:
- печатаемое double.
d
Вызывает: java.io.IOException
См. Также: java.lang.Double
public abstract void print(float f)
Печатает число с плавающей точкой. Строка, производимая
java.lang.String.valueOf(float)
, транслируется в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются
точно в манере метода java.io.Writer.write(int)
.
Параметры:
- печатаемое float.
f
Вызывает: java.io.IOException
См. Также: java.lang.Float
public abstract void print(int i)
Печатает целое число. Строка, производимая
java.lang.String.valueOf(int)
, транслируется в байты в соответствии с кодировкой
символов по умолчанию данной платформы, и эти байты записываются точно в манере
метода java.io.Writer.write(int)
.
Параметры:
- печатаемое int.
i
Вызывает: java.io.IOException
См. Также: java.lang.Integer
public abstract void print(long l)
Печатает длинное целое. Строка, производимая
java.lang.String.valueOf(long)
, транслируется в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются
точно в манере метода java.io.Writer.write(int)
.
Параметры:
- печатаемое long.
l
Вызывает: java.io.IOException
См. Также:
java.lang.Long
public abstract void print(java.lang.Object obj)
Печатает объект. Строка, производимая методом
java.lang.String.valueOf(Object)
, транслируется в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int)
.
Параметры:
- печатаемый
objObject
.
Вызывает: java.io.IOException
См. Также: java.lang.Object.toString()
public abstract void print(java.lang.String s)
Печатает строку. Если аргумент - null
, тогда печатается строка
"null". Иначе символы строки конвертируются в байты в соответствии с кодировкой
символов по умолчанию данной платформы, и эти байты записываются точно в манере
метода java.io.Writer.write(int)
.
Параметры:
- печатаемая
sString
.
Вызывает: 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 в начале её метода _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);
}
}
Класс
JspException
является базовым классом для всех JSP-исключений.
JspTag-Exception
используется механизмом исключения тэга.
JspException
Синтаксис
public class JspException extends java.lang.Exception
Прямые/Direct Известные Подклассы: JspTagException
Все Реализованные Интерфейсы: java.io.Serializable
Описание
Родовое исключение, известное JSP-машине; неотловленное JspExceptions
даст вызов механизма errorpage
.
public JspException()
Конструирует JspException
.
public JspException(java.lang.String msg)
Конструирует новое JSP-исключение со специфицированным сообщением.
Сообщение может быть записано в server log-файл и/или выводится пользователю.
Параметры:
-
msgString
, специфицирующая текст сообщения об исключении.
public JspException(java.lang.String message, java.lang.Throwable rootCause)
Конструирует новое JSP-исключение, если JSP нужно вызвать исключение и
вставить сообщение о "причине" исключения, помешавшего нормальному ходу операции, включая описательное сообщение.
Параметры:
-
messageString
, содержащая текст сообщения об исключении.
rootCause
- исключение
Throwable
, нарушившее нормальную работу сервлета; делает это исключение сервлета необходимым.
public JspException(java.lang.Throwable rootCause)
Конструирует новое JSP-исключение, если JSP нужно вызвать исключение и
вставить сообщение о "причине" исключения, помешавшего нормальному ходу операции.
Сообщение об исключении базируется на локализованном сообщении об вызвавшем его исключении.
Этот метод вызывает метод getLocalizedMessage
в исключении
Throwable
для получения локализованного сообщения об исключении. При создании
подкласса для JspException
, этот метод может быть переопределён для создания сообщения об исключении,
разработанного для определённой страны (языка и т.п.).
Параметры:
- исключение
rootCauseThrowable
, нарушившее нормальную работу
JSP-операции, ; делает это JSP-исключение необходимым.
public java.lang.Throwable getRootCause()
Возвращает исключение, вызвавшее это JSP-исключение.
Возвращает: Throwable
, вызывавшее это JSP-исключение.
JspTagException
Синтаксис
public class JspTagException extends JspException
Все Реализованные Интерфейсы:
java.io.Serializable
Описание
Исключение используется Tag Handler/Обработчиком Тэга для обозначения неисправимой ошибки. Эта ошибка
отлавливается на верхнем уровне JSP-страницы и выдаёт страницу для ошибок/errorpage.
public JspTagException()
Нет сообщения.
public JspTagException(java.lang.String msg)
Конструктор с сообщением...
В этом приложении показано два примера упаковки JSP-страницы в WAR публикации в Web-контейнере.
В первом примере JSP-страница публикуется в исходной форме. Это самый общий пример.
Во втором примере JSP-страница компилируется в Servlet, который использует
только вызовы API Servlet 2.3 и JSP
1.2; Servlet затем упаковывается в WAR с таким дескриптором публикации, что он
выглядит для любого клиента как оригинальная JSP-страница.
Это приложение не является нормативным.
В действительности, строго говоря, Это Приложение больше относится к возможностям Servlet 2.3,
чем к возможностям JSP 1.2. Приложение дано здесь, потому что эти возможности
могут представлять интерес для авторов JSP-страниц и создателей авторских утилит.
Мы начинаем с простейшей JSP-страницы HelloWorld.jsp.
<%@ page info="Пример предварительно скомпилированной JSP" %>
<p>
Hello World
</p>
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>
В качестве альтернативы мы покажем, как можно откомпилировать 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);
}
}
}
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>
Наконец, всё это упаковывается в WAR:
/WEB-INF/web.xml
/WEB-INF/classes/_jsp_HelloWorld_XXX_Impl.class
Заметьте, что, если класс Servlet, сгенерированный для JSP-страницы, зависел от
некоторых классов поддержки, они также должны были быть включены в WAR.
Пожалуйста, направляйте комментарии по 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).
JCP создаёт спецификации, используя три сообщества:
сообщество экспертов (the expert group),
participants\участники JCP и public\публика вообще.
Эксперты является авторами спецификаций, создавая проекты/drafts.
Проекты проходят путь от экспертов, через участников, к публике,
постепенно совершенствуясь в деталях, всегда возвращая комментарии обратно
группе экспертов; final draft/окончательный проект отправляется для
одобрения в Executive Committee\Исполнительный Комитет.
Лидер группы экспертов отвечает за
облегчение работы группы экспертов, авторизацию спецификации и за организацию reference
implementation\справочной реализации и conformance test suite\блока тестирования на соответствие.
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 1.2 расширяет Спецификацию JavaServer Pagesтм 1.1 (JSP 1.1) следующим образом:
Детали условий, по которым данный документ распространяется, даны в лицензии.
Этот документ является авторизованной спецификацией
JSP 1.2. Он предназначен для предоставления требований к реализациям процессинга JSP
и поддерживается web-контейнерами в web-серверах и серверами приложений.
Он не является справочником пользователя. Мы ожидаем появления других
документов, предназначенных для различных категорий читателей.
Разработчики контейнеров JSP и авторы страниц JSP могут найти необходимую информацию также в следующих документах:
Домашняя страница 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 |
Пионерами, выполнившими начальную работу по платформе 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.
Успех 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.
В этой главе детально разбираются Элементы Скриптинга, когда значением директивы language
является "java".
Этот язык скриптинга базируется на языке программирования Java (как
специфицировано в "The Java Language Specification"), но заметьте, что верная Java-программа
не является верной JSP-страницей или её разделом.
Далее детально описаны взаимоотношения объявлений скриптинга, скриптлетов и
выражений скриптов и языка программирования Java. Описание дано в терминах
структуры класса реализации JSP-страницы.
От JSP-контейнера не требуется генерировать класс реализации JSP-страницы, но он
обязан вести себя так, как будто этот класс существует.
Некоторые детали того, что делает JSP-страницу таковой, весьма специфичны для языка скриптинга, используемого на странице. Это особенно усложнено из-за того, что скриптлеты являются фрагментами, а не законченными операторами языка.
JSP-страница является таковой для Платформы Java, если, и только если, класс
реализации JSP-страницы, определённый по Таблице JSP.6-1
(после применения всех директив include
), вместе со всеми прочими
классами, определёнными JSP-контейнером, является верной программой для данной
Java-Платформы и если он передаёт методы проверки для всех библиотек тэгов,
ассоциированных с этой JSP-страницей.
Sun Microsystems резервирует для спецификаций JSP все имена, имеющие форму {_}jsp_*
и {_}jspx_*, в любом сочетании верхнего и нижнего регистров.
Имена, имеющие такую форму и не определённые в данной спецификации,
зарезервированы фирмой Sun для будущих расширений.
Трансформации, описанные в этой главе, не должны выполняться буквально.
Реализации могут выполнять их по-разному с целью обеспечения наилучшей производительности,
экономии памяти или других атрибутов реализации.
необязательное выражение импорта, как указано директивой jsp . |
import name1
|
SuperClass выбирается JSP-контейнером, либо автором
JSP через использование директивы jsp . Имя класса (_jspXXX) зависит от реализации. |
class _jspXXX extends SuperClass
|
Начало тела/body класса реализации JSP-страницы. | { |
(1) Раздел Объявлений | // объявления... |
Подпись для генерируемого метода. |
public void _jspService(<ServletRequestSubtype>
|
(2) Раздел Неявных/Implicit Объектов | // код, определяющий и инициализирующий request, response,
page, pageContext и т.п. |
(3) Главный/Main Раздел | // код, определяющий выражение отображения request/response
метода _jspService
|
закрытие метода _jspService
|
} |
закрытие _jspXXX
|
} |
Раздел объявлений соответствует элементам объявлений. Содержимое этого раздела определяется путём конкатенации всех объявлений на странице в порядке их появления.
Этот раздел определяет и инициализирует неявные объекты, доступные JSP-странице. См. Раздел JSP.2.8.3, "Неявные Объекты.
Этот раздел осуществляет главное отображение/mapping между объектами request
и response
.
Содержимое кодового сегмента 2 определяется скриптлетами, выражениями и текстовым телом JSP-страницы.
Элементы обрабатываются последовательно в порядке их появления на странице.
Трансляция каждого из них определяется так, как показано ниже, и вставляется в данный раздел.
Трансляция зависит от типа элемента:
Шаблонные данные трансформируются в код, который будет размещать
шаблонные данные в потоке, именованном неявной переменной out
в процессе
исполнения кода. Пробелы сохраняются.
Опуская подробности закавычивания и производительности, это соответствует оператору вида:
Оригинал | Эквивалентный Текст |
---|---|
шаблон | out.print(шаблон) |
Скриптлет трансформируется во фрагмент кода вида:
Оригинал | Эквивалентный Текст |
---|---|
<% фрагмент %> | фрагмент |
Выражение трансформируется в оператор Java для вставки значения выражения
(конвертированного, если необходимо, в
java.lang.String)
, в поток, именованный неявной переменной
out
.
Никакие дополнительные символы новой строки или пробелы не включаются.
Опуская подробности закавычивания и производительности, это соответствует
оператору вида:
Оригинал | Эквивалентный Текст |
---|---|
<%= выражение %> | out.print(выражение) |
Акция, определяющая один или более объектов, трансформируется в одно или
несколько объявлений переменных для этих объектов вместе с кодом, инициализирующим эти
переменные. На их видимость влияют другие конструкции, например, скриптлеты.
Семантика типа акции определяет имена переменных (обычно имя атрибута
id
, если он имеется) и их тип.
Единственной стандартной акцией в спецификации JSP, которая определяет объекты,
является акция jsp:usebean
. Имя вводимой переменной это имя атрибута
id
, а тип - атрибута класса.
Оригинал | Эквивалентный Текст |
---|---|
|
объявляются переменные AT_BEGIN |
Обратите внимание, что значение атрибута scope
/область видимости
не влияет на видимость переменных внутри генерируемой программы. Оно влияет на
то, где и как долго будут существовать дополнительные ссылки на объект, обозначенный этой переменной.
В этой главе даётся обзор технологии JavaServer Pages/Серверные Страницы Java.
JavaServer Pages≥ это технология Java≥ 2 Platform, Enterprise Edition (J2EE) для создания приложений, генерирующих динамическое web-содержимое - HTML, DHTML, XHTML и XML. Технология JavaServer Pages даёт возможность легко создавать динамическое содержимое web-страниц, предельно мощное и гибкое.
За некоторыми исключениями, интеграция JSP-страниц на платформу J2EE 1.3 наследуется из спецификации Servlet 2.3, поскольку трансляция превращает JSP-страницы в сервлеты.
В этой главе описываются обработчики тэгов и другие классы развёртывания тэгов,
а также методы доступа к файлам 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
предоставляет переносимый механизм для описания библиотек тэгов, включающий:
Tag Library Descriptor (TLD)/Дескриптор Библиотеки Тэгов (ДБТ)
Несколько классов обработчика тэга, определяющих поведение времени запроса
Несколько классов, определяющих поведение времени трансляции
Дополнительные ресурсы, используемые этими классами
Данная глава разбита на три раздела:
Первый раздел представляет базовые классы обработчика тэга.
Во втором разделе описаны более сложные обработчики тэга, которым необходим доступ к обсчёту их тела.
Последний раздел посвящён вопросам этапа/времени трансляции.
Этот раздел вводит понятие обработчика тэга и описывает простейшие типы обработчика тэга.
Обработчик тэга это объект времени выполнения, обслуживаемый контейнером,
обсчитывающий специальные акции в процессе выполнения
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
.
Tag
Синтаксис
public interface Tag
Все Известные Субинтерфейсы: BodyTag
, IterationTag
Описание
Это интерфейс простого обработчика тэга, который не хочет манипулировать своим содержимым.
Интерфейс Tag
определяет базовый протокол между обработчиком Tag
и классом реализации
JSP-страницы. Он определяет жизненный цикл и методы, вызываемые начальным и конечным тэгами.
Свойства
Интерфейс Tag
специфицирует
setter
и getter
-методы для основных свойств pageContext
и parent
.
Объект реализации JSP-страницы вызывает setPageContext
и setParent
в этом порядке до вызова
doStartTag
() или doEndTag
().
Методы
Есть две основные акции: doStartTag
и doEndTag
. После того как все соответствующие свойства
инициализированы, методы doStartTag
и doEndTag
могут быть вызваны обработчиком тэга. Между этими
вызовами принимается, что обработчик тэга имеет состояние, которое обязано
сохраняться. После вызова doEndTag
обработчик тэга доступен для последующих
вызовов (и предполагается, что сохраняет свои свойства).
Жизненный цикл
Детали жизненного цикла описываются ниже диаграммой перехода, со следующими комментариями:
[1] Этот переход предназначен для выпуска долгоживущих данных. Не даётся никаких гарантий долговечности свойств.
[2] Этот перенос происходит, если, и только если, тэг заканчивается нормально без вызова исключения.
[3] Заметьте, что, поскольку нет никаких гарантий статуса свойств, тэг, имеющий установленными какие-либо свойства по выбору/optional, может быть использован повторно, только если эти свойства устанавливаются в новое (известное) значение. Это значит, что обработчики тэгов могут использоваться только с тем же "AttSet" (набором установленных атрибутов).
Просмотрите интерфейс TryCatchFinally
на предмет дополнительных деталей
относительно обработки исключений и обслуживания ресурсов.
После того как все вызовы обработчика тэга выполнены, в нём вызывается метод release
.
После вызова метода release
, принимается, что все свойства, включая parent
и pageContext
, устанавливаются в неспецифицированное значение/unspecified
.
Компилятор страницы гарантирует, что release()
будет вызван в обработчике Tag
, до того как обработчик будет
освобождён для GC.
Пустые и Непустые Акции
Если файл TagLibraryDescriptor указывает, что акция обязана всегда быть пустой
акцией, через <body-content>
- "empty", тогда метод doStartTag
()
обязан возвращать SKIP_BODY
. В ином случае, метод doStartTag
() может вернуть SKIP_BODY
или
EVAL_BODY_INCLUDE
.
Если возвращён SKIP_BODY
, тело, если имеется, не обсчитывается.
Если возвращён EVAL_BODY_INCLUDE
, тело обсчитывается и "передаётся" текущему out
/выводу.
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
.
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_BUFFEREDBodyTag
.
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
.
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()
.
public static final int EVAL_BODY_AGAIN
Запрашивает повторение обсчёта некоторого тела/body.
Возвращается методом doAfterBody
. Для совместимости с JSP 1.1 значение должно
тщательно подбираться, чтобы быть тем же самым, что и в, теперь не рекомендуемом,
BodyTag.EVAL_BODY_TAG
.
public int doAfterBody()
Осуществляет (пере)обсчёт тела. Этот метод вызывается объектом реализации JSP-страницы
после каждого обсчёта тела в объекте BodyEvaluation
. Этот метод не вызывается, если нет обсчёта тела/body.
Если doAfterBody
возвращает
EVAL_BODY_AGAIN
, происходит новый обсчёт тела (с последующим вызовом doAfterBody
).
Если doAfterBody
возвращает SKIP_BODY
, обсчёт тела больше не производится, значение out
восстанавливается через использование метода popBody
в pageContext
, а затем
вызывается doEndTag
.
Повторные вызовы метода могут приводить к различным акциям, поскольку могли быть
произведены какие-то изменения разделяемого статуса, или из-за внешнего вычисления.
JSP-контейнер будет ресинхронизировать любые значения переменных, которые
обозначены в TagExtraInfo
, после вызова doAfterBody()
.
Возвращает: нужно ли проводить дополнительные обсчёты тела/body.
Вызывает: JspException
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(); // освобождает долгосрочные ресурсы
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
.
Этот метод предназначен для обслуживания целостности данных при вызове и акций обслуживания ресурсов.
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
и переопределять только некоторые методы.
protected java.lang.String id
protected PageContext pageContext
public TagSupport()
Конструктор по умолчанию, все классы должны определять только public-конструктор
с той же подписью и вызывать конструктор суперкласса. Этот конструктор
вызывается кодом, генерируемым JSP-транслятором.
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
для данного тэга.
Параметры:
-
idString
для id
.
public void setPageContext(PageContext pageContext)
Устанавливает контекст страницы.
Параметры:
-
pageContenxtPageContext
.
См. также:
public void setPageContext(PageContext pc)
public void setParent(Tag t)
Устанавливает вкладывающий тэг для данного тэга.
Параметры:
- родительский
tTag
.
См. также: public void setParent(Tag t)
public void setValue(java.lang.String k, java.lang.Object o)
Ассоциирует значение со String
-ключом.
Параметры:
-
kString
-ключ.
o
- Ассоциируемое значение.
Вычисление тела передаётся в объект
bodyContent
, который затем становится доступным обработчикам тэгов, реализующим интерфейс
BodyTag
. Класс
BodyTag-Support
даёт базовый класс, упрощающий написание этих обработчиков.
Если обработчик Tag
хочет иметь доступ к содержимому его тела, то он обязан
реализовывать интерфейс BodyTag
. Этот интерфейс расширяет IterationTag
, предоставляя два дополнительных метода
setBodyContent(bodyContent)
и
doInitBody()
и ссылаясь на объект типа bodyContent
.
это подкласс
bodyContentJspWriter
'а, имеющий
несколько дополнительных методов для конвертации его содержимого в 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)
.
bodyContent
Синтаксис
public abstract class bodyContent extends JspWriter
Описание
Инкапсулирует вычисление/обсчёт тела акции так, что доступен обработчику тэга. bodyContent
является подклассом JspWriter
'а.
Обратите внимание, что содержимое
bodyContent
'а является результатом вычисления, поэтому
оно не будет содержать акций и т.п., кроме результата своих вызовов.
имеет методы конвертации своего содержимого в
bodyContentString
, для чтения его
содержимого, и для очистки/clear своего содержимого.
Размер буфера объекта bodyContent
не ограничен. Объект bodyContent
не может быть
в режиме autoFlush
.
Невозможно вызвать flush
в объекте bodyContent
, так как
отсутствует фоновый/backing поток.
Экземпляры bodyContent
'а создаются через вызов методов pushBody
и popBody
класса PageContext
.
заключён внутри другого
bodyContentJspWriter
'а (возможно, другого объекта
bodyContent
), следуя структуре их ассоциированных акций.
становится доступным
bodyContentBodyTag
'у через вызов setBodyContent()
.
Обработчик тэга может использовать этот объект до момента вызова doEndTag()
.
protected bodyContent(JspWriter e)
Protected-конструктор. Несвязанный буфер, без autoflushing/автооочистки.
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
. Подклассы могут оптимизировать общие патэрны вызова.
Параметры:
- writer, в который помещается содержимое вычисления этого body.
out
Вызывает: IOException
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-страницы будет размещать вычисление/обсчёт (и повторный обсчёт, если нужно) тела.
-метод (
settersetBodyContent
) будет вызван только в том случае, если 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()
.
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
. Помечена как не рекомендуемая
с целью продвижения этих двух различных терминов, которые являются более описательными.
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
BodyTagSupport
Синтаксис
public class BodyTagSupport extends TagSupport implements BodyTag
Все Реализованные Интерфейсы: BodyTag
, IterationTag
, java.io.Serializable
, Tag
Описание
Базовый класс для определения обработчиков тэгов, реализующих BodyTag
.
Класс BodyTagSupport
реализует интерфейс BodyTag
и добавляет несколько удобных
методов, включая getter
-методы для свойства bodyContent
и методы для получения предыдущего
out JspWriter
.
Многие обработчики тэгов будут расширять
BodyTagSupport
и переопределять только несколько методов.
protected bodyContent bodyContent
public BodyTagSupport()
Конструктор по умолчанию, все подклассы должны определить public-конструктор с
той же подписью и вызвать конструктор суперкласса. Этот конструктор вызывается
кодом, генерируемым JSP-транслятором.
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-контейнер может выбрать выполнение некоторого обслуживания обработчика тэга.
Есть и другие стратегии, которым можно следовать.
В данном примере мы принимаем, что 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();
}
Акции могут кооперироваться с другими акциями и с кодом скриптинга разными способами.
PageContext
Часто две акции в JSP-странице нужно скооперировать: когда, возможно, одна акция
создаёт серверный объект, доступ к которому осуществляет вторая акция. Один из
механизмов реализации этого - дать объекту имя внутри JSP-страницы; первая акция
создаст объект и ассоциирует имя с ним, а вторая акция будет использовать это
имя для запроса объекта.
Например, в следующем JSP-фрагменте акция
foo
может создать серверный объект и дать ему имя "myObject"
. Затем акция
bar
может получить доступ к этому серверному объекту и выполнить какое-нибудь действие.
<x:foo id="myObject" />
<x:bar ref="myObjet" />
В JSP-реализации отображение "имя"->значение хранится в неявном объекте pageContext
.
Этот объект передаётся по кругу через экземпляры обработчика Tag
так, что он
(объект) может использоваться для передачи информации: всё, что необходимо, это
знать имя, под которым информация хранится в pageContext
.
Альтернативой явной передаче информации через именованный объект является
неявная координация на базе синтаксической видимости.
Например, в следующем JSP-фрагменте акция
foo могла бы создать серверный объект; затем вложенная акция
bar могла бы получить доступ к этому серверному объекту.
Этот объект не именован внутри pageContext
: он может быть найден, поскольку конкретный элемент
foo
является ближайшим содержащим экземпляром известного типа элемента.
<foo>
<bar/>
</foo>
Эта функциональность поддерживается через
BodyTagSupport.findAncestorWithClass(Tag, Class)
,
который использует ссылку на родительский тэг, сохраняемую каждым экземпляром Tag
,
что эффективно представляет стэк выполнения времени/этапа прогона.
Следующие классы используются на этапе трансляции.
Tag
-отображение, Tag
-имяДиректива taglib
вводит библиотеку тэгов и ассоциирует с ней префикс. TLD,
ассоциированный с библиотекой, ассоциирует классы обработчика Tag
(плюс другая
информация) с именами тэгов. Эта информация используется для ассоциирования Tag
-класса,
префикса и имени с каждым элементом специальной акции, появляющимся на JSP-странице.
На этапе выполнения реализация JSP-страницы будет использовать доступный
экземпляр Tag
с соответствующими установками свойств, а затем следовать
протоколу, описанному интерфейсами Tag
,
IterationTag
, BodyTag
и TryCatchFinally
. Реализация гарантирует, что все
экземпляры обработчика тэга инициализируются и высвобождаются, но реализация
может принимать, что предыдущие установки сохраняются обработчиком тэга, чтобы уменьшить затраты на этапе прогона.
JSP поддерживает переменные скриптинга, которые могут объявляться внутри одного
скриптлета и использоваться в другом. JSP-акции также можно использовать для
определения переменных скриптинга, чтобы использовать их затем в элементах
скриптинга или в других акциях. Это особенно применимо в некоторых случаях;
например, стандартная акция jsp:useBean
может определять объект, который позднее используется через
переменную скриптинга.
В некоторых случаях информация переменных скриптинга может быть описана
непосредственно в TLD, используя элементы. Особый случай - типичная итерация
атрибута "id"
. В других случаях логика, определяющая определение экземпляром
акции переменной скриптинга, может быть довольно сложной, и имя класса
TagExtraInfo
используется вместо данного в TLD.
Метод getVariableInfo
этого класса используется во время трансляции для получения
информации о каждой переменной, которая будет создана во время запроса, когда
данная акция выполняется. Метод передаётся в
TagDat
-экземпляр, содержащий значения атрибутов времени трансляции.
TLD-файл содержит несколько частей информации, которая используется для проверки
синтаксиса на этапе трансляции. Он содержит также два расширяемых механизма проверки: класс
TagLibraryValidator
может использоваться для проверки всей JSP-страницы, а класс
TagExtraInfo
может использоваться для проверки специфической акции. В некоторых
случаях дополнительная проверка на этапе запроса будет выполняться динамически
внутри методов в экземпляре Tag
. Если обнаружена ошибка, может быть вызван
экземпляр JspTagException
. Если ошибка не выловлена, этот объект будет
вызывать механизм errorpage JSP.
является дополнением к спецификации JSP 1.2 и заканчивается
очень открыто, будучи значительно более мощным, чем механизм
TagLibraryValidatorTagExtraInfo
.
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
страницы, в лексическом порядке их появления,
вызывается класс их ассоциированного проверщика (если имеется). Это вызывает
выполнение нескольких дополнительных шагов.
Первый шаг выполняется для получения инициализированного экземпляра проверщика путём, либо:
конструирования нового экземпляра и вызова в нём setInitParameters()
, либо
получения существующего объекта, который не используется, вызова в нём
и вызова следом в нём же release
()setInitParameters()
, либо
локализации существующего объекта, который не используется, в котором
необходимый setInitParameters()
уже вызван.
Имя класса - такое, какое указано в элементе <validator-class>
, а Map
,
переданный в setInitParameters()
- такой, как описано в элементе <init-params>
. Предполагается, что все
классы TagLibraryValidator
сохраняют свои initParameters
до тех пор, пока не будут
установлены новые или пока
не будет в них вызван.release
()
Второй дополнительный шаг выполняет реальную проверку. Это делается через вызов
метода validate()
с префиксом, uri
и PageData
, которые соответствуют
проверяемому экземпляру директивы taglib
и PageData
, представляющему эту страницу.
Последний дополнительный шаг вызывает метод
в тэге проверщика, когда он уже больше не нужен.
release
()
Этот метод освобождает все ресурсы.
Наконец,
после проверки всех классов проверщика библиотеки тэгов, классы TagExtraInfo
для
всех тэгов будут проверяться вызовом их метода isValid
. Порядок вызова этого метода не определён.
TagLibraryInfo
Синтаксис
public abstract class TagLibraryInfo
Описание
Это информация времени трансляции, ассоциированная с директивой taglib
и её
TLD-файлом. Большая часть информации получается непосредственно из TLD, за
исключением значений префикса и uri
, используемых в директиве taglib.
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
protected TagLibraryInfo(java.lang.String prefix, java.lang.String uri)
Конструктор. Будут вызываться конструкторы для TagInfo
и TagAttributeInfo
после разбора TLD-файла.
Параметры:
- префикс, используемый директивой
prefixtaglib
uri
- URI, используемый директивой taglib
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
для данной библиотеки.
TagInfo
Синтаксис
public class TagInfo
Описание
Информация Tag
для тэга в Библиотеке Тэгов; этот класс инстанциируется из файла TLD/Дескриптора Библиотеки Тэгов и доступна только во время трансляции.
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
.
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
- массив данных AttributeInf
o из дескриптора. Может быть 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
).
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}
Параметры:
-
dataTagData
, описывающие данную акцию.
Возвращает: массив элементов VariableInfo
.
public booleanisValid(TagData data)
Проверка атрибутов на этапе трансляции. Это удобный метод в
ассоциированном классе TagExtraInfo
.
Параметры:
- экземпляр
dataTagData
времени трансляции.
Возвращает: верны ли данные.
public void setTagExtraInfo(TagExtraInfo tei)
Набор экземпляров для дополнительной информации тэга.
Параметры:
tei
- экземпляр TagExtraInfo
.
public void setTagLibrary(TagLibraryInfo tl)
Устанавливает свойство TagLibraryInfo
.
Заметьте, что элемент TagLibraryInfo
зависит не просто от информации TLD, но
также и от специфики используемого экземпляра taglib
. Это означает, что
некоторая работа должна быть проделана для конструирования и инициализации
объектов TagLib
. Если использовать аккуратно, этот setter
поможет исключить
необходимость создания новых элементов TagInfo
для каждой директивы taglib
.
Параметры:
- назначаемый
tlTagLibraryInfo
.
public java.lang.String toString()
Строго для целей отладки ...
Переопределяет: java.lang.Object.toString()
в классе java.lang.Object
TagAttributeInfo
Синтаксис
public class TagAttributeInfo
Описание
Информация об атрибуте тэга, доступная во время трансляции. Этот класс инстанциируется из файла TLD.
Сюда включается только информация, необходимая для генерации кода. Друга
информация типа SCHEMA для проверки выводится в других местах.
public static final java.lang.String ID
окружается, чтобы стать
"id"ID
. Реально это не даёт преимущества, поскольку
IDREF
не обрабатываются раздельно.
public TagAttributeInfo(java.lang.String name, boolean required, java.lang.String type, boolean reqTime)
Конструктор для TagAttributeInfo
.
Этот класс инстанциируется только из кода TagLibrary
по запросу из
некоторого JSP-кода, разбирающего TLD.
Параметры:
- имя атрибута.
name
required
- необходим ли атрибут в экземплярах тэга.
type
- имя типа атрибута.
reqTime
- содержит ли данный атрибут Attribute
времени запроса.
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
PageData
Синтаксис
public abstract class PageData
Описание
Информация времени трансляции о
JSP-странице. Информация соответствует XML-просмотру JSP-страницы.
Объекты этого типа генерируются JSP-транслятором, например, при передаче экземпляру TagLibraryValidator
.
public PageData()
public abstract java.io.InputStream getInputStream()
Возвращает поток ввода в XML-просмотре JSP-страницы. Вызывает XML-просмотр JSP-страницы,
который содержит развёрнутые директивы include
.
Возвращает: поток ввода документа.
TagLibraryValidator
Синтаксис
public abstract class TagLibraryValidator
Описание
Класс проверщика этапа трансляции для JSP-страницы. Проверщик оперирует
документом XML, ассоциированным с JSP-страницей. TLD-файл ассоциирует класс
TagLibraryValidator
и некоторые init-аргументы с библиотекой тэгов.
JSP-контейнер отвечает за размещение соответствующих объектов соответствующего подкласса через:
новый экземпляр fresh
или через использование имеющегося экземпляра;
вызов метода setInitParams(Map)
в экземпляре после инициализации, метод
validate(String, String, PageData
) будет вызван там,
где первые два аргумента - это prefix
и uri
, используемые в директиве taglib
.
Экземпляр TagLibraryValidator
может создавать вспомогательные объекты внутри для
выполнения проверки (например, проверщик XSchema) и может использовать их для всех страниц в ходе данной трансляции.
JSP-контейнер не сериализует гарантированно вызовы метода validate()
,
и TagLibraryValidator
'ы должны выполнять синхронизацию, которая может потребоваться.
JSP-контейнер может по выбору поддерживать атрибут jsp:id
для предоставления
качественной проверки ошибок. Если такая поддержка имеется,
контейнер будет отслеживать JSP-страницы, передаваемые контейнеру, и будет
назначать каждому элементу уникальный "id"
, который передаётся как значение
атрибута jsp:id
. Каждый элемент XML, доступный в XML-просмотре, будет расширен этим атрибутом.
может затем использовать этот атрибут в
одном или более объектах
TagLibraryValidatorValidationMessage
. Контейнер тогда, в свою очередь, может использовать эти
значения для предоставления более точной информации о местонахождении ошибки.
public TagLibraryValidator()
public java.util.Map getInitParameters()
Получает данные init-параметров как неизменяемую Map/Карту. Имена параметров это ключи,
а значения параметров - это значения.
Возвращает: параметры init как неизменяемую карту.
public void release()
Высвобождает любые данные, хранимые этим экземпляром, с целью проверки.
)
public void setInitParameters(java.util.Map map
Устанавливает данные init
в TLD для этого проверщика. Имена параметров
это ключи, а значения параметров - это значения.
Параметры:
- карта, описывающая параметры
initMapinit
.
public ValidationMessage[] validate(java.lang.String prefix, java.lang.String uri, PageData page)
Проверяет JSP-страницу. Будет вызван однократно на каждую директиву в JSP-странице.
Этот метод возвратит null
, если страница верна/valid; иначе метод должен
возвратить массив объектов ValidationMessage
. Массив нулевой длины также
интерпретируется как отсутствие ошибок.
Параметры:
- значение аргумента
prefixprefix
в директиве.
uri
- значение аргумента uri
в директиве.
thePage
- JspData
-объект страницы.
Возвращает: null
-объект, или массив нулевой длины при отсутствии ошибок, или массив объектов
ValidationMessages
.
ValidationMessage
Синтаксис
public class ValidationMessage
Описание
Сообщение о проверке из TagLibraryValidator
. JSP-может (по выбору)
поддерживать атрибут jsp:id
для предоставления качественной проверки ошибок.
Если такая поддержка имеется, контейнер будет отслеживать JSP-страницы, передаваемые контейнеру, и будет
назначать каждому элементу уникальный "id", который передаётся как значение
атрибута jsp:id
. Каждый элемент XML, доступный в XML-просмотре, будет расширен
этим атрибутом. TagLibraryValidator
может затем использовать этот атрибут в
одном или более объектах ValidationMessage
. Контейнер тогда, в свою очередь, может использовать эти
значения для предоставления более точной информации о местонахождении ошибки.
public ValidationMessage(java.lang.String id, java.lang.String message)
Создаёт ValidationMessage
. String
сообщения должна быть не-null. Значение id
может быть null
, если сообщение не специфично для XML-элемента или если не были
переданы никакие атрибуты jsp:id
. Если не-null, значение id
обязано быть
значением атрибута jsp:id
для PageData
, передаваемым в метод validate()
.
Параметры:
- либо
idnull
, либо значение атрибута jsp:id
.
message
- локализованное сообщение о проверке.
public java.lang.String getId()
Получает jsp:id
.
null
означает, что нет доступной информации.
Возвращает: jsp:id
-информацию.
public java.lang.String getMessage()
Получает локализованное сообщение о проверке.
Возвращает: сообщение о проверке.
TagExtraInfo
Синтаксис
public abstract class TagExtraInfo
Описание
Класс по выбору, предоставляемый автором библиотеки тэгов для описания
дополнительной информации времени трансляции, не указанной в TLD. Класс TagExtraInfo
упоминается в файле TLD.
Этот класс может использоваться:
для указания на то, что тэг определяет переменные скриптинга;
для выполнения проверки атрибутов тэга на этапе трансляции .
JSP-транслятор отвечает за то, чтобы начальное значение, возвращаемое в вызове getTagInfo()
,
соответствовало объекту TagInfo
транслируемого тэга.
Если выполняется явный вызов setTagInfo()
, тогда передаваемый объект будет
возвращён в последующих вызовах getTagInfo()
.
Единственный способ повлиять на значение, возвращаемое методом getTagInfo()
, -
через вызов setTag-Info()
и, следовательно, TagExtraInfo.setTagInfo()
вызывается JSP-транслятором с
объектом TagInfo
, который соответствует транслируемому тэгу. Это должно
происходить до любого вызова isValid()
и до любого вызова
getVariableInfo()
.
public TagExtraInfo()
public final TagInfo getTagInfo()
Получает TagInfo
для этого класса.
Возвращает: экземпляр taginfo
, расширяемый данным экземпляром.
public VariableInfo[] getVariableInfo(TagData data)
Информация о переменных скриптинга, определённых тэгом, ассоциированным с
данным экземпляром TagExtraInfo
. Атрибуты времени запроса указаны как таковые в параметре
TagData
.
Параметры:
- экземпляр
dataTagData
.
Возвращает: массив данных VariableInfo
.
public boolean
isValid(TagData data)
Проверка атрибутов на этапе трансляции. Атрибуты времени запроса указаны
как таковые в параметре TagData
.
Параметры:
- экземпляр
dataTagData
.
Возвращает: верен ли этот экземпляр тэга.
public final void setTagInfo(TagInfo tagInfo)
Устанавливает TagInfo
для данного класса.
Параметры:
-
tagInfoTagInfo
, расширяемая этим экземпляром.
TagData
Синтаксис
public class TagData implements java.lang.Cloneable
Все Реализованные Интерфейсы:
java.lang.Cloneable
Описание
Информация (только времени трансляции)
атрибута/значения для экземпляра тэга. TagData
используется только в качестве аргумента методов isValid
и getVariableInfo
в TagExtraInfo
, которые вызываются во время трансляции.
public static final java.lang.Object REQUEST_TIME_VALUE
Значение, отличное от атрибута, для указания, что его (атрибута) значение
является выражением времени запроса (которое ещё не доступно, поскольку
экземпляры TagData
используются на этапе трансляции).
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
.
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
- значение.
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 определяет интерпретацию трёх значений:
NESTED
, если переменная скриптинга доступна между начальным и конечным тэгами
акции, которая определяет её.
AT_BEGIN
, если переменная скриптинга доступна из начального тэга акции, которая
определяет её, до достижения предела видимости.
AT_END
, если переменная скриптинга доступна после конечного тэга акции, которая
определяет её, до достижения предела видимости.
Значение области видимости переменной предполагает, какие методы влияют на значение и, следовательно, где нужна синхронизация:
для NESTED
, после doInitBody
и
doAfterBody
для обработчика тэга, реализующего
BodyTag
, и после doStartTag
- в противном случае.
для AT_BEGIN
, после doInitBody
,
doAfterBody
и doEndTag
для обработчика тэга, реализующего BodyTag
, и
doStartTag
и doEndTag
- в противном случае.
для AT_END
, после метода doEndTag
.
Информация переменной скриптинга может быть также непосредственно кодирована для
большинства случаев в Tag Library Descriptor путём использования субэлемента <variable>
элемента <tag>
. См. спецификацию JSP.
public static final int AT_BEGIN
Информация области видимости о том, что переменная скриптинга видна после
начального тэга.
public static final int AT_END
Информация области видимости о том, что переменная скриптинга видна после конечного тэга.
public static final int NESTED
Информация области видимости о том, что переменная скриптинга видна
только между начальным/конечным тэгами.
public VariableInfo(java.lang.String varName, java.lang.String className, boolean declare, int scope)
Конструктор. Эти объекты могут быть созданы (на этапе трансляции) экземплярами TagExtraInfo
.
Параметры:
- имя переменной скриптинга.
id
className
- имя переменной скриптинга (наверное, класса??).
declare
- если true
, это новая переменная (в некоторых языках это требует объявления).
scope
- обозначение лексической области видимости переменной.
public java.lang.String getClassName()
public boolean getDeclare()
public int getScope()
public java.lang.String getVarName()
TagVariableInfo
Синтаксис
public class TagVariableInfo
Описание
Информация переменной для тэга в Библиотеке Тэгов. Этот класс инстанциируется из TLD-файла и доступен только во время трансляции. Этот объект должен быть неизменяемым.
Данная информация доступна только в формате JSP 1.2.
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>
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>
.
Возвращает: область видимости для переменной.
В этой главе описаны синтаксис ядра и семантика спецификации JavaServer Pages 1.2 (JSP 1.2).
JSP-страница это текстовый документ, который описывает, как создавать объект response
из объекта request для данного протокола. Процессинг JSP-страницы может
включать создание и/или использование других объектов.
JSP-страница определяет класс реализации JSP-страницы который реализует
семантику JSP-страницы. Этот класс является подклассом Servlet'а (см.
Главу JSP.8). Во время запроса, запрос, предназначенный для JSP-страницы,
направляется объекту реализации JSP-страницы для обработки/процесинга.
HTTP является протоколом по умолчанию для запросов и ответов. Дополнительные
протоколы запроса/ответа могут поддерживаться JSP-контейнерами (см. ниже).
Объекты request
и response
по умолчанию имеют тип HttpServletRequest
и
HttpServletResponse
, соответственно.
JSP-контейнер это экземпляр системного уровня, предоставляющий
обслуживание жизненного цикла и поддержку на этапе прогона для JSP-страниц Servlet-компонентов.
Запросы, направляемые JSP-странице, направляются JSP-контейнером подходящему
объекту реализации JSP-страницы. Термин web-контейнер
является синонимом JSP-контейнера.
Web-компонент это сервлет или JSP-страница. Элемент servlet
в дескрипторе публикации
web.xml используется для описания обоих типов web-компонентов. Компоненты - JSP-страницы
- определяются неявно в дескрипторе публикации через использование неявного
отображения расширения .jsp
JSP-страницы имеют эквивалент - XML-документ. XML-просмотр JSP-страницы создан для фазы трансляции
(см. ниже).
JSP-страница может быть написана сразу как XML-документ. Начиная с версии JSP
1.2, XML-документ может быть направлен JSP-контейнеру для процесинга.
Нельзя смешивать стандартный синтаксис и XML-синтаксис в одном файле-источнике.
Однако JSP-страница любого синтаксиса может включать JSP-страницу любого
синтаксиса через директиву.
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-страница может отмечать обработку некоторых событий. В JSP 1.2 только события init и destroy могут быть описаны в JSP-странице.
Когда первый запрос направляется JSP-странице, метод
jspInit()
, если он имеется,
будет вызван для подготовки страницы.
Аналогично, JSP-контейнер может вызывать метод JSP jspDestroy()
для переделки ресурсов, используемых JSP-страницей, в любой момент, когда запрос
не обслуживается. Это такой же жизненный цикл, что и у сервлетов.
JSP-страница может быть откомпилирована в свой класс реализации, плюс
информация публикации в процессе создания (JSP-страница может также
компилироваться в процессе публикации).
Таким способом утилиты авторизации JSP-страниц и библиотеки тэгов JSP могут
использоваться для создания сервлетов. Преимущества этого подхода таковы:
Компиляция JSP-страницы в контексте web-приложения предоставляет разрешение
спецификаций относительных URL в директивы include
(и в другом месте),
ссылок на taglib
и акции времени трансляции, используемых в специальных акциях.
JSP-страница может также компилироваться во время публикации.
Когда класс реализации JSP-страницы зависит от поддержки классов (в дополнение к классам JSP 1.2 и Servlet 2.3), классы поддержки включаются в упакованный WAR-файл (как определено в спецификации Servlet 2.3) для обеспечения переносимости по JSP-контейнерам.
В Приложении JSP.A есть два примера упаковки JSP-страниц в WAR'ы:
В информации для публикации указаны необходимые поддерживающие классы и отображение между путём оригинального URL в JSP-страницу и URL для класса реализации этой JSP-страницы.
Раньше утилиты отладки не имели стандартного формата для передачи информации отображения исходного кода, позволяющей использовать отладчик одного производителя с JSP-контейнером другого. Спецификация с поддержкой отладки, преодолевшая эти ограничения, разрабатывается как JSR-045 процесса JCP 2.0 под названием "Debugging Support for Non-Java Languages/Поддержка Отладки для Не-Java-Языков".
Детали можно найти по адресу
http://jcp.org/jsr/detail/45.jsp
JSP-страница упаковывается в один или более файлов, часто - как web-приложение,
и направляется утилите типа JSP-контейнера, J2EE-контейнера или IDE. Полная JSP-страница
может содержаться в одном файле. В других случаях основной файл содержит другие
файлы, которые содержать полные JSP-страницы или включаемые фрагменты.
Утилиты обычно требуют отделения файлов JSP-страницы от других файлов.
В некоторых случаях утилиты также требуют отделения файлов верхнего уровня/top JSP
от включаемых фрагментов. Например, если фрагмент может не быть правильной JSP-страницей
и может не компилироваться соответствующим образом.
Определение типа файла также часто практикуется на уровне документации и
обслуживания, как должно быть уже известно тем, кто работает с соглашениями ".c"
и ".h" языка C.
Спецификация Servlet 2.3 использует расширение ".jsp" для обозначения JSP-страницы,
но не дифференцирует основные JSP-файлы и включаемые фрагменты.
Мы рекомендуем (но не обязываем), чтобы:
Приложение web это коллекция ресурсов, которые доступны по указанным URL.
Web-приложение состоит из следующих компонентов:
Web-приложения описаны более детально в спецификации Servlet 2.3.
Web-приложение содержит дескриптор публикации
web.xml, содержащий информация о JSP-страницах,
сервлетах и других ресурсах, используемых в этом web-приложении. Дескриптор
публикации детально описан в спецификации Servlet 2.3.
JSP 1.2 требует, чтобы эти ресурсы были неявно/косвенно ассоциированы с, и доступны через, уникальный экземпляр
ServletContext
, доступный как неявный объект приложения (Раздел JSP.2.8).
Приложение, которому принадлежит JSP-страница, отражается в объекте
application
и влияет на семантику следующих элементов:
include
(Раздел JSP.2.10.3).jsp:include
(Раздел JSP.4.4).jsp:forward
(Раздел JSP.4.5).JSP 1.2 поддерживает переносимую упаковку и публикацию/deployment web-приложений через спецификацию Servlet 2.3. Спецификация JavaServer Pages наследует от спецификации Servlet концепцию приложений, ServletContext'ы, Sessions/Сессии, Requests/Запросы и Responses/Ответы.
Элементы могут использовать спецификации относительных 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-страниц.
JSP-страница содержит элементы и шаблонные данные.
Элемент является экземпляром типа элемента, известного JSP-контейнеру.
Шаблонные данные это то, о чём JSP-танслятор ничего не знает.
Тип элемента описывает его синтаксис и семантику. Если элемент имеет атрибуты, тип описывает имена, верные типы атрибутов и их интерпретацию. Если элемент определяет объекты, семантика включает эти определяемые объекты и их типы.
Имеются элементы трёх типов: директивы, элементы скриптинга и акции.
Директивы предоставляют глобальную информацию, которая концептуально верна, независимо от специфики запроса, полученного JSP-страницей. Директивы предоставляют информацию для фазы трансляции.
Синтаксис элемента-директивы
<%@ директива...%>
Акции предоставляют информацию для фазы обработки запроса. Интерпретация
акции может, и часто так и бывает, зависеть от специфики запроса,
полученного JSP-страницей.
Акции могут быть стандартными, то есть
определёнными этой спецификацией, или
custom/специальными, то есть предоставленными через посредство механизма
развёртывания переносимых тэгов.
Элементы action
следуют синтаксису XML-элемента: они имеют начальный тэг, включающий имя
элемента, и могут иметь атрибуты, необязательное тело/body и соответствующий
конечный тэг, или они могут быть пустыми тэгами, возможно, с атрибутами:
<mytag attr1="значение атрибута"...>body</mytag>
и
<mytag attr1="значение атрибута".../>
<mytag attr1="значение атрибута" ...></mytag>
Элемент имеет тип элемента, описывающий имя его тэга, верные атрибуты и их семантику.
Мы обращаемся к типу по имени его тэга.
JSP-тэги чувствительны к регистру, как в XML и XHTML.
Акция может создавать объекты и делать их доступными элементам скриптинга через
специфические для скриптинга переменные.
Элементы Скриптинга являются связкой между шаблонным текстом и акциями.
Есть три типа элементов скриптинга:
declarations\объявления, scriptlets\скриптлеты и expressions\выражения.
Объявления имеют синтаксис
<%! ... %>
скриптлеты
<% ... %>
выражения
<%= ... %>
Элементы, имеющие разные начальный и конечный тэги (при наличии тела), обязаны
иметь начало и конец в одном файле. Стартовый тэг не может быть в одном файле,
когда конечный тэг находится в другом файле.
То же самое правило применяется к элементам с альтернативным синтаксисом.
Например, скриптлет имеет синтаксис
<% скриптлет %>
.
Открывающий <%
и закрывающий %>
символы обязаны находиться в одном
и том же физическом файле.
Язык скриптинга может также вводить ограничения на размещение начальных и
конечных тэгов для специфических конструкций скриптинга. Например, в
Главе 6
демонстрируется, как блоки языка Java не могут разделять начальный и конечный
тэг; см. детали в Разделе JSP.6.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>
Следуя спецификации XML, атрибуты всегда заключаются в кавычки. Одинарные или двойные кавычки могут использоваться для уменьшения необходимости ввода кавычек мнемониками; соглашения по кавычкам описаны в Разделе JSP.2.6. Есть два типа значений атрибутов: литералы и выражения времени запроса (Раздел JSP.2.13.1), но правила применения кавычек - одинаковы.
Имена акций обязаны следовать соглашению XML (т.е. обязаны быть NMTOKEN
, как указано
в спецификации XML 1.0). Имена атрибутов обязаны следовать соглашениям, описанным в спецификации JavaBeans.
Имена атрибутов, начинающиеся с jsp,
_jsp, java или sun зарезервированы данной спецификацией.
В HTML и XML пробел обычно не является значащим, но есть исключения.
Например, файл XML может начинаться символами
<?xml
, и,
если это так, ведущих пробельных символов не должно быть.
Данная спецификация следует поведению пробелов, определённому в спецификации XML.
Пробел в теле текста документа не является значащим, но сохраняется.
Далее идут два фрагмента JSP с ассоциированным выводом.
Обратите внимание, что директивы не генерируют никаких данных и применяются глобально к
JSP-странице.
N Строки | Исходный Текст |
---|---|
1 |
<?xml version="1.0" ?>
|
2 | <%@ page buffer="8kb" %> |
3 | Здесь - остальная часть документа. |
Результат:
N Строки | Текст на Выходе |
---|---|
1 |
<?xml version="1.0" ?>
|
2 | |
3 | Здесь - остальная часть документа. |
Следующие две таблицы - другой пример ввода и вывода:
N Строки | Исходный Текст |
---|---|
1 |
<% response.setContentType("....");
|
2 | что-нибудь... %><?xml version="1.0" ?>
|
3 |
<%@ page buffer="8kb" %>
|
4 | Здесь - остальная часть документа. |
Результат:
N Строки | Текст на Выходе |
---|---|
1 |
<?xml version="1.0" ?>
|
2 | |
4 | Здесь - остальная часть документа. |
Ошибки могут появляться на этапах трансляции или запроса. В этом разделе описывается, как ошибки обрабатываются соответствующей реализацией.
Трансляция JSP-страницы-источника в соответствующий класс реализации JSP-страницы JSP-контейнером
может производиться в любой момент между начальной публикацией JSP-страницы в JSP-контейнер
и получением и обработкой запроса клиентом целевой JSP-страницы.
Если трансляция возникает до получения клиентского запроса целевой JSP-страницы,
обработка ошибок и уведомление зависят от реализации и не рассматриваются в
данной спецификации. Фатальные ошибки трансляции должны в результате приводить к
невозможности выполнения последующих клиентских запросов на трансляцию целевой
страницы с соответствующей спецификацией ошибки:
для протоколов HTTP будет возвращаться код ошибки 500 (Server Error/Ошибка Сервера).
В процессе обработки запросов клиентов ошибки могут возникать в теле класса
реализации 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-странице есть два типа комментариев:
комментарии к самой JSP-странице, документирующие действия страницы, и
комментарии, предназначенные для вывода в генерируемом документе, направляемом клиенту.
Для генерации комментариев, появляющихся в потоке вывода response
к
запрашивающему клиенту, используется следующий синтаксис комментариев HTML и XML:
<!-- комментарии
... -->
Такие комментарии рассматриваются JSP-контейнером как неизменяемый шаблонный
текст. Если генерируемый комментарий должен содержать динамические данные, это
может быть сделано посредством такого синтаксиса:
<!-- комментарии
<%= выражение %> ещё комментарии ... -->
JSP-комментарий имеет форму:
<%-- что-либо, кроме закрывающих символов --%> ... --%>
Содержимое тела комментария полностью игнорируется. Комментарии используются для
документирования, а также для
"закомментирования" некоторой части JSP-страницы.
Обратите внимание, что JSP-комментарии не вкладываются.
Альтернативным способом размещения "комментария" на JSP-странице является
использование механизма комментария языка скриптинга. Например:
<% /** это комментарий ... **/ %>
В JSP-страницах применяются следующие соглашения по кавычкам:
Литерал %>
закавычивается %\>
Литерал <%
закавычивается <\%
Закавычивание выполняется независимо от того, является значение атрибута
литералом или выражением атрибута этапа запроса. Закавычивание может
использоваться в значениях атрибутов независимо от того, ограничены они
одинарными или двойными кавычками. Это выполняется только так, как описано ниже:
\'
. Это необходимо делать внутри значения атрибута,
ограниченного одинарными кавычками.\"
. Это необходимо делать внутри значения атрибута,
ограниченного двойными кавычками.\\
%>
записывается %\>
<%
записывается <\%
В следующей строке показаны неправильные значения атрибутов:
<mytags:tag value="<%= "hi!" %>"
/>
В следующей строке дан верный скриптлет, но с, возможно, неожиданным результатом. Результат будет "Joe said %\>", а не "Joe said %>":
<%= "Joe said %\\>" %>
В следующих строках - правильное закавычивание:
<%= "Joe said %/>" %>
<%= "Joe said %\>" %>
<% String joes_statement = "hi!";
%>
<%= "Joe said \"" + joes_statement
+ "\"." %>
<x:tag value='<%="Joe said \\"" +
joes_statement + "\\"."%>'/>
<x:tag value='<%= "hi!" %>' />
<x:tag value="<%= \"hi!\" %>" />
<x:tag value='<%= \"name\" %>' />
<x:tag value="<%= \"Joe said
'hello'\" %>"/>
<x:tag value="<%= \"Joe said
\\\"hello\\\" \" %>"/>
<x:tag value="end expression
%\>"/>
<% String s="abc"; %>
<x:tag value="<%= s + \"def\" + \"jkl\"
+ 'm' + \'n\' %>" />
<x:tag value='<%= s + \"def\" + "jkl"
+ \'m\' + \'n\' %>' />
Соглашения по кавычкам отличаются от соглашений XML. См. Главу JSP.5.
Класс реализации JSP-страницыопределяет отображение метода _jspService()
из объекта request в объект response. Некоторые детали этой
трансформации специфичны для используемого языка скриптинга (см.
Главу JSP.6).
Некоторые детали не зависят от языка и описаны в данной главе.
Содержимое JSP-страницы большей частью описывает данные, которые записываются в
поток вывода ответа. (JSP-контейнер обычно посылает эти данные обратно клиенту.)
Это описание базируется на объекте JspWriter
, который выводится через неявный объект
out (см. Раздел JSP.2.8.3, "Неявные Объекты).
Его значение варьируется:
JspWriter
. Этот объект может отличаться
от объекта stream, возвращаемого от response.getWriter()
, и может рассматриваться
как вставляемый позднее в последнем, чтобы
реализовать буферизацию (см. Раздел JSP.2.10.1, "Директива page
").
Это - начальный объект out. Авторам JSP-страниц запрещено записывать
непосредственно в
PrintWriter
или OutputStream
, ассоциированные с
ServletResponse
.response.getWriter()
до тех пор, пока первая часть содержимого не будет
переслана клиенту. Здесь поднимаются вопросы использования JSP, включая использование JSP
как языка для 'склейки' акций, дающих бинарный контекст, или надёжного
перенаправления сервлету, или динамического изменения типа содержимого ответа
до генерации содержимого. См. Главу JSP.3.JspWriter
. То, какой это случай, зависит от деталей семантики акции. Обычно
содержимое этих временных потоков присоединяется к потоку, на который out
ссылался перед этим, и out последовательно переназначается для того,
чтобы ссылаться на предыдущий (внешний) поток. Такие вложенные потоки всегда
буферизуются и требуют явной очистки/flushing, чтобы выгрузить вкладывающие потоки и их содержимое.JspWriter
буферизуется, тогда, в зависимости от значения атрибута
autoFlush
директивы page
, содержимое этого буфера будет либо автоматически очищаться перед потоком
вывода ServletResponse
, чтобы избежать переполнения, либо должно вызываться
исключение, чтобы сигнализировать о переполнении буфера. Если начальный out-объект
JspWriter
не буферизуется, тогда содержимое, записанное в него, будет передано прямо в поток вывода
ServletResponse
.JSP-страница может создавать и модифицировать серверные объекты/server-side и
получать к ним доступ.
Объекты могут быть сделаны видимыми для акций и элементов
скриптинга. Объект имеет scope\область видимости, которая описывает,
какие экземпляры могут получать доступ к объекту.
Акции могут получать доступ к объекту, используя имя в объекте
PageContext
. Объект, видимый через переменную
скриптинга, имеет область видимости в пределах страницы.
Элементы скриптинга могут получать доступ к объектам непосредственно через
переменную скриптинга.
Некоторые неявные объекты видны через переменные скриптинга на любой
JSP-странице.
Объект может быть сделан доступным для кода в элементах скриптинга через переменную языка скриптинга.
Элемент может определять переменные скриптинга,
которые будут содержать, в процессе времени запроса, ссылку на объект, определённый этим элементом,
хотя могут существовать и другие ссылки, в зависимости от области видимости объекта.
Тип элемента указывает имя и тип таких переменных, хотя в деталях имя переменной
может зависеть от Языка Скриптинга.
Язык скриптинга может также влиять на то, как происходит доступ к различным
свойствам объекта. Например, в спецификации
JavaBeans доступ к свойствам осуществляется через методы
getter
и setter, в то время как эти свойства доступны напрямую как переменные в
языке JavaScript≥.
Точные правила видимости переменных зависят от языка скриптинга. В
Главе JSP.2.1
определены правила для случая, когда атрибут
language
директивы page
установлен в "java"
.
JSP-страница может создавать и/или получать доступ к Java-объектам при обработке
запроса. Спецификация JSP указывает, что некоторые объекты создаются неявно,
возможно, как результат директивы
(см. Раздел JSP.2.8.3, "Неявные Объекты"). Другие объекты создаются явно через
акции или непосредственно путём использования кода скрипта. Созданные объекты
имеют атрибут scope, определяющий, где находится ссылка на объект и когда
эта ссылка удаляется.
Созданные объекты могут также непосредственно видимы элементам скриптинга через
переменные уровня скриптинга (см. Раздел JSP.2.8.3, "Неявные Объекты").
Каждая акция и объявление определяют, как часть своей семантики, какой объект
они создают, с каким атрибутом scope
и доступны ли они элементам скриптинга.
Объекты создаются внутри экземпляра JSP-страницы, которая отвечает объекту request.
Имеется несколько областей видимости:
pageContext
.request
.session
из страницы, которая не находится в данной сессии (см.
Раздел
JSP.2.10.1, "Директива page"). Все ссылки на такой объект должны быть
разорваны после того, как ассоциированная сессия закончилась. Ссылки на
объекты с областью видимости session хранятся в объекте session
,
ассоциированном с активацией страницы.application
, ассоциированном с активацией страницы. Объект application
является
контекстом сервлета, получаемым из объекта конфигурации сервлета. Все ссылки
на этот объект должны быть разорваны, когда рабочая среда/runtime environment запрашивает ServletContext
.Имя/name должно ссылаться на уникальный объект из всех точек в ходе выполнения, то есть все области видимости должны в действительности вести себя как единое пространство имён. Реализация JSP-контейнера может или может не форсировать это правило явно по соображениям производительности.
Авторы JSP-страниц имеют доступ к определённым неявным (неявно создаваемым) объектам,
которые всегда доступны для использования в скриптлетах и выражениях через
переменные скриптинга, которые объявляются неявно в начале страницы. Все языки
скриптинга должны предоставлять доступ к этим объектам.
Неявные объекты доступны обработчикам тэгов через объект pageContext
(см. ниже).
Каждый неявный объект имеет тип класса или интерфейса, определённый в основной
технологии Java или в пакете Java Servlet API, как
показано в Таблице JSP. 2-1.
Имя Переменной | Тип | Семантика & Области Видимости |
---|---|---|
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.
pageContext
PageContext
это объект, предоставляющий контекст для хранения ссылок на объекты,
используемые страницей. Он инкапсулирует зависящие от реализации свойства и
предоставляет нужные методы. Класс реализации JSP-страницы может использовать
PageContext для прогона в неизменённом виде в любом подходящем JSP-контейнере,
одновременно используя преимущества специфичных для реализации улучшений типа
высокопроизводительного JspWriters
.
См. детали в Главе JSP.9.
Имя Переменной | Тип | Семантика & Область Видимости |
---|---|---|
|
java.lang.Throwable
|
Неотловленный Throwable ,
приводящий к вызову страницы информации об ошибках.Область видимости: page . |
Имена объектов с префиксами jsp, _jsp, jspx и _jspx, в любой комбинации нижнего и верхнего регистров, зарезервированы данной спецификацией JSP. См. в Разделе JSP.7.6.1 некоторые ненормативные соглашения для введения новых неявных объектов.
Семантика шаблонного (или неинтерпретированного) Текста очень проста:
шаблонный текст передаётся текущему out\выводящему неявному объекту
JspWriter
после применения замен Раздела JSP.2.6,
"Соглашения по Кавычкам и Escape-Последовательностям".
Директивы являются сообщениями JSP-контейнеру.
Синтаксис директивы:
<%@ директива {
атрибут="значение" }* %>
Могут иметься необязательные пробелы после "<%@" и перед "%>".
Это синтаксис легко вводится и понятен, но он несовместим с XML.
В Главе JSP.5 описано отображение директив в элементы XML.
Директивы не производят никакого вывода в текущий поток out.
Есть три директивы:
page
и taglib
описаны здесь, а директива include
- в следующей главе.
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"
Далее дана детальная информация об атрибутах:
Атрибут | Описание |
---|---|
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" с необязательным пробелом после ";". |
pageEncoding
|
Определяет кодировку символов для JSP-страницы.
Значения имеют форму "CHARSET", который обязан быть IANA-значением для кодировки символов.
Значение contentType для CHARSET используется по умолчанию, если
имеется, в противном случае - ISO-8859-1.
См. в Главе 3 детальную информацию о кодировках символов. |
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" %>
где атрибуты:
uri
|
Спецификация абсолютного или относительного URI, который
уникально идентифицирует дескриптор библиотеки тэгов, ассоциированной с данным префиксом. URI используется для локализации описания библиотеки тэгов, как указано в Главе 7. |
tagPrefix
|
Определяет строку prefix в конструкции
<prefix>:<tagname> , которая используется для отличения специальной
акции, например, <myPrefix:myTag> .Использование префиксов, начинающихся с jsp:, jspx:, java:, javax:, servlet:, sun: и sunw:, зарезервировано. Префикс обязан следовать соглашению об именовании, специфицированному в спецификации пространств имён XML. Пустые префиксы в данной версии спецификации не допускаются. |
Фатальная ошибка трансляции возникнет, если транслятор JSP-страницы обнаруживает
тэг с именем prefix: Name,
использующий префикс, введённый директивой taglib
,
и если Name не распознаётся соответствующей библиотекой тэгов.
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-страницы. Соответственно, спецификация JSP 1.2 имеет два механизма включения для различных задач. Обобщение их семантики дано в Таблице JSP.2-1.
include
в спецификации JSP 1.2Синтаксис | Спецификация | Объект | Описание | |
---|---|---|---|---|
Директива 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 объекту; т.е.
запрос направляется этому объекту, и результат процессинга включается .
Элементы скриптинга обычно используются
для манипулирования объектами и для выполнения вычислений, влияющих на генерируемое содержимое.
Есть три класса элементов скриптинга: 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-странице. Объявление должно быть декларативным
оператором или последовательность операторов, соответствующей синтаксису
специфицированного языка скриптинга.
Объявления не производят никакого вывода в текущий поток вывода.
Объявления инициализируются в момент инициализации JSP-страницы и становятся
доступными другим объявлениям, скриптлетам и выражениям.
Например, первое объявление здесь объявляет целое число, глобальное в пределах страницы.
Второе объявление делает то же самое и инициализирует число в нуль. Этот тип
инициализации должен выполняться осторожно при наличии нескольких запросов к
странице.
В третьем случае объявляется метод, глобальный в пределах страницы.
<%! int i; %>
<%! int i = 0;
%>
<%! public String f(int i) { if (i<3) return("..."); ... } %>
<%!
объявление(-я) %>
Скриптлеты могут содержать любые фрагменты кода, которые являются верными для
языка скриптинга, специфицированного директивой
language
. Является ли фрагмент кода действующим, зависит от деталей языка
скриптинга (см. Главу JSP.6).
Скриптлеты выполняются во время обработки запроса. Производят они вывод в поток
вывода или нет, зависит от кода скриптлета.
Скриптлеты могут иметь побочные эффекты,
модифицируя объекты, видимые для них.
Когда все фрагменты скриптлетов в данном трансляционном модуле комбинируются для появления на JSP-странице,
они обязаны давать в результате верный оператор или последовательность
операторов на специфицированном языке скриптинга.
Чтобы использовать последовательность символов
%> как литеральные символы в скриптлете, вместо того , чтобы они оканчивали
скриптлет, вводите их так %\>.
Вот простой пример динамического изменения страницы, в зависимости от времени суток.
<% if
(Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM) {%>
Good Morning
<% } else { %>
Good Afternoon
<% } %>
Скриптлет может также содержать объявление локальных переменных, например, следующий скриптлет просто объявляет и инициализирует целое число и затем отображает это число и увеличивает его.
<% int i; i= 0;
%>
Привет, значение
i равно <% i++ %>
<% скриптлет %>
Элемент expression
в JSP-странице является выражением языка скриптинга, которое
вычисляется, а результат приводится к String
.
Результат затем посылается в текущий объект вывода JspWriter
.
Если результат выражения не может быть приведён к String
, обязаны выполняться следующие действия:
Если проблема обнаружена на этапе трансляции, должна возникать ошибка времени трансляции.
Если приведение не обнаруживается в процессе трансляции, должно вызываться исключение
ClassCastException
/ОшибкаПриведенияКласса во время запроса.
Язык скриптинга может поддерживать побочные эффекты в выражениях, когда выражение вычисляется.
Выражения вычисляются слева направо на JSP-странице. Если выражения появляется в
более чем одном атрибуте времени выполнения, они должны вычисляться слева
направо в тэге. Выражение может изменять значение объекта out
, хотя это не всегда легко выполнимо.
Выражение обязано быть полным выражением языка скриптинга, на котором оно написано.
Выражения вычисляются во время HTTP-процессинга.
Значение выражения конвертируется к String и вставляется в соответствующую позицию в .jsp-файл.
Вставляется текущая дата:
<%= (new
java.util.Date()).toLocaleString() %>
<%= выражение
%>
Акции могут воздействовать на текущий поток вывода и использовать,
модифицировать и/или создавать объекты.
Акции могут зависеть от деталей конкретного объекта request/запроса, получаемого JSP-страницей.
Данная спецификация JSP содержит некоторые акции, которые являются
стандартными и обязаны реализовываться всеми соответствующими JSP-контейнерами;
эти акции описываются в Главе 4.
Новые акции определяются в соответствии с механизмами, описанными в Главах 7
и 10, и вводятся с использованием директивы taglib
.
Синтаксис элементов акций базируется на XML. Акции могут быть пустыми и непустыми.
Интерпретация всех акций начинается с вычисления значений, данных их атрибутам,
слева направо и присвоения этих значений атрибутам. В этом процессе могут
производиться конверсии; правила конверсии описаны в Разделе JSP.2.13.2.
Многие значения являются фиксированными 'значениями времени трансляции', но JSP 1.2
предоставляет также механизм описания этих значений, когда они вычисляются на
этапе запроса, правила описаны в Разделе JSP.2.13.1.
Значение атрибута в форме
"<%= scriptlet_expr %>"
или '<%= scriptlet_expr %>'
обозначает значение атрибута времени запроса.
Указываемое значение является значением включаемого скриптлета. Значения
атрибутов времени запроса могут использоваться только в акциях и не могут
использоваться в директивах. Если в тэге имеется более одного такого атрибута,
выражения вычисляются слева направо.
Закавычивание выполняется так же, как и в других значениях атрибута (Раздел JSP.2.6).
Таким способом могут обозначаться только значения атрибута (имя атрибута всегда
является явно определённым именем).
Выражение обязано появляться само по себе (множественные выражений и смешивание
выражений и строковых констант не допускаются).
Множественные операции обязаны выполняться внутри выражения.
Конверсия типов описана в Разделе JSP.2.13.2.
По умолчанию все атрибуты имеют семантику времени трансляции страницы. Попытка
специфицировать выражение скриптлета как значение атрибута, который (по
умолчанию или нет) имеет семантику времени трансляции, является недопустимой и
приводит к фатальной ошибке трансляции.
Тип элемента action
указывает, будет ли данный атрибут принимать значения атрибута времени запроса.
Большинство атрибутов стандартных акций из Главы 4 имеют семантику времени
трансляции страницы, но следующие атрибуты принимают выражения атрибутов времени
запроса:
jsp:setProperty
(Раздел JSP.4.2).beanName
в jsp:useBean
(Раздел JSP.4.1).page
в jsp:include
(Раздел JSP.4.4).page
в jsp:forward
(Раздел JSP.4.5).jsp:param
(Раздел JSP.4.6).height
и width
в jsp:plugin
(Раздел JSP.4.7).Мы описываем два случая конверсии типов:
String
Значение строки может использоваться для описания значения типа не-String через
конверсию. Возможна ли конверсия и, если да, какая она, зависит от типа назначения.
Значения String
могут использоваться для присвоения значений типу, который имеет класс
PropertyEditor
, как указано в спецификации JavaBeans. Если это именно тот случай,
используется метод setAs-Text(String)
.
Конверсия терпит неудачу, если метод вызывает исключение
IllegalArgumentException
.
Значения String
могут также использоваться для присвоения типов, как указано в Таблице 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
.
Выражения времени запроса могут назначаться свойству любого типа.
Автоматическая конверсия не выполняется.
В этой Главе описаны требования по локализации в JavaServer Pages 1.2 (JSP 1.2).
Поддержка платформой 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
директивы
, если она имеется, или, в противном случае, устанавливается
ISO-8859-1. ISO-8859-1 известна также как Latin-1.page
Верные имена кодировок символов в JSP 1.2 - те же, что и имена
IANA. Они описаны по адресу:
ftp://venera.isi.edu/in-notes/iana/assignments/character-sets
Атрибут
pageEncoding
должен использоваться только тогда, когда кодировка символов JSP-страницы
организована так, что символы
ASCII отображают сами себя. Директива, содержащая атрибут
pageEncoding
, должна появляться на JSP-странице как можно раньше.
JSP-контейнер может использовать какую-нибудь зависящую от реализации эвристику
и/или структуру для определения ожидаемой кодировки JSP-страницы и проверки
соответствия атрибута
contentType
.
JSP-контейнер вызовет ошибку времени трансляции, если запрошена неподдерживаемая
кодировка символов.
Большинство 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-страницы созданы так, что они могут направлять содержимое,
используя различные типы содержимого и кодировки символов, в зависимости от
ввода времени запроса. Эти страницы могут быть организованы как специальные
акции или скриптлеты, которые определяют тип содержимого ответа и предоставляют 'связку'
с другим кодом, реально генерирующим содержимое ответа.
Динамическая установка типа содержимого основана на вызове response.setcontentType
().
Этот метод может быть вызван, пока никакого содержимого не было выслано в поток
ответа. Данные высылаются в поток ответа при очистках буфера буферизованных
страниц или при обнаружении первого содержимого (избегая пробелов)
небуферизованных страниц.
Пробел в страницах JSP вводится известным трюком синтаксиса JSP, но более
управляем в JSP-страницах с синтаксисом XML.
Спецификация JSP не предписывает определённого подхода к структурированию
локализованного содержимого, поэтому возможны различные подходы.
Два обычных подхода заключаются в использовании шаблонной taglib
и помещения локализованных строк из хранилища ресурсов, либо в
использовании локализованных JSP-страниц. Каждый подход имеет свои преимущества
и недостатки. Некоторые пользователи используют трансформацию
JSP-документов для простого замещения элементов локализованными строками,
обрабатывая таким образом синтаксис JSP без снижения производительности на этапе
прогона. Сочетание этих трёх подходов также имеет определённый смысл.
Есть несколько подходов к наилучшему проведению локализации. Мы ожидаем
появления JSR-052,
стандартной библиотеки тэгов JSP, чтобы адресовать к ней некоторые из этих
вопросов.
В этой главе описаны стандартные акции JavaServer Pages 1.2 (JSP 1.2).
<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-контейнера
во время трансляции страницы при обработке запроса клиента.
Конкретно:
id
, найденные в том же самом трансляционном
модуле, приводят в фатальной ошибке времени трансляции.Это 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, используемые для доступа к этой ассоциации, таким образом:
page
|
Именованный объект, доступный из javax.
для данной страницы.Эта ссылка должна быть уничтожена после выполнения текущего запроса телом страницы. Не допускается изменение объекта экземпляра, ассоциированного таким образом, что его (объекта?) тип времени прогона/выполнения является поднабором типа текущего объекта, ассоциированного ранее. |
request
|
Именованный объект, доступный из объекта ServletRequest текущей страницы через использование
метода getAttribute(name) .Эта ссылка должна быть уничтожена после выполнения текущего клиентского запроса. Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, что его (объекта?) тип времени прогона/выполнения является поднабором(-ами) типа объекта, ассоциированного ранее таким же образом. |
session
|
Именованный
объект, доступный из объекта HttpSession текущей страницы
(который, в свою очередь, может быть получен из объекта ServletRequest )
через использование методаgetAttribute(name) .Эта ссылка должна быть уничтожена после аннулирования текущей сессии. Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, чтобы его новый тип времени прогона был поднабором(-ами) типа объекта, ассоциированного ранее. Заметьте, что будет фатальной ошибкой трансляции попытка использовать область видимости сессии, когда JSP-страница, делающая эту попытку, объявляется через директиву <%@ page ... %>
(см. далее) так, что она не участвует в сессии. |
application
|
Именованный объект, доступный из объекта ServletContext
текущей страницы через использование метода getAttribute(name) .Эта ссылка должна быть уничтожена после использования ServletContext .Не допускается изменение значения объекта экземпляра, ассоциированного таким образом, чтобы его новый тип времени прогона был поднабором(-ами) типа объекта, ассоциированного ранее таким же образом. |
Акциями, выполняемыми в jsp:useBean
, являются:
id
и scope
.
Синхронно выполняется проверка пространства имён области
видимости/scope
для исключения недетерминистического поведения.class
/класс
(если type
не задан) определяется с данным
id
в текущей лексической области видимости языка скриптинга.java.lang.ClassCastException
. Это завершает работу данной акции
jsp:useBean
.jsp:useBean
имел непустое тело/body, он игнорируется. Это завершает работу
данной акции jsp:useBean
.class
,
ни beanName
, должно возникать исключение
java.lang.InstantiationException
. Это завершает работу данной
акции jsp:useBean
.class
специфицировал имена неабстрактного класса, который
определяет публичный/public безаргументный конструктор,
тогда создаётся экземпляр этого класса.PageContext
). После этого выполняется шаг 7.java.lang.InstantiationException
.
Это завершает работу данной акции jsp:useBean
.beanName
,
тогда метод instantiate()
класса java.beans.Beans
будет вызван с Class-Loader/Загрузчиком-Классов объекта Servlet
и с beanName
в
качестве аргументов.PageContext
). После этого выполняется шаг 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
>
имеет следующие атрибуты:
id
|
Имя, используемое для идентификации
экземпляра объекта в пространстве имён специфицированной области видимости, а
также имя переменной скриптинга, объявленное и инициализированное
вместе со ссылкой на этот объект. Специфицированное пространство имён чувствительно к регистру и должно соответствовать соглашениям текущего языка скриптинга по именованию переменных. |
scope
|
Область видимости/scope ,
в зоне которой ссылка доступна. Значение по умолчанию - page.См. описание атрибута scope ,
определённого ранее здесь же. |
class
|
Полное
квалифицированное имя класса, определяющего реализацию объекта. Имя класса чувствительно к регистру. Если атрибуты class и beanName
не специфицированы, объект обязан быть представлен в данной области видимости.
|
beanName
|
Имя для Bean, как предполагается методом instantiate()
класса java.beans.Beans . Этот атрибут может принимать в
качестве значения выражение атрибута времени запроса. |
type
|
Если специфицирован, определяет тип переменной скриптинга. Это позволяет типу переменной скриптинга отличаться от (но соотноситься с) типа специфицированного класса реализации. Тип должен быть самим классом, суперклассом этого класса, либо интерфейсом, реализованным специфицированным классом. Объект, на который ссылаются, должен быть этого типа, иначе должно возникать исключение java.lang. во время
запроса, когда делается попытка назначения объекта, на который ссылаются, переменной скриптинга.Если не специфицировано, значение будет тем же, что и значение атрибута class . |
<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>
имеет следующие атрибуты:
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
|
Значение, присваиваемое данному свойству. |
<jsp:getProperty>
Акция <
помещает значение свойства экземпляра
Bean'а, конвертированное к String, в неявный объект вывода, из которого Вы можете отобразить значение в качестве
вывода. Экземпляр Bean'а обязан быть определён так, как указано в атрибуте
jsp:getProperty
>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" />
name
|
Имя экземпляра объекта, из которого получено свойство. |
property
|
Именует получаемое свойство. |
<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:
<%@ include file="dir/B.jsp"%>
, а
dir/B.jsp говорит <%@ include file="C.jsp"%>
.<jsp:include page="dir/B.jsp"/>
, а dir/B.jsp говорит <jsp:include
page="C.jsp" />
.<%@ include file="dir/B.jsp"%>
, а dir/B.jsp говорит <jsp:include
page="C.jsp"/>
.
<jsp:include page="urlSpec" flush="true|false"/>
и
<jsp:include page="urlSpec" flush="true|false">
{ <jsp:<code></code> .... /> }*
</jsp:include>
В первом примере синтаксиса выполняется включение на этапе запроса.
Во втором случае значения в субэлементах param
используются для увеличения запроса с целью включения.
Верными атрибутами являются:
page
|
Этот URL является относительным urlSpec,
как указано в Разделе JSP.2.2.1. Относительные пути интерпретируются относительно текущей JSP-страницы. Принимает атрибут времени запроса value (который обязан вычисляться до String, которая является спецификацией относительного URL). |
flush
|
Необязательный булев атрибут. Если "true", буфер немедленно очищается. По умолчанию - "false". |
<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>
Этот тэг позволяет автору страницы осуществлять воздействие на процессинг
текущего запроса специфицированными атрибутами:
page
|
URL является относительным urlSpec, как указано в
Разделе JSP.2.2.1. Относительные пути интерпретируются относительно текущей JSP-страницы.
Принимает атрибут времени запроса |
<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:param name="name"
value="value" />
Эта акция имеет два мандатных/обязательных атрибута: name
и value
.
Name
это имя параметра, а
value
, которое может быть выражением времени запроса, это его
значение.
<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>
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:params>
Акция jsp:params
является частью акции jsp:plugin
и
может появляться только как прямой потомок элемента <jsp:plugin>
.
Использование элемента jsp:params
в любом ином контексте должно
приводит к ошибке времени трансляции.
Семантика и синтаксис jsp:params
описаны в Разделе JSP.4.7.
<jsp:fallback>
Акция jsp:fallback
является частью акции jsp:plugin
и
может появляться только как прямой потомок элемента <jsp:plugin>
.
Использование элемента jsp:fallback
в любом ином контексте должно
приводит к ошибке времени трансляции.
Семантика и синтаксис jsp:fallback
описаны в Разделе
JSP.4.7.
В этой главе определён синтаксис XML для JSP-страниц и интерпретация страниц, написанных с этим синтаксисом. Мы используем термин JSP-документ для обозначения JSP-страницы с синтаксисом XML.
Эта глава также определяет отображение/mapping между JSP-страницей и XML-описанием этой страницы, её XML view\XML-просмотр. XML-просмотр определён для JSP-страниц, написанных на JSP с синтаксисом XML.
Синтаксис XML для JSP-страниц может использоваться по-разному, с том числе:
Проверка JSP-страницы поддерживается в спецификации JSP 1.2 с помощью класса
TagLibraryValidator
, ассоциированного с библиотекой тэгов. Класс-проверщик
работает с объектом PageData
, который представляет XML-просмотр JSP-страницы (см.,
например, Раздел JSP.7.5.1.2).
JSP-страница с любым синтаксисом может подключать с помощью директивы JSP-страницу
с любым синтаксисом. Нельзя, однако, смешивать стандартный JSP-синтаксис и XML-синтаксис в одном исходном файле.
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:root
, который используется для ввода пространства имён для специальных тэгов страницы;jsp:text
, соответствующие шаблонным данным;Модель семантики JSP-документа не изменилась по сравнению с моделью семантики JSP-страницы
с синтаксисом JSP: JSP-страницы генерируют ответный поток символов из шаблонных
данных и динамических элементов. Шаблонные данные могут быть описаны явно
элементом jsp:text
или неявно фрагментом XML.
Динамические элементы являются элементами
скриптинга, стандартными акциями или специальными акциями. Элементы скриптинга
представляются как элементы XML, кроме выражений времени/этапа запроса,
которые представляются специальным синтаксисом атрибутов.
Чтобы точнее показать процессинг пробелов, мы следуем структуре спецификации
XSLT. Первым шагом обработки JSP-документа является идентификация узлов
документа. При этом все текстуальные узлы, содержащие только пробелы, из
документа удаляются; единственным исключением являются узлы элемента jsp:text
,
которые сохраняются дословно. Результирующие узлы интерпретируются так, как
описано в последующих разделах. Шаблонные данные либо передаются непосредственно
в ответ/response, либо опосредованно через (стандартные или специальные/custom) акции.
В соответствии со спецификацией XML (и спецификацией XSLT), пробельными символами являются #x20, #x9, #xD и #xA.
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: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: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:declaration
Элемент jsp:declaration
используется для объявления конструкций языка скриптинга,
которые доступны всем другим элементам скриптинга. Элемент
jsp:declaration
не имеет атрибутов, и его тело/body - это само объявление.
Его синтаксис:
<jsp:declaration> здесь идёт объявление </jsp:declaration>
Интерпретация элемента
jsp:declaration
описана в Разделе JSP.2.11.1.
jsp:scriptlet
Элемент jsp:scriptlet
используется для описания акций, выполняемых в ответ на некоторый
запрос. Скриптлеты являются фрагментами программы. Элемент
jsp:scriptlet
не имеет атрибутов, и его тело - это фрагмент программы, содержащий скриптлет.
Его синтаксис:
<jsp:scriptlet> здесь - фрагмент кода </jsp:scriptlet>
Интерпретация элемента jsp:scriptlet
описана в Разделе
JSP.2.11.2.
jsp:expression
Элемент jsp:expression
используется для описания сложных выражений на языке скриптинга,
вычисляемых на этапе ответа. Элемент jsp:expression
не имеет атрибутов, и его тело - это выражение.
Его синтаксис:
<jsp:expression>
здесь - выражение </jsp:expression>
Интерпретация элемента
jsp:expression
описана в Разделе JSP.2.11.3.
JSP-документ может использовать стандартные акции, описанные в
Главе JSP.4.
Поскольку синтаксис этих элементов уже базируется на XML, описания этой главы
достаточно, за исключением того, что в шаблоне JSP-документа текст может быть
описан элементом jsp:text
, либо посредством элемента XML, который не является ни
стандартной, ни специальной акцией (см. Раздел
JSP.5.2.11).
Для полноты приведём элементы-акции:
jsp:useBean
jsp:setProperty
jsp:getProperty
jsp:include
jsp:forward
jsp:param
jsp:params
jsp:plugin
jsp:text
Семантика и ограничения описаны в Главе JSP.4, а интерпретация элементов
скриптинга - в Главе JSP.6.
Библиотеки тэгов вводят новые элементы атрибутам
xmlns
или элементом
jsp:root
, а их синтаксис и семантика описаны в Главе JSP.7.
Элемент акции, который может принимать атрибут времени запроса (Раздел JSP.2.13.1), принимает аргумент для этого атрибута в форме "%= text %" (пробелы вокруг text не нужны, и отметьте отсутствие '<' и '>'). Text, после применения кавычек (как и в любом другом документе XML), является выражением, вычисляемым по правилам Раздела JSP.2.13.1.
jsp:text
Элемент jsp:text
можно использовать для включения шаблонных данных в представление XML.
Элемент jsp:text
не имеет атрибутов и может появляться в любом месте, где могут появляться шаблонные данные.
Его синтаксис:
<jsp:text
> шаблонные данные </jsp:text
>
При интерпретации элемента jsp:text
, его содержимое передаётся текущему значению out/вывода.
Это очень напоминает работу элемента xsl:text
из XSLT.
Синтаксис XML для JSP-страниц допускает также появление XML-элементов, которые
не представляют ни стандартных, ни специальных акций, в любом месте, где может появляться
jsp:text
.
Интерпретация такого XML-элемента - это передача его текстуального представления
текущему значению out после процессинга пробелов, описанного в Разделе JSP.5.2.1.
Как пример, если фрагмент JSP-документа таков:
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>
|
то результат будет:
N Строки | Итоговый Текст |
---|---|
1 |
<hello> <hi> hi you all
|
2 |
3 </hi></hello>
|
Обратите внимание на работу с пробелами.
В этом разделе описан XML-просмотр/view JSP-страницы: отображение между JSP-страницей, написанной с синтаксисом XML или JSP, и XML-документом, описывающим её.
XML-просмотр JSP-страницы, написанной с синтаксисом XML, очень похож на оригинал JSP-страницы.
Выполняются только две трансформации:
include
разворачиваются в JSP-фрагменты.jsp:id
, этот атрибут добавляется. См. Раздел JSP.5.3.13.XML-просмотр JSP-страницы, написанной с синтаксисом XML, определяется следующей трансформацией:
include
разворачиваются в JSP-фрагменты;jsp:root
добавляется в качестве корневого, с соответствующим атрибутом
xmlns:jsp
, и директива taglib
конвертируется в атрибуты xmlns:
элемента jsp:root
;jsp:text
для всего шаблонного текста;jsp:id
, этот атрибут добавляется. См.
Раздел JSP.5.3.13.Обратите внимание, что XML-просмотр JSP-страницы не имеет информации DOCTYPE; см. Раздел JSP.5.4.
Краткий обзор трансформации дан в Таблице JSP.5-1:
Элемент 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-комментарии (в форме
<%-- комментарий --%
>) не передаются в
XML-просмотр JSP-страницы.
page
Директива page
в форме:
<%@ page {
атрибут="значение" }* %>
транслируется в элемент в форме:
<jsp:directive.page { атрибут="значение" }* />
taglib
Директива taglib
в форме:
<%@ taglib uri="uriValue\значениеURI"
prefix="префикс" %>
транслируется в атрибут
xmlns:prefix
элемента root
JSP-документа со значением. которое зависит от uriValue.
Если uriValue является относительным путём, то используемое значение будет
"urn:jsptld:uriValue"; иначе uriValue используется напрямую.
include
Директива include
в форме:
<%@ include file="value" %>
развёртывается в JSP-фрагмент, обозначенный value. Это сделано для того,
чтобы дать возможность проверять страницу.
Объявления транслируются в элемент
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>
Альтернативно мы можем использовать < и записать:
<jsp:declaration> public String f(int i) { if (i<3) return("..."); }
</jsp:declaration>
Скриптлеты транслируются в элементы
jsp:scriptlet
. В XML-документе, соответствующем JSP-страницам, директивы
представлены с использованием следующего синтаксиса:
<jsp:scriptlet> здесь - фрагмент кода </jsp:scriptlet>
В XML-документе, соответствующем JSP-страницам, директивы представлены с
использованием элемента jsp:expression
:
<jsp:expression> здесь - выражение </jsp:expression>
Синтаксис элементов стандартных и специальных акций базируется на XML. Необходимы трансформации в связи с соглашениями по кавычкам и с синтаксисом выражений атрибутов времени запроса.
Выражения атрибутов времени запроса/Request-time attribute expressions имеют форму
"<%= expression %>"
.
Хотя этот синтаксис следует синтаксису, используемому в JSP-странице, он не
является допустимым в XML.
Отображение XML для таких выражений - это значение в форме
"%= выражение'%"
, где соглашение по кавычкам спецификации JSP конвертировано в соглашение по кавычкам XML.
Весь текст, который не интерпретируется JSP-транслятором, конвертируется в тело/body элемента
jsp:text
. Как следствие, никакие XML-элементы в форме, описанной в
Разделе JSP.5.2.11,
не будут появляться в XML-просмотре JSP-странице, написанной с синтаксисом JSP.
jsp:id
JSP-контейнер может, по выбору, поддерживать атрибут
jsp:id
. Этот атрибут может присутствовать только в XML-просмотре JSP-страницы и
может использоваться для повышения качества сообщений об ошибках времени трансляции.
Он вводится по выбору, и соответствующий JSP-контейнер может выбрать,
поддерживать его или нет.
В JSP-контейнере, поддерживающем атрибут
jsp:id
, XML-просмотр любой JSP-страницы будет содержать дополнительный атрибут
jsp:id
во всех XML-элементах. Этому атрибуту даётся значение, уникальное среди
всех элементов XML-просмотра. См. детали в Главе 10.
XML-просмотр JSP-страницы это документ, связанный с пространством имён, и он не
может быть проверен относительно ОТД/DTD (Определение Типа Данных), за
исключением лишь наиболее простых случаев.
Чтобы уменьшить конфликты и возможные нежелательные последствия, XML-просмотр JSP-страницы
не будет включать DOCTYPE. Однако пока ОТД могут содержать некоторое значение в
качестве документации,
Приложение JSP.C содержит описания и DTD, и XSchema JSP-документов.
Есть несколько механизмов с участием пространства имён, которые могут
использоваться для проверки XML-просмотра JSP-страниц. Самым популярным
механизмом является язык XML Schema консорциума W3C, но подойдут также и другие,
включая некоторые простейшие, которые, например, могут использовать только
некоторые элементы,
или, напротив, которые не используют их. Проверщик TagLibraryValidator
для
библиотеки тэгов разрешает инкапсуляцию этих сведений в библиотеке тэгов.
работает в XML-просмотре JSP-страницы. Если страница создана
с синтаксисом JSP, этот просмотр не предоставляет никаких деталей о шаблонных
данных
(всё группируется внутри элементов
TagLibraryValidatorjsp:text
), но отдельные детали могут быть
описаны при использовании JSP-документов. Аналогично, когда XSLT-трансформация
применяется к JSP-документу,
XML-фрагменты будут нормально видимы, в то время как содержимое элементов
jsp:text
- нет.
В этом разделе представлены два примера JSP-документов. В первом дана JSP-страница
с синтаксисом JSP и её отображение в синтаксис XML. Во втором - JSP-страница с
синтаксисом XML, включающая XML-фрагменты.
Пример отображения между синтаксисом JSP и XML.
<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>
<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-документа, содержащего некоторые шаблонные 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>
В этой главе детально разбираются Элементы Скриптинга, когда значением директивы language
является "java".
Этот язык скриптинга базируется на языке программирования Java (как
специфицировано в "The Java Language Specification"), но заметьте, что верная Java-программа
не является верной JSP-страницей или её разделом.
Далее детально описаны взаимоотношения объявлений скриптинга, скриптлетов и
выражений скриптов и языка программирования Java. Описание дано в терминах
структуры класса реализации JSP-страницы.
От JSP-контейнера не требуется генерировать класс реализации JSP-страницы, но он
обязан вести себя так, как будто этот класс существует.
Некоторые детали того, что делает JSP-страницу таковой, весьма специфичны для языка скриптинга, используемого на странице. Это особенно усложнено из-за того, что скриптлеты являются фрагментами, а не законченными операторами языка.
JSP-страница является таковой для Платформы Java, если, и только если, класс
реализации JSP-страницы, определённый по Таблице JSP.6-1
(после применения всех директив include
), вместе со всеми прочими
классами, определёнными JSP-контейнером, является верной программой для данной
Java-Платформы и если он передаёт методы проверки для всех библиотек тэгов,
ассоциированных с этой JSP-страницей.
Sun Microsystems резервирует для спецификаций JSP все имена, имеющие форму {_}jsp_*
и {_}jspx_*, в любом сочетании верхнего и нижнего регистров.
Имена, имеющие такую форму и не определённые в данной спецификации,
зарезервированы фирмой Sun для будущих расширений.
Трансформации, описанные в этой главе, не должны выполняться буквально.
Реализации могут выполнять их по-разному с целью обеспечения наилучшей производительности,
экономии памяти или других атрибутов реализации.
необязательное выражение импорта, как указано директивой jsp . |
import name1
|
SuperClass выбирается JSP-контейнером, либо автором
JSP через использование директивы jsp . Имя класса (_jspXXX) зависит от реализации. |
class _jspXXX extends SuperClass
|
Начало тела/body класса реализации JSP-страницы. | { |
(1) Раздел Объявлений | // объявления... |
Подпись для генерируемого метода. |
public void _jspService(<ServletRequestSubtype>
|
(2) Раздел Неявных/Implicit Объектов | // код, определяющий и инициализирующий request, response,
page, pageContext и т.п. |
(3) Главный/Main Раздел | // код, определяющий выражение отображения request/response
метода _jspService
|
закрытие метода _jspService
|
} |
закрытие _jspXXX
|
} |
Раздел объявлений соответствует элементам объявлений. Содержимое этого раздела определяется путём конкатенации всех объявлений на странице в порядке их появления.
Этот раздел определяет и инициализирует неявные объекты, доступные JSP-странице. См. Раздел JSP.2.8.3, "Неявные Объекты.
Этот раздел осуществляет главное отображение/mapping между объектами request
и response
.
Содержимое кодового сегмента 2 определяется скриптлетами, выражениями и текстовым телом JSP-страницы.
Элементы обрабатываются последовательно в порядке их появления на странице.
Трансляция каждого из них определяется так, как показано ниже, и вставляется в данный раздел.
Трансляция зависит от типа элемента:
Шаблонные данные трансформируются в код, который будет размещать
шаблонные данные в потоке, именованном неявной переменной out
в процессе
исполнения кода. Пробелы сохраняются.
Опуская подробности закавычивания и производительности, это соответствует оператору вида:
Оригинал | Эквивалентный Текст |
---|---|
шаблон | out.print(шаблон) |
Скриптлет трансформируется во фрагмент кода вида:
Оригинал | Эквивалентный Текст |
---|---|
<% фрагмент %> | фрагмент |
Выражение трансформируется в оператор Java для вставки значения выражения
(конвертированного, если необходимо, в
java.lang.String)
, в поток, именованный неявной переменной
out
.
Никакие дополнительные символы новой строки или пробелы не включаются.
Опуская подробности закавычивания и производительности, это соответствует
оператору вида:
Оригинал | Эквивалентный Текст |
---|---|
<%= выражение %> | out.print(выражение) |
Акция, определяющая один или более объектов, трансформируется в одно или
несколько объявлений переменных для этих объектов вместе с кодом, инициализирующим эти
переменные. На их видимость влияют другие конструкции, например, скриптлеты.
Семантика типа акции определяет имена переменных (обычно имя атрибута
id
, если он имеется) и их тип.
Единственной стандартной акцией в спецификации JSP, которая определяет объекты,
является акция jsp:usebean
. Имя вводимой переменной это имя атрибута
id
, а тип - атрибута класса.
Оригинал | Эквивалентный Текст |
---|---|
|
объявляются переменные AT_BEGIN |
Обратите внимание, что значение атрибута scope
/область видимости
не влияет на видимость переменных внутри генерируемой программы. Оно влияет на
то, где и как долго будут существовать дополнительные ссылки на объект, обозначенный этой переменной.
В этой главе рассматриваются возможности библиотеки тэгов по введению новых акций в JSP-страницу.
Сюда относятся поддержка переносимости, механизм проверки и поддержка утилит авторизации.
Здесь дан также концептуальный обзор библиотеки тэгов. Рассмотрен
Tag Library Descriptor/Дескриптор Библиотеки Тэгов и директива
taglib
. Детальное описание задействованных API даётся в
Главе JSP.10.
Библиотека Тэгов/Tag Library абстрагирует функциональность, используемую JSP-страницей, определяя специализированный (суб)язык, что делает возможным более естественно использовать эту функциональность в JSP-страницах.
Акции, вводимые Библиотекой Тэгов, могут использоваться авторами JSP-страниц явно
при авторизации - вручную, или неявно - через использование утилит авторизации.
Библиотеки Тэгов особенно применимы в утилитах авторизации, поскольку позволяют
сосредоточиться на главном, а параметры, указанные в экземпляре акции, сами
передают информацию утилите.
Акции, которые предоставляются из библиотеки тэгов, импортируются в JSP-страницу путём использования директивы
taglib
. Они доступны для использования на странице через префикс, заданный этой директивой.
Акции могут создавать новые объекты, которые могут
затем передаваться другим акциям или обрабатываться программно элементами скриптинга в JSP-странице.
Библиотеки тэгов являются переносимыми: они могут использоваться на любой JSP-странице
вне зависимости от того, какой язык скриптинга используется на этой странице.
Механизм развёртывания тэгов содержит информацию для:
Библиотека Тэгов описывается через Tag Library Descriptor ( TLD)/Дескриптор Библиотеки Тэгов, документ XML, рассматриваемый ниже.
Механизм расширения/развёртывания тэгов преследует следующие цели:
Процессинг/обработка JSP-страницы концептуально состоит из следующих этапов:
JSP-страницы могут авторизоваться с использованием двух различных синтаксисов: JSP- и XML-синтаксиса. Семантика и проверка страницы с синтаксисом JSP даётся со ссылкой на семантику и проверку эквивалентного документа с синтаксисом XML.
Первый этап - разбор JSP-страницы. Разбираемая страница разворачивается путём
выполнения директив include
. Информация из TLD используется на
данном этапе и включает идентификацию специальных тэгов так, что происходит
некоторая обработка директивами taglib
на JSP-странице.
Библиотеки Тэгов в XML-документе обрабатываются в порядке их появления на странице.
Каждая библиотека проверяется на наличие класса-проверщика/validator class. Если
он имеется, весь документ становится доступным её методу
validate()
как объект PageData
. Если JSP-контейнер поддерживает
jsp:id
, то эта информация может использоваться для предоставления информации оместонахождении ошибок.
Каждый специальный тэг в библиотеке проверяется на наличие класса
TagExtraInfo
. Если класс имеется, вызывается метод
isValid()
.
Далее документ XML обрабатывается для создания класса реализации JSP-страницы.
В ходе этого процесса могут создаваться переменные скриптинга.
Каждая
специальная акция будет предоставлять информацию о переменных, либо статично - в TLD,
либо более гибко - через использование метода getVariableInfo
класса TagExtraInfo
.
После того как класс реализации JSP-страницы ассоциирован с JSP-страницей, он будет рассматриваться как любой другой Servlet-класс: запросы будут направляться экземплярам этого класса. На этапе прогона экземпляры обработчиков будут создаваться, а их методы будут вызываться.
Семантика специфики специальной акции в библиотеке тэгов описывается через класс
обработчика тэга, который обычно инстанциируется на этапе прогона классом реализации 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
.
Tag
определяет базовые методы, необходимые всем обработчикам тэгов. Это методы setter
для инициализации обработчика тэга, в контексте данных и значений атрибутов акции, и методы
doStartTag()
и doEndTag()
.
IterationTag
является расширением
Tag
'а, предоставляя дополнительный метод doAfterBody()
, вызываемый для повторного обсчёта тела тэга.BodyTag
является расширением
IterationTag
'а с двумя новыми методами для обработчика тэга для манипулирования телом тэга:
setBodyContent()
передаёт буфер, объект BodyContent
, а
doInitBody()
даёт возможность обработки буфера до первого обсчёта тела в буфере.Использование интерфейсов упрощает создание обработчика тэга из существующего Java-объекта.
Имеются также два класса поддержки, которые могут использоваться в качестве базовых классов:
TagSupport
и BodyTagSupport
.
В JSP 1.2 имеется новый интерфейс, помогающий поддерживать целостность данных и
обслуживать ресурсы при возникновении исключительных ситуаций.
Интерфейс
TryCatchFinally
может добавляться в класс, реализующий любой интерфейс:
Tag
, IterationTag
или BodyTag
.
Библиотека тэгов может содержать классы, которые являются прослушивателями событий (см. спецификацию Servlet 2.3). Классы-прослушиватели перечисляются в дескрипторе библиотеки тэгов, и JSP-контейнер автоматически инстанциирует и регистрирует их. Контейнер нужен для размещения всех TLD-файлов (см. в Разделе JSP.7.3.1 детали об их идентификации), чтения их элементов-прослушивателей и рассмотрения прослушивателей событий как расширений этих же прослушивателей, перечисленных в web.xml. Порядок регистрации прослушивателей не определён, но они регистрируются до старта приложения.
В качестве примеров мы рассмотрим прототипы использования развёртывания тэгов, кратко остановившись на преимуществах этих механизмов.
Простейшая акция просто делает что-нибудь, возможно - с параметрами, для
модификации этого "что-нибудь" и улучшения использования.
Акция этого типа может быть реализована через обработчик тэга, который реализует
интерфейс Tag. Этот обработчик тэга должен использовать только метод
doStartTag()
, который вызывается при обнаружении начального/стартового тэга. Он
имеет доступ к атрибутам тэга и информации о статусе JSP-страницы. Эта
информация передаётся объекту
Tag через вызовы setter-метода, прежде чем будет вызван
doStartTag()
.
Поскольку часто встречаются простые акции с пустым телом, Tag Library
Descriptor может использоваться для указания на то, что данный тэг всегда предполагается как пустой.
Такая индикация позволяет лучше проверять ошибки на этапе трансляции и даёт код
более высокого качества в классе реализации JSP-страницы.
Другой набор простых акций требует, чтобы что-нибудь происходило, когда
обнаруживается начальный тэг и когда обнаруживается конечный тэг. Интерфейс Tag
может также использоваться для этих акций. Метод
doEndTag()
похож на метод
doStartTag()
, за исключением того, что он вызывается при обнаружении конечного
тэга акции. Результат вызова doEndTag
показывает, вычисляется ли оставшаяся часть страницы, или нет.
В некоторых случаях тело должно вызываться только при возникновении некоторого (возможно, сложного)
условия. И опять, этот тип акции поддерживается базовым интерфейсом
Tag
через использование return-значений метода doStartTag()
.
Для итераций необходим интерфейс IterationTag
. Метод
doAfterBody()
вызывается для определения необходимости повторного обсчёта тела.
Рассмотрим акцию, которая обсчитывает своё тело несколько раз, создавая поток
данных ответа. Для этого используется протокол IterationTag
.
Если результат повторной интерпретации будет в дальнейшем обрабатываться, по
каким-то соображениям, в том числе и просто может быть отброшен, то нам нужен
способ "отвлечь" вывод/output от повторных обсчётов.
Это выполняется путём создания объекта
BodyContent
и использования метода setBodyContent()
, который является частью интерфейса BodyTag
.
BodyTag
также предоставляет метод doInitBody()
, вызываемый после
setBodyContent()
и до первого обсчёта тела, что является удобным моментом для взаимодействия с телом/body.
Кооперирующиеся акции могут предлагать наилучший способ описания необходимой функциональности.
Например, одна акция может использоваться для описания информации, приводящей к
созданию серверного объекта, а другая может использовать этот объект где-либо
на этой странице. Эти акции могут кооперироваться явно через переменные
скриптинга: одна акция создаёт объект и даёт ему имя; другая ссылается на объект по имени.
Переменные скриптинга кратко обсуждаются далее.
Две акции могут также кооперироваться неявно. Гибкий и удобный механизм
кооперирования акций использует вложение структуры акций для описания области
видимости. В данной спецификации это поддерживается через предоставление
обработчика каждого тэга и обработчика тэга его родителя (если имеется) через
вызов метода setParent()
. Статический метод findAncestorWithClass
в
TagSupport
может затем использоваться для локализации обработчика тэга и, после
локализации, для выполнения операций в обработчике тэга.
Специальные акции могут создавать серверные объекты и делать их доступными
элементам скриптинга через создание или обновление переменных скриптинга.
Обработанные таким образом переменные являются частью семантики специальной
акции и находятся в зоне ответственности автора библиотеки тэгов.
Эта информация используется во время трансляции JSP-страницы и может быть
описана одним из двух способов: непосредственно в
TLD - для простых случаев, или через субклассы TagExtraInfo
.
Каждый механизм будет указывать имена и типы переменных скриптинга.
На этапе запроса обработчик тэга будет ассоциировать объекты с переменными
скриптинга через объект pageContext
.
Транслятор JSP-страницы отвечает за то, чтобы автоматически снабжать кодом,
необходимым для выполнения "синхронизации" между значениями pageObject
и переменными скриптинга.
Библиотека тэгов это коллекция акций, инкапсулирующая некоторую
функциональность, используемую в JSP-странице. Библиотека тэгов становиться
доступной JSP-странице через использование директивы
taglib
, которая идентифицирует эту библиотеку тэгов с помощью URI (Universal Resource Identifier/Универсальный
Идентификатор Ресурсов).
URI, идентифицирующий библиотеку тэгов, может быть любым верным URI, который
может использоваться для уникальной идентификации семантики библиотеки тэгов.
URI, идентифицирующий библиотеку тэгов, ассоциируется с файлом Tag Library
Description (TLD) и с классами обработчиков тэгов, как указано далее
в Разделе JSP.7.3.
Утилиты авторизацииJSP-страниц и JSP-контейнеры должны принимать библиотеку тэгов, упакованную в JAR-файл.
При поставке в JSP-контейнере применяются стандартные соглашения по JAR,
описанные в спецификации Servlet 2.3, включая
соглашения для зависимостей расширений.
Упакованные библиотеки тэгов обязаны иметь как минимум один файл дескриптора библиотеки тэгов.
Спецификация JSP 1.1 разрешала только один TLD, в META-INF/taglib.tld, а в
JSP 1.2 разрешены несколько библиотек тэгов. См. в Разделе JSP.7.3.1 об
идентификации TLD.
Библиотека тэгов содержит классы для инстанциации на этапе трансляции и классы
для инстанциации на этапе запроса. Первые содержат классы TagLibraryValidator
и
TagExtraInfo
. Вторые содержат классы обработчика тэгов и прослушивателя событий.
Применяются обычные соглашения по классам Java: как часть web-приложения они
обязаны находиться внутри либо JAR-файла в директории WEB-INF/lib, либо в директории WEB-INF/classes.
JAR, содержащий упакованные библиотеки тэгов, может быть сброшен в директорию WEB-INF/
lib, чтобы сделать его классы доступными на этапе запроса (а также на этапе
трансляции, см. Раздел JSP.7.3.7).
Отображение между URI и TLD объясняется далее.
Директива taglib
в JSP-страниц объявляет, что эта страница использует библиотеку тэгов,
уникально идентифицирует эту библиотеку через URI и ассоциирует префикс тэга с использованием акций библиотеки.
JSP-контейнер отображает URI, используемый в директиве taglib
, в Tag Library
Descriptor/Дескриптор Библиотеки Тэгов за два шага: сначала разрешает URI в путь
ресурса TLD, а затем получает TLD-объект из пути ресурса TLD.
Если JSP-контейнер не может локализовать путь ресурса TLD для данного URI,
должна происходить фатальная ошибка трансляции.
Аналогично, фатальной ошибкой трансляции является развёртывание/разрешение
значения атрибута uri
в два различных пути ресурса TLD.
Для директивы taglib
будет фатальной ошибкой, если она появится после акций,
использующих префикс, вводимый ею.
Дескриптор Библиотеки Тэгов/Tag Library Descriptor (TLD) это XML-документ,
который описывает библиотеку тэгов. TLD библиотеки тэгов используется JSP-контейнером
для интерпретации страниц, которые содержат директивы
taglib
, ссылающиеся на эту библиотеку тэгов. TLD используется также утилитами
авторизации/создания JSP-страниц, которые будут генерировать JSP-страницы,
использующие библиотеку, и авторами, делающими то же самое вручную.
TLD содержит документацию о библиотеке в целом и о каждом из её тэгов,
информацию о версии JSP-контейнера и о библиотеке и информацию о каждой акции, определённой в этой библиотеке тэгов.
TLD может именовать класс TagLibraryValidator
, который может проверять
соответствие JSP-страницы набору ограничений, ожидаемых этой библиотекой тэгов.
Каждой акции в библиотеке присваивается имя, класс её обработчика тэга,
информация о переменных скриптинга, создаваемых этой акцией, и информация об
атрибутах акции. Информация о переменных скриптинга может быть задана
непосредственно в TLD или через класс TagExtraInfo
.
Каждый верный атрибут содержит указания на то, является ли он мандатным, может
ли он принимать выражения времени запроса, и дополнительную информацию.
Файл TLD используется для предоставления информации о библиотеке тэгов. Он может
быть прочитан утилитами без инстанциации объектов или классов загрузчика.
Наш подход соответствует соглашениям в других технологиях J2EE.
ОТД для дескриптора библиотеки тэгов организовано так, что нужные элементы имеют
необязательный атрибут ID. Этот атрибут может использоваться другими
документами, типа документации продавца, для предоставления аннотаций по информации TLD.
Файл дескриптора библиотеки тэгов (ДБТ) именуется с использованием расширения ".tld", которое указывает, что это файл ДБТ.
Если размещены внутри файла JAR,
файлы ДБТ обязаны находиться в директории META-INF или в её субдиректории.
При размещении непосредственно в web-приложении файлы ДБТ обязаны всегда
находиться в директории WEB-INF или в одной из её субдиректорий.
Документ ОТД для ДБТ это
"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd".
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).
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.
Отображение taglib
, описанное в web.xml, расширяется за счёт новых вхождений,
извлекаемых из файлов TLD Web-Приложения.
Новые вхождения обсчитываются так:
<uri>
,
создаётся новый элемент <taglib>
с субэлементом
<taglib-uri>
, значением которого является значение элемента
<uri>
, и с субэлементом <taglib-location>
, указывающим на TLD-файл.<taglib>
содержит разные <taglib-uri>
для каждого отображения taglib
, он добавляется.
Этот механизм предоставляет автоматическое отображение URI в TLD, а также
поддержку нескольких TLD в одном JAR-пакете.
Обратите внимание, что эта функциональность не требует явного именования места
размещения TLD-файла, которого мог бы потребовать механизм типа протокола
jar:.
Заметьте также, что этот механизм не добавляет дублирующие вхождения.
Контейнер также может добавлять дополнительные вхождения к отображению taglib
.
Как и в предыдущем случае, входы добавляются только для тех URI, которые не
представлены в отображении. Концептуально эти вхождения соответствуют TLD,
описывающему эти библиотеки тэгов.
Эти неявные вхождения отображения соответствуют библиотекам, которые известны
контейнеру, который отвечает за предоставление их реализации, либо через
обработчики тэгов, либо через механизм, описанный в Разделе JSP.7.3.9.
Путь ресурса TLD может быть определён из атрибута uri
директивы
taglib
, как показано ниже. В последующем разъяснении "абсолютным URI" называется
такой, который начинается с названия протокола и имени хоста,
а "относительный URI" даётся так, как указано в Разделе
2.5.2, т.е. без протокола и имени хоста.
Все шаги описаны так, будто они выполнялись, но реализация может использовать
различные стратегии для получения того же результата.
Карта 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
следующим образом:
<taglib-location>
это относительный URI, начинающийся с "/", то
TAGLIB_LOCATION
является этим URI.<taglib-location>
это относительный URI, не начинающийся с "/", то
TAGLIB_LOCATION
является разрешением этого URI относительно
/WEB-INF/web.xml (результатом этого разрешения является относительный URI, начинающийся с "/").
Здесь показано, как разрешить директиву taglib
для вычисления пути ресурса TLD
на базе значения атрибута uri
директивы taglib
.
uri
является ABS_URI
,
абсолютным URI. Идёт поиск в карте taglib
вхождения, чей TAGLIB_URI
является
ABS_URI
.
Если он найден, соответствующее TAGLIB_LOCATION
является путём ресурса TLD. Если он не найден,
возникает ошибка трансляции.uri
является ROOT_REL_URI
,
относительным URI, начинающимся с "/".
Идёт поиск в карте taglib
вхождения, чей
TAGLIB_URI
является ROOT_REL_URI
.
Если он найден, соответствующее
TAGLIB_LOCATION
является путём ресурса TLD. Если он не найден, ROOT_REL_URI
является путём ресурса TLD.uri
является
NOROOT_REL_URI
,
относительным URI, не начинающимся с "/". Идёт поиск в карте taglib
вхождения,
чей TAGLIB_URI
является NOROOT_REL_URI
.
Если он найден, соответствующее
TAGLIB_LOCATION
является путём ресурса TLD. Если он не найден,
NOROOT_REL_URI
разрешается относительно текущей JSP-страницы, где появилась
директива; это значение (по определению, это спецификация относительного URI,
начинающегося с "/") является путём ресурса TLD.Явное отображение 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" %>
Набор классов, доступных во время трансляции, - тот же, что и для времени
прогона/runtime: классы основной платформы Java, в JSP-контейнере и в файлах
классов в WEB-INF/classes, в JAR-файлах в
WEB-INF/lib и, косвенно, классы, обозначенные через использование атрибута class-path
в файле-манифесте META-INF/MANIFEST этих JAR-файлов.
Как часть процесса ассемблирования 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-контейнер может "знать" некоторые URI и может предоставлять альтернативные
реализации для библиотек тэгов, описанных этими URI, но пользователь обязан
видеть поведение как таковое, описанное описанием требуемой, переносимой
библиотеки тэгов, указанной в URI.
JSP-контейнер обязан всегда использовать отображение, специфицированное для URI,
в дескрипторе публикации
web.xml, если он имеется.
Если публикатор хочет использовать платформозависимую реализацию хорошо
известного URI, отображение такого
URI должно быть удалено во время публикации.
В этом разделе описано ОТД (Определение Типа Данных), для 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-страницы должна соответствовать некоторым правилам проверки:
Проверка может выполняться на этапе трансляции или на этапе запроса. Обычно проверка на этапе трансляции даёт больше информации, и спецификация JSP 1.2 предоставляет очень гибкий механизм проверки на этапе трансляции.
Определённая проверка на этапе трансляции проводится в Tag Library Descriptor (TLD).
В некоторых случаях для предоставления поддержки этой информации необходимо наличие класса
TagExtraInfo
.
Tag Library Descriptor содержит базовую синтаксическую информацию. Атрибуты
описываются с включением его имени, являются ли они необязательными или
мандатными и принимают ли они выражения времени запроса. Кроме того, элемент
bodycontent
может использоваться для указания на то, что акция обязаны быть пустой.
Все ограничения, описанные в TLD, обязаны форсироваться. Автор библиотеки тэгов может принять как данное, что
экземпляр обработчика тэга соответствует акции, которая удовлетворяет всем
ограничениям, указанным в TLD.
Класс TagLibraryValidator
может быть указан в TLD библиотеки тэгов для запроса проверки этой JSP-страницы.
XML-просмотр JSP-страницы экспонируется через класс
PageData, и класс validator/проверщика может выполнять любую проверку, которую
автор библиотеки тэгов сочтёт необходимой.
JSP-контейнер может по выбору уникально идентифицировать все XML-элементы в
XML-просмотре JSP-страницы через атрибут
jsp:id
. этот атрибут может использоваться для предоставления большей информации о местонахождении ошибки.
механизм класса проверщика является новым для спецификации JSP 1.2.
может быть передан некоторым параметрам инициализации в TLD.
Это облегчает многократное использование классов проверщика. Мы ожидаем, что validator-классы
будут написаны на базе различных механизмов схемы XML
(DTDs, XSchema, Relaxx, других). Стандартные классы проверщика могут быть внедрены в последующих версиях
спецификации JSP, если когда-нибудь появится полный стандарт схемы.
TagLibraryValidator
TagExtraInfo
Дополнительная проверка на этапе трансляции может выполняться путём
использования метода isValid
класса TagExtraInfo
. Метод
isValid
вызывается на этапе трансляции и передаётся в экземпляр
Tag Dat в качестве его аргумента.
Механизм isValid
был первоначальным механизмом проверки, введённым в
JSP 1.1 вместе с механизмами Расширения Тэгов. Библиотеки тэгов, созданные для запуска в контейнерах JSP 1.2, должны
использовать механизм класса проверщика.
В некоторых случаях может динамически выполняться дополнительная проверка на
этапе запроса в методах обработчиков тэгов. Если обнаруживается ошибка, вызывается экземпляр
JspException
. Если ошибка не отловлена, этот объект вызовет механизм errorpage спецификации JSP.
Этот раздел не является нормативным, хотя отражает практику разработки.
Мы предлагаем придерживаться следующего стиля введения неявных объектов:
defineObjects
определяет необходимые объекты.JSP-страница может сделать эти объекты доступными так:
<%@ tablig
prefix="me" uri="......" %>
<me:defineObjects />
.... начинается использование объектов ....
Этот подход имеет то преимущество, что не требует новых механизмов и установления слишком явной зависимости.
В некоторых случаях доступность этих объектов может зависеть от реализации.
Например, они могут предоставлять доступ к некоторой функциональности, которая имеется
только в определённой реализации. Это может быть выполнено через проверку
классом расширения тэга на этапе прогона на предмет наличия некоторых свойств
данной реализации и вызова ошибки этапа прогона (это, конечно, не делает страницу ближе к J2EE).
Этот механизм, вместе с доступом к информации метаданных, позволяет продвигать новинки наряду со стандартом.
Примечание: если новая возможность добавлена к спецификации
JSP и продавец также предоставляет эту возможность через свой специфический
механизм, стандартным механизмом, как указано в спецификации JSP, будет "win".
Это значит, что механизмы, специфичные для продавца, могут постепенно перейти в
спецификацию, если докажут свою пригодность.
Если продавец хочет ассоциировать некоторую информацию, не описанную в текущей версии TLD, с некоторой библиотекой тэгов, он может сделать это, вставив информацию в контролируемый им документ, включив этот документ в часть WEB-INF JAR-файла там, где находится Tab Library/Библиотека Тэгов, и используя стандартные механизмы Servlet 2.2 для доступа к этой информации. Продавец может теперь использовать ID-механизмы для ссылки на элемент внутри TLD.
Библиотека тэгов может быть специализирована в ходе ассемблирования и публикации. Например,
библиотека тэгов, предоставляющая доступ к базам данных, может быть
специализирована информацией логина и пароля.
В web.xml в спецификации Servlet 2.2 нет подходящего места для специализированной
информации. Стандартизованный механизм, возможно, станет частью последующей
JSP-спцификации, но пока советуем авторам библиотек тэгов размещать такую
информацию в хорошо известном месте какого-нибудь ресурса в части
WEB-INF/ Web-Приложения давать к ней доступ через вызов getResource()
в ServletContext
.
В этой главе рассматриваются контракты между JSP-контейнером и JSP-страницей.
Протокол прекомпиляции (см. Раздел JSP.8.4) также представлен здесь.
Информация, представленная здесь, не зависит от Языка Скриптинга, используемого на JSP-странице.
Глава JSP.6 описывает информацию для случая, когда атрибут
language
директивы page
установлен в "java"
.
Классы реализации
JSP-страницы должны использовать классы JspFactory
и PageContext
для получения
преимуществ платформозависимых реализаций.
JSP-страница представлена на этапе выполнения объектом реализации JSP-страницы и выполняется JSP-контейнером. Объект реализации JSP-страницы - это servlet/сервлет. JSP-контейнер направляет запросы от клиента объекту реализации JSP-страницы и ответы объекта реализации JSP-страницы - клиенту.
JSP-страница описывает создание объекта response из объекта request
для данного протокола, возможно, создавая и/или используя в ходе этого процесса
некоторые другие объекты. JSP-страница может также указывать, как должны обрабатываться некоторые события.
В JSP 1.2 только события init и destroy являются допустимыми событиями.
JSP-контейнер локализует соответствующий экземпляр класса реализации
JSP-страницы и направляет ему запросы, используя протокол Servlet.
JSP-контейнеру может потребоваться создать такой класс динамически из исходной JSP-страницы до
направления ей объектов request
и response
.
Класс Servlet
определяет контракт между JSP-контейнером и классом реализации JSP-страницы.
Если используется протокол HTTP, контракт описывается классом
HttpServlet
. Большинство JSP-страниц используют протокол HTTP, но другие
протоколы также разрешены данной спецификацией.
JSP-контейнер автоматически делает несколько серверных/server-side объектов
доступными объекту реализации JSP-страницы. См. Раздел JSP.2.8.3.
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, в любом сочетании регистров.
HttpJspPage
Выполнению контракта между JSP-контейнером и автором JSP-страницы помогает
требование о том, что класс Servlet
, соответствующий JSP-странице, обязан
реализовывать интерфейс HttpJspPage
(или интерфейс JspPage
, если протокол - не HTTP).
JSP-Контейнер |
JSP-Страница |
---|---|
|
На Рисунке J2EE.8.1 показаны включённые контракты. Теперь мы рассмотрим этот процесс более детально.
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-контейнером и Java-классом, реализующим JSP-страницу, соответствует интерфейсу
Servlet
. См. детали в спецификации Servlet 2.3.
Ответственность за выполнение этого контракта лежит на реализации JSP-контейнера,
если JSP-страница не использует атрибут extends директивы jsp.
Если атрибут extends директивы jsp
используется, автор JSP-страниц обязан гарантировать, что суперкласс, заданный в
атрибуте extends
, поддерживает этот контракт.
Комментарии | Методы, вызываемые JSP-Контейнером |
---|---|
Метод может по выбору/optionally быть определён в JSP-странице. Метод вызывается при инициализации JSP-страницы. Если метод вызывается, доступны все методы сервлета, включая getServletConfig() . |
void jspInit()
|
Метод по выбору определяется в JSP-странице. Метод вызывается при уничтожении страницы. |
void jspDestroy()
|
Метод не может быть определён в JSP-странице. JSP-контейнер автоматически генерирует этот метод, базируясь на содержимом JSP-страницы. Метод вызывается при каждом клиентском запросе. |
void_jspService(<ServletRequestSubtype>, <ServletResponseSubtype>) throws
IOException, |
Как видно из Таблицы 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-протокола, как описано в этом разделе.
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()
.
Это значительно упрощает реализацию.
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;
}
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());
// далее идёт код из скриптлетов, выражений и статического текста.
}
}
extends
Если автор JSP-страниц использует extends
,
генерируемый класс идентичен классу из Примера Кода 8.2, за исключением того,
что имя этого класса это имя, специфицированное в атрибуте extends
.
Контракт класса реализации JSP-страницы не изменяется. JSP-контейнер должен
проверить (обычно через отражение/reflection), что предоставленный суперкласс:
HttpJspPage
, если протокол - HTTP, либо
JspPage
- в ином случае.Servlet
объявлены final
.service()
из Servlet API вызывает метод _jspService()
;
init(ServletConfig)
хранит конфигурацию,
даёт к ней доступ как к getServletConfig
, затем вызывает jspInit
;destroy
вызывает jspDestroy
.JSP-контейнер может выдавать фатальную ошибку трансляции, если обнаружит, что предоставленный суперкласс не удовлетворяет этим требованиям, но большинство JSP-контейнеров эту проверку не будут выполнять.
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-страница, использующая протокол HTTP, будет получать HTTP-запросы.
Контейнеры, соответствующие JSP 1.2, обязаны поддерживать простой протокол
прекомпиляции, а также некоторые базовые зарезервированные имена
параметров. Заметьте, что протокол прекомпиляции это понятие близкое, но не
то же самое, что компиляция JSP-страницы в Servlet-класс (Приложение JSP.A).
Все имена параметров запроса, начинающиеся с префикса "jsp"
,
зарезервированы спецификацией
JSP и не должны использоваться иначе, чем установлено данной спецификацией.
Все JSP-страницы должны игнорировать (и не зависеть от) параметры, начинающиеся
с "jsp_"
Запрос к 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).
Эта глава описывает пакет javax.servlet.jsp
. В главе имеется содержимое,
сгенерированное автоматически из javadoc, внедрённых в Java-классы и интерфейсы.
Это делает возможным создание единого авторизованного документа спецификации.
Пакет javax.servlet.jsp
содержит несколько классов и интерфейсов, описывающих и
определяющих контракты между классом реализации JSP-страницы и средой работы
программы/runtime environment, предоставляемые экземпляру такого класса соответствующим JSP-контейнером.
В разделе рассматривается базовый контракт между объектом реализации JSP-страницы
и его контейнером. Главный контракт определяется классами JspPage
и HttpJspPage
.
Класс JspFactory
описывает механизм портативной инстанциации всех необходимых объектов
прогона, а JspEngineInfo
предоставляет базовую информацию о текущем JSP-контейнере.
Ни один из классов, рассматриваемых здесь, не предназначен для использования
авторами JSP-страниц; пример использования этих классов имеется в данной главе.
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;
()
public void jspDestroy
Метод jspDestroy()
вызывается при уничтожении JSP-страницы. JSP-страница может
переопределять этот метод включением его определения в элемент declaration
. JSP-страница
должна переопределять метод destroy()
из Servlet'а.
public void jspInit()
Метод jspInit()
вызывается при инициализации JSP-страницы. Реализация JSP
(и класса, упоминаемого атрибутом
extends
, если имеется) отвечает за то, что с этой точки вызовы метода getServlet-Config()
будут возвращать требуемое значение. JSP-страница может переопределять этот
метод включением его определения в элемент declaration
. JSP-страница должна
переопределять метод init()
из Servlet'а.
HttpJspPage
Синтаксис
public interface HttpJspPage extends JspPage
Все Суперинтерфейсы: JspPage, javax.servlet.Servlet
Описание
Интерфейс HttpJspPage
описывает взаимодействие, которое Класс Реализации JSP-Страницы
обязан выполнять при использовании HTTP-протокола.
Поведение идентично поведению JspPage
, за исключением подписи метода
_jspService
, которая теперь выражается в системе типов Java и включается в интерфейс явно.
См. Также: JspPage
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
JspFactory
Синтаксис
public abstract class JspFactory
Описание
является абстрактным классом, определяющим несколько factory/"фабричных"-методов,
доступных JSP-странице на этапе прогона, для создания экземпляров различных
интерфейсов и классов, используемых для поддержки JSP-реализации.
JspFactory
Соответствующая реализация JSP Engine будет, в процессе своей инициализации,
инстанциировать зависящий от реализации подкласс этого класса сделает его
глобально доступным для использования классами реализации JSP
путём регистрации экземпляра, созданного этим классом, через static/статичный
метод setDefaultFactory()
.
Классы PageContext
и
JspEngineInfo
являются единственными зависящими от реализации классами, которые
могут создаваться из factory/фактории.
JspFactory-объекты не должны использоваться авторами JSP-страниц.
public JspFactory()
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 - PageContextgetPageContext()
public static synchronized void setDefaultFactory(JspFactory deflt)
Устанавливает факторию по умолчанию для данной реализации. Для любой principal (основной среды
работы?), кроме среды JSP Engine, недопустимо вызывать этот метод.
Параметры:
- реализация фактории по умолчанию.
default
JspEngineInfo
Синтаксис
public abstract class JspEngineInfo
Описание
это абстрактный класс, предоставляющий информацию о текущей
JSP-машине.
JspEngineInfo
public JspEngineInfo()
public abstract java.lang.String getSpecificationVersion()
Возвращает номер версии JSP-спецификации, поддерживаемой этой JSP-машиной.
Номера версии состоят из положительных целых чисел, разделённых точками ".", например, "2.0" или "1.2.3.4.5.6.7". Это позволяет использовать расширенную нумерацию для представления версий major, minor, micro и т.д.
Номер версии обязан начинаться с цифры.
Возвращает: версию спецификации, null
возвращается, если номер неизвестен.
Объекты PageContext
и
JspWriter
доступны по умолчанию в качестве неявных объектов.
PageContext
Синтаксис
public abstract class PageContext
Описание
Экземпляр PageContext
предоставляет доступ ко всем пространствам имён, ассоциированным с
JSP-страницей, предоставляет доступ к некоторым атрибутам страницы, а также слой поверх деталей реализации.
Неявные объекты добавляют pageContext
автоматически.
Класс PageContext
является абстрактным классом,
созданный как расширяемый для предоставления реализаций соответствующей средой запуска программ JSP-машины.
Экземпляр PageContext
получается классом реализации JSP через вызов метода
JspFactory.getPageContext()
и освобождается через вызов
JspFactory.releasePageContext()
.
Примеры использования PageContext
,
JspFactory
и других классов в объекте реализацииJSP-страницы можно найти повсюду.
облегчает работу автора страниц/компонентов и реализатора страниц, предоставляя:
PageContext
JspWriter
для вывода/outputpage
в среде скриптингаerrorpage
Некоторые методы предназначены для использования в коде, генерируемом контейнером, а не для кода, написанного авторами JSP-страниц или библиотек тэгов JSP.
Методы, поддерживающие lifecycle/жизненный цикл
- initialize()
и release()
Следующие методы делают возможным обслуживание вложенных JspWriter-потоков
через реализацию Tag Extensions/Расширений Тэгов: pushBody()
и popBody()
Некоторые методы предоставляют универсальный доступ к различным объектам,
представляющим области видимости/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()
.
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
не будет закрыта.
public PageContext()
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(...)
после вызова этого метода.
Параметры:
- специфицирует относительный путь URL к целевому ресурсу, как рассмотрено выше.
relativeUrlPath
Вызывает:
ServletException, IOException
IllegalArgumentException
- если URL целевого ресурса не может быть разрешён/высчитан.
IllegalStateException
- если
ServletResponse
не в том состоянии, чтобы выполнить forward/направление.
SecurityException
- если вызывающий не может получить доступ к целевому ресурсу.
public abstract java.lang.Object getAttribute(java.lang.String name)
Возвращает объект, ассоциированный с именем в области видимости страницы, или null
, если объект не найден.
Параметры:
- имя атрибута для получения.
name
Вызывает:
- если имя - null.
NullPointerException
IllegalArgumentException
- если область видимости неверна.
public abstract java.lang.Object getAttribute(java.lang.String name, int scope)
Возвращает объект, ассоциированный с именем в специфицированной области видимости, или null, если объект не найден.
Параметры:
- имя атрибута для установки.
name
- область видимости, с которой ассоциировать имя/объект.
scope
Вызывает:
- если имя -
NullPointerExceptionnull.
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
после этого вызова.
Параметры:
- обрабатываемый
tthrowable
.
Вызывает:
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.
Параметры:
- специфицирует относительный путь-URL
к включаемому целевому ресурсу.
relativeUrlPath
Вызывает:
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, ассоциированный с данным
servletPageContext
.
request
- текущий рассматриваемый запрос для данного Servlet
.
response
- текущий рассматриваемый ответ для данного Servlet
.
errorPageURL
- значение атрибута errorpage в директиве page, или null
.
needsSession
- значение атрибута session директивы page.
bufferSize
- значение атрибута buffer
директивы page
.
autoFlush
- значение атрибута autoflush
директивы page.
Вызывает:
- во время создания
IOExceptionJspWriter
.
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
- объект для ассоциирования с этим именем.
Вызывает:
- если
NullPointerExceptionname
или object
- null
.
public abstract void setAttribute(java.lang.String name, java.lang.Object o,
int scope)
Регистрирует имя и объект, специфицированные с семантикой соответствующей области видимости.
Параметры:
- имя устанавливаемого атрибута.
name
o
- объект для ассоциирования с этим именем.
scope
- область видимости, с которой ассоциируется name/object
.
Вызывает:
- если
NullPointerExceptionname
или object
- null
.
IllegalArgumentException
- если область видимости неверна.
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
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
.
protected JspWriter(int bufferSize, boolean autoFlush)
protected-конструктор.
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)
.
Параметры:
- печатаемый char.
c
Вызывает: java.io.IOException
public abstract void print(char[] s)
Печатает массив символов. Символы конвертируются в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются
точно в манере метода java.io.Writer.write(int)
.
Параметры:
- массив печатаемых chars.
s
Вызывает:
-если
NullPointerExceptions
- null
.
java.io.IOException
public abstract void print(double d)
Печатает число с плавающей точкой двойной точности. Строка, производимая
java.lang.String.valueOf(double)
, транслируется в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int)
.
Параметры:
- печатаемое double.
d
Вызывает: java.io.IOException
См. Также: java.lang.Double
public abstract void print(float f)
Печатает число с плавающей точкой. Строка, производимая
java.lang.String.valueOf(float)
, транслируется в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются
точно в манере метода java.io.Writer.write(int)
.
Параметры:
- печатаемое float.
f
Вызывает: java.io.IOException
См. Также: java.lang.Float
public abstract void print(int i)
Печатает целое число. Строка, производимая
java.lang.String.valueOf(int)
, транслируется в байты в соответствии с кодировкой
символов по умолчанию данной платформы, и эти байты записываются точно в манере
метода java.io.Writer.write(int)
.
Параметры:
- печатаемое int.
i
Вызывает: java.io.IOException
См. Также: java.lang.Integer
public abstract void print(long l)
Печатает длинное целое. Строка, производимая
java.lang.String.valueOf(long)
, транслируется в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются
точно в манере метода java.io.Writer.write(int)
.
Параметры:
- печатаемое long.
l
Вызывает: java.io.IOException
См. Также:
java.lang.Long
public abstract void print(java.lang.Object obj)
Печатает объект. Строка, производимая методом
java.lang.String.valueOf(Object)
, транслируется в байты в соответствии с
кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int)
.
Параметры:
- печатаемый
objObject
.
Вызывает: java.io.IOException
См. Также: java.lang.Object.toString()
public abstract void print(java.lang.String s)
Печатает строку. Если аргумент - null
, тогда печатается строка
"null". Иначе символы строки конвертируются в байты в соответствии с кодировкой
символов по умолчанию данной платформы, и эти байты записываются точно в манере
метода java.io.Writer.write(int)
.
Параметры:
- печатаемая
sString
.
Вызывает: 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 в начале её метода _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);
}
}
Класс
JspException
является базовым классом для всех JSP-исключений.
JspTag-Exception
используется механизмом исключения тэга.
JspException
Синтаксис
public class JspException extends java.lang.Exception
Прямые/Direct Известные Подклассы: JspTagException
Все Реализованные Интерфейсы: java.io.Serializable
Описание
Родовое исключение, известное JSP-машине; неотловленное JspExceptions
даст вызов механизма errorpage
.
public JspException()
Конструирует JspException
.
public JspException(java.lang.String msg)
Конструирует новое JSP-исключение со специфицированным сообщением.
Сообщение может быть записано в server log-файл и/или выводится пользователю.
Параметры:
-
msgString
, специфицирующая текст сообщения об исключении.
public JspException(java.lang.String message, java.lang.Throwable rootCause)
Конструирует новое JSP-исключение, если JSP нужно вызвать исключение и
вставить сообщение о "причине" исключения, помешавшего нормальному ходу операции, включая описательное сообщение.
Параметры:
-
messageString
, содержащая текст сообщения об исключении.
rootCause
- исключение
Throwable
, нарушившее нормальную работу сервлета; делает это исключение сервлета необходимым.
public JspException(java.lang.Throwable rootCause)
Конструирует новое JSP-исключение, если JSP нужно вызвать исключение и
вставить сообщение о "причине" исключения, помешавшего нормальному ходу операции.
Сообщение об исключении базируется на локализованном сообщении об вызвавшем его исключении.
Этот метод вызывает метод getLocalizedMessage
в исключении
Throwable
для получения локализованного сообщения об исключении. При создании
подкласса для JspException
, этот метод может быть переопределён для создания сообщения об исключении,
разработанного для определённой страны (языка и т.п.).
Параметры:
- исключение
rootCauseThrowable
, нарушившее нормальную работу
JSP-операции, ; делает это JSP-исключение необходимым.
public java.lang.Throwable getRootCause()
Возвращает исключение, вызвавшее это JSP-исключение.
Возвращает: Throwable
, вызывавшее это JSP-исключение.
JspTagException
Синтаксис
public class JspTagException extends JspException
Все Реализованные Интерфейсы:
java.io.Serializable
Описание
Исключение используется Tag Handler/Обработчиком Тэга для обозначения неисправимой ошибки. Эта ошибка
отлавливается на верхнем уровне JSP-страницы и выдаёт страницу для ошибок/errorpage.
public JspTagException()
Нет сообщения.
public JspTagException(java.lang.String msg)
Конструктор с сообщением...