web.xml 배포 설명자 구성

web.xml 파일은 Eclipse Jetty 9/ 서블릿 3 서버를 포함하는 런타임에 자바 앱을 배포할 때만 사용됩니다. 자세한 내용은 Eclipse Jetty 9.3 런타임을 참조하세요.

자바 웹 애플리케이션은 배포 설명자 파일을 사용하여 URL이 서블릿에 매핑되는 방법, 인증이 필요한 URL, 기타 정보를 확인합니다. 이 파일은 이름이 web.xml로 지정되며, 앱 WAR에서 WEB-INF/ 디렉토리 아래에 있습니다. web.xml은 웹 애플리케이션을 위한 서블릿 표준의 일부입니다.

web.xml 표준에 대한 자세한 내용은 Metawerx web.xml 참조 위키서블릿 사양을 참조하세요.

배포 설명자 정보

웹 애플리케이션의 배포 설명자는 애플리케이션의 클래스, 리소스, 구성을 기술하고, 웹 서버가 이를 사용해서 웹 요청을 처리하는 방법을 기술합니다. 웹 서버가 애플리케이션에 대한 요청을 수신하면 배포 설명자를 사용해서 해당 요청을 처리해야 하는 코드로 요청의 URL을 매핑합니다.

배포 설명자는 이름이 web.xml인 파일입니다. 이 파일은 앱 WAR에에서 WEB-INF/ 디렉토리 아래에 있습니다. 이 파일은 해당 루트 요소가 <web-app>인 XML 파일입니다.

