[JSP/Servlet] The method getServletContext() is undefined 에러 원인 및 해결 방법 (Maven pom.xml 설정)

잘 따라 쳤는데 왜 빨간 줄이 생길까?
JSP나 서블릿(Servlet) 환경에서 웹 사이트의 루트 디렉터리 실제 물리적 경로를 알아내기 위해, 혹은 파일 업로드 경로를 설정하기 위해 아래와 같은 코드를 작성해 본 적이 있으실 겁니다.

// 웹사이트 루트 디렉토리의 실제 디스크 경로 알아내기 String path = request.getServletContext().getRealPath("upload");

 

그런데 코드를 똑같이 작성했는데도 불구하고, 이클립스(Eclipse)나 STS(Spring Tool Suite)에서 request.getServletContext() 부분에 빨간 줄이 그어지며 다음과 같은 에러 메시지가 뜨는 경우가 있습니다.

오류 메시지:
The method getServletContext() is undefined for the type HttpServletRequest

"HttpServletRequest 타입에는 그런 메서드가 정의되어 있지 않다"는 뜻인데요. 오늘은 이 에러가 도대체 왜 발생하는지 정확한 원인을 알아보고, 상황에 맞는 2가지 해결 방법을 깔끔하게 정리해 보겠습니다.

 

---

1. 에러 발생 원인: Servlet 스펙 버전의 차이
이 에러의 원인은 아주 명확합니다. 바로 서블릿(Servlet) 버전의 차이 때문입니다.

HttpServletRequest 객체에서 getServletContext() 함수를 직접 호출하는 기능은 Servlet 3.0 스펙부터 새롭게 추가된 기능입니다.
서블릿 3.0 스펙은 Apache Tomcat 7.0 이상의 버전부터 지원합니다. 따라서 현재 프로젝트에 설정된 서블릿 API 버전이 2.5 이하이거나, 톰캣 6.0 이하의 버전을 사용하고 있다면 이클립스가 해당 메서드를 찾지 못해 에러를 뱉어내는 것입니다.

---

2. 해결 방법 1: 하위 버전(Tomcat 6 이하)에서의 우회 방법
만약 서버 환경을 당장 톰캣 7 이상으로 올릴 수 없는 레거시 환경(Servlet 2.5 이하)이라면, request 객체를 통하지 않고 우회해서 컨텍스트를 가져오는 방법을 사용할 수 있습니다.

JSP 문서나 서블릿 파일 내부에서 request. 부분을 빼고, 그냥 getServletContext() 메서드만 단독으로 호출하면 됩니다.

// Servlet 2.5 이하 환경에서의 사용법 (request 객체 없이 바로 호출) String path = getServletContext().getRealPath("upload");

 

원리 설명: 여기서 단독으로 호출한 getServletContext()는 HttpServletRequest에 있는 것이 아니라, 서블릿의 최상위 부모 클래스 중 하나인 GenericServlet 클래스에 이미 정의되어 있는 메서드를 상속받아 사용하는 것입니다. 따라서 하위 버전의 톰캣(Tomcat 6 등)에서도 아무런 에러 없이 정상적으로 작동합니다.

 

---

3. 해결 방법 2: Maven (pom.xml) 의존성 업데이트 (권장)
최근 개발 환경에서는 대부분 톰캣 8.0 이상과 Servlet 3.0 이상을 사용합니다. 특히 STS(Spring Tool Suite)를 이용해 기본 WEB_MVC 프로젝트를 생성하면, pom.xml에 구버전인 Servlet 2.5로 기본 세팅이 되어 있어 이 에러를 자주 만나게 됩니다.

이때는 Maven 설정 파일인 pom.xml을 수정하여 서블릿 라이브러리 버전을 3.0 이상으로 올려주면 됩니다. 하지만 여기서 아주 주의해야 할 함정이 하나 있습니다.

 

※흔히 하는 실수 (Missing artifact 에러)
기존 pom.xml을 보면 아래와 같이 설정되어 있습니다.

groupId: javax.servlet

artifactId: servlet-api

version: 2.5

단순히 버전만 올리면 되겠지 생각해서 <version>3.0</version>으로 숫자만 덜렁 바꾸게 되면, Missing artifact javax.servlet:servlet-api:jar:3.0 이라는 새로운 라이브러리 다운로드 에러가 발생합니다.

 

●올바른 Servlet 3.0 이상 Maven 설정법
서블릿 3.0부터는 메이븐 중앙 저장소(Maven Central Repository)에 등록된 artifactId 이름 자체가 변경되었습니다. 기존 servlet-api에서 **javax.servlet-api**로 변경해 주어야 정상적으로 라이브러리를 가져옵니다.

pom.xml의 Servlet 의존성 부분을 아래 코드로 완전히 교체해 줍니다.

 

<dependency>     <groupId>javax.servlet</groupId>     <artifactId>javax.servlet-api</artifactId>  <version>3.0.1</version>     <scope>provided</scope> </dependency> <dependency>     <groupId>javax.servlet.jsp</groupId>     <artifactId>jsp-api</artifactId>     <version>2.2</version>     <scope>provided</scope> </dependency>

설정을 완료하고 저장한 뒤, 프로젝트를 우클릭하여 [Maven] -> [Update Project]를 한 번 실행해 주시면 지긋지긋하던 빨간 줄이 마법처럼 사라지는 것을 볼 수 있습니다!