カスタムコネクタのための Java のアップグレード (顧客)

このガイドは MuleSoft ユーザーにのみ適用されます。MuleSoft パートナーの場合は、カスタムコネクタのための Java のアップグレード (パートナー)を参照してください。

Java 17 用のカスタムコネクタをアップグレード、テスト、リリースして、MuleSoft エコシステム内で互換性を確保します。互換性のないコネクタを実行すると、ランタイムエラー、パフォーマンスの低下、セキュリティの脆弱性につながり、アプリケーションの安定性に影響する可能性があるため、この互換性を確保することが重要になります。

始める前に

Java 17 用のカスタムコネクタをアップグレードしてテストする前に、次の考慮事項について理解しておく必要があります。

対象コンパイルレベル

Mule 4.9.0 以降では、Java 17 以下の Mule プロジェクトをコンパイルできます。Java 17 以下では、追加の連動関係をコンパイルする必要があります。

Java 17 でコンパイルする場合、mule-modules-parent をバージョン 1.9.0 以降にアップグレードします。コネクタの最小 Mule バージョンも 4.9.0 になるため、Mule 4.9.0 以降との互換性のみが確保されます。META-INF/mule-artifact/mule-artifact.json の minMuleVersion が 4.9.0 以降であることを確認します。「Specify Java Compatibility (Java の互換性を指定する)」を参照してください。

mule-modules-parent が 1.9.0 より前のバージョンである場合、コネクタのバイトコードレベルとその追加の連動関係は Java 8 に対応している必要があります。Java 11 または Java 17 の言語機能は使用できません。
サポートされていないディレクティブ

-add-opens または -add-export ディレクティブは設定しないでくださいください。これらのディレクティブは CloudHub または Runtime Fabric では許可されず、すべての環境でコネクタごとに管理する必要があります。また、後方互換性の負担が生じ、今後の Java アップグレードが複雑になり、セキュリティの脆弱性が生じる可能性があります。
最小 Mule バージョン

カスタムコネクタが Mule 4.5.x 以前で実行されている場合、MuleArtifactFunctionalTestCase を拡張する Java 17 テストは実行できませんが、Java 8 テストは引き続き実行できます。

テストを実行するときに最小 Mule バージョンを切り離すには、-Dmunit.jvm パラメーターを追加して、MUnit を使用したカスタムコネクタのテストの説明に従って Java 17 を使用します。

カスタム Mule SDK Connector のアップグレード

カスタム Mule SDK (Java SDK および XML SDK) Connector を Java 17 にアップグレードします。

サードパーティライブラリのアップグレード

カスタムコネクタでサードパーティライブラリを使用している可能性があるため、Java 17 との互換性を確保することも重要です。カスタムコネクタがテストに合格しても、安全で信頼性のあるソフトウェアを提供することが引き続き重要になります。重要なバグや脆弱性が見つかった場合、修正されたバージョンにアップグレードする必要があります。Java 17 を明示的にサポートしている最新のライブラリを使用すると、ベンダーがそれらをすでに Java 17 でテストしているため、このプロセスが容易になり、信頼性が高まります。

カスタムコネクタのサードパーティライブラリをアップグレードして、Java 17 と互換性があるようにします。

Java EE ライブラリ

Mule 4.6.x では、以前の Mule バージョンとは異なる方法で Java EE ライブラリが公開されます。BOM 連動関係をカスタムコネクタに追加し、該当する場合は、提供された競合するライブラリを除外する必要があります。また、ライブラリを BOM 連動関係に個別に追加することもできます。
```
<properties>
 <muleJavaEeBomVersion>4.6.0</muleJavaEeBomVersion>
</properties>
<dependencyManagement>
 <dependencies>
   <dependency>
     <groupId>org.mule</groupId>
     <artifactId>mule-javaee-runtime-bom</artifactId>
     <version>${muleJavaEeBomVersion}</version>
     <type>pom</type>
     <scope>import</scope>
   </dependency>
 </dependencies>
</dependencyManagement>
```
詳細は、Java EE Librariesを参照してください。
外部ライブラリ

