Глава JSP.9

Основной API

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


Пакет javax.servlet.jsp содержит несколько классов и интерфейсов, описывающих и определяющих контракты между классом реализации JSP-страницы и средой работы программы/runtime environment, предоставляемые экземпляру такого класса соответствующим JSP-контейнером.

JSP.9.1 Контракт Объекта Реализации JSP-Страницы

В разделе рассматривается базовый контракт между объектом реализации JSP-страницы и его контейнером. Главный контракт определяется классами JspPage и HttpJspPage. Класс JspFactory описывает механизм портативной инстанциации всех необходимых объектов прогона, а JspEngineInfo предоставляет базовую информацию о текущем JSP-контейнере.


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

JSP.9.1.1 JspPage

Синтаксис
 

public interface JspPage extends javax.servlet.Servlet


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


Все Суперинтерфейсы: javax.servlet.Servlet


Описание


Интерфейс JspPage описывает основное взаимодействие, которому класс реализации JSP-страницы обязан удовлетворять; страницы, использующие HTTP-протокол, описаны через интерфейс HttpJspPage.

Методы Два плюс Один
 

Этот интерфейс определяет протокол с 3 методами; только два из них: jspInit() и jspDestroy() являются частью этого интерфейса как подпись третьего метода: _jsp-Service() зависит от специфического используемого протокола и не может быть выражен общим способом в Java.


Класс, реализующий этот интерфейс, отвечает за вызов вышеуказанных методов в нужное время, базируясь на соответствующих вызовах методов на базе Servlet'а.


Методы jspInit() и jspDestroy() могут быть определены автором JSP, но метод _jspService() определяется автоматически JSP-процессором на основе содержимого JSP-страницы.


_jspService()
 

Метод _jspService() соответствует телу JSP-страницы. этот метод определяется автоматически JSP-контейнером и никогда не должен определяться автором JSP.
 

Если суперкласс специфицируется через использование атрибута extends, то этот суперкласс может избрать выполнение некоторых акций в своём методе service() до или после вызова метода _jspService().

См. использование атрибута extends в главе JSP_Engine JSP-спецификации.
 

Специфика подписи зависит от протокола, поддерживаемого JSP-страницейJSP page.
 

public void _jspService(ServletRequestSubtype request, ServletResponseSubtype response)

throws ServletException, IOException;

JSP.9.1.1.1 Методы


public void jspDestroy()
 

Метод jspDestroy() вызывается при уничтожении JSP-страницы. JSP-страница может переопределять этот метод включением его определения в элемент declaration. JSP-страница должна переопределять метод destroy() из Servlet'а.


public void jspInit()
 

Метод jspInit() вызывается при инициализации JSP-страницы. Реализация JSP (и класса, упоминаемого атрибутом extends, если имеется) отвечает за то, что с этой точки вызовы метода getServlet-Config() будут возвращать требуемое значение. JSP-страница может переопределять этот метод включением его определения в элемент declaration. JSP-страница должна переопределять метод init() из Servlet'а.

JSP.9.1.2 HttpJspPage

Синтаксис
 

public interface HttpJspPage extends JspPage


Все Суперинтерфейсы: JspPage, javax.servlet.Servlet


Описание


Интерфейс HttpJspPage описывает взаимодействие, которое Класс Реализации JSP-Страницы обязан выполнять при использовании HTTP-протокола.

Поведение идентично поведению JspPage, за исключением подписи метода _jspService, которая теперь выражается в системе типов Java и включается в интерфейс явно.


См. Также: JspPage



JSP.9.1.2.2 Методы
 

public void _jspService(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)


Метод _jspService() соответствует телу JSP-страницы. Этот метод определяется автоматически JSP-контейнером и никогда не должен определяться автором JSP-страниц.


Если суперкласс специфицируется через использование атрибута extends, то этот суперкласс может избрать выполнение некоторых акций в своём методе service() до или после вызова метода _jspService(). См. использование атрибута extends в главе JSP_Engine JSP-спецификации.


Вызывает: IOException, ServletException

JSP.9.1.3 JspFactory

Синтаксис
 

public abstract class JspFactory


Описание


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


