Javax에서 Jakarta 마이그레이션을 처리하기 위한 모범 사례

자카르타 EE 9+로 성공적으로 곧 업그레이드하기 위해 알아야 할 모든 것을 설명해 드리겠습니다.

이전 버전의 Jakarta EE 또는 Java EE에서 Jakarta EE 9 이상으로 업그레이드하는 것은 javax에서 Jakarta Prefix로 변경하는 것이 다소 어려울 수 있습니다. 일부 라이브러리는 여전히 javax 패키지를 사용하고 있을 수 있으며, 이는 Eclipse GlassFish 7과 같은 Jakarta EE 서버에서 응용 프로그램을 실행하려고 할 때 충돌을 일으킬 수 있습니다. Spring Framework 6 또는 Spring Boot 3, Quarkus 3 및 현재 Jakarta EE 9 API에 의존하는 다른 많은 프레임워크의 새로운 버전으로 업그레이드할 때 동일한 문제가 발생할 수 있습니다.

하지만 걱정하지 마세요, 제가 당신을 보호하고 있습니다! 이 게시물에서 자카르타 EE 9+로 성공적으로 곧 업그레이드하기 위해 알아야 할 모든 것을 설명하겠습니다. 자카르타 EE 9+는 자카르타 EE 9 또는 10을 의미하는데, 이것은 현재 자카르타 EE의 최신 버전입니다.

 

 

Javax에서 Jakarta 마이그레이션을 처리하기 위한 모범 사례

 

 

업그레이드 단계 자동화를 위한 기존 툴

다행히 오픈리라이트(Openrewrite), 윈드업(WindUp), 이클립스 트랜스포머(Eclipse Transformer)와 같은 자유 및 오픈 소스 도구를 사용하여 많은 문제를 자동화할 수 있습니다. 오픈리라이트는 새로운 자카르타 접두사로 오래된 자바스 패키지에 대한 모든 참조를 업데이트하는 등 응용 프로그램의 소스 코드를 자동으로 변경할 수 있는 강력한 도구입니다.

이클립스 트랜스포머는 동일한 작업을 수행할 수 있지만 프로젝트가 아직 소스 코드 변환 준비가 되지 않은 경우 최종 JAR, WAR 또는 EAR 이진 파일을 변환할 수도 있습니다. 이는 자카르타 EE 9+ 런타임에서 이전 응용 프로그램을 실행해보고 싶을 때 유용합니다.

자카르타 EE 9+로 업그레이드할 때 이 모든 도구를 사용하면 시간과 노력을 절약할 수 있으므로 애플리케이션 개발의 다른 중요한 측면에 집중할 수 있습니다. 그러나 이러한 도구를 통해 변경한 내용을 검토하고 테스트하여 의도하지 않은 결과를 초래하지 않도록 해야 합니다.

 

 

Eclipse Transformer를 통한 애플리케이션 전환

애플리케이션이 변경 없이 자카르타 EE 10 런타임으로 마이그레이션될 수 있는지 여부를 신속하게 확인하거나 마이그레이션에 대한 잠재적 문제를 식별할 수 있도록 모든 마이그레이션을 이클립스 트랜스포머로 시작하는 것이 좋습니다. 특히 애플리케이션이 자카르타 EE 9+와 아직 호환되지 않는 종속성에 의존하거나 호환되는 버전으로 업그레이드하는 것이 위험한 경우 마이그레이션의 후반 단계에서도 이클립스 트랜스포머를 사용하는 것이 필수적일 수 있습니다. 결국 자카르타 EE 9+ 런타임으로 애플리케이션을 배포하기 전에 이클립스 트랜스포머로 변환하면 이전 API 패키지에 의존하는 나머지 클래스와 파일을 감지하고 변환하는 안전망으로 작동할 수 있습니다. 애플리케이션의 모든 것이 마이그레이션되었는지 확실하게 확인할 때까지 이클립스 트랜스포머를 계속 사용할 수 있습니다.

