2.1.1 Jakarta EEのパッケージ名

変更内容

Jakarta EE 8以前で使用されたjavaのパッケージ名、プロパティ名の名前空間は、Jakarta EE 9以降、javaxからjakartaに変更されました。

例

クラスjavax.servlet.http.HttpServletは、Jakarta EE 9以降ではjakarta.servlet.http.HttpServletという完全限定名になっています。

プロパティjavax.servlet.request.cipher_suiteは、Jakarta EE 9以降ではjakarta.servlet.request.cipher_suiteというキー名で利用する必要があります。

非互換

Jakarta EE 8以前のJava資産(Javaのソースファイル、またはビルドしてできたjarファイル、warファイルなど)を本製品で使うには、Java資産を配備・実行する前に、Java資産に含まれるパッケージ名・プロパティ名をjavaxからjakartaに変換する必要があります。

注意

Java SEのjavaxパッケージ(javax.net、javax.sql等）はjakartaに変更されていないため、変換しないでください。

なお、web.xmlなどのdeployment descriptorのスキーマも、Jakarta EE 8以前で使用されていた"http://xmlns.jcp.org/xml/ns/javaee/"および"http://java.sun.com/xml/ns/javaee/"から、Jakarta EE 9以降では"https://jakarta.ee/xml/ns/jakartaee"に変更されています。

注意

ただし、Jakarta EE 9以降で導入されたdeployment descriptorの新しいタグや属性を利用する場合を除き、Jakarta EE 8以前で使用されていたスキーマも継続利用することはできるため、deployment descriptorのスキーマの変換は必須ではありません。

変換対象の資産は、保守の観点からバイナリー(jar、warなどのJakarta EEのアーカイブファイル)ではなくソースを変換することをお勧めします。ソースを対象にパッケージ名やプロパティ名を変換するという方法で、変換後のソースを管理してソースとバイナリーの整合性を維持することができ、保守性を高めることができます。しかし何かしらの理由によりソースを対象に変換ができない場合には、後述する方法でバイナリーも変換できます。

対処方法

OSSのツール「Eclipse Transformer」のバイナリー(jarファイル)をダウンロードして実行し、名前空間を変換する方法について説明します。

注意

OSSの利用については、適用された使用条件(ライセンス条件)に従い、お客様の責任において入手、ご利用ください。
以降の説明は、Eclipse Transformer 0.5.0 2022年6月30日ビルド版のバイナリー(org.eclipse.transformer.cli-0.5.0-20220630.153847-40-distribution.jar)に基づいています。

Eclipse Transformerの変換対象は、以下のとおりです。

対象のファイル形式

単体のファイル
- classファイル
- javaファイル
- xmlファイル
- propertiesファイル
- JSP関連のファイル(.jsp、.tag、.tld)
- Jakarta EEのdeployment descriptorやプロパティファイル
- jarファイルのMETA-INFに格納されているService Loaderの設定ファイル
Jakarta EEのアーカイブファイル(war、jar、rar、ear)
上記を格納したディレクトリーやzipファイル

ファイルの変更箇所

classファイル内のJakarta EEのjavaxパッケージ名、プロパティ名
テキスト形式のファイル内のJakarta EEのjavaxパッケージ名、プロパティ名
Service Loaderの設定ファイルのファイル名
deployment descriptorの以下の名前空間、対応するスキーマおよびバージョン
- http://xmlns.jcp.org/xml/ns/javaee
- http://xmlns.jcp.org/xml/ns/persistence

例

input.warが以下のファイル構成の場合

index.jsp
META-INF/
  MANIFEST.MF
WEB-INF/
  classes/
    com/
      example/
        SampleApplication.java
        SampleApplication.class
        Hello.java
        Hello.class
  lib/
    sample.jar
  web.xml

input.warに含まれるsample.jarが以下のファイル構成の場合

META-INF/
  MANIFEST.MF
  services/
    javax.servlet.ServletContainerInitializer
com/
  example/
    SampleStarter.java
    SampleStarter.class

Eclipse Transformerにinput.warを入力として与えると、warファイル内の各ファイル(index.jsp、MANIFEST.MF、SampleApplication.java、SampleApplication.class、Hello.java、Hello.class、web.xml)に含まれるJakarta EEのパッケージ名がjavaxからjakartaに変換されたwarファイルが出力されます。なお、sample.jar内に含まれるMANIFEST.MF、SampleStarter.java、SampleStarter.classも変換されます。javax.servlet.ServletContainerInitializerファイルは、ファイル名がjakarta.servlet.ServletContainerInitializerに変換されます。

変換前のSampleApplication.java

package com.example;
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/api")
public class SampleApplication extends Application {
}

変換後のSampleApplicatin.java

package com.example;
import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("/api")
public class SampleApplication extends Application {
}

Eclipse Transformerの詳細については、以下を参照してください。

参照

Eclipse Transformer

https://projects.eclipse.org/projects/technology.transformer

https://github.com/eclipse/transformer

注意

Jakarta Connectors の deployment descriptor (ra.xml) も変換対象ですが、以下の場合、XMLの検証に失敗し、変換後のコネクタモジュールの配備に失敗することがあります。
- 変換前の ra.xml のルート要素に指定する名前空間にhttp://java.sun.com/xml/ns/javaeeまたはhttp://java.sun.com/xml/ns/j2eeが含まれる場合、かつ
- 以下の要素が含まれる場合
```
<authentication-mechanism> 
     : 
   <credential-interface> 
     javax.resource.spi.security.PasswordCredential 
      または、 
     javax.resource.spi.security.GenericCredential 
   </credential-interface> 
     : 
</authentication-mechanism> 
```
この場合、ra.xmlのルート要素に指定する名前空間や対応するスキーマ、バージョン属性を、jakartaパッケージに対応したものに修正してください。
＜修正例＞
```
<connector xmlns="https://jakarta.ee/xml/ns/jakartaee"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
           https://jakarta.ee/xml/ns/jakartaee/connector_2_1.xsd"
           version="2.1">
```
Jakarta BatchのジョブXMLの名前空間およびバージョンは、Eclipse Transformerの変換対象外です。jarファイルのMETA-INF/batch-jobs配下やwarファイルのWEB-INF/classes/META-INF/batch-jobs配下にジョブXMLが格納されている場合は、「2.1.6 ジョブXMLの名前空間およびバージョン」を参照して、名前空間とバージョンを変更してください。

Eclipse Transformerの変換対象外となっているファイルでも、以下のファイルは動作させるために変換が必要になる場合があります。「Eclipse Transformerがデフォルトで変換対象としていないファイルを変換する場合」の内容を参考に、必要なファイルは変換してください。
- xhtmlファイル
- 拡張子が.jsp、.tag以外のJSPとして使用するファイル

xmlファイルに含まれるパッケージ名は変換対象のため、build.xmlに記載されたjarファイル名やpom.xmlのartifactIdに含まれているパッケージ名も変換します。この時、jarファイル名に含まれているバージョンや、pom.xmlのartifactIdに対応するversionタグの値は変換されません。Eclipse Transformerによる変換対象にこれらのファイルを含めた場合、変換後に適切なバージョンに修正してください。

Jakarta EE 8以前のアプリケーションでJakarta Batchを使用していると、データベースにJakarta EEのjavaxパッケージ名が自動的に登録される場合があります。そのため、Jakarta EE 8以前の実行環境で使用していたデータベースをそのまま流用すると、アプリケーションの処理やasadminコマンドなどの運用操作に失敗する可能性があります。Eclipse Transformerではデータベースに登録されたパッケージ名を置換することができないため、Jakarta EE 8以前の実行環境で使用していたデータベースを使用する場合は、データベースのテーブルを作り直してください。
同様に、アプリケーションで独自にJakarta EEのjavaxパッケージをデータベースに登録している場合も、必要に応じてデータベースのテーブルを作り直してください。

Eclipse Transformerを利用した名前空間の変更手順

Eclipse Transformerのアーカイブファイルをダウンロードする
1. WebブラウザーでEclipse Transformer project(https://projects.eclipse.org/projects/technology.transformer)にアクセスします。
2. 「Downloads」タブの中の「Sonatype OSS Snapshots」のハイパーリンクをクリックします。
3. 表示されたページ内の「org.eclipse.transformer.cli/」のハイパーリンクをクリックします。
4. 「(バージョン)-SNAPSHOT」というハイパーリンク（例: 0.5.0-SNAPSHOT）があるので、最新バージョンをクリックします。
5. "org.eclipse.transformer.cli-(バージョン)-distribution.jar"ファイルのうち最新のファイルをダウンロードします。このアーカイブファイルの中にEclipse Transformer本体、および必要なライブラリーファイルが含まれています。
  例
  0.5.0-SNAPSHOT/org.eclipse.transformer.cli-0.5.0-20220630.153847-40-distribution.jar
なお、本製品の提供後、ダウンロード可能なURLが変更になることがあります。
Eclipse Transformerのアーカイブファイルを展開する
1.で取得したEclipse Transformerのアーカイブファイル "org.eclipse.transformer.cli-(バージョン)-distribution.jar"に対してjarコマンドを実行し、カレントディレクトリーにEclipse Transformerの本体のjarファイル"org.eclipse.transformer.cli-(バージョン)-SNAPSHOT.jar"、およびライブラリーファイル(libsディレクトリー)を展開します。
実行例
```
> C:\eapf\openjdk\jdk11\bin\jar xf org.eclipse.transformer.cli-0.5.0-20220630.153847-40-distribution.jar
```
```
# /opt/FJSVeapf/openjdk/jdk11/bin/jar xf org.eclipse.transformer.cli-0.5.0-20220630.153847-40-distribution.jar
```
Eclipse Transformerを実行する
以下のファイルを準備します。
- 2.で展開したEclipse Transformer本体およびライブラリーファイルの一式
- 変換処理対象のファイルまたはディレクトリー
その後、次のコマンドによりEclipse Transformerを実行すると、変換処理が実行されます。
```
java -jar org.eclipse.transformer.cli-(バージョン)-SNAPSHOT.jar inputfile [outputfile] [オプション]
```
引数には、以下を指定します。
inputfile
変換処理対象のファイルまたはディレクトリーのパスを指定します。
outputfile
変換処理により出力するファイルまたはディレクトリーのパスを指定します。
outputfileを指定しなかった場合、inputfileのファイル名の前に「output_」が付与されたファイルまたはディレクトリーがinputfileと同じディレクトリー配下に出力されます。
注意
inputfile、outputfileに指定するパスの種別（フォルダーやディレクトリー、ファイル）は、一致させてください。inputfile、outputfileに異なる種別を指定した場合、不正な場所にファイルを出力する、または変換が異常終了する場合があります。
拡張子が.txtのファイルなど、Eclipse Transformerが変換対象としていないファイルをinputfileに直接指定すると異常終了するため、直接指定しないでください。warなどのアーカイブファイルやディレクトリーにEclipse Transformerが変換対象としていないファイルが含まれている場合は、問題ありません。
引数の数や値のバリデーションが行われない場合があるため、変換結果が期待通りでない場合は、指定した引数が正しいか確認してください。
指定可能なオプションについては、以下を参照してください。
- https://github.com/eclipse/transformer
- -hオプション(help)をつけて実行して表示される説明
```
java -jar org.eclipse.transformer.cli-(バージョン)-SNAPSHOT.jar -h
```
オプションの指定は、以下の場合に必要になります。
javaファイルやjspファイルなどのテキストで書かれたファイルが、UTF-8以外の文字コードでエンコードされている場合、またはzipファイルのエントリーがUTF-8以外の文字コードでエンコードされている場合
Eclipse Transformerは、UTF-8でファイルの入出力をします。
UTF-8以外でエンコードされているファイルを扱う場合は、jakarta-selection.propertiesファイルの末尾にファイルと文字コードのマッピング(=の左が対象となるファイル名、=の右側に文字コード)を追記し、-tsオプションにjakarta-selection.propertiesファイルを指定してください。
jakarta-selection.propertiesファイルの準備方法は、以下の通りです。
1. ライブラリーファイルを展開する
  「2. Eclipse Transformerのアーカイブファイルを展開する」で展開したディレクトリーの中にある、"libs/org.eclipse.transformer.jakarta-(バージョン)-SNAPSHOT.jar"ファイルに対してjarコマンドを実行し、jarファイルを展開します。すでに展開済みの場合は、本手順は不要です。
  実行例
```
> C:\eapf\openjdk\jdk11\bin\jar xf libs\org.eclipse.transformer.jakarta-0.5.0-SNAPSHOT.jar
```
```
# /opt/FJSVeapf/openjdk/jdk11/bin/jar xf libs/org.eclipse.transformer.jakarta-0.5.0-SNAPSHOT.jar
```
2. jakarta-selection.propertiesファイルを編集する
  1.の操作をすると、org/eclipse/transformer/jakarta/jakarta-selection.propertiesが展開されます。このファイルの末尾に、UTF-8で扱うファイルのマッピングと、UTF-8以外の文字コードで扱うファイルのマッピングを追記します。記載方法の詳細は、jakarta-selection.propertiesファイルのコメントを参照してください。
  例
  javaファイルがMS932でエンコードされている場合に、-tsオプションに指定するjakarta-selection.propertiesファイル
  「*=UTF-8」を省略するとjavaファイル以外が変換されなくなってしまうため、記載が必要です。
```
*=UTF-8
*.java=MS932
```
  例
  zipファイルのエントリーがMS932でエンコードされている場合(日本語のWindows環境で作成された場合)に、-tsオプションに指定するjakarta-selection.propertiesファイル
  「*=UTF-8」を省略するとzipファイル以外が変換されなくなってしまうため、記載が必要です。
```
*=UTF-8
*.zip=MS932
```
Eclipse Transformerがデフォルトで変換対象としていないファイルを変換する場合
Eclipse Transformerがデフォルトで変換対象としていないファイルを変換する場合は、jakarta-text-master.propertiesファイルの末尾に、ファイルと変換内容のマッピング(=の左側に変換対象のファイル名や拡張子名、=の右側に変換ルールを記載したルールファイル名)を追記し、-tfオプションにjakarta-text-master.propertiesファイルを指定してください。
jakarta-text-master.propertiesファイルの準備方法は、以下の通りです。
1. ライブラリーファイルを展開する
  「2. Eclipse Transformerのアーカイブファイルを展開する」で展開したディレクトリーの中にある、"libs/org.eclipse.transformer.jakarta-(バージョン)-SNAPSHOT.jar"ファイルに対してjarコマンドを実行し、jarファイルを展開します。すでに展開済みの場合は、本手順は不要です。
  実行例
```
> C:\eapf\openjdk\jdk11\bin\jar xf libs\org.eclipse.transformer.jakarta-0.5.0-SNAPSHOT.jar
```
```
# /opt/FJSVeapf/openjdk/jdk11/bin/jar xf libs/org.eclipse.transformer.jakarta-0.5.0-SNAPSHOT.jar
```
2. jakarta-text-master.propertiesファイルを編集する
  1.の操作をすると、org/eclipse/transformer/jakarta/jakarta-text-master.propertiesが展開されます。このファイルの末尾に、=の左側に変換対象のファイル名や拡張子名を、右側に"jakarta-direct.properties,jakarta-renames.properties"を追記します。記載方法の詳細は、jakarta-text-master.propertiesファイルのコメントを参照してください。
  例
  拡張子がxhtmlのファイルでJakarta EEのパッケージを使用している場合に、-tfオプションに指定するjakarta-text-master.propertiesファイルの追記内容
```
*.xhtml=jakarta-direct.properties,jakarta-renames.properties
```
Eclipse Transformerの処理によってパッケージ名の変換が正しく行われたかどうかは、以下のメッセージがコマンドの標準出力の最後に出力されているかで判断できます。
```
[main] INFO Transformer - [ Content changes ]: [ 数値 ]
[main] INFO Transformer - Transformer Return Code [ 0 ] [ Success ]
```
変換処理対象のファイルにjavaxパッケージが含まれておらず、変換が行われなかった場合は、以下のメッセージがコマンドの標準出力の最後に出力されます。
```
[main] INFO Transformer - [ No changes ]: [ 0 ]
[main] INFO Transformer - Transformer Return Code [ 0 ] [ Success ]
```
なお、jar、war、rar、earファイルやzipファイル、ディレクトリーを変換処理対象に指定した場合、以下のメッセージが出力されます。
```
[main] INFO Transformer - [  All Resources ] [ 数値 ] Unaccepted [ 数値 ]   Accepted [ 数値 ]
[main] INFO Transformer - [  All Unchanged ] [ 数値 ]     Failed [ 数値 ] Duplicated [ 数値 ]
[main] INFO Transformer - [    All Changed ] [ 数値 ]    Renamed [ 数値 ]    Content [ 数値 ]
[main] INFO Transformer - Transformer Return Code [ 0 ] [ Success ]
```
注意
メッセージの出力形式は、OSSで変更される可能性があるため、メッセージの内容に依存した処理を作ることはおすすめしません。
実行例
Eclipse Transformer本体およびライブラリーファイルをカレントディレクトリーに配置して、変換処理対象のファイルとしてC:\work\input.warを入力し、変換処理後のファイルはC:\work\output.warに出力する場合
```
> C:\eapf\openjdk\jdk11\bin\java -jar org.eclipse.transformer.cli-0.5.0-SNAPSHOT.jar C:\work\input.war C:\work\output.war
```
jakarta-selection.propertiesファイルに指定した文字コードで、warファイルを変換する場合
```
> C:\eapf\openjdk\jdk11\bin\java -jar org.eclipse.transformer.cli-0.5.0-SNAPSHOT.jar C:\work\input.war C:\work\output.war -ts org\eclipse\transformer\jakarta\jakarta-selection.properties
```
jakarta-text-master.propertiesファイルに指定したルールで、warファイルを変換する場合
```
> C:\eapf\openjdk\jdk11\bin\java -jar org.eclipse.transformer.cli-0.5.0-SNAPSHOT.jar C:\work\input.war C:\work\output.war -tf org\eclipse\transformer\jakarta\jakarta-text-master.properties
```
Eclipse Transformer本体およびライブラリーファイルをカレントディレクトリーに配置して、変換処理対象のファイルとして/work/input.warを入力し、変換処理後のファイルは/work/output.warに出力する場合
```
# /opt/FJSVeapf/openjdk/jdk11/bin/java -jar org.eclipse.transformer.cli-0.5.0-SNAPSHOT.jar /work/input.war /work/output.war
```
jakarta-selection.propertiesファイルに指定した文字コードで、warファイルを変換する場合
```
# /opt/FJSVeapf/openjdk/jdk11/bin/java -jar org.eclipse.transformer.cli-0.5.0-SNAPSHOT.jar /work/input.war /work/output.war -ts org/eclipse/transformer/jakarta/jakarta-selection.properties
```
jakarta-text-master.propertiesファイルに指定したルールで、warファイルを変換する場合
```
# /opt/FJSVeapf/openjdk/jdk11/bin/java -jar org.eclipse.transformer.cli-0.5.0-SNAPSHOT.jar /work/input.war /work/output.war -tf org/eclipse/transformer/jakarta/jakarta-text-master.properties
```
変換後のアプリケーションの動作を確認する
ソースコードを変換した場合、Eclipse Transformerの実行によって出力されたファイルまたはディレクトリーに含まれるアプリケーションのソースコードをコンパイルしてアプリケーションを作成し、本製品に配備してアプリケーションの動作を確認してください。
jar、warなどのJakarta EEのアーカイブファイルを変換した場合、Eclipse Transformerの実行によって出力されたファイルまたはディレクトリーを本製品に配備してアプリケーションの動作を確認してください。

メッセージの対処

注意

メッセージの出力形式は、OSSで変更されて以下に示す通りにならない可能性があります。

ERROR Transformer - Output already exists [ {0} ]

[可変情報]

{0}:出力ファイルのパス

[意味]

出力ファイルがすでに存在します。

[ユーザーの対処]

引数outputfileには、存在しないファイル名を指定してください。

引数outputfileの指定を省略した場合は、output_から始まるファイルが存在しないか確認してください。

ERROR Transformer - Input does not exist [ {0} ] [ {1} ]

[可変情報]

{0}:入力ファイルのパス

{1}:入力ファイルの絶対パス

[意味]

入力ファイルが存在しません。

[ユーザーの対処]

引数inputfileの指定に誤りがないか、確認してください。
入力ファイルに権限がついているか、確認してください。

ERROR Transformer - Transform failure:
org.eclipse.transformer.TransformException: Failed to read [ {0} ]

[可変情報]

{0}:入力ファイルのパス

[意味]

入力ファイルの読み込みができませんでした。

[ユーザーの対処]

引数inputfileの指定に誤りがないか、確認してください。
入力ファイルに権限がついているか、確認してください。

ERROR Transformer - Transform failure:
org.eclipse.transformer.TransformException: Failed to write [ {0} ]

[可変情報]

{0}:出力ファイルのパス

[意味]

出力ファイルの書き込みができませんでした。

[ユーザーの対処]

引数outputfileの指定に誤りがないか、確認してください。
出力先のディレクトリーに権限がついているか、確認してください。
出力ファイル名または出力ディレクトリー名の親ディレクトリーが存在するか、確認してください。

ERROR Transformer - Unexpected failure

[意味]

予期せぬ例外が発生しました。

[ユーザーの対処]

java.lang.UnsupportedOperationExceptionが同時に出力されている場合、引数inputfileにEclipse Transformerの変換対象外のファイルが指定されている可能性があります。引数inputfileの指定に誤りがないか、確認してください。
zipファイルを変換する際にjava.lang.IllegalArgumentException: MALFORMEDが同時に出力されている場合、zipファイルのエントリーがUTF-8ではない可能性があります。zipファイルをディレクトリーに展開した状態でEclipse Transformerを実行するか、-tsオプションにzipファイルのエントリーの文字コード(日本語のWindows環境で作成したzipファイルの場合はMS932)を記載したjakarta-selection.propertiesファイルを指定して、Eclipse Transformerを実行してください。
引数inputfileに指定したファイルが壊れている可能性があります。引数inputfileに指定したファイルの内容に問題がないか、確認してください。

ERROR Transformer - Transform failure [ {0} ] of [ {1} ]

[可変情報]

{0}:{1}に含まれるファイルのパス

{1}:入力ファイルのパス

[意味]

変換中に例外が発生しました。

[ユーザーの対処]

可変情報が示すファイルが壊れている可能性があります。引数inputfileに指定したファイルの内容に問題がないか、確認してください。

ERROR Transformer - Input directory is invalid. Don't designate the top directory. [ {0} ] [ {1} ]

[可変情報]

{0}:入力ファイルのパス

{1}:入力ファイルの絶対パス

[意味]

入力ファイルのパスに、ルートディレクトリーまたはドライブ直下が指定されています。

[ユーザーの対処]

引数inputfileには、ルートディレクトリーやドライブ直下を指定しないでください。

ERROR Transformer - Output path is under input directory [ {0} ]

[可変情報]

{0}:出力ディレクトリーのパス

[意味]

出力ディレクトリーのパスに、入力ディレクトリー配下のパスが指定されています。

[ユーザーの対処]

引数outputfileには、入力ディレクトリー配下のパスを指定しないでください。

ERROR Transformer - Resource [ {0} ] Action [ {1} ]: Failed transform

[可変情報]

{0}:入力ファイルに含まれるファイル

{1}:変換に失敗したアクション

[意味]

変換中に例外が発生しました。

[ユーザーの対処]

可変情報が示すファイルが壊れている可能性があります。引数inputfileに指定したファイルの内容に問題がないか、確認してください。

ERROR Transformer - Exception loading rules:

[意味]

ルールファイルの読み込みに失敗しました。

[ユーザーの対処]

オプションに指定したファイルのパスや権限が正しいか、確認してください。
-tfオプションに指定したファイルの中から参照している他のファイルが、見つからない可能性があります。同時に出力されている例外メッセージに含まれるファイルが、-tfオプションに指定したファイルと同じディレクトリーに存在するか、確認してください。

WARN Transformer - Invalid charset name for selection [ {0} ]: "{1}". Defaulting to UTF-8

[可変情報]

{0}:-tsオプションに指定したファイルに記述されている、ファイル名

{1}:-tsオプションに指定したファイルに記述されている、文字コード名

[意味]

不正な文字コード名が指定されたため、UTF-8を使用して処理を継続します。

[ユーザーの対処]

-tsオプションに指定したファイルの内容が正しいか、確認してください。