Mengonfigurasi deployment descriptor web.xml

File web.xml hanya digunakan saat men-deploy aplikasi Java ke runtime yang menyertakan server Eclipse Jetty 9/ servlet 3. Untuk detail selengkapnya, lihat Runtime Eclipse Jetty 9.3.

Aplikasi web Java menggunakan file deployment descriptor untuk menentukan cara URL dipetakan ke servlet, URL mana yang memerlukan autentikasi, dan informasi lainnya. File ini bernama web.xml, dan berada dalam WAR aplikasi dalam direktori WEB-INF/. web.xml adalah bagian dari standar servlet untuk aplikasi web.

Untuk informasi selengkapnya tentang standar web.xml, lihat spesifikasi Servlet.

Tentang deployment descriptor

Deployment descriptor aplikasi web menjelaskan class, resource, dan konfigurasi aplikasi serta cara server web menggunakannya untuk melayani permintaan web. Saat menerima permintaan untuk aplikasi, server web akan menggunakan deployment descriptor untuk memetakan URL permintaan tersebut ke kode yang seharusnya menangani permintaan tersebut.

Deployment descriptor adalah file bernama web.xml. File ini berada di WAR aplikasi dalam direktori WEB-INF/. Filenya adalah file XML yang elemen root-nya adalah <web-app>.

