Deployment-Deskriptor "web.xml" konfigurieren

Die web.xml-Datei wird nur verwendet, wenn eine Java-Anwendung für eine Laufzeit bereitgestellt wird, die den Eclipse Jetty 9/ Servlet 3-Server enthält. Weitere Informationen finden Sie unter Eclipse Jetty 9.3-Laufzeit.

Mithilfe einer Bereitstellungsdeskriptordatei ermitteln Java-Webanwendungen unter anderem, wie URLs den Servlets zugeordnet sind und welche URLs eine Authentifizierung voraussetzen. Diese Datei heißt web.xml und befindet sich im WAR der Anwendung unter dem WEB-INF/-Verzeichnis. web.xml ist Teil des Servletstandards für Webanwendungen.

Weitere Informationen zum web.xml-Standard finden Sie in der Servlet-Spezifikation.

Bereitstellungsdeskriptoren

Der Bereitstellungsdeskriptor einer Webanwendung beschreibt die Klassen, Ressourcen und Konfiguration der Anwendung und gibt außerdem an, wie der Webserver diese verwendet, um Webanfragen nachzukommen. Wenn der Webserver eine Anfrage für die Anwendung erhält, ordnet er die Anfragen-URL mithilfe des Bereitstellungsdeskriptors dem Code zu, der die Anfrage zu verarbeiten hat.

Die Einrichtungsbeschreibung ist eine Datei namens web.xml. Diese befindet sich im WAR der Anwendung unter dem WEB-INF/-Verzeichnis. Die Datei ist eine XML-Datei mit dem Stammelement <web-app>.