外部ライブラリ (カスタムコネクタにバンドルされていないサードパーティライブラリ) をアップグレードします。例として、JDBC ドライバー、JMS ブローカークライアント、Groovy Runtime などがあります。次の例は、JDBC ドライバーの外部ライブラリ設定を示しています。
```
@ExternalLib(name = "MySQL JDBC Driver",
description = "A JDBC driver that supports connection to the MySQL Database",
nameRegexpMatcher = "(.*)\\.jar",
requiredClassName = "com.mysql.jdbc.Driver",
coordinates = "mysql:mysql-connector-java:5.1.44")
public class MySqlConnectionProvider implements ConnectionProvider<Connection> {
  //
}
```
外部ライブラリを Java 17 と互換性のあるバージョンに更新する必要があります。

コードのレビュー

カスタムコネクタをコンパイルしたら、Java 17 でカスタムコネクタを実行できることを確認します。Java 11 では一部の制限に警告のフラグが付けられますが、Java 17 では失敗のフラグが付けられ、無効にすることができないため、コードのレビューを行うことが重要です。たとえば、Java 17 ではリフレクションがより制限されているため、コードをレビューして不正なアクションがないことを確認する必要があります。

コードのレビューに役立つように、Java 17 のさまざまな変更の詳細を確認してください。

JDK 移行ガイド

Java 8 から Java 17 への変更の完全なリストについては、「Oracle JDK 移行ガイド」を参照してください。このガイドを使用してコードへの影響を評価します。
Mule Runtime Engine

Mule Runtime Engine で行われた Java 17 の変更についての詳細は、「Mule Runtime」を参照してください。
- Java クラスのリフレクション
  
  Java 17 との互換性を確保するには、Java クラスへのアクセスやパラメーター値の設定にリフレクションを使用しているコードを確認して更新します。Java 17 では、より厳格なアクセス制御が課されるため、JDK 内部要素のイントロスペクションを回避してください。Java 17 で動作する堅牢なテストスイートを用意します。Java 17 では、setAccessible(true) メソッドのアクセスの変更が許可されていないため、このメソッドには特に注意してください。
- シリアル化
  
  Java 17 の制限に対応するようにシリアル化コードを更新します。コードで Gson などのライブラリを使用してクラスをシリアル化している場合、JDK クラスへのリフレクティブアクセスが含まれる Data Transfer Object (DTO) の使用に切り替えます。シリアル化ライブラリが更新されていることを確認し、リフレクションへの依存を最小限に抑えるようにコードを調整します。詳細は、Configure Custom Serializersを参照してください。
- ライブラリのアップグレード
  
  ライブラリを Java 17 と互換性のあるバージョンにアップグレードします。これには、バージョン 1.14.0 への ByteBuddy の更新、0.8.10 への Jacoco の更新、バージョン 2.x への SLF4J の更新が含まれます。CGLib を ByteBuddy で置き換えて、Groovy や JRuby などの他のライブラリへの更新がないかを確認します。すべての連動関係に Java 17 との互換性があることを確認し、ランタイムの問題を回避します。
- テストスイートの実行に伴う変更
  
  テスト方法を Java 17 に適応させます。Mockito を使用する場合、Mockito では JVM クラスをモックできないことに注意してください。モッキング用のカスタム実装を考慮し、PowerMock から新しい Mockito バージョンに切り替えます。Java 17 の変更を処理するようにテストを更新し、非推奨になったメソッドを回避します。
- Java プラットフォームモジュールシステム (JPMS)
  
  JPMS は Java 9 で導入されました。この機能では、より厳格なカプセル化が導入され、Mule モジュールで JDK クラスとやり取りする方法が影響を受けます。Mule が Java 17 および JPMS にアップグレードされると、次の変更が必要になります。
  - 分割パッケージのリファクタリング: JPMS モジュール化標準に準拠するようにパッケージの再編成とリファクタリングを行うことで、内部および API パッケージ分割の問題を解決します。
  - ResourceBundle の読み込みへの対処: ResourceBundleProvider や代替方法を使用するなど、リソースバンドルの読み込みに関連する問題のソリューションを実装します。
  - サードパーティライブラリの変更ログを分析して、JPMS に関連する Java 17 の互換性と変更を理解します。