Соответствующая реализация JSP Engine будет, в процессе своей инициализации, инстанциировать зависящий от реализации подкласс этого класса сделает его глобально доступным для использования классами реализации JSP путём регистрации экземпляра, созданного этим классом, через static/статичный метод setDefaultFactory().


Классы PageContext и JspEngineInfo являются единственными зависящими от реализации классами, которые могут создаваться из factory/фактории.


JspFactory-объекты не должны использоваться авторами JSP-страниц.

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

public JspFactory()


JSP.9.1.3.4 Методы
 

public static synchronized JspFactory getDefaultFactory()


Возвращает: факторию по умолчанию для данной реализации


public abstract JspEngineInfo getEngineInfo()


вызывается для получения специфической для реализации информации о текущей JSP-машине.


Возвращает: объект JspEngineInfo, описывающий текущую JSP-машину.


public abstract PageContext getPageContext(javax.servlet.Servlet servlet, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String errorPageURL, boolean needsSession, int buffer, boolean autoflush)

Получает экземпляр зависящего от реализации абстрактного класса javax.servlet.jsp.Page-Context для вызова Servlet и текущего отправления запроса/request и ответа/response.


Этот метод обычно вызывает раньше при обработке методом _jspService() класса реализации JSP для того, чтобы получить объект PageContext для обрабатываемого запроса.


Вызов этого метода должен давать в результате вызов метода PageContext.initialize(). Возвращённый PageContext соответственно инициализирован.


Все объекты PageContext, полученные этим методом, должны быть освобождены через вызов releasePageContext().


Параметры:


servlet - запрашивающий сервлет

config - ServletConfig для запрашивающего Servlet'а

request - текущий запрос, находящийся в сервлете.

response - текущий ответ, находящийся в сервлете.

errorPageURL - URL страницы ответа на ошибки для запрашивающей JSP, или null.

needsSession - true, если JSP участвует в сессии.

buffer - размер буфера в байтах, PageContext.NO_BUFFER - если буфера нет, PageContext.DEFAULT_BUFFER - если по умолчанию в реализации.

autoflush - должен ли буфер автоматически зачищаться (опять зачистка...) в потоке вывода при переполнени буфера, или должно вызываться IOException?


Возвращает: page context/контекст страницы.


См. Также: PageContext .


public abstract void releasePageContext(PageContext pc)

Вызывается для освобождения ранее размещённого объекта PageContext. Даёт в результате вызов Page-Context.release(). Этот метод должен вызываться до возвращения из метода _jspService() класса реализации JSP.


Параметры:


pc - PageContext, полученный ранее методом getPageContext()
 

public static synchronized void setDefaultFactory(JspFactory deflt)

Устанавливает факторию по умолчанию для данной реализации. Для любой principal (основной среды работы?), кроме среды JSP Engine, недопустимо вызывать этот метод.


Параметры:


default - реализация фактории по умолчанию.

JSP.9.1.4 JspEngineInfo

Синтаксис
 

public abstract class JspEngineInfo


Описание


JspEngineInfo это абстрактный класс, предоставляющий информацию о текущей JSP-машине.


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

public JspEngineInfo()


JSP.9.1.4.6 Методы
 

public abstract java.lang.String getSpecificationVersion()


Возвращает номер версии JSP-спецификации, поддерживаемой этой JSP-машиной.

Номера версии состоят из положительных целых чисел, разделённых точками ".", например, "2.0" или "1.2.3.4.5.6.7". Это позволяет использовать расширенную нумерацию для представления версий major, minor, micro и т.д.


Номер версии обязан начинаться с цифры.


Возвращает: версию спецификации, null возвращается, если номер неизвестен.

JSP.9.2  Неявные Объекты

Объекты PageContext и JspWriter доступны по умолчанию в качестве неявных объектов.

JSP.9.2.1 PageContext

Синтаксис
 


public abstract class PageContext


Описание


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

Неявные объекты добавляют pageContext автоматически.


Класс PageContext является абстрактным классом, созданный как расширяемый для предоставления реализаций соответствующей средой запуска программ JSP-машины.

