WEB WAS OS APM
#EAP7#JBoss#Troubleshooting

[JBoss EAP 7] 마이그레이션 이슈 해결: Apache CXF 라이브러리 충돌 (WFLYWS0059)

JBoss EAP 6.4에서 7.x로 마이그레이션 시, 애플리케이션에 포함된 Apache CXF 라이브러리와 JBoss 내부의 WebServices 서브시스템이 충돌하여 배포가 실패하는 현상(WFLYWS0059)을 해결합니다. jboss-deployment-structure.xml을 통한 모듈 제외(Exclude) 설정을 다룹니다.

1. 문제 현상 및 로그 분석 (Issue)

기존 EAP 6에서는 잘 돌던 애플리케이션이 EAP 7 배포 시 PARSE 단계에서 실패하며 아래와 같은 에러를 뱉어냅니다.

에러 로그

WFLYSRV0153: Failed to process phase PARSE of deployment "sso.war"
Caused by: org.jboss.as.server.deployment.DeploymentUnitProcessingException: 
WFLYWS0059: Apache CXF library (cxf-api-2.7.8.jar) detected in ws endpoint deployment; 
either provide a proper deployment replacing embedded libraries with container module dependencies 
or disable the webservices subsystem for the current deployment adding a proper jboss-deployment-structure.xml descriptor to it.

원인 분석

  • JBoss EAP 7: 기본적으로 최신 Apache CXF 기반의 WebServices 서브시스템을 로드합니다.
  • 애플리케이션: WEB-INF/lib 안에 자체적인 CXF 라이브러리(예: cxf-api-2.7.8.jar)를 포함하고 있습니다.
  • 충돌: JBoss는 애플리케이션이 자체 라이브러리 대신 컨테이너가 제공하는 모듈을 사용하길 권장하며, 중복이 감지되면 배포를 중단시킵니다.

2. 해결 방법 (Resolution)

애플리케이션이 JBoss의 WebServices 기능을 사용하지 않고, "내가 가진 라이브러리를 쓰겠다"고 선언해야 합니다. 이를 위해 jboss-deployment-structure.xml 파일을 생성하여 컨테이너의 특정 서브시스템을 비활성화합니다.

설정 파일 위치

  • WAR 파일: WEB-INF/jboss-deployment-structure.xml
  • EAR 파일: META-INF/jboss-deployment-structure.xml

작성 내용

JBoss의 webservices와 jaxrs 서브시스템을 제외(exclude)하고, 필요한 기본 API만 의존성(dependencies)으로 추가합니다.

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
    <deployment>
        
        <!-- 1. JBoss 내부 서브시스템 비활성화 -->
        <exclude-subsystems>
            <!-- JBoss의 CXF 모듈이 로드되지 않도록 차단 -->
            <subsystem name="webservices" />
            <!-- RESTful 서비스 충돌 방지 (필요 시) -->
            <subsystem name="jaxrs" />
        </exclude-subsystems>
        
        <!-- 2. 필수 API 의존성 추가 -->
        <!-- 서브시스템은 뺐지만, 기본적인 Java EE API는 필요하므로 명시적 로드 -->
        <dependencies>
            <module name="javax.xml.ws.api"/>
            <module name="javax.jws.api"/>
        </dependencies>
        
    </deployment>
</jboss-deployment-structure>

3. 적용 결과 및 주의사항

  • 결과: 위 파일을 추가하고 재배포하면, JBoss는 해당 애플리케이션에 대해 WebServices 서브시스템 초기화를 건너뛰고 WEB-INF/lib 내의 jar 파일들을 우선적으로 로딩합니다.
  • 주의: 이 방식을 사용하면 JBoss 관리 콘솔에서 제공하는 웹 서비스 모니터링이나 관리 기능을 해당 애플리케이션에 대해서는 사용할 수 없게 됩니다. (애플리케이션 자체 프레임워크인 Spring-CXF 등이 전적으로 처리함)
Comments