Configurazione del descrittore di deployment web.xml

Il file web.xml viene utilizzato solo quando esegui il deployment di un'app Java in un runtime che include il server Eclipse Jetty 9/ servlet 3. Per maggiori dettagli, consulta il runtime di Eclipse Jetty 9.3.

Le applicazioni web Java utilizzano un file descrittore di deployment per determinare in che modo gli URL vengono mappati ai servlet, quali URL richiedono l'autenticazione e altre informazioni. Questo file è denominato web.xml e si trova nella WAR dell'applicazione nella directory WEB-INF/. web.xml fa parte dello standard servlet per le applicazioni web.

Per ulteriori informazioni sullo standard web.xml, consulta la specifica Servlet.

Informazioni sui descrittori di deployment

Il descrittore di deployment di un'applicazione web descrive le classi, le risorse e la configurazione dell'applicazione e il modo in cui il server web le utilizza per gestire le richieste web. Quando il server web riceve una richiesta per l'applicazione, utilizza il descrittore di deployment per mappare l'URL della richiesta al codice che deve gestire la richiesta.

Il descrittore di deployment è un file denominato web.xml. Si trova nella sezione WAR dell'app, nella directory WEB-INF/. Il file è un file XML il cui elemento principale è <web-app>.

Ecco un semplice esempio di web.xml che mappa tutti i percorsi dell'URL (/*) alla classe 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>

Servlet e percorsi URL

web.xml definisce le mappature tra i percorsi degli URL e i servlet che gestiscono le richieste con questi percorsi. Il server web utilizza questa configurazione per identificare il servlet per gestire una determinata richiesta e chiamare il metodo della classe che corrisponde al metodo della richiesta (ad es. il metodo doGet() per le richieste HTTP GET).

Per mappare un URL a un servlet, devi dichiarare il servlet con l'elemento <servlet>, quindi definire un mapping da un percorso URL a una dichiarazione servlet con l'elemento <servlet-mapping>.

L'elemento <servlet> dichiara il servlet, incluso un nome utilizzato per fare riferimento al servlet da altri elementi nel file, la classe da utilizzare per il servlet e i parametri di inizializzazione. Puoi dichiarare più servlet utilizzando la stessa classe con parametri di inizializzazione diversi. Il nome di ogni servlet deve essere univoco in tutto il descrittore di deployment.

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

L'elemento <servlet-mapping> specifica un pattern URL e il nome di un servlet dichiarato da utilizzare per le richieste il cui URL corrisponde al pattern. Il pattern URL può utilizzare un asterisco (*) all'inizio o alla fine del pattern per indicare zero o più caratteri. Lo standard non supporta i caratteri jolly all'interno di una stringa e non consente l'utilizzo di più caratteri jolly nello stesso pattern. Il pattern corrisponde al percorso completo dell'URL, iniziando con la barra (/) che segue il nome di dominio e inclusa.

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

Con questo esempio, la richiesta dell'URL http://www.example.com/blue/teamProfile viene gestita dalla classe TeamServlet, con il parametro teamColor uguale a blue e il parametro bgColor uguale a #0000CC. Il servlet può recuperare la parte del percorso dell'URL che corrisponde al carattere jolly utilizzando il metodo getPathInfo() dell'oggetto ServletRequest.

Il servlet può accedere ai propri parametri di inizializzazione ottenendo la sua configurazione utilizzando il proprio metodo getServletConfig(), quindi chiamando il metodo getInitParameter() sull'oggetto di configurazione utilizzando il nome del parametro come argomento.

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

JSP

Un'app può utilizzare JSP (JavaServer Pages) per implementare le pagine web. I JSP sono servlet definiti mediante contenuti statici (come HTML) mescolati con codice Java.

App Engine supporta la compilazione automatica e la mappatura degli URL per i JSP. Un file JSP nel WAR dell'applicazione (esterno a WEB-INF/), il cui nome file termina con .jsp, viene compilato automaticamente in una classe servlet e mappato al percorso dell'URL equivalente al percorso del file JSP dalla radice WAR. Ad esempio, se un'app ha un file JSP denominato start.jsp in una sottodirectory denominata register/ nella sua directory WAR, App Engine lo compila e la mappa al percorso dell'URL /register/start.jsp.

Se vuoi un maggiore controllo sul modo in cui JSP viene mappato a un URL, puoi specificare il mapping in modo esplicito dichiarandolo con un elemento <servlet> nel descrittore di deployment. Anziché un elemento <servlet-class>, devi specificare un elemento <jsp-file> con il percorso del file JSP dalla radice WAR. L'elemento <servlet> per JSP può contenere parametri di inizializzazione.

    <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: il <jsp-file> deve iniziare con una barra (/) se il JSP si trova nella directory root dell'applicazione.