Экземпляр PageContext получается классом реализации JSP через вызов метода JspFactory.getPageContext() и освобождается через вызов JspFactory.releasePageContext().


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


PageContext облегчает работу автора страниц/компонентов и реализатора страниц, предоставляя:


Методы, Предназначенные для Кода, Генерируемого Контейнером
 

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


Методы, поддерживающие lifecycle/жизненный цикл - initialize() и release()


Следующие методы делают возможным обслуживание вложенных JspWriter-потоков через реализацию Tag Extensions/Расширений Тэгов: pushBody() и popBody()


Методы, Предназначенные для Авторов JSP
 

Некоторые методы предоставляют универсальный доступ к различным объектам, представляющим области видимости/scopes. Реализация обязана использовать основные механизмы Servlet, соответствующие данной области видимости/scope, чтобы информация могла передаваться туда и обратно между Сервлетами и JSP-страницами.

Это методы: setAttribute(), getAttribute(), find-Attribute(), removeAttribute(), getAttributesScope() и getAttributeNamesIn-Scope().


Следующие методы предоставляют удобный доступ к неявным/implicit объектам: getOut(), getException(), getPage() getRequest(), getResponse(), getSession(), getServlet-Config() и getServletContext().


Следующие методы предоставляют поддержку перенаправления/forwarding, включения в/inclusion и обработки ошибок: forward(), include()  handlePageException().

JSP.9.2.1.7 Поля
 

public static final java.lang.String APPLICATION

Имя используется в для хранения ServletContext в таблице имён PageContext.


public static final int APPLICATION_SCOPE

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


public static final java.lang.String CONFIG

Имя используется для хранения ServletConfig в таблице имён PageContext.


public static final java.lang.String EXCEPTION

Имя используется для хранения неотловленного исключения в списке атрибутов ServletRequest и в таблице имён PageContext.


public static final java.lang.String OUT

Имя используется для хранения текущего JspWriter в таблице имён PageContext.


public static final java.lang.String PAGE

Имя используется для хранения Сервлета в таблицах имён данного PageContext.


public static final int PAGE_SCOPE

Область видимости: (по умолчанию) именованные ссылки остаются видимыми в данном PageContext до возврата из текущего вызова Servlet.service().


public static final java.lang.String PAGECONTEXT

Имя используется для хранения этого PageContext в его собственной таблице имён.


public static final java.lang.String REQUEST

Имя используется для хранения ServletRequest в таблице имён PageContext.


public static final int REQUEST_SCOPE

Область видимости: именованные ссылки остаются доступными из Servlet-Request, ассоциированного с Сервлетом, до завершения текущего запроса.


public static final java.lang.String RESPONSE

Имя используется для хранения ServletResponse в таблице имён PageContext.


public static final java.lang.String SESSION

Имя используется для хранения HttpSession в таблице имён PageContext.


public static final int SESSION_SCOPE

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

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

public PageContext()

JSP.9.2.1.9 Методы
 

public abstract java.lang.Object findAttribute(java.lang.String name)

Ищет именованные атрибуты на странице, в запросе/request, сессии/session (если запущена) и области(-ях) видимости приложения, чтобы возвратить ассоциированные значения или null.
 

Возвращает: ассоциированное значение или null.


public abstract void forward(java.lang.String relativeUrlPath)

Этот метод используется для "направления" или перенаправления текущих ServletRequest и ServletResponse другому активному компоненту приложения.


Если relativeUrlPath начинается с "/", тогда специфицированный URL вычисляется относительно DOCROOT ServletContext'а для данной JSP. Если путь не начинается с "/", тогда специфицированный URL вычисляется относительно URL запроса, который был отображён в вызывающую JSP.


Верен только для вызова этого метода из выполнения Thread/Потока в методе _jsp-Service(...)JSP.


Если этот метод был успешно вызван, вызывающему Thread не разрешается модификация объекта ServletResponse. Любая попытка сделать это даёт непредсказуемый результат. Обычно вызывающий объект сразу же возвращается из _jspService(...) после вызова этого метода.


Параметры:


relativeUrlPath - специфицирует относительный путь URL к целевому ресурсу, как рассмотрено выше.


Вызывает:
 

