Facesをジャカルタにアップグレードする

Liferay DXP 2025.Q3+

Liferay Faces は、Jakarta EE 9 API と整合するために、 jakarta.* 名前空間を使用するようになりました。 既存の Liferay Faces (JSF) ポートレットを従来の javax.* 名前空間から移行するには、依存関係の座標、XML 名前空間、および Java インポートを更新する必要があります。

この移行ではJSF 2.3の変換ビルドを使用しているため、基盤となるJSFのセマンティクスは変更されていません。 アプリケーションの動作変更は最小限です。

重要

Facesの依存関係を変更する前に、Liferay WorkspaceとターゲットプラットフォームをJakartaベースのリリースに更新してください。 一般的な Jakarta アップグレード ガイドの ワークスペースの更新 を参照してください。ワークスペース Gradle プラグインを 14.0.0 以降、および liferay.workspace.target.platform.version=2025.q3.0 以降に設定します。

ステップ1：Jakartaランタイムをインストールする（Thin WARのみ）

プロジェクトで Thin WAR パッケージング モデル (ランタイム依存関係が WAR ファイルにバンドルされるのではなく、Liferay サーバーによって提供されるモデル) を使用している場合は、移行したポートレットをデプロイする前に、新しい Jakarta 名前空間のランタイム JAR を Liferay インスタンスにデプロイする必要があります。

以下の JAR ファイルを ${liferay.home}/osgi/modules/ フォルダーにコピーします。 続行する前に、サーバーログですべてのバンドルが STARTED 状態に達するまで待ちます。

ロール	必要なJARファイル
ポートレットブリッジAPI	com.liferay.faces.bridge.api-7.0.0.jar
ポートレットブリッジ実装	com.liferay.faces.bridge.impl-7.0.0.jar
橋梁拡張工事	com.liferay.faces.bridge.ext-9.0.0.jar
共用ユーティリティ	com.liferay.faces.util-5.0.0.jar
Liferayポータルタグ	com.liferay.faces.portal-7.0.0.jar
合金タグ（使用する場合）	com.liferay.faces.alloy-5.0.0.jar
JSF 2.3 実装	jakarta.faces-2.3.21.LIFERAY-PATCHED-4.JAKARTA-LIFERAY-PATCHED-1.jar
PrimeFaces（使用する場合）	org.primefaces-15.0.6.LIFERAY-PATCHED-3.JAKARTA-LIFERAY-PATCHED-1.jar

注

これらのバンドルがアクティブになる前に Thin WAR をデプロイすると、WAR の起動に失敗し、 ClassNotFoundException: jakarta.faces.webapp.FacesServlet がスローされます。

ステップ2：プロジェクトの依存関係を更新する

プロジェクトのビルド ファイル (例: pom.xml または build.gradle) を更新して、新しい Jakarta 名前空間の依存関係バージョンを使用するようにしてください。

Thin WAR を使用している場合は、これらの依存関係のスコープを provided に設定します。 Thick WAR (ランタイムをバンドル) を使用している場合は、スコープを コンパイル または ランタイムに設定します。ただし、 jakarta.portlet-api および jakarta.servlet-apiは例外で、常に 提供 のままにしておく必要があります。

主要な依存関係座標:

依存	バージョン
com.liferay.faces:com.liferay.faces.bridge.api	7.0.0
com.liferay.faces:com.liferay.faces.bridge.impl	7.0.0
com.liferay.faces:com.liferay.faces.bridge.ext	9.0.0
com.liferay.faces:com.liferay.faces.util	5.0.0
com.liferay.faces:com.liferay.faces.portal	7.0.0
com.liferay.faces:com.liferay.faces.alloy	5.0.0
com.liferay:jakarta.faces	2.3.21.LIFERAY-PATCHED-4.JAKARTA-LIFERAY-PATCHED-1
com.liferay:org.primefaces	15.0.6.LIFERAY-PATCHED-3.JAKARTA-LIFERAY-PATCHED-1
com.liferay.jakarta.portlet:com.liferay.jakarta.portlet-api	4.0.0
jakarta.servlet:jakarta.servlet-api	5.0.0

ステップ3：名前空間の移行を自動化する