OmniFish에서 이클립스 트랜스포머 사용의 용이성을 입증하기 위해 자백스-자카르타-트랜스포머-전면전면전에서 샘플 적용 프로젝트를 준비했습니다. 이 프로젝트는 메이븐 프로젝트 구축에 이클립스 트랜스포머를 적용하는 방법을 보여줍니다.

메이븐 프로젝트에서 변환을 적용하기 위한 핵심 요소는 메이븐 플러그인 트랜스포머-메이븐-플러그인입니다. 이 플러그인을 확장으로 설치한 다음 표준 메이븐 빌드 메커니즘에 연결하여 최종 빌드 아티팩트를 수정할 수 있습니다. 

 

메이븐 플러그인은 다음 두 가지 목표를 제공합니다:

jar – 이 목표는 JAR, WAR, EAR 파일과 같은 응용프로그램 패키지를 변형시킵니다. 응용프로그램 패키지를 제자리에서 수정하거나 변형된 버전을 별도의 파일로 만들 수 있습니다

변환 – 이 목표는 디렉터리를 (JAR, WAR 또는 다른 애플리케이션 패키지로 포장되기 전에) 변환합니다. 앱 서버로 배포되기 전에 분해된 디렉터리에서 사용할 수 있습니다.

 

예제 애플리케이션은 두 플러그인 목표를 모두 사용합니다. jar 목표는 파일을 나중에 배포하거나 메이븐 저장소에 배포하는 데 필요한 최종 아티팩트 파일을 변환하는 데 사용됩니다. 변환 목표는 옵션이며 폭발한 디렉토리를 변환하는 데 사용되며, 이는 개발 중에 여러 IDE에서 애플리케이션을 배포하는 데 자주 사용됩니다. 변환 목표를 사용하면 옵션이지만 자카르타 EE 9로 완전히 마이그레이션될 때까지 IDE에서 애플리케이션을 개발하고 쉽게 배포할 수 있습니다.

메이븐 플러그인으로 사용하는 것 외에도 이클립스 트랜스포머는 명령줄에서도 사용할 수 있으므로 모든 프로젝트 또는 연속 통합 시스템과 함께 사용할 수 있습니다.

명령줄에서 Eclipse Transformer를 실행하려면 먼저 메이븐 센트럴에서 org.eclipse.transformer.cli distribution JAR 파일을 다운로드합니다. 그런 다음, 이 JAR을 예를 들어 트랜스포머라는 이름의 폴더로 언팩합니다. 그런 다음, 다음 명령을 사용하여 응용 프로그램 파일(예: jakarta-ee-8-app.war)을 새 응용 프로그램 파일 jakarta-ee-10-app-transformed.war로 변환할 수 있습니다:

java -jar transformer/org.eclipse.transformer.cli-0.5.0.jar jakarta-ee-8-app.war jakarta-ee-10-app-transformed.war

 

 

변환할 파일이 WAR 파일일 필요는 없습니다. 디렉토리, WAR, JAR 및 이클립스 트랜스포머가 지원하는 여러 패키지 유형일 수 있습니다.

이클립스 트랜스포머 사용법에 대한 자세한 내용은 깃허브 프로젝트의 명령줄에서 확인할 수 있습니다. 하지만 대부분의 경우 다른 것이 필요하지 않습니다. 기본 옵션을 사용하더라도 도구가 매우 잘 작동합니다.

 

 

변환 종속성이 자카르타 접두사와 호환되지 않음

이제 응용 프로그램에서 사용하는 개별 라이브러리를 업그레이드하거나 변환해야 합니다. 이렇게 하면 두 가지 문제가 해결됩니다. 첫째, 각 빌드 후 최종 바이너리를 변환하는 단계를 제거하여 개발 중 응용 프로그램의 빌드 시간을 향상시킵니다. 둘째, 자카르타 EE 9용 응용 프로그램의 소스 코드를 조정한 후 일부 라이브러리에서 직면할 수 있는 컴파일 문제를 해결합니다.

