El archivo web.xml solo se usa al desplegar una aplicación Java en un entorno de ejecución que incluye el servidor Eclipse Jetty 9/ servlet 3. Para obtener más información, consulta Eclipse Jetty 9.3 Runtime.
Las aplicaciones web Java usan un archivo de descriptor de despliegue para determinar cómo se asignan las URLs a los servlets, qué URLs requieren autenticación y otra información. Este archivo se llama web.xml y se encuentra en el archivo WAR de la aplicación, en el directorio WEB-INF/.
web.xml forma parte del estándar de servlets para aplicaciones web.
Para obtener más información sobre el estándar web.xml, consulta la especificación de servlet.
Acerca de los descriptores de implementación
El descriptor de implementación de una aplicación web describe las clases, los recursos y la configuración de la aplicación, así como la forma en que el servidor web los usa para atender las solicitudes web. Cuando el servidor web recibe una solicitud para la aplicación, usa el descriptor de implementación para asignar la URL de la solicitud al código que debe gestionar la solicitud.
El descriptor de implementación es un archivo llamado web.xml. Se encuentra en el archivo WAR de la aplicación, en el directorio WEB-INF/. El archivo es un archivo XML cuyo elemento raíz es <web-app>.
Aquí tienes un ejemplo sencillo de web.xml que asigna todas las rutas de URL (/*) al servlet
class =mysite.server.ComingSoonServlet:
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
<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>
Servlets y rutas de URL
web.xml define las asignaciones entre las rutas de URL y los servlets que gestionan las solicitudes con esas rutas. El servidor web usa esta configuración para identificar el servlet que debe gestionar una solicitud determinada y llamar al método de clase que corresponde al método de solicitud (por ejemplo, el método doGet() para las solicitudes HTTP GET).
Para asignar una URL a un servlet, declara el servlet con el elemento <servlet> y, a continuación, define una asignación de una ruta de URL a una declaración de servlet con el elemento <servlet-mapping>.
El elemento <servlet> declara el servlet, incluido un nombre que se usa para hacer referencia al servlet por otros elementos del archivo, la clase que se va a usar para el servlet y los parámetros de inicialización. Puede declarar varios servlets usando la misma clase con diferentes parámetros de inicialización. El nombre de cada servlet debe ser único en el descriptor de despliegue.
<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>
El elemento <servlet-mapping> especifica un patrón de URL y el nombre de un servlet declarado que se usará en las solicitudes cuya URL coincida con el patrón. El patrón de URL puede usar un asterisco (*) al principio o al final del patrón para indicar cero o más caracteres de cualquier tipo. El estándar no admite comodines en medio de una cadena ni permite varios comodines en un patrón. El patrón coincide con la ruta completa de la URL, empezando por la barra diagonal (/) que va después del nombre de dominio y que también se incluye.
<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>
En este ejemplo, la solicitud de la URL http://www.example.com/blue/teamProfile se gestiona mediante la clase TeamServlet, con el parámetro teamColor igual a blue y el parámetro bgColor igual a #0000CC. El servlet puede obtener la parte de la ruta de la URL que coincide con el comodín mediante el método getPathInfo() del objeto ServletRequest.
El servlet puede acceder a sus parámetros de inicialización obteniendo su configuración de servlet mediante su propio método getServletConfig() y, a continuación, llamando al método getInitParameter() en el objeto de configuración con el nombre del parámetro como argumento.
String teamColor = getServletConfig().getInitParameter("teamColor");
Páginas JSP
Una aplicación puede utilizar la tecnología JavaServer Pages (JSP) para implementar las páginas web. Los JSPs son servlets definidos mediante contenido estático (como HTML) combinado con código Java.
En el caso de las páginas JSP, App Engine admite tanto la compilación automática como la asignación de direcciones URL. Un archivo JSP en el archivo WAR de la aplicación (fuera de WEB-INF/) cuyo nombre de archivo termina en .jsp se compila automáticamente en una clase de servlet y se asigna a la ruta de URL equivalente a la ruta del archivo JSP desde la raíz del archivo WAR. Por ejemplo, si una aplicación tiene un archivo JSP llamado start.jsp en un subdirectorio llamado register/ en su archivo WAR, App Engine lo compila y lo asigna a la ruta de URL /register/start.jsp.
Si quieres tener más control sobre cómo se asigna el JSP a una URL, puedes especificar la asignación explícitamente declarándola con un elemento <servlet> en el descriptor de implementación. En lugar de un elemento <servlet-class>, especifica un elemento <jsp-file> con la ruta al archivo JSP desde la raíz del archivo WAR. El elemento <servlet> del JSP puede contener parámetros de inicialización.
<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>
Puedes instalar bibliotecas de etiquetas JSP con el elemento <taglib>. Una biblioteca de etiquetas tiene una ruta al archivo de descriptor de biblioteca de etiquetas JSP (TLD) (<taglib-location>) y un URI que usan los JSP para seleccionar la biblioteca que se va a cargar (<taglib-uri>). Ten en cuenta que App Engine proporciona la biblioteca de etiquetas estándar de JavaServer Pages (JSTL) y no es necesario que la instales.
<taglib>
<taglib-uri>/escape</taglib-uri>
<taglib-location>/WEB-INF/escape-tags.tld</taglib-location>
</taglib>
La lista de archivos de bienvenida
Cuando las URLs de su sitio representan rutas a archivos estáticos o JSPs de su archivo WAR, a menudo es una buena idea que las rutas a directorios también hagan algo útil.
Un usuario que visite la ruta de URL /help/accounts/password.jsp para obtener información sobre las contraseñas de las cuentas puede intentar visitar /help/accounts/ para encontrar una página que presente la documentación del sistema de cuentas. El descriptor de implementación puede especificar una lista de nombres de archivo que el servidor debe probar cuando el usuario acceda a una ruta que represente un subdirectorio WAR (que aún no se haya asignado explícitamente a un servlet). El estándar de servlet lo denomina "lista de archivos de bienvenida".
Por ejemplo, si el usuario accede a la ruta de URL /help/accounts/, el siguiente elemento <welcome-file-list> del descriptor de implementación indica al servidor que compruebe help/accounts/index.jsp y help/accounts/index.html antes de informar de que la URL no existe:
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
</welcome-file-list>
Filtros
Un filtro es una clase que actúa en una solicitud como un servlet, pero puede permitir que la solicitud se siga procesando con otros filtros o servlets. Un filtro puede realizar una tarea auxiliar, como registrar, llevar a cabo comprobaciones de autenticación especializadas o anotar los objetos de solicitud o respuesta antes de llamar al servlet. Los filtros le permiten componer tareas de procesamiento de solicitudes a partir del descriptor de implementación.
Una clase de filtro implementa la interfaz javax.servlet.Filter, incluido el método doFilter(). A continuación, se muestra una implementación de filtro sencilla que registra un mensaje y pasa el control a la cadena, que puede incluir otros filtros o un servlet, tal como se describe en el descriptor de implementación:
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.ServletRequest;
import javax.servlet.ServletResponse;
public class LogFilterImpl implements Filter {
private FilterConfig filterConfig;
private static final Logger log = Logger.getLogger(LogFilterImpl.class.getName());
public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
throws IOException, ServletException {
log.warning("Log filter processed a " + getFilterConfig().getInitParameter("logType")
+ " request");
filterChain.doFilter(request, response);
}
public FilterConfig getFilterConfig() {
return filterConfig;
}
public void init(FilterConfig filterConfig) {
this.filterConfig = filterConfig;
}
public void destroy() {}
}
Al igual que los servlets, los filtros se configuran en el descriptor de implementación. Para ello, se declara el filtro con el elemento <filter> y, a continuación, se asigna a un patrón de URL con el elemento <filter-mapping>. También puedes asignar filtros directamente
a otros servlets.
El elemento <filter> contiene elementos <filter-name>, <filter-class> y <init-param> opcionales.
<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>
El elemento <filter-mapping> contiene un <filter-name> que coincide con el nombre de un filtro declarado y un elemento <url-pattern> para aplicar el filtro a las URLs o un elemento <servlet-name> que coincide con el nombre de un servlet declarado para aplicar el filtro cada vez que se llama al servlet.
<!-- 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>
Controladores de error
Puedes personalizar lo que el servidor envía al usuario cuando se produce un error mediante el descriptor de implementación. El servidor puede mostrar una ubicación de página alternativa cuando esté a punto de enviar un código de estado HTTP concreto o cuando un servlet genere una excepción de Java concreta.
El elemento <error-page> contiene un elemento <error-code> con un valor de código de error HTTP (como 500) o un elemento <exception-type> con el nombre de clase de la excepción esperada (como java.io.IOException). También contiene un elemento <location> que incluye la ruta de la URL del recurso que se debe mostrar cuando se produzca el error.
<error-page>
<error-code>500</error-code>
<location>/errors/servererror.jsp</location>
</error-page>
Funciones de web.xml no admitidas
Las siguientes funciones de web.xml no son compatibles con App Engine:
- App Engine admite el elemento
<load-on-startup>para las declaraciones de servlet. Sin embargo, la carga se produce durante la primera solicitud gestionada por la instancia del servidor web, no antes. - Algunos elementos del descriptor de implementación pueden tener un nombre visible, una descripción y un icono legibles por humanos para usarlos en IDEs. App Engine no las usa y las ignora.
- App Engine no admite variables de entorno JNDI
(
<env-entry>). - App Engine no admite recursos EJB (
<resource-ref>). - No se admite la notificación de la destrucción de servlets, contextos de servlet o filtros.
- El elemento
<distributable>se ignora. - No se admite la programación de servlets con
<run-at>. - No se admiten restricciones de seguridad. Para obtener una función equivalente, consulta Autenticarse en servicios de Cloud mediante bibliotecas de cliente.
- CONFIDENTIAL no se admite en
web.xml.