Berikut adalah contoh web.xml sederhana yang memetakan semua jalur URL (/*) ke class 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 dan jalur URL

web.xml menentukan pemetaan antara jalur URL dan servlet yang menangani permintaan dengan jalur tersebut. Server web menggunakan konfigurasi ini untuk mengidentifikasi servlet guna menangani permintaan tertentu dan memanggil metode class yang sesuai dengan metode permintaan tersebut (misalnya, metode doGet() untuk permintaan GET HTTP).

Untuk memetakan URL ke servlet, deklarasikan servlet dengan elemen <servlet>, lalu tentukan pemetaan dari jalur URL ke deklarasi servlet dengan elemen <servlet-mapping>.

Elemen <servlet> mendeklarasikan servlet, termasuk nama yang digunakan untuk merujuk ke servlet oleh elemen lain dalam file, class yang akan digunakan untuk servlet, dan parameter inisialisasi. Anda dapat mendeklarasikan beberapa servlet menggunakan class yang sama dengan parameter inisialisasi yang berbeda. Nama untuk setiap servlet harus unik di seluruh deployment descriptor.

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

Elemen <servlet-mapping> menentukan pola URL dan nama servlet yang dideklarasikan untuk digunakan oleh permintaan yang URL-nya cocok dengan pola. Pola URL dapat menggunakan tanda bintang (*) di awal atau akhir pola untuk menunjukkan nol atau beberapa karakter apa pun. Standar ini tidak mendukung karakter pengganti di tengah string, dan tidak mengizinkan beberapa karakter pengganti dalam satu pola. Polanya cocok dengan jalur lengkap URL, dimulai dengan dan termasuk garis miring (/) setelah nama domain.

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

Dengan contoh ini, permintaan untuk URL http://www.example.com/blue/teamProfile ditangani oleh class TeamServlet, dengan parameter teamColor sama dengan blue dan parameter bgColor sama dengan #0000CC. Servlet dapat memperoleh bagian jalur URL yang cocok dengan karakter pengganti menggunakan metode getPathInfo() objek ServletRequest.

Servlet dapat mengakses parameter inisialisasinya dengan mendapatkan konfigurasi servlet menggunakan metode getServletConfig()-nya sendiri, lalu memanggil metode getInitParameter() pada objek konfigurasi menggunakan nama parameter sebagai argumen.

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

JSP

Aplikasi dapat menggunakan JavaServer Pages (JSP) untuk mengimplementasikan halaman web. JSP adalah servlet yang ditentukan menggunakan konten statis (seperti HTML) yang dicampur dengan kode Java.

App Engine mendukung kompilasi otomatis dan pemetaan URL untuk JSP. File JSP dalam WAR aplikasi (di luar WEB-INF/) yang nama filenya berakhiran .jsp dikompilasi ke dalam class servlet secara otomatis, dan dipetakan ke jalur URL yang setara dengan jalur ke file JSP dari root WAR. Misalnya, jika sebuah aplikasi memiliki file JSP bernama start.jsp dalam subdirektori bernama register/ dalam WAR-nya, App Engine mengompilasinya dan memetakannya ke jalur URL /register/start.jsp.

Jika menginginkan kontrol lebih besar atas cara pemetaan JSP ke URL, Anda dapat menentukan pemetaan secara eksplisit dengan mendeklarasikannya bersama elemen <servlet> dalam deployment descriptor. Namun, tentukan elemen <jsp-file> dengan jalur ke file JSP dari root WAR, bukan elemen <servlet-class>. Elemen <servlet> untuk JSP dapat berisi parameter inisialisasi.

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

Catatan: <jsp-file> harus diawali dengan garis miring (/) jika JSP berada di direktori utama aplikasi.

Anda dapat menginstal library tag JSP dengan elemen <taglib>. Library tag memiliki jalur ke file Deskripsi Library Tag (TLD) JSP (<taglib-location>) dan URI yang digunakan JSP untuk memilih library untuk dimuat (<taglib-uri>). Perhatikan bahwa App Engine menyediakan Library Tag Standar Halaman JavaServer (JSTL), dan Anda tidak perlu menginstalnya.

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

Daftar file sambutan

Jika URL untuk situs Anda mewakili jalur ke file statis atau JSP di WAR, sebaiknya jalur ke direktori juga melakukan hal yang berguna. Pengguna yang mengunjungi jalur URL /help/accounts/password.jsp untuk mengetahui informasi tentang sandi akun dapat mencoba membuka /help/accounts/ untuk menemukan halaman yang memperkenalkan dokumentasi sistem akun. Deskriptor deployment dapat menentukan daftar nama file yang harus dicoba server saat pengguna mengakses jalur yang mewakili subdirektori WAR (yang belum dipetakan secara eksplisit ke servlet). Standar servlet menyebutnya sebagai "daftar file sambutan".

Misalnya, jika pengguna mengakses jalur URL /help/accounts/, elemen <welcome-file-list> berikut dalam deployment descriptor memberi tahu server untuk memeriksa help/accounts/index.jsp dan help/accounts/index.html sebelum melaporkan bahwa URL tidak ada:

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

Filter

Filter adalah class yang bertindak berdasarkan permintaan seperti servlet, tetapi dapat memungkinkan penanganan permintaan untuk dilanjutkan dengan filter atau servlet lainnya. Filter dapat melakukan tugas tambahan seperti logging, melakukan pemeriksaan autentikasi khusus, atau menganotasi objek permintaan atau respons sebelum memanggil servlet. Filter memungkinkan Anda membuat tugas pemrosesan permintaan dari deployment descriptor.

Class filter mengimplementasikan antarmuka javax.servlet.Filter, termasuk metode doFilter(). Berikut adalah implementasi filter sederhana yang mencatat pesan, dan meneruskan kontrol secara berkesinambungan, yang dapat mencakup filter lain atau servlet, seperti yang dijelaskan oleh deployment descriptor:

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

}

Serupa dengan servlet, Anda mengonfigurasi filter dalam deployment descriptor dengan mendeklarasikan filter menggunakan elemen <filter>, lalu memetakannya ke pola URL dengan elemen <filter-mapping>. Anda juga dapat memetakan filter secara langsung ke servlet lainnya.

Elemen <filter> berisi elemen <filter-name>, <filter-class>, dan <init-param> opsional.

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

Elemen <filter-mapping> berisi <filter-name> yang cocok dengan nama filter yang dideklarasikan, dan elemen <url-pattern> untuk menerapkan filter ke URL, atau elemen <servlet-name> yang sesuai dengan nama servlet yang dideklarasikan untuk menerapkan filter setiap kali servlet dipanggil.

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

Catatan: Filter tidak dipanggil pada aset statis, meskipun jalurnya cocok dengan pola filter-mapping. File statis ditayangkan langsung ke browser.

Pengendali Error

Anda dapat menyesuaikan apa yang dikirim server kepada pengguna saat terjadi error, menggunakan deployment descriptor. Server dapat menampilkan lokasi halaman alternatif saat akan mengirimkan kode status HTTP tertentu, atau saat servlet memunculkan pengecualian Java tertentu.

Elemen <error-page> berisi elemen <error-code> dengan nilai kode error HTTP (seperti 500), atau elemen <exception-type> dengan nama class pengecualian yang diharapkan (seperti java.io.IOException). Objek ini juga berisi elemen <location> yang berisi jalur URL resource yang akan ditampilkan saat terjadi error.

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

Catatan: Saat ini, Anda tidak dapat mengonfigurasi pengendali error kustom untuk beberapa kondisi error. Secara khusus, Anda tidak dapat menyesuaikan halaman respons 404 jika tidak ada pemetaan servlet yang ditentukan untuk URL, halaman error kuota 403, atau halaman error server 500 yang muncul setelah error internal App Engine.

Fitur web.xml tidak didukung

Fitur web.xml berikut tidak didukung oleh App Engine:

• App Engine mendukung elemen <load-on-startup> untuk deklarasi servlet. Namun, pemuatan sebenarnya terjadi selama permintaan pertama yang ditangani oleh instance server web, bukan sebelum permintaan tersebut.
• Beberapa elemen deployment descriptor dapat mengambil nama tampilan, deskripsi, dan ikon yang dapat dibaca manusia untuk digunakan dalam IDE. App Engine tidak menggunakannya, dan mengabaikannya.
• App Engine tidak mendukung variabel lingkungan JNDI (<env-entry>).
• App Engine tidak mendukung resource EJB (<resource-ref>).
• Notifikasi tentang penghancuran servlet, konteks servlet, atau filter tidak didukung.
• Elemen <distributable> diabaikan.
• Penjadwalan servlet dengan <run-at> tidak didukung.
• Batasan Keamanan tidak didukung: untuk fungsi yang setara, lihat Mengautentikasi ke layanan Cloud menggunakan library klien.
• RAHASIA tidak didukung di web.xml.