Configurazione del descrittore di deployment web.xml

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

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

Per saperne di più 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 gestirla.

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

Ecco un esempio di web.xml che mappa tutti i percorsi 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 i mapping tra i percorsi URL e le servlet che gestiscono le richieste con questi percorsi. Il server web utilizza questa configurazione per identificare la servlet per gestire una determinata richiesta e chiamare il metodo della classe corrispondente al metodo di richiesta (ad esempio, il metodo doGet() per le richieste HTTP GET).

Per mappare un URL a una servlet, dichiara la servlet con l'elemento <servlet>, poi definisci una mappatura da un percorso URL a una dichiarazione di servlet con l'elemento <servlet-mapping>.

L'elemento <servlet> dichiara la servlet, incluso un nome utilizzato per fare riferimento alla servlet da altri elementi del file, la classe da utilizzare per la 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 nel 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 una servlet dichiarata da utilizzare per le richieste il cui URL corrisponde al pattern. Il pattern dell'URL può utilizzare un asterisco (*) all'inizio o alla fine del pattern per indicare zero o più caratteri qualsiasi. Lo standard non supporta i caratteri jolly al centro di una stringa e non consente più caratteri jolly in un pattern. Il pattern corrisponde al percorso completo dell'URL, a partire dalla barra (/) che segue il nome di dominio.

<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, una richiesta per l'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. La servlet può ottenere la porzione del percorso URL corrispondente al carattere jolly utilizzando il metodo getPathInfo() dell'oggetto ServletRequest.

La servlet può accedere ai parametri di inizializzazione ottenendo la configurazione della servlet 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 le JavaServer Pages (JSP) per implementare le pagine web. Le JSP sono servlet definite utilizzando contenuti statici (come HTML) combinati con codice Java.

App Engine supporta la compilazione automatica e la mappatura degli URL per le JSP. Un file JSP nel WAR dell'applicazione (al di fuori di WEB-INF/) il cui nome file termina con .jsp viene compilato automaticamente in una classe servlet e mappato al percorso 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/ nel relativo file WAR, App Engine lo compila e lo mappa al percorso URL /register/start.jsp.

Se vuoi avere un maggiore controllo sulla mappatura della JSP a un URL, puoi specificare la mappatura in modo esplicito dichiarandola con un elemento <servlet> nel descrittore di deployment. Anziché un elemento <servlet-class>, specifica un elemento <jsp-file> con il percorso del file JSP dalla radice WAR. L'elemento <servlet> per il 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: <jsp-file> deve iniziare con una barra (/) se il file JSP si trova nella directory principale dell'applicazione.

Puoi installare le 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 che le JSP utilizzano per selezionare la libreria da caricare (<taglib-uri>). Tieni presente che App Engine fornisce la JavaServer Pages Standard Tag Library (JSTL) e non devi 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 a file statici o JSP nel tuo file WAR, spesso è una buona idea che anche i percorsi alle directory facciano qualcosa di utile. Un utente che visita il percorso URL /help/accounts/password.jsp per informazioni sulle password dell'account potrebbe provare a visitare /help/accounts/ per trovare una pagina che introduce la documentazione del sistema di account. Il descrittore di deployment può specificare un elenco di nomi di file che il server deve provare quando l'utente accede a un percorso che rappresenta una sottodirectory WAR (che non è già mappata in modo esplicito a una servlet). Lo standard servlet lo chiama "elenco dei file di benvenuto".

Ad esempio, se l'utente accede al percorso URL /help/accounts/, il seguente elemento <welcome-file-list> nel descrittore di deployment indica al server di controllare 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 una servlet, ma può consentire la gestione della richiesta di continuare con altri filtri o servlet. Un filtro può eseguire un'attività ausiliaria come la registrazione, l'esecuzione di controlli di autenticazione specializzati o l'annotazione degli oggetti richiesta o risposta prima di chiamare la servlet. I filtri ti consentono di comporre attività di elaborazione delle richieste dal descrittore di deployment.

Una classe di filtri implementa l'interfaccia javax.servlet.Filter, incluso il metodo doFilter(). Ecco una semplice implementazione del filtro che registra un messaggio e passa il controllo alla catena, che può includere altri filtri o una 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() {}

}

Analogamente alle servlet, puoi configurare un filtro nel descrittore di deployment dichiarando il filtro con l'elemento <filter> e poi mappandolo a un pattern URL con l'elemento <filter-mapping>. Puoi anche mappare i filtri direttamente ad altre 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 <filter-name> che corrisponde al nome di un filtro dichiarato e un elemento <url-pattern> per applicare il filtro agli URL o un elemento <servlet-name> che corrisponde al nome di una servlet dichiarata per applicare il filtro ogni volta che viene chiamata la 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.

Gestione degli errori

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

L'elemento <error-page> contiene un elemento <error-code> con un valore di codice di errore HTTP (ad esempio 500) o un elemento <exception-type> con il nome della classe dell'eccezione prevista (ad esempio java.io.IOException). Contiene anche un elemento <location> contenente il percorso 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: non puoi configurare gestori di errori personalizzati per alcune condizioni di errore. In particolare, non puoi personalizzare la pagina di risposta 404 quando non è definita alcuna mappatura servlet per un URL, la pagina di errore di 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 dei servlet. Tuttavia, il caricamento si verifica effettivamente durante la prima richiesta gestita dall'istanza del server web, non prima.
• Alcuni elementi del descrittore di deployment possono accettare un nome visualizzato leggibile, una descrizione e un'icona da utilizzare 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 della distruzione 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 funzionalità equivalenti, vedi Autenticarsi ai servizi cloud utilizzando le librerie client.
• CONFIDENTIAL non è supportato in web.xml.