欠落しているコードの追加

Java 17 ではリフレクションがより制限されているため、API オブジェクトにはセッターが必要になります。以前の Java 8 では、API オブジェクトには、DataWeave のすべてのアクセス可能なプロパティに対してデフォルトのコンストラクターと getter のみがあれば十分でした。DataWeave がリフレクションを使用することなくこれらのプロパティを書き込むことができるように、API オブジェクトには setter も必要になりました。

クラスが DataWeave によってインスタンス化される場合はコンストラクターと setter が必要であり、クラスが読み取られる場合は getter が必要です。クラスが返され、インスタンス化されていない場合は、getter のみが必要です。ただし、getter と setter の両方を使用すると、検証と認定のプロセスが簡素化されます。

カスタム REST Connect Connector のアップグレード

カスタム REST Connect Connector を Java 17 にアップグレードします。

REST Connect で Java 17 がサポートされるようになりました。REST Connect Connector は、REST Connect を使用して API 仕様から生成されます。コネクタを Java 17 互換にするには、API 仕様を Exchange に再パブリッシュします。「REST Connect Connector ジェネレーター」を参照してください。

REST Connect に TLS のサポートが追加されました。時間を節約するために、Java 17 用に生成されたコネクタを更新するときに TLS を有効にし、コネクタの生成とアプリケーションのテストを 1 回だけ行えばいいようにします。

カスタム設定プロパティプロバイダーのアップグレード

カスタム設定プロパティプロバイダーをアップグレードして Java 17 との互換性を確保するには、Java SDK の使用に切り替えて、「カスタムコネクタのリリース」の説明に従って @JavaVersionSupport アノテーションを使用します。カスタムコネクタと同様にカスタムコネクタのための Java のアップグレード (顧客), just like with any custom connector. The example custom configuration properties provider mentioned in Example: Mule SDK Module で説明されているすべての手順も実行する必要があります。「例: Mule SDK モジュール」に記載されているカスタム設定プロパティプロバイダーの例は、Java 17 をサポートするように更新されています。この例を参照して、カスタム設定プロパティプロバイダーを更新してください。変更されたコード (MUnit へのテストの移行を含む) がどのようなものかについては、この changeset を参照してください。

または、Java SDK の使用への切り替えに非常に多くの変更が伴う場合、カスタム設定プロパティプロバイダーの ExtensionLoadingDelegate 内で ExtensionDeclarer を使用して宣言を追加します。変更されたコードがどのようなものかについては、この changeset を参照してください。

MUnit を使用したカスタムコネクタのテスト

MUnit テストを実行し、Java 17 に対してコネクタの互換性をテストします。ローカル JDK バージョンが 17 であることを確認します。

Mule アプリケーションの pom.xml ファイルを開きます。
mule-maven-plugin バージョンを ${mule.maven.plugin.version} パラメーターで置き換えます。

munit-maven-plugin をまだ追加していない場合は追加します。バージョンを ${munit.version} パラメーターで置き換えて、runtimeVersion を ${app.runtime} パラメーターで置き換えます。

	<plugin>
		<groupId>com.mulesoft.munit.tools</groupId>
		<artifactId>munit-maven-plugin</artifactId>
		<version>${munit.version}</version>
		<executions>
			<execution>
				<id>test</id>
				<phase>test</phase>
				<goals>
					<goal>test</goal>
					<goal>coverage-report</goal>
				</goals>
			</execution>
		</executions>
		<configuration>
			<coverage>
				<runCoverage>true</runCoverage>
				<formats>
					<format>html</format>
				</formats>
			</coverage>
			<runtimeVersion>${app.runtime}</runtimeVersion>
			<dynamicPorts>
				<dynamicPort>http.port</dynamicPort>
			</dynamicPorts>
		</configuration>
	</plugin>

MUnit 3.1 は Mule Runtime 4.3.0 以降とのみ互換性があります。コネクタに Mule Runtime 4.2.0 以前との互換性がある場合、MUnit バージョンを上書きする従来のプロファイルを作成する必要があります。