자카르타 EE 9와 호환되는 버전이 있는 라이브러리는 이 버전으로 간단히 업데이트할 수 있습니다. 엔터프라이즈 프로젝트에서 널리 사용되는 대부분의 라이브러리는 이미 자카르타 EE 9를 지원합니다. 그러나 일부 라이브러리는 자카르타 EE 9+ 및 이전 버전의 자카르타 EE 및 자바 EE 버전을 모두 지원합니다. 해당 라이브러리에는 동일한 라이브러리 버전에 대해 두 가지 변형이 있습니다. 자카르타 EE 9+를 지원하는 변형을 선택해야 합니다. 메이븐을 사용하는 경우 대부분의 경우 다음과 같은 자카르타 분류기를 사용해야 합니다:

<dependency>
  <groupId>org.primefaces</groupId>
  <artifactId>primefaces</artifactId>
  <version>13.0.0</version>
  <classifier>jakarta</classifier>
</dependency>

 

 

하지만 모든 도서관이 그렇지는 않습니다. 일부 도서관은 완전히 다른 좌표로 자카르타 EE 9 호환 메이븐 유물을 제공하고 있으며, 이들을 찾기 위해서는 조사가 필요할 것입니다.

라이브러리를 업그레이드할 수 없을 때는 이전 기사에서 설명한 전체 애플리케이션 WAR을 변환하는 것과 유사한 기술을 사용하여 이클립스 트랜스포머를 사용하여 개별 라이브러리를 변환할 수 있습니다. 또한 개별 라이브러리 JAR에서 이클립스 트랜스포머를 사용한 다음, 빌드 중에 변환된 JAR을 사용할 수 있습니다. 그러나 현대 메이븐 또는 그래들 기반 프로젝트에서는 과도 의존성 때문에 이 작업이 간단하지 않습니다. 현재 모든 과도 의존성을 자동으로 변환하여 로컬 저장소에 올바르게 설치할 수 있는 툴링은 없습니다. 그러나 단일 JAR(Uber JAR)로 변환해야 하는 모든 JAR을 모든 과도 의존성과 병합한 다음 변환한 다음 이 단일 JAR을 메이븐 저장소로 설치하는 방법을 사용할 수 있습니다. 그런 다음 변환된 모든 개별 아티팩트에 의존하지 않고 이 단일 아티팩트에 의존하도록 애플리케이션 POM 파일만 변경하면 됩니다.

기존 프로젝트 옆에 새 메이븐 프로젝트(예: 변환 종속성)를 만들어야 합니다. 그런 다음 이 새 프로젝트로 변환하는 데 필요한 모든 종속성을 이동합니다. 그런 다음 원래 프로젝트에서 모든 종속성을 제거하고 새 변환 종속성 프로젝트에 대한 단일 종속성으로 대체합니다.

최종 WAR 파일에서는 WAR에서 각각의 JAR 파일을 별도로 가지는 대신 다음과 같이 설정합니다:

WEB-INF
	classes
		jasperreports.jar
		quartz.jar

 

 

다음과 같은 단일 변환된 JAR로 귀결될 것입니다:

WEB-INF
	classes
		transform-dependencies.jar

 

 

이 transform-dependencies.jar 파일에는 병합된 모든 아티팩트가 포함됩니다. 모든 아티팩트의 모든 클래스와 파일이 포함됩니다.

이를 위해 여러 JAR 파일을 프로젝트에서 생성한 단일 아티팩트로 병합하는 Maven Shade 플러그인을 사용할 수 있습니다:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.5.0</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <shadedClassifierName>jakarta</shadedClassifierName>
        <shadedArtifactAttached>true</shadedArtifactAttached>
        <transformers>
          <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
          <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"/>
        </transformers>
      </configuration>
    </execution>
  </executions>
</plugin>

 

 

