Веб-приложения Java используют файл дескриптора развертывания для определения способа сопоставления URL с сервлетами, URL, для которых необходима аутентификация, и других сведений. Этот файл называется web.xml и находится в WAR приложения в каталоге WEB-INF/. web.xml является частью стандарта Servlet для веб-приложений.
Дополнительную информацию о стандарте web.xml см. в справочной вики Metawerx web.xml, справке по элементам WebLogic web.xmlи спецификации Servlet.
Дескриптор веб-приложения описывает классы, ресурсы и конфигурацию приложения, а также их использование веб-сервером для получения веб-запросов. При получении веб-сервером запроса для приложения он использует дескриптор развертывания, чтобы сопоставить URL запроса с кодом, который должен обработать запрос.
Дескриптор развертывания – это файл с названием web.xml. Он находится в WAR приложения в каталоге WEB-INF/. Это XML-файл, корневой элемент которого – <web-app>.
Ниже приведен простой пример web.xml, сопоставляющий все пути URL (/*) с классом сервлета mysite.server.ComingSoonServlet:
| 
<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
<servlet>
<servlet-name>comingsoon</servlet-name>
<servlet-class>mysite.server.ComingSoonServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>comingsoon</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
web.xml определяет сопоставления между путями URL и сервлетами, обрабатывающими запросы с этими путями. Веб-сервер использует эту конфигурацию для определения сервлета, который должен обрабатывать определенный запрос, и вызова метода класса, соответствующего методу запроса (например, метод doGet() для запросов HTTP GET).
Чтобы сопоставить URL сервлету, необходимо объявить сервлет с элементом <servlet>, а затем определить сопоставление пути URL к объявлению сервлета с элементом <servlet-mapping>.
Элемент <servlet> объявляет сервлет, включая имя для указания этого сервлета другими элементами файла, класс для использования с сервлетом и параметры инициализации. Можно объявить несколько сервлетов, используя один класс с разными параметрами инициализации. Имя каждого сервлета должно быть уникальным в дескрипторе развертывания.
<servlet>
<servlet-name>redteam</servlet-name>
<servlet-class>mysite.server.TeamServlet</servlet-class>
<init-param>
<param-name>teamColor</param-name>
<param-value>red</param-value>
</init-param>
<init-param>
<param-name>bgColor</param-name>
<param-value>#CC0000</param-value>
</init-param>
</servlet>
<servlet>
<servlet-name>blueteam</servlet-name>
<servlet-class>mysite.server.TeamServlet</servlet-class>
<init-param>
<param-name>teamColor</param-name>
<param-value>blue</param-value>
</init-param>
<init-param>
<param-name>bgColor</param-name>
<param-value>#0000CC</param-value>
</init-param>
</servlet>
Элемент <servlet-mapping> определяет схему URL и имя объявленного сервлета для использования с запросами, URL которых соответствует схеме. В схеме URL может использоваться звездочка (*) в начале или конце схемы для обозначения нуля или более любых символов. (Стандарт не поддерживает подстановочные знаки в середине строки, а также несколько подстановочных знаков в одной схеме.) Схема соответствует полному пути URL и начинается с символа косой черты (/), которая также указывается после имени домена.
<servlet-mapping>
<servlet-name>redteam</servlet-name>
<url-pattern>/red/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>blueteam</servlet-name>
<url-pattern>/blue/*</url-pattern>
</servlet-mapping>
В этом примере запрос URL http://www.example.com/blue/teamProfile обрабатывается классом TeamServlet с параметром teamColor равным blue и параметром bgColor равным #0000CC. Сервлет может получить часть пути URL, соответствующую подстановочному символу, используя метод getPathInfo() объекта ServletRequest.
Примечание. Статические файлы, файлы, передаваемые пользователям, такие как изображения, CSS и JavaScript, обрабатываются отдельно от путей, указанных в дескрипторе развертывания. Запрос пути URL, соответствующего пути к файлу в WAR, который считается статическим, получит файл независимо от сопоставлений сервлета и фильтра в дескрипторе развертывания. Можно исключить файлы из файлов, которые считаются статическими, с помощью файла appengine-web.xml.
Сервлет может получить параметры инициализации, получив конфигурацию сервлета, используя собственный метод getServletConfig(), затем вызвав метод getInitParameter() для объекта конфигурации, используя имя параметра в качестве аргумента.
String teamColor = getServletConfig().getInitParameter("teamColor");
Приложение может использовать JSP (JavaServer Pages) для реализации веб-страниц. JSP – это сервлеты, определенные с помощью статического содержания (такого как HTML) и кода Java.
App Engine поддерживает автоматическую компиляцию и сопоставление URL для JSP. Файл JSP в WAR приложения (внеWEB-INF/) имя которого заканчивается на .jsp, автоматически компилируется в сервлет и сопоставляется с путем URL, эквивалентным пути к файлу JSP в корне WAR. Например, если приложение имеет файл JSP с именем start.jsp в подкаталоге register/ в WAR, App Engine компилирует его и сопоставляет с путем URL /register/start.jsp.
При необходимости большего контроля над сопоставлением JSP с URL можно явно указать сопоставление путем его объявления с элементом <servlet> в дескрипторе развертывания. Вместо элемента <servlet-class> указывается элемент <jsp-file> с путем к файлу JSP из корня WAR. Элемент <servlet> для JSP может содержать параметры инициализации.
<servlet>
<servlet-name>register</servlet-name>
<jsp-file>register/start.jsp</jsp-file>
</servlet>
<servlet-mapping>
<servlet-name>register</servlet-name>
<url-pattern>/register/*</url-pattern>
</servlet-mapping>
Можно установить библиотеки тегов JSP с элементом <taglib>. Библиотека тегов имеет путь к файлу Tag Library Descriptor (TLD) JSP (<taglib-location>) и URI, который используют JSP для выбора библиотеки для загрузки (<taglib-uri>). Имейте в виду, что App Engine предоставляет JavaServer Pages Standard Tag Library (JSTL); ее установка не требуется.
<taglib>
<taglib-uri>/escape</taglib-uri>
<taglib-location>/WEB-INF/escape-tags.tld</taglib-location>
</taglib>
Приложение App Engine может использовать аккаунты Google для аутентификации пользователя. Приложение может использовать API аккаунтов Google для определения регистрации пользователя, получения адреса электронной почты текущего пользователя и создания URL входа и выхода. Приложение также может указать ограничения доступа для путей URL на основе аккаунтов, используя дескриптор развертывания.
Элемент <security-constraint> определяет ограничение безопасности для URL, соответствующих схеме. Если пользователь открывает URL, путь которого имеет ограничение безопасности, и пользователь не зарегистрирован, App Engine перенаправляет пользователя на страницу входа аккаунтов Google. После успешного входа или регистрации аккаунта аккаунты Google перенаправляют пользователя обратно к URL приложения. Приложению необходимо обеспечивать только доступ к URL только зарегистрированных пользователей.
Ограничение безопасности включает ограничение авторизации, указывающее пользователей аккаунтов Google, которым доступен путь. Если ограничение авторизации указывает роль пользователя *, URL доступен всем пользователям зарегистрированным пользователям аккаунтов Google. Если ограничение определяет роль пользователя admin, URL доступен только зарегистрированным разработчикам (администраторам). Роль admin упрощает создание разделов сайта только для администратора.
<security-constraint>
<web-resource-collection>
<url-pattern>/profile/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>*</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<url-pattern>/admin/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>admin</role-name>
</auth-constraint>
</security-constraint>
App Engine не поддерживает специальные роли безопасности (<security-role>) или альтернативные механизмы аутентификации (<login-config>) в дескрипторе развертывания.
Ограничения безопасности применяются к статическим файлам и сервлетам.
Google App Engine поддерживает безопасные подключения через HTTPS для URL-адресов, используя домен *.appspot.com. Когда запрос обращается к URL, используя HTTPS, данные запроса и ответа шифруются сервером перед передачей, и расшифровываются получателем после получения. Защищенные подключения полезны для защиты данных клиентов, таких как контактная информация, пароли и личные сообщения.
Примечание. Домены Служб Google в настоящий момент не поддерживают HTTPS. Поддержка HTTPS ограничена приложениями, доступ к которым осуществляется через домены *.appspot.com. Доступ к URL HTTPS на домене Служб Google вернет ошибку "узел не найден", а доступ к URL, обработчик которого принимает только HTTPS (см. ниже), через HTTP, вернет ошибку "HTTP 403 – запрещено". Можно создать ссылку на URL HTTPS с доменом *.appspot.com для функций безопасности и использовать домен Служб и HTTP для остальной части узла.
Для доступа к защищенным URL для приложения необходимо включить защищенные URL в файле appengine-web.xml приложения, используя элемент <ssl-enabeld>true</ssl-enabled>. Дополнительную информацию об этом файле см. в статье Конфигурация приложения: включение защищенных URL.
Для объявления использования HTTPS для URL можно настроить ограничение безопасности в дескрипторе развертывания (как описано в статье Безопасность и аутентификация) с <user-data-constraint>, для <transport-guarantee> которого установлено CONFIDENTIAL, следующим образом:
<security-constraint>
<web-resource-collection>
<url-pattern>/profile/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
Запросы, использующие HTTP (небезопасные) для URL, для гарантии транспорта которых установлено CONFIDENTIAL, автоматически перенаправляются этому же URL, используя HTTPS.
Безопасные подключения используют больше ресурсов процессора и трафика, чем небезопасные, и поэтому более затратны. Безопасные подключения медленнее небезопасных.
Все URL могут использовать гарантию транспорта CONFIDENTIAL, включая JSP и статические файлы.
Веб-сервер разработки не поддерживает HTTPS-соединения. Он игнорирует гарантию транспорта, поэтому пути, предназначенные для использования с HTTPS, могут быть протестированы с помощью обычного подключения HTTP к веб-серверу разработки.
При тестировании обработчиков HTTPS приложения с помощью URL appspot.com с контролем версий, например https://1.latest.app-id.appspot.com/, браузер выдаст предупреждение, что сертификат HTTPS не подписан для указанного пути домена. При принятии сертификата для этого домена страницы будут успешно загружены. Пользователи не будут видеть предупреждение сертификата при доступе к https://app-id.appspot.com/.
Входы и выходы в аккаунты Google всегда выполняются с помощью защищенного подключения независимо от настройки URL приложения.
Как указано выше, ограничения безопасности применяются к статическим файлам и сервлетам. Сюда входит и гарантия транспорта.
Если URL для сайта представляют пути к статическим файлам или JSP в WAR, часто бывает желательно, чтобы путь к каталогам также выполняли какие-либо функции. Пользователь, посещающий путь URL /help/accounts/password.jsp для получения сведения о паролях аккаунтов, также может посетить /help/accounts/, чтобы найти страницу с документацией к системе аккаунтов. Дескриптор развертывания может указывать список имен файлов, которые должен проверить сервер при доступе пользователя к пути, представляющему подкаталог WAR (которые не сопоставлен явно с сервлетом). В стандарте Servlet это называется "списком приветственных файлов".
Например, если пользователь обращается к пути URL /help/accounts/, следующий элемент <welcome-file-list> в дескрипторе развертывания указывает серверу на необходимость проверки help/accounts/index.jsp и help/accounts/index.html до сообщения о том, что этот URL не существует:
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
</welcome-file-list>
Фильтр – это класс, работающий с запросом как сервлет, но который может позволять обработку запроса для продолжения работы с другими фильтрами или сервлетами. Фильтр может выполнять дополнительные задачи, такие как регистрация, выполняя специальные проверки аутентификации или добавляя комментарии до вызова сервлета. Фильтры позволяют создавать задачи обработки запросов из дескриптора развертывания.
Класс фильтра реализует интерфейс javax.servlet.Filter, включая метод doFilter(). Ниже приведена простая реализация фильтра, регистрирующая сообщение и передающая управление по цепочке, которая может включать другие фильтры или сервлеты, как описано дескриптором развертывания:
package mysite.server;
import java.io.IOException;
import java.util.logging.Logger;
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
public class LogFilterImpl implements Filter {
private FilterConfig filterConfig;
private static final Logger log = Logger.getLogger(LogFilterImpl.class.getName());
public void doFilter(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain)
throws IOException, ServletException {
log.info("Log filter processed a " +
getServletConfig().getInitParameter("logType") +
" request");
filterConfig.doFilter(request, response);
}
public FilterConfig getFilterConfig() {
return filterConfig;
}
public void setFilterConfig(FilterConfig filterConfig) {
this.filterConfig = filterConfig;
}
}
Аналогично сервлетам, фильтр настраивается в дескрипторе развертывания путем объявления фильтра с элементом <filter> и последующим сопоставлением со схемой URL с элементом <filter-mapping>. Фильтры также можно сопоставить напрямую другим сервлетам.
Элемент <filter> содержит элементы <filter-name>, <filter-class> и дополнительный элемент <init-param>.
<filter>
<filter-name>logSpecial</filter-name>
<filter-class>mysite.server.LogFilterImpl</filter-class>
<init-param>
<param-name>logType</param-name>
<param-value>special</param-value>
</init-param>
</filter>
Элемент <filter-mapping> содержит <filter-name>, соответствующий имени объявленного фильтра и элемент <url-pattern> для применения фильтра к URL или элемент <servlet-name>, соответствующий имени объявленного сервлета, для применения фильтра при каждом вызове сервлета.
<!-- Log for all URLs ending in ".special" -->
<filter-mapping>
<filter-name>logSpecial</filter-name>
<url-pattern>*.special</url-pattern>
</filter-mapping>
<!-- Log for all URLs that use the "comingsoon" servlet -->
<filter-mapping>
<filter-name>logSpecial</filter-name>
<servlet-name>comingsoon</servlet-name>
</filter-mapping>
Можно настроить, что сервер отправляет пользователю при возникновении ошибки, используя дескриптор развертывания. Сервер может отобразить альтернативное местоположение страницы вместо отправки определенного HTTP-кода состояния или при создании сервлетом определенного исключения Java.
Элемент <error-page> содержит элемент <error-code> со значением HTTP-кода ошибки (такого как 500) или элемент <exception-type> с именем класса ожидаемого исключения (например, java.io.IOException). Он также включает элемент <location>, содержащий путь URL ресурса для отображения при возникновении ошибки.
<error-page>
<error-code>500</error-code>
<location>/errors/servererror.jsp</location>
</error-page>
Примечание. На момент написания статьи нельзя настроить специальные обработчики ошибок для определенных условий ошибки. В частности, нельзя настроить код ответа 404, если для URL не определено сопоставление сервлета; в таких случаях внутренняя ошибка App Engine вызывает страницу ошибки квоты 403 или ошибку сервера 500.
App Engine поддерживает элемент <load-on-startup> для объявлений сервлета. Однако нагрузка в действительности возникает во время первого запроса, обрабатываемого экземпляром веб-сервера, а не до него.
App Engine поддерживает элементы <mime-mapping> для указания типа MIME, который должен использоваться для ресурсов, имена файлов которых имеют определенные расширения. Однако сопоставления MIME применяются только к сервлетам; они не применяются для статических файлов. Статические файлы используют фиксированный список сопоставлений расширений имен файлов с типами MIME.
Некоторые элементы дескриптора развертывания могут принимать отображаемое имя в формате для чтения, описание и значок для использования в IDE. App Engine не использует и игнорирует их.
App Engine не поддерживает переменные среды JNDI (<env-entry>).
App Engine не поддерживает ресурсы EJB (<resource-ref>).
Элемент <distributable> игнорируется.
Назначение сервлета с помощью <run-at> не поддерживается.