ServletException, IOException

IllegalArgumentException - если URL целевого ресурса не может быть разрешён/высчитан.

IllegalStateException - если ServletResponse не в том состоянии, чтобы выполнить forward/направление.

SecurityException - если вызывающий не может получить доступ к целевому ресурсу.


public abstract java.lang.Object getAttribute(java.lang.String name)

Возвращает объект, ассоциированный с именем в области видимости страницы, или null, если объект не найден.


Параметры:


name - имя атрибута для получения.


Вызывает:


NullPointerException - если имя - null.

IllegalArgumentException - если область видимости неверна.


public abstract java.lang.Object getAttribute(java.lang.String name, int scope)

Возвращает объект, ассоциированный с именем в специфицированной области видимости, или null, если объект не найден.


Параметры:


name - имя атрибута для установки.


scope - область видимости, с которой ассоциировать имя/объект.


Вызывает:


NullPointerException - если имя - null.

IllegalArgumentException - если область видимости неверна.


public abstract java.util.Enumeration getAttributeNamesInScope(int scope)

Перечисляет все атрибуты в данной области видимости.


Возвращает: перечисление имён (java.lang.String) всех атрибутов специфицированной области видимости.


public abstract int getAttributesScope(java.lang.String name)

Получает область видимости, в которой определён данный атрибут.


Возвращает: область видимости объекта, ассоциированного со специфицированным именем, или 0.


public abstract java.lang.Exception getException()

Текущее значение объекта exception (Exception).


Возвращает: любое исключение, переданное ему как errorpage.


public abstract JspWriter getOut()

Текущее значение объекта вывода/out (JspWriter).


Возвращает: поток текущего JspWriter, используемый для ответа клиенту.


public abstract java.lang.Object getPage()

Значение объекта страницы/page (Servlet).


Возвращает: экземпляр класса реализации (Servlet), ассоциированный с этим PageContext.


public abstract javax.servlet.ServletRequest getRequest()
Текущее значение объекта request (ServletRequest).


Возвращает: ServletRequest для данного PageContext.


public abstract javax.servlet.ServletResponse getResponse()

Текущее значение объекта response (ServletResponse).


Возвращает: ServletResponse для данного PageContext.


public abstract javax.servlet.ServletConfig getServletConfig()

Экземпляр ServletConfig.


Возвращает: ServletConfig для данного PageContext.


public abstract javax.servlet.ServletContext getServletContext()

Экземпляр ServletContext.


Возвращает: ServletContext для данного PageContext.


public abstract javax.servlet.http.HttpSession getSession()

Текущее значение объекта session (HttpSession).


Возвращает: HttpSession для данного PageContextили null.


public abstract void handlePageException(java.lang.Exception e)

Этот метод предназначен для обработки необработанных исключений уровня "page" путём перенаправления исключения специализированной для данной JSP странице ошибок/error page, или, если ничего не специфицировано, для выполнения акции, определяемой реализацией.


Класс реализации JSP обычно будет очищать локальный статус до вызова этого метода и будет возвращать сразу после этого. Не разрешается генерировать какой-либо вывод клиенту или модифицировать любой статус ServletResponse после этого вызова.


Этот метод сохранён для обеспечения обратной совместимости. Вновь генерируемый код должен использовать PageContext.handlePageException(Throwable).


Параметры:


e - обрабатываемое исключение.


Вызывает:


ServletException, IOException

NullPointerException - если исключение - null.

SecurityException - если вызывающий не может достичь целевого ресурса.


См. Также: public abstract void handlePageException(java.lang.Throwable t)


public abstract void handlePageException(java.lang.Throwable t)

Этот метод идентичен handlePageException(Exception), за исключением того, что он принимает Throwable. Это предпочтительный метод, так как он даёт возможность правильной реализации семантики errorpage.


Этот метод предназначен для обработки необработанных исключений уровня "page" путём перенаправления исключения специализированной для данной JSP странице ошибок/error page, или, если ничего не специфицировано, для выполнения акции, определяемой реализацией.


Класс реализации JSP обычно будет очищать локальный статус до вызова этого метода и будет возвращать сразу после этого. Не разрешается генерировать какой-либо вывод клиенту или модифицировать любой статус ServletResponse после этого вызова.