다음에 표시된 간단한 web.xml 예에서는 모든 URL 경로(/*)를 서블릿 클래스 mysite.server.ComingSoonServlet에 매핑합니다.

<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
    <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>

서블릿 및 URL 경로

web.xml은 URL 경로와 해당 경로의 요청을 처리하는 서블릿 사이의 매핑을 정의합니다. 웹 서버는 이 구성을 사용해서 제공된 요청을 처리할 서블릿을 식별하고 요청 메소드(예: HTTP GET 요청의 doGet() 메소드)에 해당하는 클래스 메소드를 호출합니다.

URL을 서블릿에 매핑하기 위해서는 <servlet> 요소로 서블릿을 선언한 후 <servlet-mapping> 요소를 사용해서 URL 경로에서 서블릿 선언으로의 매핑을 정의합니다.

<servlet> 요소는 서블릿을 선언합니다. 여기에는 파일 내 다른 요소가 서블릿을 참조하기 위해 사용되는 이름, 서블릿에 사용할 클래스, 초기화 매개변수가 포함됩니다. 여러 초기화 매개변수에 동일한 클래스를 사용해서 여러 서블릿을 선언할 수 있습니다. 각 서블릿의 이름은 배포 설명자에서 고유해야 합니다.

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

<servlet-mapping> 요소는 패턴과 일치하는 URL의 요청에 사용할 선언된 서블릿의 이름과 URL 패턴을 지정합니다. URL 패턴은 패턴의 시작 또는 끝 부분에 별표(*)를 사용하여 0개 이상의 문자를 나타낼 수 있습니다. (이 표준은 문자열 중간의 와일드 카드 사용을 지원하지 않으며, 하나의 패턴에서 여러 개의 와일드 카드 사용을 허용하지 않습니다.) 패턴은 도메인 이름 다음에 오는 슬래시(/)를 포함하고, 이로 시작되는 URL의 전체 경로와 일치합니다.

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

이 예에서 URL http://www.example.com/blue/teamProfile의 요청은 TeamServlet 클래스로 처리되며, teamColor 매개변수는 blue이고 bgColor 매개변수는 #0000CC입니다. 서블릿은 ServletRequest 객체의 getPathInfo() 메소드를 사용해서 와일드 카드와 일치하는 URL 경로의 일부를 가져올 수 있습니다.

서블릿은 고유한 getServletConfig() 메소드를 사용해서 서블릿 구성을 가져와서 초기화 매개변수에 액세스한 후 매개변수 이름을 인수로 사용해서 구성 객체에서 getInitParameter() 메소드를 호출할 수 있습니다.

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

JSP

앱은 JSP(자바 서버 페이지)를 사용해서 웹 페이지를 구현할 수 있습니다. JSP는 자바 코드와 혼합된 정적 콘텐츠(예: HTML)를 사용하여 정의된 서블릿입니다.

App Engine은 자동 컴파일 및 JSP에 대한 URL 매핑을 지원합니다. 애플리케이션의 WAR(WEB-INF/ 외부)에서 파일 이름이 .jsp로 끝나는 JSP 파일은 서블릿 클래스로 자동으로 컴파일되며, WAR 루트에서 JSP 파일의 경로에 해당하는 URL 경로로 매핑됩니다. 예를 들어 WAR의 register/ 하위 디렉토리에서 이름이 start.jsp인 JSP 파일 이름이 앱에 포함된 경우 App Engine이 이를 컴파일하여 URL 경로 /register/start.jsp로 매핑합니다.

JSP가 URL에 매핑되는 방법을 보다 세부적으로 제어하기 위해서는 배포 설명자에서 <servlet> 요소로 선언하여 매핑을 명시적으로 지정할 수 있습니다. <servlet-class> 요소 대신 WAR 루트의 JSP 파일에 대한 경로로 <jsp-file> 요소를 지정합니다. JSP에 대한 <servlet> 요소는 초기화 매개변수를 포함할 수 있습니다.

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

참고: JSP가 애플리케이션의 루트 디렉토리에 있는 경우 <jsp-file>이 슬래시(/)로 시작해야 합니다.

JSP 태그 라이브러리는 <taglib> 인수로 설치할 수 있습니다. 태그 라이브러리에는 JSP가 로드할 라이브러리를 선택하기 위해 사용하는 URI(<taglib-uri>)와 JSP TLD(태그 라이브러리 설명자) 파일(<taglib-location>)에 대한 경로가 포함됩니다. App Engine은 JSTL(자바 서버 페이지 표준 태그 라이브러리)을 제공하므로, 사용자가 이를 설치할 필요가 없습니다.

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

시작 파일 목록

사이트의 URL이 사용자의 WAR에 있는 정적 파일 또는 JSP에 대한 경로를 나타내는 경우, 디렉토리 경로가 일부 유용한 작업을 수행하도록 하는 것이 좋습니다. 계정 암호에 대한 정보를 보기 위해 URL 경로 /help/accounts/password.jsp를 방문하는 사용자는 계정 시스템 문서를 소개하는 페이지를 찾기 위해 /help/accounts/에 방문을 시도할 수 있습니다. 배포 설명자는 WAR 하위 디렉토리(아직 서블릿에 명시적으로 매핑되지 않은)를 나타내는 경로에 사용자가 액세스할 때 서버가 시도할 파일 이름 목록을 지정할 수 있습니다. 서블릿 표준에서는 이를 '시작 파일 목록'이라고 부릅니다.

예를 들어 사용자가 URL 경로 /help/accounts/에 액세스할 때, 배포 설명자에 있는 다음 <welcome-file-list> 요소는 URL이 존재하지 않음을 보고하기 전에 서버가 help/accounts/index.jsphelp/accounts/index.html을 확인하도록 지시합니다.

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

필터

필터는 서블릿과 같이 요청에 따라 작동하는 클래스이지만, 다른 필터 또는 서블릿에서 요청 처리가 계속되도록 허용할 수 있습니다. 필터는 로깅, 특수 인증 검사 수행, 서블릿 호출 전 요청 또는 응답 객체 주석 처리와 같은 보조 작업을 수행할 수 있습니다. 필터를 사용하면 배포 설명자로부터 요청 처리 작업을 만들 수 있습니다.

필터 클래스는 javax.servlet.Filter 인터페이스를 구현합니다. 여기에는 doFilter() 메소드가 포함됩니다. 다음은 메시지를 기록하고, 배포 설명자에 기술된 대로 다른 필터 또는 서블릿을 포함할 수 있는 체인을 따라 제어를 아래로 전달하는 간단한 필터 구현입니다.

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

}

서블릿과 비슷하게, <filter> 요소를 사용해서 필터를 선언하여 배포 설명자에서 필터를 구성한 후 <filter-mapping> 요소를 사용하여 이를 URL 패턴에 매핑합니다. 또한 다른 서블릿에 필터를 직접 매핑할 수 있습니다.

<filter> 요소에는 <filter-name>, <filter-class>, 선택적인 <init-param> 요소가 포함됩니다.

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

<filter-mapping> 요소에는 선언된 필터의 이름과 일치하는 <filter-name>과 URL에 필터를 적용하기 위한 <url-pattern> 요소 또는 서블릿이 호출될 때마다 필터를 적용하기 위해 선언된 서블릿의 이름과 일치하는 <servlet-name> 요소가 포함됩니다.

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

참고: 경로가 filter-mapping 패턴과 일치하더라도 정적 에셋에서는 필터가 호출되지 않습니다. 정적 파일은 브라우저에 직접 제공됩니다.

오류 핸들러

배포 설명자를 사용하여 오류가 발생할 때 어떤 서버가 사용자에게 이를 전송할지를 맞춤설정할 수 있습니다. 서버는 특정 HTTP 상태 코드를 전송하려고 할 때 또는 서블릿에서 특정 자바 예외가 발생할 때 대체 페이지 위치를 표시할 수 있습니다.

<error-page> 요소에는 HTTP 오류 코드 값을 포함하는 <error-code> 요소(예: 500) 또는 예상되는 예외의 클래스 이름을 포함하는 <exception-type> 요소(예: java.io.IOException)가 포함됩니다. 또한 오류가 발생할 때 표시할 리소스의 URL 경로가 있는 <location> 요소가 포함됩니다.

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

참고: 현재는 일부 오류 조건에 대해 커스텀 오류 핸들러를 구성할 수 없습니다. 특히 URL에 대해 서블릿 매핑이 정의되지 않았을 때 404 응답 페이지, App Engine 내부 오류 이후 표시되는 500 서버 오류 페이지 또는 403 할당량 오류 페이지를 맞춤설정할 수 없습니다.

지원되지 않는 web.xml 기능

다음 web.xml 기능은 App Engine에서 지원되지 않습니다.

  • App Engine은 서블릿 선언에 대해 <load-on-startup> 요소를 지원합니다. 하지만 부하는 웹 서버 인스턴스에서 처리되는 첫 번째 요청 중에 실제로 발생하며, 그 전에 발생하지 않습니다.
  • 일부 배포 설명자 요소는 IDE에서 사람이 읽을 수 있는 표시 이름, 설명, 아이콘을 사용할 수 있습니다. App Engine은 이러한 항목을 사용하지 않으며, 이를 무시합니다.
  • App Engine은 JNDI 환경 변수(<env-entry>)를 지원하지 않습니다.
  • App Engine은 EJB 리소스(<resource-ref>)를 지원하지 않습니다.
  • 서블릿, 서블릿 컨텍스트 또는 필터 삭제 알림은 지원되지 않습니다.
  • <distributable> 요소는 무시됩니다.
  • <run-at>를 사용한 서블릿 일정 지정은 지원되지 않습니다.
  • 보안 제약조건이 지원되지 않습니다. 이와 동일한 기능은 bookshelf 가이드를 참조하세요.
  • CONFIDENTIAL은 web.xml에서 지원되지 않지만 app.yaml을 수정하여 달성할 수 있습니다.
이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

App Engine flexible environment for Java docs