Im Folgenden finden Sie ein einfaches web.xml-Beispiel, in dem alle URL-Pfade (/*) der Servletklasse =mysite.server.ComingSoonServlet zugeordnet werden:

<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 und URL-Pfade

web.xml definiert Zuordnungen zwischen URL-Pfaden und den Servlets, die Anfragen an diese Pfade bearbeiten. Der Webserver verwendet diese Konfiguration, um das Servlet zu identifizieren, das eine bestimmte Anfrage bearbeiten soll, und ruft die Klassenmethode auf, die der Anfragemethode entspricht (zum Beispiel die doGet()-Methode für HTTP-GET-Anfragen).

Für die Zuordnung einer URL zu einem Servlet deklarieren Sie das Servlet mithilfe des <servlet>-Elements und definieren dann eine Zuordnung von einem URL-Pfad zu einer Servletdeklaration unter Verwendung des <servlet-mapping>-Elements.

Das <servlet>-Element deklariert das Servlet, einschließlich eines Namens, mit dem andere Elemente in der Datei auf das Servlet verweisen, der Klasse, die für das Servlet verwendet werden soll, sowie Initialisierungsparametern. Sie können mehrere Servlets mit derselben Klasse, aber unterschiedlichen Initialisierungsparametern deklarieren. Der Name jedes Servlets darf innerhalb des Bereitstellungsdeskriptors nur einmal vorkommen.

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

Das <servlet-mapping>-Element gibt ein URL-Muster sowie den Namen eines deklarierten Servlets an, das für Anfragen verwendet werden soll, deren URL dem Muster entspricht. Am Anfang oder Ende des URL-Musters kann ein Sternchen (*) stehen, um null oder mehr Vorkommen eines beliebigen Zeichens anzugeben. Im Standard werden weder Platzhalter in der Mitte eines Strings noch mehrere Platzhalter innerhalb eines Musters unterstützt. Das Muster gleicht den vollständigen Pfad der URL ab und beginnt mit dem Schrägstrich (/) gefolgt vom Domainnamen.

    <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 diesem Beispiel wird eine·Anfrage für die URL http://www.example.com/blue/teamProfile von der TeamServlet-Klasse bearbeitet, wobei der teamColor-Parameter blue und der bgColor-Parameter #0000CC entspricht. Das Servlet kann den Teil des URL-Pfads abrufen, der vom Platzhalter mithilfe der getPathInfo()-Methode des ServletRequest-Objekts gefunden wurde.

Das Servlet kann durch Abrufen seiner Servletkonfiguration mithilfe seiner eigenen getServletConfig()-Methode und Aufrufen der getInitParameter()-Methode für das Konfigurationsobjekt unter Verwendung des Parameternamens als Argument auf seine Initialisierungsparameter zugreifen.

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

JSPs

Eine Anwendung kann JavaServer Pages (JSPs) für die Implementierung von Webseiten verwenden. JSP-Dateien sind Servlets, die mithilfe von statischen Inhalten, z. B. HTML, und Java-Code definiert werden.

App Engine unterstützt die automatische Kompilierung und URL-Zuordnung für JSPs. Eine JSP-Datei im WAR der Anwendung (außerhalb von WEB-INF/), deren Dateiname auf .jsp endet, wird automatisch in eine Servletklasse kompiliert und dem URL-Pfad zugeordnet, der dem Pfad zur JSP-Datei aus dem WAR-Stamm entspricht. Beispiel: Wenn die JSP-Datei einer Anwendung den Namen start.jsp trägt und sich in einem Unterverzeichnis des WARs mit dem Namen register/ befindet, wird diese von App Engine kompiliert und dem URL-Pfad /register/start.jspzugeordnet.

Wenn Sie mehr Kontrolle darüber möchten, wie die JSP einer URL zugeordnet wird, können Sie die Zuordnung explizit durch Deklaration eines <servlet>-Elements in der Deployment-Deskriptor festlegen. Geben Sie dann anstelle eines <servlet-class>-Elements ein <jsp-file>-Element mit dem Pfad zur JSP-Datei aus dem WAR-Stamm an. Das <servlet>-Element für die JSP kann Initialisierungsparameter enthalten.

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

Hinweis: Der <jsp-file> muss mit einem Vorwärts-Schrägstrich (/) beginnen, wenn sich die JSP im Stammverzeichnis der Anwendung befindet.

Sie können JSP-Tag-Bibliotheken mithilfe des <taglib>-Elements installieren. Eine Tag-Bibliothek hat einen Pfad zur TLD-Datei (JSP Tag Library Descriptor) (<taglib-location>) und einen URI, mit dem JSPs die Bibliothek zum Laden auswählen (<taglib-uri>). Beachten Sie, dass App Engine die JavaServer Pages Standard Tag Library (JSTL) bereitstellt und Sie diese nicht installieren müssen.

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

Element "welcome-file-list"

Wenn die URLs für Ihre Website Pfade zu statischen oder JSP-Dateien in Ihrem WAR-Verzeichnis darstellen, bietet es sich häufig an, auch bei Pfaden zu Verzeichnissen etwas Sinnvolles vorzusehen. Ein Nutzer, der den URL-Pfad /help/accounts/password.jsp aufruft, um Informationen zu Kontopasswörtern zu erhalten, versucht möglicherweise, /help/accounts/ aufzurufen, um eine Seite mit einer Einführung in die Kontosystemdokumentation zu finden. Für solche Fälle kann im Bereitstellungsdeskriptor eine Liste mit Dateinamen angegeben werden, die der Server bei einem Zugriff des Nutzers auf einen Pfad zu einem WAR-Unterverzeichnis, das nicht bereits explizit einem Servlet zugeordnet ist, verwenden soll. Im Servlet-Standard heißt diese Liste "welcome-file-list".

Wenn ein Nutzer beispielsweise auf den URL-Pfad /help/accounts/ zugreift, wird der Server durch das folgende <welcome-file-list>-Element in der Deployment-Deskriptor aufgefordert, zuerst help/accounts/index.jsp und help/accounts/index.html zu prüfen, bevor er meldet, dass die URL nicht existiert:

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

Filter

Ein Filter ist eine Klasse, die im Fall einer Anfrage wie ein Servlet agiert. Dabei ist es möglich, die Bearbeitung der Anfrage mit anderen Filtern oder Servlets fortzusetzen. Ein Filter kann zusätzliche Aufgaben wie Logging, Ausführung spezieller Authentifizierungsprüfungen oder Annotieren von Anfrage- oder Antwortobjekten vor dem Abrufen des Servlets übernehmen. Mit Filtern haben Sie die Möglichkeit, Anfragenverarbeitungsaufgaben über den Bereitstellungsdeskriptor zu erstellen.

Eine Filterklasse implementiert die javax.servlet.Filter-Schnittstelle, einschließlich der doFilter()-Methode. Hier eine einfache Filterimplementierung, bei der eine Nachricht protokolliert und die Steuerung entlang der Kette untergeordneter Objekte weitergegeben wird. Dabei können entsprechend den Vorgaben im Bereitstellungsdeskriptor weitere Filter oder ein Servlet einbezogen werden:

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

}

Ähnlich wie Servlets können Sie auch einen Filter in der Deployment-Deskriptor konfigurieren. Deklarieren Sie den Filter mithilfe des <filter>-Elements und weisen Sie ihn dann mithilfe des <filter-mapping>-Elements einem URL-Muster zu. Sie können Filter auch direkt anderen Servlets zuordnen.

Das <filter>-Element enthält einen <filter-name>, eine <filter-class> sowie optionale <init-param>-Elemente.

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

Das <filter-mapping>-Element weist einen <filter-name> auf, der dem Namen eines deklarierten Filters entspricht, sowie entweder ein <url-pattern>-Element für die Anwendung von Filtern auf URLs oder ein <servlet-name>-Element, das dem Namen eines deklarierten Servlets entspricht und den Filter immer dann anwendet, wenn das Servlet aufgerufen wird.

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

Hinweis: Filter werden nicht bei statischen Objekten aufgerufen, selbst wenn der Pfad einem filter-mapping-Muster entspricht. Statische Dateien werden direkt an den Browser geliefert.

Fehlerhandler

Mithilfe des Bereitstellungsdeskriptors können Sie selbst festlegen, was der Server beim Auftreten eines Fehlers an den Nutzer sendet. Der Server kann eine alternative Seitenadresse anzeigen, wenn ein bestimmter HTTP-Statuscode gesendet wird oder ein Servlet eine bestimmte Java-Ausnahme auslöst.

Das <error-page>-Element enthält entweder ein <error-code>-Element mit einem HTTP-Fehlercodewert (z. B. 500) oder ein <exception-type>-Element mit dem Klassennamen der erwarteten Ausnahme (z. B. java.io.IOException). Es enthält auch ein <location>-Element, das den URL-Pfad der Ressource enthält, die angezeigt wird, wenn der Fehler auftritt.

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

Hinweis: Zurzeit können Sie für einige Fehlerzustände keine benutzerdefinierten Fehlerhandler konfigurieren. Insbesondere betrifft dies die 404-Antwortseite, wenn keine Servlet-Zuordnung für eine URL definiert ist, die 403-Kontingentfehlerseite und die 500Serverfehlerseite, die nach einem internen App Engine-Fehler angezeigt wird.

Nicht unterstützte web.xml-Funktionen

Die folgenden web.xml-Funktionen werden von App Engine nicht unterstützt:

• App Engine unterstützt das <load-on-startup>-Element für Servletdeklarationen. das Laden erfolgt jedoch erst, wenn die erste Anfrage von der Webserverinstanz bearbeitet wird, nicht vorher.
• Einige Elemente im Bereitstellungsdeskriptor können einen für Menschen lesbaren Anzeigenamen, eine Beschreibung sowie ein Symbol zur Verwendung in IDEs annehmen. App Engine verwendet diese nicht und ignoriert sie.
• App Engine unterstützt keine JNDI-Umgebungsvariablen (<env-entry>).
• App Engine unterstützt keine EJB-Ressourcen (<resource-ref>).
• Benachrichtigungen über das Löschen von Servlets, Servlet-Kontexten oder Filtern werden nicht unterstützt.
• Das <distributable>-Element wird ignoriert.
• Eine Servletplanung mit <run-at> wird nicht unterstützt.
• Sicherheitsbeschränkungen werden nicht unterstützt. Entsprechende Funktionen finden Sie unter Mithilfe von Clientbibliotheken bei Cloud-Diensten authentifizieren..
• "CONFIDENTIAL" wird in web.xml nicht unterstützt.