Параметры:


t - обрабатываемый throwable.


Вызывает:


ServletException, IOException

NullPointerException - если исключение - null.

SecurityException - если вызывающий не может достичь целевого ресурса.


См. Также: public abstract void handlePageException(java.lang.Exception e)


public abstract void include(java.lang.String relativeUrlPath)

Вызывает обработку ресурса, специфицированного для обработки как часть текущих Servlet-Request и ServletResponse, в вызывающем Thread. Вывод обработки целевых ресурсов запроса записывается непосредственно в поток вывода ServletResponse.


Текущий JspWriter "out" для данной JSP очищается - как побочный эффект этого вызова - до обработки include.


Если relativeUrlPath начинается с "/", тогда специфицированный URL вычисляется относительно DOCROOT ServletContext'а для данной JSP. Если путь не начинается с "/", тогда специфицированный URL вычисляется относительно URL запроса, который был отображён в вызывающую JSP. Верным является только вызов этого метода из выполнения Thread в методе _jsp-Service(...) JSP.


Параметры:


relativeUrlPath - специфицирует относительный путь-URL к включаемому целевому ресурсу.


Вызывает:


ServletException, IOException

IllegalArgumentException - если URL целевого ресурса не может быть разрешён.

SecurityException - если вызывающий не может достичь целевого ресурса.


public abstract void initialize(javax.servlet.Servlet servlet, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String errorPageURL, boolean needsSession, int bufferSize, boolean autoFlush)

Метод initialize вызывается для инициализации неинициализированного PageContext, чтобы он мог быть использован классом реализации JSP для обслуживания входящих запросов и для ответов в его методе _jspService().


Этот метод обычно вызывается из JspFactory.getPageContext() для инициализации статуса.
 

Этот метод необходим для создания начального JspWriter и ассоциирования имени "out" в области видимости страницы с этим вновь созданным объектом.


Этот метод не должен использоваться авторами страниц или библиотек тэгов.


Параметры:


servlet - Servlet, ассоциированный с данным PageContext.

request - текущий рассматриваемый запрос для данного Servlet.

response - текущий рассматриваемый ответ для данного Servlet.

errorPageURL - значение атрибута errorpage в директиве page, или null.

needsSession - значение атрибута session директивы page.

bufferSize - значение атрибута buffer директивы page.

autoFlush - значение атрибута autoflush директивы page.


Вызывает:


IOException - во время создания JspWriter.

IllegalStateException - если некорректно инициализирован.

IllegalArgumentException


public JspWriter popBody()

Возвращает предыдущий JspWriter "out", сохранённый совпадающим pushBody(), и обновляет значение атрибута "out" в пространстве имён атрибута страницы scope в PageConxtext.


Возвращает: сохранённый JspWriter.


public BodyContent pushBody()

Возвращает новый объект BodyContent, сохраняет текущий "out" JspWriter и обновляет значение атрибута "out" в пространстве имён атрибута страницы scope в PageContext.


Возвращает: новый BodyContent.


public abstract void release()

Этот метод должен "reset/восстанавливать" внутренний статус PageContext, освобождая все внутренние ссылки и подготавливая PageCont для возможного использования последующим вызовом initialize(). Этот метод обычно вызывается из Jsp-Factory.releasePageContext().


Подклассы будут окружать/envelop этот метод.


Этот метод не должен использоваться авторами страниц или библиотек тэгов.


public abstract void removeAttribute(java.lang.String name)

Удаляет ссылку на объект, ассоциированную с данным именем, просматривает во всех scope в порядке scope.


Параметры:


name - имя удаляемого объекта.


public abstract void removeAttribute(java.lang.String name, int scope)

Удаляет ссылку на объект, ассоциированную с данным именем, в данной области видимости.


Параметры:


name - имя удаляемого объекта.

scope - область видимости, где идёт просмотр.


public abstract void setAttribute(java.lang.String name, java.lang.Object attribute)

Регистрирует имя и объект, специфицированные с семантикой области видимости страницы.


Параметры:


name - имя устанавливаемого атрибута.

attribute - объект для ассоциирования с этим именем.


Вызывает:


NullPointerException - если name или object - null.


public abstract void setAttribute(java.lang.String name, java.lang.Object o, int scope)

Регистрирует имя и объект, специфицированные с семантикой соответствующей области видимости.


Параметры:


name - имя устанавливаемого атрибута.

o - объект для ассоциирования с этим именем.

scope - область видимости, с которой ассоциируется name/object.


Вызывает:


NullPointerException - если name или object- null.

IllegalArgumentException - если область видимости неверна.

JSP.9.2.2 JspWriter

Синтаксис
 


public abstract class JspWriter extends java.io.Writer


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


Описание


Акции и шаблонные данные JSP-страницы записываются с использованием объекта JspWriter, на который ссылаются через неявную переменную out, которая инициализируется автоматически при использовании методов в объекте PageContext.


Этот абстрактный класс эмулирует некоторую функциональность классов java.io.BufferedWriter и java.io.PrintWriter, однако он отличается тем, что вызывает java.io.IOException из методов print, в то время как PrintWriter этого не делает.


Буферизация


Начальный объект JspWriter ассоциируется с объектом PrintWriter в ServletResponse способом, зависящим от того, буферизуется страница, или нет.

Если страница не буферизуется, вывод, записываемый в этот объект JspWriter, будет записан непосредственно через PrintWriter, который будет создан, если необходимо, путём вызова метода getWriter() в объекте response.

Но если страница буферизуется, объект PrintWriter не будет создан, пока буфер не будет очищен, и операции типа setContentType() также будут разрешены. Поскольку такая гибкость частично облегчает программирование, буферизация JSP-страниц выполняется по умолчанию.


Буферизация поднимает вопрос: что делать, если буфер исчерпан/переполнен?

Можно использовать два подхода:

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

В общем, JSP-страницы, которым необходимо удостовериться в корректности и полноте высылаемых клиентам данных, могут установить атрибут autoFlush в false, что типично для случая, когда клиентом является само приложение. С другой стороны, JSP-страницы, высылающие данные, что имеет место даже если они сконструированы только частично, могут "захотеть" установить autoFlush в true; как если бы данные высылались для немедленного просмотра в браузере. Каждое приложение должно учитывать свои специфические потребности.


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


Неявная переменная "out" класса реализации JSP имеет этот тип. Если директива page выбирает autoflush="true", то все операции ввода/вывода (I/O) этого класса будут автоматически очищать содержимое буфера, если условие overflow/переполнения будет достигнуто при выполнении текущей операции без очистки.

Если autoflush="false", все операции ввода/вывода (I/O) этого класса будут должны вызывать IOException, если выполнение текущей операции будет давать выполнение условия переполнения буфера.


См. Также: java.io.Writer, java.io.BufferedWriter, java.io.PrintWriter

JSP.9.2.2.10 Поля
 

protected boolean autoFlush


protected int bufferSize


public static final int DEFAULT_BUFFER
 константа, обозначающая, что Writer буферизуется и использует размер буфера по умолчанию для данной реализации.


public static final int NO_BUFFER
 константа, обозначающая, что Writer не буферизует вывод.


public static final int UNBOUNDED_BUFFER
 константа, обозначающая, что Writer буферизуется и не лимитирован; это используется в BodyContent.


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

protected JspWriter(int bufferSize, boolean autoFlush)
  protected-конструктор.


JSP.9.2.2.12 Методы
 

public abstract void clear()


Очищает содержимое буфера. Если буфер уже был очищен, тогда операция clear должна вызывать IOException, сигнализируя, что некоторые данные уже безвозвратно записаны в поток вывода клиенту.


Вызывает: IOException - если возникает ошибка I/O.


public abstract void clearBuffer()

Очищает текущее содержимое буфера. В отличие от clear(), этот метод не вызывает IOExceptio, если буфер уже был очищен. Он лишь очищает текущее содержимое буфера и возвращает управление.


Вызывает: IOException - если возникает ошибка I/O.


public abstract void close()

