HeadlessException 클래스

키보드, 디스플레이 또는 마우스에 의존하는 코드가 그런 장치를 지원하지 않는 환경에서 호출될 때 던져져요. 이 장치들 중 하나에 의존하는 코드는 먼저 GraphicsEnvironment.isHeadless() 메서드로 가용성을 확인하고, true를 반환하면 HeadlessException을 던져야 해요.

출처: Java API Reference

본문

헤드리스(headless) 환경은 디스플레이·키보드·마우스가 없는 환경이에요. 전형적으로 서버·CI 환경처럼 GUI가 없는 곳에서 발생해요. Frame, Dialog 같은 GUI 컴포넌트를 만들거나 화면 관련 기능을 사용하려 할 때 이 예외가 던져져요.

public class HeadlessException
extends UnsupportedOperationException

런타임 예외

UnsupportedOperationException을 상속하므로 체크 예외가 아니에요. 하지만 GUI 코드를 실행하기 전에 헤드리스 여부를 확인해서 예외를 예방하는 게 좋아요.

if (GraphicsEnvironment.isHeadless()) {
    // GUI를 만들 수 없으므로 다른 방식 처리
    throw new HeadlessException("GUI가 지원되지 않는 환경입니다.");
}

주요 생성자

HeadlessException() — 상세 설명 없이 예외를 만들어요.
HeadlessException(String msg) — 지정한 상세 설명으로 예외를 만들어요.

예방 방법

GraphicsEnvironment.isHeadless()로 확인하거나, GraphicsEnvironment.isHeadlessInstance()를 사용해 현재 환경에서 GUI가 가능한지 미리 검사해요. 헤드리스 환경에서도 폰트 조회나 이미지 처리는 가능한 경우가 많아요.

HeadlessException 클래스