이 플러그인은 프로젝트에 정의된 모든 종속성을 가져와 단일 Uber JAR로 병합하고 JAR을 자카르타 분류기와 함께 아티팩트로 프로젝트에 첨부합니다.

이제는 트랜스포머 플러그인을 추가하여 Uber JAR을 트랜스포머하여 자카르타 EE 9+와 호환되도록 구성합니다. 트랜스포머 플러그인을 다음과 같이 구성해야 합니다:

"jar"라는 목표를 실행에 옮기다

자카르타 기본값 규칙을 사용하여 자카르타 EE 9에 대한 변환을 적용합니다

쉐이드 메이븐 플러그인에 의해 생성된 클래스파이어 "자카르타"로 아티팩트를 정의합니다. 이것은 현재 프로젝트와 동일한 groupId, artifactId 및 버전을 가질 것입니다.

 

로컬 메이븐 저장소에서 종속성을 단일 아티팩트로 변환하려면 mvn 설치를 통해 변환 종속성 프로젝트를 한 번만 구축해야 합니다. 원래 애플리케이션 프로젝트를 구축할 때 변환된 우버 JAR을 사용하고 모든 개별(변환되지 않은) JAR 대신 최종 WAR에 추가합니다. 물론 소스 코드가 여전히 자바스 접두사를 사용하기 때문에 컴파일 실패를 초래할 가능성이 높습니다. 이를 해결하기 위한 쉬운 해결책이 있습니다. 다음 섹션에서 설명하겠습니다.

 

 

응용프로그램 원본 코드 변환

예, 소스 코드의 컴파일 오류를 수동으로 수정하거나 간단한 찾기 및 바꾸기 메커니즘을 사용하여 수정할 수 있습니다. 하지만 그렇게 하는 것은 권장하지 않습니다. "javax" 접두사가 붙은 모든 패키지를 변환해야 하는 것은 아닙니다. XML 디스크립터와 같은 리소스 파일도 변환해야 하는 등. 자카르타 EE 9용 코드를 변환하도록 설계된 자동화 도구를 사용하는 것이 훨씬 쉽고 훨씬 더 방탄적입니다.

여기에 도움이 될 수 있는 두 가지 무료 도구가 있습니다:

Eclipse Transformer – 이전에 최종 애플리케이션을 변환하는 데 사용했지만 Java 소스 파일 및 리소스를 변환할 수도 있습니다

Openrewrite – 지정된 규칙에 따라 응용프로그램의 소스 코드를 자동으로 변경할 수 있는 도구. 자카르타 EE 9에 대한 규칙이 들어 있습니다.

 

이 단계에서도 이클립스 트랜스포머를 사용하는 것이 좋습니다. 오픈리라이트보다 자카르타 EE 9에 대한 변환 규칙이 더 완벽하고 오픈리라이트가 무시하는 일부 리소스 파일을 변환할 수 있기 때문입니다. 그러나 Openrewrite를 사용하더라도 결과는 매우 유사합니다. 소스 코드를 대신 사용할 경우 몇 가지 수동 변경만 추가하면 됩니다. 이 두 가지 도구를 모두 사용하는 방법을 설명해 드리겠습니다.

단일 응용 프로그램의 경우 소스 코드를 한 번만 변환해야 합니다. 이 단계에서만 프로젝트 구성을 변경할 가치가 없습니다. 따라서 프로젝트에 메이븐 플러그인이나 구성을 추가하지 않고 명령줄에서 이클립스 트랜스포머를 사용하는 방법을 설명합니다. 이는 메이븐 이외의 다른 빌드 도구(예: 그래들)를 사용할 경우 이 절차를 적용할 수 있음을 의미합니다.

다음 단계에 따라 응용프로그램의 소스 코드를 변환합니다:

• 메이븐 센트럴에서 이클립스 트랜스포머 CLI 배포 아티팩트를 다운로드하십시오. 일반 jar 파일이 아닌 최신 버전의 distribution.jar 파일을 다운로드하십시오. 0.5.0 버전의 경우 직접 다운로드 링크: org.eclipse.transformer.cli-0.5.0-distribution.jar
• JAR 파일을 일부 디렉토리(예: /path/to/transformer)에 언팩합니다
• 응용프로그램의 프로젝트 디렉토리로 이동합니다.
• src 디렉토리(소스 코드, 리소스, 테스트 코드 및 리소스 등 포함)를 output_src 디렉토리로 변환하려면 다음을 실행합니다. java-jar /path/to/transformer/org.eclipse.cli-0.5.0.jar src
• output_src 디렉토리의 내용을 src(오버라이트 파일)로 이동합니다. Linux 및 Mac OS에서는 rsync 명령줄 도구를 사용할 수 있습니다. rsync -a output_src/* src
• Eclipse Transformer는 다음 작업을 수행하지 않으므로 pom.xml을 수동으로 편집합니다:
• 프로젝트가 다음 종속성(또는 동등한 웹 프로파일 또는 핵심 프로파일 종속성)에 의존하도록 자카르타 EE 버전을 9.0.0 또는 10.0.0으로 늘립니다:

<dependency>
<groupId>jakarta.platform</groupId>
<artifactId>jakarta.jakartaee-api</artifactId>
<version>10.0.0</version>
<scope>provided</scope>
</dependency>

 

 

Eclipse Transformer를 사용하는 대신 Openrewrite를 사용하여 애플리케이션 소스 코드를 자카르타 EE 9와 호환되도록 변환할 수 있습니다.

OpenRewrite를 적용하는 것은 매우 쉽습니다. 이미 Maven을 설치한 상태라면 명령줄에 구성된 Maven 플러그인으로 사용할 수 있습니다(프로젝트가 Maven 기반일 필요는 없으며 Maven은 변환 실행에만 필요합니다):

응용프로그램의 프로젝트 디렉토리로 이동

다음 명령을 실행합니다:

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:LATEST \
-Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta

 

 

그러면 응용 프로그램이 수정될 것입니다. 이론적으로는 지금 빌드가 가능해야 하며 모든 것이 예상대로 작동해야 합니다. 하지만 경험을 바탕으로 메이븐 기반의 WAR 프로젝트에서 몇 가지 수정 사항을 pom.xml, web.xml 및 자바 주석에 적용해야 했는데, 이클립스 트랜스포머를 사용한 후에는 수정할 필요가 없었습니다.

 

 

결론

이러한 단계를 수행한 후,  애플리케이션은 자카르타 EE 9와 완전히 호환되어야 합니다. 변환되지 않은 종속성이 모두 자카르타 EE 9와 호환된다면, 당신은 빌드 시간을 절약하기 위해 당신의 최종 애플리케이션의 변환을 제거할 수 있습니다.

이 세 단계를 수행해야 했습니다:

• (선택적 단계) Eclipse Transformer를 사용하여 최종 응용 프로그램을 변환하고 자카르타 EE 9+ 서버 또는 프레임워크에서 실행되는지 테스트합니다.
• 종속성을 자카르타 EE 9와 호환되는 버전으로 업그레이드합니다.
• 의존성을 자카르타 EE 9로 업그레이드할 수 없는 경우 Eclipse Transformer를 사용하여 변환합니다.
• Eclipse Transformer 또는 OpenRewrite를 사용하여 응용 프로그램 소스 코드를 변환합니다.
• (선택적 단계) 최종 응용프로그램의 변환을 제거합니다.

 

이 모든 단계를 완료한 후에는 지금 애플리케이션을 구축할 수 있어야 합니다. 자카르타 EE 9+ 서버에 배포하거나 원하는 프레임워크로 실행하면 성공적으로 컴파일되고 잘 작동할 것입니다. 프로젝트가 자카르타 EE 9+로 완전히 변환되어 처음부터 자카르타 EE 9+를 위해 설계된 것처럼 이전처럼 작업을 계속할 수 있습니다.