Закрывает поток, предварительно очищая его. Этот метод не должен вызываться явно для начального JspWriter, так как код, генерируемый JSP-контейнером, будет автоматически включать вызов close().


Закрытие ранее уже закрытого потока, в отличие от flush(), не имеет эффекта.


Переопределяет: java.io.Writer.close() в классе java.io.Writer.


Вызывает: IOException - если возникает ошибка I/O.


public abstract void flush()

Очищает поток. Если поток сохранил какие-либо символы из различных методов write() в буфере, записывает их непосредственно по назначению. Затем, если назначением является другой поток символов или байтов, очищает их. Таким образом, один вызов flush очистит все буферы в цепи из Writers и OutputStreams.

Этот метод может быть вызван неявно, если ёмкость буфера исчерпана. Если поток был уже закрыт, дальнейшие вызовы write( или flush() вызовут IOException.


Переопределяет: java.io.Writer.flush() в классе java.io.Writer.

Вызывает: IOException - если возникает ошибка I/O.


public int getBufferSize()

Этот метод возвращает размер буфера, используемого JspWriter.


Возвращает: размер буфера в байтах, или 0 - если не буферизован.


public abstract int getRemaining()

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


Возвращает: количество неиспользованных байтов в буфере.


public boolean isAutoFlush()

Этот метод сообщает, является ли JspWriter autoFlushing (очищается ли автоматически).


Возвращает: очищается ли данный JspWriter автоматически, или вызывает IOExceptions при достижении переполнения буфера.


public abstract void newLine()

Записывает символы новой строки. Строка - разделитель строк - определяется системным свойством line.separator, и это не обязательно просто символ новой строки ('\n').


Вызывает:


IOException - если возникает ошибка ввода/вывода.


public abstract void print(boolean b)

Печатает булево значение. Строка произведённая java.lang.String.valueOf(boolean), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


b - печатаемый булев параметр.


Вызывает: java.io.IOException


public abstract void print(char c)

Печатает символ. Этот символ транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


c - печатаемый char.


Вызывает: java.io.IOException


public abstract void print(char[] s)

Печатает массив символов. Символы конвертируются в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


s - массив печатаемых chars.


Вызывает:


NullPointerException -если s - null.

java.io.IOException


public abstract void print(double d)

Печатает число с плавающей точкой двойной точности. Строка, производимая java.lang.String.valueOf(double), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


d- печатаемое double.


Вызывает: java.io.IOException


См. Также: java.lang.Double


public abstract void print(float f)

Печатает число с плавающей точкой. Строка, производимая java.lang.String.valueOf(float), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


f - печатаемое float.


Вызывает: java.io.IOException


См. Также: java.lang.Float


public abstract void print(int i)

Печатает целое число. Строка, производимая java.lang.String.valueOf(int), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


i - печатаемое int.


Вызывает: java.io.IOException


См. Также: java.lang.Integer


public abstract void print(long l)

Печатает длинное целое. Строка, производимая java.lang.String.valueOf(long), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


l - печатаемое long.


Вызывает: java.io.IOException


См. Также: java.lang.Long


public abstract void print(java.lang.Object obj)

Печатает объект. Строка, производимая методом java.lang.String.valueOf(Object), транслируется в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


obj - печатаемый Object.


Вызывает: java.io.IOException


См. Также: java.lang.Object.toString()


public abstract void print(java.lang.String s)

Печатает строку. Если аргумент - null, тогда печатается строка "null". Иначе символы строки конвертируются в байты в соответствии с кодировкой символов по умолчанию данной платформы, и эти байты записываются точно в манере метода java.io.Writer.write(int).


Параметры:


s - печатаемая String.


Вызывает: java.io.IOException


public abstract void println()

Обрывает текущую строку, печатая строку разделителя строк. Строка разделителя строк определяется системным свойством line.separator, и это не обязательно одиночный символ новой строки ('\n').


Вызывает: java.io.IOException


public abstract void println(boolean x)

Печатает булево значение и затем заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(boolean b), а затем - public abstract void println().


Вызывает: java.io.IOException


public abstract void println(char x)

Печатает символ и затем заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(char c), а затем - public abstract void println().


Вызывает: java.io.IOException


public abstract void println(char[] x)

Печатает массив символов и затем заканчивает строку. Это метод ведёт себя так, будто он вызывает  print(char[]) и затем println().


Вызывает: java.io.IOException


public abstract void println(double x)

Печатает число двойной точности с плавающей точкой и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(double d) и затем public abstract void println().


Вызывает: java.io.IOException


public abstract void println(float x)

Печатает число с плавающей точкой и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(float f) и затем public abstract void println().


Вызывает: java.io.IOException


public abstract void println(int x)

Печатает целое число и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(int i) и затем public abstract void println().


Вызывает: java.io.IOException


public abstract void println(long x)

Печатает длинное целое и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(long l) и затем public abstract void println().


Вызывает: java.io.IOException


public abstract void println(java.lang.Object x)

Печатает Object и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(java.lang.Object obj) и затем public abstract void println().


Вызывает: java.io.IOException


public abstract void println(java.lang.String x)

Печатает String и заканчивает строку. Это метод ведёт себя так, будто он вызывает public abstract void print(java.lang.String s) и затем public abstract void println().


Вызывает: java.io.IOException

JSP.9.3  Пример Реализации

Экземпляр зависящего от реализации подкласса этого абстрактного базового класса может быть создан классом реализации JSP в начале её метода _jspService() через JspFactory по умолчанию для данной реализации.


Вот пример использования этих классов:


public class foo implements Servlet {

// ...

public void _jspService(HttpServletRequest request, HttpServletResponse response)

throws IOException, ServletException {

JspFactory factory = JspFactory.getDefaultFactory();

PageContext pageContext = factory.getPageContext(

this,

request,

response,

null, // errorPageURL

false, // needsSession

JspWriter.DEFAULT_BUFFER,

true // autoFlush

);

// инициализируются неявные переменные среды скриптинга ...

HttpSession session = pageContext.getSession();

JspWriter out = pageContext.getOut();

Object page = this;

try {

// здесь тело транслированной JSP ...

} catch (Exception e) {

out.clear();

pageContext.handlePageException(e);

} finally {

out.close();

factory.releasePageContext(pageContext);

}

}

JSP.9.4  Исключения

Класс JspException является базовым классом для всех JSP-исключений. JspTag-Exception используется механизмом исключения тэга.

JSP.9.4.1 JspException

Синтаксис
 

public class JspException extends java.lang.Exception


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


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


Описание


Родовое исключение, известное JSP-машине; неотловленное JspExceptions даст вызов механизма errorpage.

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

public JspException()

Конструирует JspException.


public JspException(java.lang.String msg)

Конструирует новое JSP-исключение со специфицированным сообщением. Сообщение может быть записано в server log-файл и/или выводится пользователю.


Параметры:


msg - String, специфицирующая текст сообщения об исключении.


public JspException(java.lang.String message, java.lang.Throwable rootCause)

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


Параметры:


message - String, содержащая текст сообщения об исключении.

rootCause - исключение Throwable, нарушившее нормальную работу сервлета; делает это исключение сервлета необходимым.


public JspException(java.lang.Throwable rootCause)

Конструирует новое JSP-исключение, если JSP нужно вызвать исключение и вставить сообщение о "причине" исключения, помешавшего нормальному ходу операции. Сообщение об исключении базируется на локализованном сообщении об вызвавшем его исключении.


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


Параметры:


rootCause - исключение Throwable, нарушившее нормальную работу JSP-операции, ; делает это JSP-исключение необходимым.

JSP.9.4.1.14 Методы
 

public java.lang.Throwable getRootCause()

Возвращает исключение, вызвавшее это JSP-исключение.


Возвращает: Throwable, вызывавшее это JSP-исключение.

JSP.9.4.2 JspTagException

Синтаксис
 

public class JspTagException extends JspException


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


Описание


Исключение используется Tag Handler/Обработчиком Тэга для обозначения неисправимой ошибки. Эта ошибка отлавливается на верхнем уровне JSP-страницы и выдаёт страницу для ошибок/errorpage.

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

public JspTagException()

Нет сообщения.


public JspTagException(java.lang.String msg)

Конструктор с сообщением...