Configurazione del descrittore di deployment web.xml

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

Le applicazioni web Java utilizzano un file descrittore di deployment per determinare la mappatura degli URL ai servlet, quali URL richiedono l'autenticazione e altre informazioni. Questo file è denominato 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 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 come 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 per gestire la richiesta.

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 semplice esempio di web.xml che mappa tutti i percorsi dell'URL (/*) alla classe del 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 dell'URL e i servlet che gestiscono richieste con quei percorsi. Il server web utilizza questa configurazione per identificare il servlet da utilizzare per gestire una determinata richiesta e chiamare il metodo di classe corrispondente al metodo di 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 definisci una mappatura da un percorso URL a una dichiarazione servlet con Elemento <servlet-mapping>.

L'elemento <servlet> dichiara il servlet, incluso un nome utilizzato per fare riferimento al servlet da altri elementi del file, la classe da utilizzare per il servlet e i parametri di inizializzazione. Puoi dichiarare più servlet utilizzando lo stesso con diversi parametri di inizializzazione. Il nome di ogni servlet deve essere univoci 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 un servlet dichiarato da utilizzare per le richieste il cui URL corrisponde al pattern. URL utilizzare un asterisco (*) all'inizio o alla fine del pattern per indicare zero o più caratteri. Lo standard non supporta i caratteri jolly al centro di una stringa e non consente più caratteri jolly pattern. Il pattern corrisponde al percorso completo dell'URL, iniziando con e inclusa la 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>

In questo esempio, una richiesta per l'URLhttp://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ò ottenere la porzione del percorso dell'URL che corrisponde alla carattere jolly che utilizza il metodo getPathInfo() dell'oggetto ServletRequest.

Il servlet può accedere ai suoi parametri di inizializzazione ottenendo la configurazione del 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");

JSPs

Un'app può utilizzare JavaServer Pages (JSP) per implementare pagine web. I JSP sono servlet definiti utilizzando contenuti statici (ad esempio HTML) misti con codice Java.

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

Se vuoi avere un maggiore controllo sul modo in cui la JSP viene mappata 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. La 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 è in alla directory radice 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 dalle JSP per selezionare la libreria da caricare (<taglib-uri>). Tieni presente che App Engine fornisce JavaServer Pages Standard Tag Library (JSTL), e non è necessario installarlo.

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

Elenco dei file di benvenuto

Quando gli URL del tuo sito rappresentano percorsi a file statici o JSP nel file WAR, spesso è buona norma che anche i percorsi alle directory facciano qualcosa di utile. Un utente visita il percorso dell'URL /help/accounts/password.jsp per informazioni su password degli account può provare a visitare /help/accounts/ per trovare una pagina di presentazione la documentazione del sistema di 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 (non già mappata esplicitamente a un servlet). Lo standard servlet lo definisce "elenco di file di benvenuto".

Ad esempio, se l'utente accede al percorso dell'URL /help/accounts/, il seguente codice L'elemento <welcome-file-list> nel descrittore di deployment comunica al server di controlla help/accounts/index.jsp e help/accounts/index.html prima segnalando 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 della richiesta per 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 di richiesta o risposta prima di chiamare il servlet. I filtri ti consentono di comporre attività di elaborazione delle richieste dal descrittore di implementazione.

Una classe di filtro implementa l'interfaccia javax.servlet.Filter, che include la classe 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() {}

}

Analogamente ai servlet, configuri un filtro nel descrittore di deployment dichiarando il filtro con l'elemento <filter> e associandolo a un 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 <filter-name> che corrisponde al nome di un filtro dichiarato e un elemento <url-pattern> per l'applicazione filtrare in base agli URL o a un elemento <servlet-name> che corrisponde al nome di un servlet dichiarato per l'applicazione del filtro ogni volta che viene chiamato 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 patternfilter-mapping. I file statici vengono pubblicati direttamente nel browser.

Gestori degli errori

Puoi personalizzare i dati inviati dal server all'utente quando si verifica un errore utilizzando il descrittore di deployment. Il server può mostrare una posizione della 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 (ad es. 500) o un elemento <exception-type> con nome della classe dell'eccezione prevista (ad esempio java.io.IOException). Inoltre, contiene 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. Nello specifico, non puoi personalizzare la pagina di risposta 404 se non la mappatura dei servlet viene definita per un URL, la pagina di errore della quota 403 o la 500 pagina di errore del server 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 del servlet. Tuttavia, il caricamento si verifica effettivamente durante la prima richiesta gestite dall'istanza del server web, non prima.
• Alcuni elementi del descrittore di deployment possono avere un nome visualizzato, una descrizione e un'icona leggibili per l'utilizzo nelle 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 del servlet con <run-at> non è supportata.
• I vincoli di sicurezza non sono supportati: per funzionalità equivalenti, vedi Eseguire l'autenticazione nei servizi Cloud utilizzando librerie client.
• CONFIDENTIAL non è supportato in web.xml.