munit-runner や munit-tools などの MUnit 連動関係がある場合、各連動関係のバージョンを ${munit-version} パラメーターで置き換えます。
各コネクタ連動関係のバージョンをコネクタの Java 17 互換バージョンで置き換えます。
Mule プロジェクトのルートでターミナルウィンドウを開き、次のコマンドを入力します。このコマンドを実行すると、Java 17 と互換性のある Mule Runtime、MUnit、Mule Maven プラグインの最古のバージョンが表示されます。
```
mvn -f pom.xml -s ~/.m2/settings.xml -Dapp.runtime=4.6.0 -Dmunit.version=3.1.0 -Dmule.maven.plugin.version=4.1.0 -fae test
```

コネクタに Java 17 との互換性があるかどうかを確認できるようになりました。MUnit テストの実行についての詳細は、「MUnit」を参照してください。

使用する Mule Runtime バージョンで mule-modules-parent のバージョンが決まります。たとえば、Mule Runtime 4.6.0 を使用する場合、mule-modules-parent 1.6.0 を使用する必要があります。マイナーバージョンは、Mule Runtime 4.1.0 と mule-modules parent 1.1.0、Mule Runtime 4.2.0 と mule-modules-parent 1.2.0 などのように対応関係を維持します。

Java 17 は Mule Runtime 4.6.0 以降でサポートされます。ただし、コネクタは Mule 4.3.0 と Java 17 の両方との互換性を同時に持つことができます。コネクタに Mule 4.3.0 との互換性が必要な場合、mule-modules-parent バージョンは 1.3.0 を超えることはできません。コネクタを Java 17 と互換性のあるものにするために、必ずしも mule-modules-parent 1.6.0 を使用する必要はありません。コネクタで Mule Runtime 4.6.0 のその他の機能を活用するには、特に mule-modules-parent 1.6.0 を使用する必要があります。

カスタムコネクタのリリース

コードを更新し、テストが緑色になったら、カスタムコネクタの新しい Java 17 互換バージョンをリリースする準備が整いました。

Java 17 の互換性を伝えるには、カスタムコネクタの mule-sdk-api 連動関係を追加または最新バージョンにアップグレードして、カスタムコネクタの Java 互換性のメタデータを生成します。
```
<dependency>
   <groupId>org.mule.sdk</groupId>
   <artifactId>mule-sdk-api</artifactId>
   <version>0.10.1</version>
</dependency>
```
Java SDK の場合は、次に示すように @Extension アノテーションと同じクラスに @JavaVersionSupport アノテーションを追加して、JAVA_17 という値を含めます。

XML SDK Module は Java 17 と互換性があり、プロパティを自動的に継承するため、XML SDK についてのアノテーションを追加する必要はありません。
```
@Extension(name = "Database")
@Operations(...)
@JavaVersionSupport({JAVA_8, JAVA_11, JAVA_17})
public class DatabaseConnector {
..
}
```

Mule 4.5.0 以降では、@JavaVersionSupport アノテーションを指定しないカスタムコネクタは Java 8 および Java 11 と互換性があると見なされます。

カスタムコネクタは、Java 17 のみと互換性があるとマークできます。ただし、採用や下位互換性の問題が存在しないことを確認する必要があります。

Mule アプリケーションをデプロイすると、Mule アプリケーションのすべてのモジュールに Java バージョンとの互換性があることが検証されます。互換性がないことがわかると Mule はエラーをスローし、アプリケーションはデプロイされません。

XML SDK ベースのコネクタに固有のエラーメッセージ (Extension 'module-error-handler-plugin' does not support Java 17.Supported versions are: [1.8, 11] など) が表示された場合は、Mule アプリケーションに Java 17 と互換性のないコネクタがまだ含まれていることを意味します。このエラーを解決するには、Mule アプリケーションのすべてのコネクタをアップグレードして、Java 17 と互換性があるようにします。

コードが Java 17 と互換性があるが、Java 17 互換性を宣言しない場合でも、テストの実行は成功します。

カスタムコネクタのクイックチェックを実行する場合、またはすべての連動関係の準備ができていない場合は、次の引数を渡して、Java サポート宣言のハードチェックをスキップします。

-M-Dmule.jvm.version.extension.enforcement=LOOSE

詳細は、Java Version Supportを参照してください。