Javadoc Doclet에서 Fat JAR의 JAXB 런타임 클래스를 찾지 못하는 문제 해결
Javadoc Doclet을 사용하여 문서를 생성할 때 Fat JAR 내의 JAXB 런타임 클래스를 찾지 못하는 문제가 발생할 수 있습니다. 이 문제는 주로 "jakarta.xml.bind.JAXBException: Implementation of JAXB-API has not been found on module path or classpath"라는 오류 메시지와 함께 나타납니다. 이 글에서는 이 문제의 원인과 해결 방법을 살펴보겠습니다.
1. 문제 상황
Fat JAR를 사용하여 프로젝트를 빌드하고 Javadoc을 생성하려고 할 때, Doclet이 JAXB 런타임 클래스를 찾지 못하는 경우가 있습니다. 이는 주로 다음과 같은 상황에서 발생합니다:
- 프로젝트가 Jakarta EE 9 이상을 사용하는 경우
- Fat JAR에 JAXB 구현체가 포함되어 있지만, Javadoc 툴이 이를 인식하지 못하는 경우
- 모듈 경로와 클래스 경로 설정이 올바르지 않은 경우
2. 주요 원인
- 클래스로더 이슈: Javadoc 툴이 사용하는 클래스로더가 Fat JAR 내의 클래스를 로드하지 못함
- 의존성 충돌: 프로젝트 내에서 사용하는 JAXB 버전과 Javadoc 툴이 사용하는 버전 간의 불일치
- 모듈 경로 설정: Java 9 이상에서 모듈 시스템을 사용할 때 발생하는 설정 문제
3. 해결 방법
3.1 명시적으로 JAXB 의존성 추가
Javadoc 생성 시 JAXB 구현체를 명시적으로 클래스패스에 추가합니다:
javadoc -cp path/to/jaxb-runtime.jar:path/to/your-fat.jar ...3.2 Maven을 사용하는 경우
Maven-javadoc-plugin 설정에 JAXB 의존성을 추가합니다:
org.apache.maven.plugins
maven-javadoc-plugin
org.glassfish.jaxb
jaxb-runtime
3.0.0
3.3 Gradle을 사용하는 경우
Gradle javadoc 태스크에 JAXB 의존성을 추가합니다:
javadoc {
options.additionalDependencies = [
'org.glassfish.jaxb:jaxb-runtime:3.0.0'
]
}
4. 추가 팁
- Java 9 이상을 사용하는 경우, --add-modules java.xml.bind 옵션을 Javadoc 명령에 추가해 보세요.
- JAXB 구현체 버전이 프로젝트의 다른 의존성과 호환되는지 확인하세요.
- Fat JAR 생성 시 JAXB 관련 클래스가 제대로 포함되었는지 확인하세요.
결론
Javadoc Doclet에서 Fat JAR의 JAXB 런타임 클래스를 찾지 못하는 문제는 주로 클래스 로딩과 의존성 관리의 문제입니다. 명시적으로 JAXB 의존성을 추가하고, 빌드 도구 설정을 올바르게 조정함으로써 이 문제를 해결할 수 있습니다. 프로젝트의 특성과 사용 중인 Java 버전, 빌드 도구에 따라 적절한 해결 방법을 선택하여 적용하시기 바랍니다.