Javaのインポート文やXMLファイルを手動で編集しないでください。 Jakarta Upgrade Tool (blade gw upgradeJakarta)、 Eclipse Transformer、または OpenRewrite などのバッチ移行ツールを使用してください。

Jakarta Upgrade Tool は、 javax.* 参照 ( javax.faces.*、 javax.portlet.*、 javax.inject.*、および javax.enterprise.* を含む) を書き換えて、 jakarta.* Java ソース、JSP、XML 記述子、 bnd.bnd、および build.gradle ファイル全体。 また、Liferay Faces、jakarta.faces、およびPrimeFacesのGradle/BND座標を、Jakarta名前空間の代替値に再マッピングします。

注

Facelet .xhtml テンプレートは、 Liferay DXP 2026.Q1 の時点で Jakarta Upgrade Tool の拡張機能ごとのハンドラー リストには含まれていません。 .xhtmlの各xmlns属性がまだhttp://java.sun.com/jsfまたはhttp://xmlns.jcp.org/jsfを参照しているか、およびjavax.*を参照しているかを調べます。ビューテンプレートを手動で更新するか、補完ツール（Eclipse Transformerなど）を実行して更新してください。

警告

標準の Java SE パッケージ ( javax.sql.* および javax.crypto.*など) は Jakarta EE の一部ではないため、名前を変更してはなりません。 Jakartaアップグレードツールは、意図的にこれらを除外しています。 別のツールを使用する場合は、そのツールがそれらを除外していることを確認するか、手動で元に戻してください。

ステップ4：XML記述子を更新する

WEB-INF フォルダ内の各記述子が正しいことを確認してください。

1. web.xmlでは、名前空間は https://jakarta.ee/xml/ns/jakartaee (バージョン 5.0 以降) である必要があり、 <servlet-class> は Jakarta FacesServlet を指している必要があります。

   <servlet>
       <servlet-name>Faces Servlet</servlet-name>
       <servlet-class>jakarta.faces.webapp.FacesServlet</servlet-class>
       <load-on-startup>1</load-on-startup>
   </servlet>
   

2. portlet.xmlでは、名前空間は Jakarta Portlet 4.0 スキーマ を使用する必要があり、 <portlet-class> は Jakarta パッケージを指す必要があります。

   <portlet-class>jakarta.portlet.faces.GenericFacesPortlet</portlet-class>
   <init-param>
       <name>jakarta.portlet.faces.defaultViewId.view</name>
       <value>/WEB-INF/views/view.xhtml</value>
   </init-param>
   

3. liferay-plugin-package.propertiesで、 -cdiannotations: 命令が存在することを確認してください。

   -cdiannotations:
   

   これにより、LiferayのWABジェネレーターがCDIアノテーションをスキャンするのを防ぎ、バンドルされているCDI実装（Weld）がJSFポートレット用のBeanを検出できるようになります。

ステップ5：デプロイと検証

更新されたWARファイルをコンパイルしてLiferayインスタンスにデプロイし、移行を検証します。

1. Liferayのログを確認して、WARファイルがバンドル配線エラーなく起動していることを確認してください。

2. ポートレットに移動して、ビューのレンダリング、ファイルのアップロード、およびポートレット間のイベントをテストしてください。

3. Ajax 操作を実行し、 403 エラーを返さずに正しくルーティングされることを確認します。

4. PrimeFaces をバンドルする場合は、使用するコンポーネントをテストして、 LIFERAY-PATCHED Jakarta ビルドとの互換性を確認してください。

Liferay Faces アーティファクトのバージョン管理の詳細については、 Liferay Faces バージョン スキーム を参照してください。

トラブルシューティング

• 注入された依存関係の接続に失敗しました: beans.xml が WEB-INF フォルダーに存在し、 -cdiannotations: が liferay-plugin-package.propertiesに存在し、スコープ注釈が古い を参照していないことを確認してください。 javax.* パッケージ。
• ステージングまたは本番環境でのバンドル配線エラー: リモート osgi/modules フォルダー内の Thin WAR ランタイム JAR が、WAR が想定するバージョンと完全に一致していることを確認してください。 移行したWARファイルをデプロイする前に、サーバーのランタイム環境を調整してください。