Configurar o descritor de implementação web.xml

O ficheiro web.xml só é usado quando implementa uma app Java num motor de execução que inclui o servidor Eclipse Jetty 9/ servlet 3. Para mais detalhes, consulte o tempo de execução do Eclipse Jetty 9.3.

As aplicações Web Java usam um ficheiro de descritor de implementação para determinar como os URLs são mapeados para servlets, que URLs requerem autenticação e outras informações. Este ficheiro tem o nome web.xml e reside no WAR da app no diretório WEB-INF/. O web.xml faz parte da norma de servlet para aplicações Web.

Para mais informações sobre a norma web.xml, consulte a especificação de servlet.

Acerca dos descritores de implementação

O descritor de implementação de uma aplicação Web descreve as classes, os recursos e a configuração da aplicação, bem como a forma como o servidor Web os usa para publicar pedidos Web. Quando o servidor Web recebe um pedido para a aplicação, usa o descritor de implementação para mapear o URL do pedido para o código que deve processar o pedido.

O descritor de implementação é um ficheiro denominado web.xml. Está localizado no WAR da app no diretório WEB-INF/. O ficheiro é um ficheiro XML cujo elemento raíz é <web-app>.

Segue-se um exemplo simples de web.xml que mapeia todos os caminhos de URL (/*) para a classe de servlet =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 e caminhos de URLs

web.xml define mapeamentos entre caminhos de URL e os servlets que processam pedidos com esses caminhos. O servidor Web usa esta configuração para identificar o servlet para processar um determinado pedido e chamar o método de classe que corresponde ao método de pedido (por exemplo, o método doGet() para pedidos HTTP GET).

Para mapear um URL para um servlet, declara o servlet com o elemento <servlet> e, em seguida, define um mapeamento de um caminho do URL para uma declaração de servlet com o elemento <servlet-mapping>.

O elemento <servlet> declara o servlet, incluindo um nome usado para se referir ao servlet por outros elementos no ficheiro, a classe a usar para o servlet e parâmetros de inicialização. Pode declarar vários servlets usando a mesma classe com diferentes parâmetros de inicialização. O nome de cada servlet tem de ser exclusivo no descritor de implementação.

    <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>

O elemento <servlet-mapping> especifica um padrão de URL e o nome de um servlet declarado a usar para pedidos cujo URL corresponda ao padrão. O padrão de URL pode usar um asterisco (*) no início ou no fim do padrão para indicar zero ou mais de qualquer caráter. A norma não suporta carateres universais no meio de uma string e não permite vários carateres universais num padrão. O padrão corresponde ao caminho completo do URL, começando e incluindo a barra (/) a seguir ao nome do domínio.

    <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>

Com este exemplo, um pedido para o URL http://www.example.com/blue/teamProfile é processado pela classe TeamServlet, com o parâmetro teamColor igual a blue e o parâmetro bgColor igual a #0000CC. O servlet pode obter a parte do caminho do URL correspondente ao caráter universal através do método getPathInfo() do objeto ServletRequest.

O servlet pode aceder aos respetivos parâmetros de inicialização obtendo a respetiva configuração do servlet através do respetivo método getServletConfig() e, em seguida, chamando o método getInitParameter() no objeto de configuração com o nome do parâmetro como argumento.

        String teamColor = getServletConfig().getInitParameter("teamColor");

JSPs

Uma app pode usar páginas JavaServer (JSPs) para implementar páginas Web. Os JSPs são servlets definidos através de conteúdo estático (como HTML) misturado com código Java.

O App Engine suporta a compilação automática e o mapeamento de URLs para JSPs. Um ficheiro JSP no WAR da aplicação (fora de WEB-INF/) cujo nome de ficheiro termina em .jsp é compilado automaticamente numa classe de servlet e mapeado para o caminho do URL equivalente ao caminho para o ficheiro JSP a partir da raiz do WAR. Por exemplo, se uma app tiver um ficheiro JSP denominado start.jsp num subdiretório denominado register/ no respetivo WAR, o App Engine compila-o e mapeia-o para o caminho do URL /register/start.jsp.

Se quiser ter mais controlo sobre como a JSP é mapeada para um URL, pode especificar o mapeamento explicitamente declarando-o com um elemento <servlet> no descritor de implementação. Em vez de um elemento <servlet-class>, especifica um elemento <jsp-file> com o caminho para o ficheiro JSP a partir da raiz do WAR. O elemento <servlet> para o JSP pode conter parâmetros de inicialização.

    <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>

Nota: o <jsp-file> tem de começar com uma barra (/) se o JSP estiver no diretório raiz da aplicação.

Pode instalar bibliotecas de etiquetas JSP com o elemento <taglib>. Uma biblioteca de etiquetas tem um caminho para o ficheiro do descritor da biblioteca de etiquetas (TLD) do JSP (<taglib-location>) e um URI que os JSPs usam para selecionar a biblioteca para carregamento (<taglib-uri>). Tenha em atenção que o App Engine fornece a biblioteca de etiquetas padrão das páginas JavaServer (JSTL) e não precisa de a instalar.

    <taglib>
        <taglib-uri>/escape</taglib-uri>
        <taglib-location>/WEB-INF/escape-tags.tld</taglib-location>
    </taglib>

A lista de ficheiros de boas-vindas

Quando os URLs do seu site representam caminhos para ficheiros estáticos ou JSPs no seu WAR, é frequentemente uma boa ideia que os caminhos para diretórios também façam algo útil. Um utilizador que visite o caminho de URL /help/accounts/password.jsp para obter informações sobre as palavras-passe da conta pode tentar visitar /help/accounts/ para encontrar uma página que apresente a documentação do sistema de contas. O descritor de implementação pode especificar uma lista de nomes de ficheiros que o servidor deve tentar quando o utilizador acede a um caminho que representa um subdiretório WAR (que ainda não está explicitamente mapeado para um servlet). A norma de servlet chama a isto a "lista de ficheiros de boas-vindas".

Por exemplo, se o utilizador aceder ao caminho do URL /help/accounts/, o seguinte elemento <welcome-file-list> no descritor de implementação indica ao servidor que verifique help/accounts/index.jsp e help/accounts/index.html antes de comunicar que o URL não existe:

    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
        <welcome-file>index.html</welcome-file>
    </welcome-file-list>

Filtros

Um filtro é uma classe que atua num pedido como um servlet, mas pode permitir que o processamento do pedido continue com outros filtros ou servlets. Um filtro pode executar uma tarefa auxiliar, como registar, executar verificações de autenticação especializadas ou anotar os objetos de pedido ou resposta antes de chamar o servlet. Os filtros permitem-lhe compor tarefas de processamento de pedidos a partir do descritor de implementação.

Uma classe de filtro implementa a interface javax.servlet.Filter, incluindo o método doFilter(). Segue-se uma implementação de filtro simples que regista uma mensagem e passa o controlo para a cadeia, que pode incluir outros filtros ou um servlet, conforme descrito pelo descritor de implementação:

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() {}

}

Semelhante aos servlets, configura um filtro no descritor de implementação declarando o filtro com o elemento <filter> e, em seguida, mapeando-o para um padrão de URL com o elemento <filter-mapping>. Também pode mapear filtros diretamente para outros servlets.

O elemento <filter> contém elementos <filter-name>, <filter-class> e <init-param> opcionais.

    <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>

O elemento <filter-mapping> contém um <filter-name> que corresponde ao nome de um filtro declarado e um elemento <url-pattern> para aplicar o filtro a URLs ou um elemento <servlet-name> que corresponde ao nome de um servlet declarado para aplicar o filtro sempre que o servlet é chamado.

    <!-- 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>

Nota: os filtros não são invocados em recursos estáticos, mesmo que o caminho corresponda a um padrão filter-mapping. Os ficheiros estáticos são publicados diretamente no navegador.

Controladores de erros

Pode personalizar o que o servidor envia ao utilizador quando ocorre um erro através do descritor de implementação. O servidor pode apresentar uma localização de página alternativa quando está prestes a enviar um código de estado HTTP específico ou quando um servlet gera uma exceção Java específica.

O elemento <error-page> contém um elemento <error-code> com um valor de código de erro HTTP (como 500) ou um elemento <exception-type> com o nome da classe da exceção esperada (como java.io.IOException). Também contém um elemento <location> com o caminho do URL do recurso a apresentar quando ocorre o erro.

    <error-page>
        <error-code>500</error-code>
        <location>/errors/servererror.jsp</location>
    </error-page>

Nota: atualmente, não pode configurar controladores de erros personalizados para algumas condições de erro. Em concreto, não pode personalizar a página de resposta 404 quando não é definida nenhuma associação de servlet para um URL, a página de erro de quota 403 ou a página de erro do servidor 500 que é apresentada após um erro interno do App Engine.

Funcionalidades web.xml não suportadas

As seguintes funcionalidades do web.xml não são suportadas pelo App Engine:

• O App Engine suporta o elemento <load-on-startup> para declarações de servlet. No entanto, o carregamento ocorre realmente durante o primeiro pedido processado pela instância do servidor Web e não antes.
• Alguns elementos do descritor de implementação podem ter um nome a apresentar legível, uma descrição e um ícone para utilização em IDEs. O App Engine não usa estes elementos e ignora-os.
• O App Engine não suporta variáveis de ambiente JNDI (<env-entry>).
• O App Engine não suporta recursos EJB (<resource-ref>).
• A notificação da destruição de servlets, contexto de servlet ou filtros não é suportada.
• O elemento <distributable> é ignorado.
• O agendamento de servlets com <run-at> não é suportado.
• As restrições de segurança não são suportadas: para uma funcionalidade equivalente, consulte o artigo Autentique-se nos serviços na nuvem através de bibliotecas de cliente.
• CONFIDENTIAL não é suportado em web.xml.