Puoi installare librerie di tag JSP con l'elemento <taglib>. Una libreria di tag ha un percorso al file JSP Tag Library Descriptor (TLD) (<taglib-location>) e un URI utilizzato dai JSP per selezionare la libreria per il caricamento (<taglib-uri>). Tieni presente che App Engine fornisce la JavaServer Pages Standard Tag Library (JSTL), che non è necessario installarla.

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

L'elenco dei file di benvenuto

Quando gli URL del tuo sito rappresentano percorsi di file statici o JSP nella WAR, spesso è una buona idea che anche i percorsi delle directory possano svolgere qualcosa di utile. Un utente che visita il percorso dell'URL /help/accounts/password.jsp per informazioni sulle password degli account può provare a visitare la pagina /help/accounts/ per trovare una pagina che presenta la documentazione del sistema dell'account. Il descrittore di deployment può specificare un elenco di nomi file che il server deve provare quando l'utente accede a un percorso che rappresenta una sottodirectory WAR (che non è già mappata esplicitamente a un servlet). Lo standard servlet lo chiama "elenco dei file di benvenuto".

Ad esempio, se l'utente accede al percorso dell'URL /help/accounts/, il seguente elemento <welcome-file-list> nel descrittore di deployment indica al server di verificare la presenza di help/accounts/index.jsp e help/accounts/index.html prima di segnalare che l'URL non esiste:

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

Filtri

Un filtro è una classe che agisce su una richiesta come un servlet, ma può consentire la gestione della richiesta per continuare con altri filtri o servlet. Un filtro può eseguire un'attività ausiliaria come il logging, l'esecuzione di controlli di autenticazione specializzati o l'annotazione degli oggetti richiesta o risposta prima di chiamare il servlet. I filtri consentono di comporre attività di elaborazione delle richieste dal descrittore di deployment.

Una classe di filtro implementa l'interfaccia javax.servlet.Filter, che include il metodo doFilter(). Ecco una semplice implementazione di filtro che registra un messaggio e passa il controllo lungo la catena, che può includere altri filtri o un servlet, come descritto dal descrittore di deployment:

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

}

Come per i servlet, devi configurare un filtro nel descrittore di deployment dichiarando il filtro con l'elemento <filter>, quindi mappandolo a un pattern URL con l'elemento <filter-mapping>. Puoi anche mappare i filtri direttamente ad altri servlet.

L'elemento <filter> contiene elementi <filter-name>, <filter-class> e <init-param> facoltativi.

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

L'elemento <filter-mapping> contiene un elemento <filter-name> che corrisponde al nome di un filtro dichiarato e un elemento <url-pattern> per l'applicazione del filtro agli URL oppure un elemento <servlet-name> che corrisponde al nome di un servlet dichiarato per l'applicazione del filtro ogni volta che viene richiamato il 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>

Nota: i filtri non vengono richiamati sugli asset statici, anche se il percorso corrisponde a un pattern filter-mapping. I file statici vengono pubblicati direttamente nel browser.

Gestori degli errori

Puoi personalizzare ciò che il server invia all'utente in caso di errore utilizzando il descrittore di deployment. Il server può visualizzare un percorso di pagina alternativa quando sta per inviare un determinato codice di stato HTTP o quando un servlet genera una determinata eccezione Java.

L'elemento <error-page> contiene un elemento <error-code> con un valore del codice di errore HTTP (come 500) o un elemento <exception-type> con il nome della classe dell'eccezione prevista (come java.io.IOException). Contiene inoltre un elemento <location> contenente il percorso dell'URL della risorsa da mostrare quando si verifica l'errore.

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

Nota: al momento non è possibile configurare gestori degli errori personalizzati per alcune condizioni di errore. In particolare, non puoi personalizzare la pagina di risposta 404 se non è stata definita alcuna mappatura servlet per un URL, la pagina di errore della quota 403 o la pagina di errore del server 500 che viene visualizzata dopo un errore interno di App Engine.

Funzionalità web.xml non supportate

Le seguenti funzionalità di web.xml non sono supportate da App Engine:

• App Engine supporta l'elemento <load-on-startup> per le dichiarazioni servlet. Tuttavia, il carico si verifica in realtà durante la prima richiesta gestita dall'istanza del server web, non prima.
• Alcuni elementi descrittore di deployment possono utilizzare un nome visualizzato, una descrizione e un'icona leggibili negli IDE. App Engine non li utilizza e li ignora.
• App Engine non supporta le variabili di ambiente JNDI (<env-entry>).
• App Engine non supporta le risorse EJB (<resource-ref>).
• La notifica dell'eliminazione di servlet, contesto servlet o filtri non è supportata.
• L'elemento <distributable> viene ignorato.
• La pianificazione dei servlet con <run-at> non è supportata.
• I vincoli di sicurezza non sono supportati: per una funzionalità equivalente, consulta l'articolo su come autenticarsi nei servizi Cloud utilizzando librerie client.
• INFORMAZIONI RISERVATE non sono supportate in web.xml.