Migration Guide 5.8.1_ja

5.7.1(5.7.1.SP1)から5.8.1への移行ガイド

1. 5.8.1での主な変更点
2. 5.7.1から5.8.1への移行手順

Note	5.7.1.RELEASEから5.8.1.RELEASEの移行手順として説明します。 5.7.1.SP1.RELEASEはバージョン表記を読み替えてください。

Caution	5.7.1から5.8.1への変更では以下の変更が取り込まれているため、バージョンアップにより既存アプリケーションが独自に参照するライブラリが動作しなくなる可能性があることに注意してください。 Jakarta EE 8 ベースからJakarta EE 10 ベースへの変更 Java SE 8 ベースからJava SE 17 ベースへの変更

Note	当移行ガイドと合わせて Upgrading to Spring Framework 6.x Migrating to 6.0 を一読し、Spring Framework及びSpring Securityの変更を把握することを推奨します。

1. 5.8.1での主な変更点

5.8.1での主な変更点は以下の通りです。

主要なライブラリのバージョンを更新
共通ライブラリの仕様を一部変更
ブランクプロジェクトの変更

1.1. 主要なライブラリのバージョンを更新

Spring Boot Dependenciesを3.0.1へ更新
- Spring Frameworkを6.0.3へ更新
- Spring Securityを6.0.2へ更新
- Spring Dateを3.0.0へ更新
- Hibernate ORMを6.1.6.Finalへ更新
MyBatisを3.5.11、MyBatis Springを3.0.1へ更新

1.2. Java ベースの変更

Spring 6.0ではJavaのベースバージョンが17に変更されたため、TERASOLUNAも合わせてJava 8ベースからJava 17ベースへ変更しました。

Note	開発ガイドラインの Java SE 17を使用するための設定で、開発ガイドラインに関連のある機能についてJava SE 17で使用するための設定方法を解説をしています。

1.3. Jakarta ベースの変更

Spring 6.0ではJakarta EE 9以降を動作要件としていますが、Jakarta EE 9に対応したTomcatがすでにEOLしていることから、TERASOLUNAではJakarta EE 8ベースからJakarta EE 10ベースへ変更しました。

1.4. Bean Mapping ライブラリの変更

Jakarta EE 10に変更したことに伴い、 Dozer が使用できなくなりました。
そのため、Bean Mappingのライブラリを Dozer から MapStruct へ変更しました。

1.5. Apache Tiles の削除

Jakarta EE 10に変更したことに伴い、 Apache Tiles が使用できなくなりました。
そのため、 Apache Tiles を依存関係から削除しました。

1.6. Joda Timeの非推奨化

共通ライブラリが提供するJoda Timeに関する機能を非推奨とし、代替としてJSR-310の機能を提供しました。

1.7. 共通ライブラリの変更

共通ライブラリのライブラリ及びMavenプラグインのバージョンを変更
- [#1183] Change BeanMapper from Dozer to MapStruct
- [#1189] Update Guava version from 30.1.1-jre to 31.1-jre
- [#1201] Apply MyBatis 3.5.11, MyBatis Spring 3.0.0
- [#1207] Update the library version
- [#1210] Apply Spring Boot 3.0.1
- [#1216] Updated libraries and plugins
機能追加
- [#420] Add Date Factory classes for Date and Time API
- [#703] Consider to support JSP Tag Library for JSR-310 Date and Time API
非推奨化
- [#1189] deprecated joda time
使用ライブラリの削除
- [#1194] Deleting Tiles
その他軽微な修正
- [#1069] Check what SonarQube points out
- [#1089] license-maven-plugin setting change and license grant
- [#1222] Fix deprecated methods
- [#1224] Organize source code

1.8. ブランクプロジェクトの変更

ブランクプロジェクトのライブラリ及びMavenプラグインのバージョンを変更
- [single#525] [multi#573] Change BeanMapper from Dozer to MapStruct
- [single#542] [multi#594] Apply Spring Boot 3.0.1
- [single#543] [multi#595] Updated libraries and plugins
- [single#537] [multi#587] Algorithm change in PasswordEncoders
ブランクプロジェクトのフォルダ構成を変更
- [single#544] [multi#596] Change the folder structure of the blank project
Spring Securityがパス解析で使用するRequestMatcherを変更
- [single#549] [multi#601] Change RequestMatcher used by Spring Security from MvcRequestMatcher to AntPathRequestMatcher

2. 5.7.1から5.8.1への移行手順

移行手順は、以下の通りです。

Note	凡例 Required : 手順の適用は必須 Required by case : 手順の適用は条件付きで必須 Optional : 手順の適用を推奨 (必要に応じて手順の適用を実施) - : 手順の適用は必要なし

ステップ	手順	MavenMultiple Projects	MavenSingle Project
1.	依存ライブラリを更新	Required	Required
2.	Jakarta パッケージの修正	Required	Required
3.	GroupIdまたはArtifactIdの変更に伴う対応	Required by case	Required by case
4.	Logbackのバージョンアップに伴う対応	Required by case	Required by case
5.	Apache POIのバージョンアップに伴う対応	Required by case	Required by case
6.	共通ライブラリが管理するMavenプラグインの最新化に伴う対応	Required by case	Required by case
7.	サーブレットバージョンの変更	Required	Required
8.	認可処理のデフォルト値が変更されたことに伴う対応	Required	Required
9.	Spring Security のパス解析のデフォルトがMVCパターンマッチに変わったことに伴う対応	Required	Required
10.	認可処理フィルターがFilterSecurityInterceptorからAuthorizationFilterに変更されたことに伴う対応	Required by case	Required by case
11.	NestedServletExceptionの削除	Required	Required
12.	PasswordEncorderのデフォルトコンストラクタ削除に伴う対応	Required by case	Required by case
13.	Tiles の削除	Required	Required
14.	Dozer から MapStruct への移行	Required by case	Required by case
15.	Joda Time から JSR-310 への移行	Optional	Optional
16.	JDBCの切り替え	Required by case	Required by case
17.	Spring Data 3.0.0から非推奨となったAPIへの対応	Required by case	Required by case
18.	末尾`/`がデフォルトで非許容となったことに伴う対応	Required by case	Required by case

2.1. [Step 1] 依存ライブラリを更新

TERASOLUNA Server Framework for Java (5.x)の共通ライブラリと依存ライブラリを更新してください。
以下に、この手順により更新される代表的な依存ライブラリを示します。

ライブラリ名	更新前バージョン	更新後バージョン	備考
TERASOLUNA Server Framework for Java (5.x) Common Library	5.7.1.RELEASE	5.8.1.RELEASE
Spring Framework	5.3.13	6.0.3
Spring Data	2.6.0	3.0.0
Spring Security	5.6.0	6.0.1
Spring Test	5.3.18	6.0.3
MyBatis3	3.5.7	3.5.11
MyBatis3 Spring	2.0.6	3.0.1
Hibernate ORM	5.6.1.Final	6.1.6.Final
Jakarta Dependency Injection	1.0.5	2.0.1
AOP	1.9.7	1.9.19
Logback	1.2.7	1.4.5
SLF4J	1.7.32	2.0.6
Jakson	2.13.0	2.14.1
Hibernate Validator	6.2.0.Final	8.0.0.Final
Dozer	6.5.2	削除	MapStructへ移行します。
MapStruct	-	1.5.3.Final
Joda Time	2.10.9	削除
Jadira Usertype	6.0.1.GA	削除
Joda Time JSP Tags Support	1.1.1	削除
Java Time Jsptags	-	2.0.0
Tiles	3.0.8	削除
Commons FileUpload	1.3.3	削除
OpenPDF	1.0.5	1.3.30
Apache POI	4.1.2	5.2.3
Jakarta Mail API	1.6.7	削除	Angus Mail へ移行します。
Angus Mail	-	1.0.0
Apache HttpComponents	4.5.13	5.1.4	`groupId`が`org.apache.httpcomponents`から`org.apache.httpcomponents.client5`に、`artifactId`が`httpclient`から`httpclient5`に変更されます。
Google Guava	30.1.1-jre	31.1-jre
Commons Collections	3.2.2	4.4	`groupId`が`commons-collections`から`org.apache.commons`に、`artifactId`が`commons-collections`から`commons-collections4`に変更されます。
Apache Taglibs	1.2.5	削除	Jakarta Standard Tag Library API へ移行します。
Jakarta Standard Tag Library API	-	3.0.1
Lombok	1.18.22	1.18.24
Mockito	4.0.0	4.8.1
DbUnit	2.7.2	2.7.3
Bouncy Castle Provider	1.69	1.72	`artifactId`が`bcprov-jdk15on`から`bcprov-jdk18on`に変更されます。

[手順が必要なケース]

この手順の適用は必須です。

2.1.1. [Step 1-1] オンライン環境でバージョン更新を実施する場合

この更新手順は、Mavenをオンライン環境で使用しているプロジェクト向けです。

Maven Multiple Projectsを利用している場合
この更新手順は、 mvn archetype を使用して作成したプロジェクト向けです。

親プロジェクトのPOMファイルのversionを5.8.1.RELEASEに修正してください。
- ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)
   <parent> <groupId>org.terasoluna.gfw</groupId> <artifactId>terasoluna-gfw-parent</artifactId> <version>5.8.1.RELEASE</version>  </parent>
Maven Single Projectを利用している場合
この更新手順は、 mvn archetype を使用して作成したプロジェクト向けです。

プロジェクトのPOMファイルのversionを5.8.1.RELEASEに修正してください。
- ($YOUR_SINGLE_PROJECT/pom.xml)
   <parent> <groupId>org.terasoluna.gfw</groupId> <artifactId>terasoluna-gfw-parent</artifactId> <version>5.8.1.RELEASE</version>  </parent>

2.1.2. [Step 1-2] オフライン環境でバージョン更新を実施する場合

この更新手順は、依存ライブラリをインターネットにつながる環境でダウンロードし、ダウンロードした依存ライブラリをオフライン環境のプロジェクトに展開することで、Mavenをオフライン環境で使用しているプロジェクト向けです。

以下に記載する手順を実施してください。

オンライン環境
1. ブランクプロジェクトを作成
  ガイドラインの記述を参考に、archetype:generateを実行し、5.8.1.RELEASEのブランクプロジェクトを作成してください。
2. 依存関係の追加
  現行アプリのpom.xmlを確認し、アプリ独自で設定しているdependencyをブランクプロジェクトのpom.xmlに追加してください。
  アプリ独自で設定しているdependencyが不明な場合は、現行アプリで採用しているバージョンのブランクプロジェクトも作成して比較してください。
3. ローカルリポジトリへのダウンロード
  以下のコマンドを実行し、依存ライブラリおよびMavenビルドに必要となるライブラリやプラグイン等をローカルリポジトリ（repositoryディレクトリ）へダウンロードしてください。
  mvn -P warpack clean install -Dmaven.repo.local=repository mvn dependency:go-offline -Dmaven.repo.local=repository
オンライン環境⇒オフライン環境
1. オフライン環境へのコピー
  repositoryをオフライン環境の「ユーザのホームディレクトリ/.m2」へコピーしてください。
オフライン環境
1. POMの修正
  オフライン環境のプロジェクトにて、[Step 1-1]に記載されている内容と同様に、pom.xmlのバージョン表記を修正してください。
2. ビルドの実行
  1. envモジュールのjarファイルをwarファイルに含めない場合
    以下のコマンドを実行してください。
    
    mvn -P warpack clean install
    
    xxx-env配下に移動し以下のコマンドを実行してください。
    
    mvn -P test-server clean package
  2. envモジュールのjarファイルをwarファイルに含める場合
    以下のコマンドを実行してください。
    
    mvn -P warpack-with-env,test-server clean package

2.2. [Step 2] Jakarta パッケージの修正

Jakarta EE 8 から Jakarta EE 10に変更することに伴い、パッケージ名が変更されます。

[手順が必要なケース]

この手順の適用は必須です。

[修正方法]

javaxパッケージをjakartaパッケージへ変更します。

javaxパッケージの修正例

import javax.servlet.http.HttpServletRequest; // ### 修正前 ###
import jakarta.servlet.http.HttpServletRequest; // ### 修正後 ###

Note	Java SEの中にも`javax.sql.DataSource`のように`javax`パッケージが含まれており、そちらのパッケージ名は変更されない点に注意してください。

2.3. [Step 3] GroupIdまたはArtifactIdの変更に伴う対応

共通ライブラリで取り込むライブラリを見直し、一部ライブラリのGroupIdまたはArtifactIdが変更されました。
依存ライブラリを更新の備考欄にGroupIdまたはArtifactIdが変更されたことを記載しているライブラリは、依存関係を修正する必要があります。

[手順が必要なケース]

以下のケースに当てはまる場合、修正を行ってください。

アプリケーションでGroupIdまたはArtifactIdが変更されるライブラリを使用している

[修正方法]

pom.xmlを修正します。
例えば、 Bouncy Castle Provider を修正する場合は以下を修正します。

pom.xmlで定義している依存関係を修正します。

pom.xml

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk18on</artifactId> <!-- ### 修正箇所 ### -->
</dependency>

2.4. [Step 4] Logbackのバージョンアップに伴う対応

CVE-2021-42550 に対応するため、Logback1.2.8以降のバージョンではモジュール構成が変更されDBAppenderに関する機能は別モジュールとなりました。
logback-classicやlogback-accessのDBAppenderを使用した機能を利用するためには、pom.xmlに依存関係を追加する必要があります。

[手順が必要なケース]

以下のケースに当てはまる場合、修正を行ってください。

アプリケーションでlogback-classicまたはlogback-accessのDBAppender機能を使用している

[修正方法]

pom.xmlに依存関係を追加します。

pom.xml

<dependency>
  <groupId>ch.qos.logback.db</groupId>
  <artifactId>logback-classic-db</artifactId>
  <version>1.2.11.1</version>
</dependency>

<dependency>
  <groupId>ch.qos.logback.db</groupId>
  <artifactId>logback-access-db</artifactId>
  <version>1.2.11.1</version>
</dependency>

2.5. [Step 5] Apache POIのバージョンアップに伴う対応

Apache POI は5.1.0以降のバージョンでは Apache Log4j v2 を依存関係に含むようになり、ロガーの優先順の関係によりSLF4JではなくLog4j2が使用されるようになります。そのため、Log4j2からSLF4Jに切り替える設定が必要となります。

[手順が必要なケース]

以下のケースに当てはまる場合、修正を行ってください。

アプリケーションでApache POIを使用している

[修正方法]

pom.xmlに依存関係を追加します。

pom.xml

<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-to-slf4j</artifactId>
</dependency>

Note	上記設定のversionはterasoluna-gfw-parentが依存するSpring Bootで管理されているため、versionを定義する必要はありません。

2.6. [Step 6] 共通ライブラリが管理するMavenプラグインの最新化に伴う対応

共通ライブラリが管理するMavenプラグインの最新化を行いました。

最新化されたプラグインのバージョンについては、以下を参照してください。

変更前 : terasoluna-gfw-parent 5.7.1.RELEASEのpom.xml

変更後 : terasoluna-gfw-parent 5.8.1.RELEASEのpom.xml

[手順が必要なケース]

以下のケースに当てはまる場合、ビルドの挙動を確認して必要に応じて修正を行ってください。

アプリケーションで独自にプラグインのバージョンを指定していない

[修正方法]

プラグインごとに対応方法が異なるため、各公式リファレンスを参照して対応してください。

なお、プラグインを5.7.1までのバージョンに戻す場合はterasoluna-gfw-parentのpom.xmlに定義されたプロパティを上書きします。
例えば Maven Dependency Plugin のバージョンを戻す場合は以下のように定義します。

pom.xml

<properties>
    <!-- omitted -->
    <org.apache.maven.plugins.maven-dependency-plugin.version>3.2.0</org.apache.maven.plugins.maven-dependency-plugin.version>  <!-- ### 追加箇所 ### -->
</properties>

2.7. [Step 7] サーブレットバージョンの変更

TERASOLUNAではサーブレットのバージョンを6.0前提とするため、Jakarta Servlet 6.0 へ変更します。

[手順が必要なケース]

この手順の適用は必須です。

[修正方法]

web.xmlのweb-appを変更します。

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- ### 修正箇所 開始 ### -->
<web-app 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/web-app_6_0.xsd"
    version="6.0">
<!-- ### 修正箇所 終了 ### -->

pom.xmlで定義している依存関係を修正します。
以下はTomcatで動作させる際の一例となります。

pom.xml

<!-- ### 削除箇所 開始 ### -->
<!-- Servlet API 4.0 & JSP API 2.3 -->
<dependency>
    <groupId>org.apache.tomcat</groupId>
    <artifactId>tomcat-jsp-api</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>org.apache.taglibs</groupId>
    <artifactId>taglibs-standard-jstlel</artifactId>
    <scope>runtime</scope>
</dependency>
<!-- == End Tomcat == -->
<!-- ### 削除箇所 終了 ### -->

<!-- ### 追加箇所 開始 ### -->
<!-- Servlet API & JSP API -->
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
</dependency>
<dependency>
    <groupId>jakarta.servlet.jsp</groupId>
    <artifactId>jakarta.servlet.jsp-api</artifactId>
</dependency>
<dependency>
    <groupId>jakarta.servlet.jsp.jstl</groupId>
    <artifactId>jakarta.servlet.jsp.jstl-api</artifactId>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>jakarta.servlet.jsp.jstl</artifactId>
    <scope>runtime</scope>
</dependency>
<!-- ### 追加箇所 終了 ### -->

2.8. [Step 8] 認可処理のデフォルト値が変更されたことに伴う対応

Spring Security#11958 の変更により、認可処理のデフォルト挙動がpermitAllからdenyAllへ変更されました。これにより、intercept-urlを設定していない認可処理はすべて非許容となりました。今まで暗黙的にpermitAllとして動作させていた場合、intercept-urlの設定が必要となります。

[手順が必要なケース]

以下のケースに当てはまる場合、修正を行ってください。

アプリケーションで暗黙的にpermitAllを使用している

[修正方法]

spring-security.xmlのhttpタグにintercept-urlを設定します。

spring-security.xml

<sec:http>
    <sec:form-login/>
    <sec:logout/>
    <sec:access-denied-handler ref="accessDeniedHandler"/>
    <sec:custom-filter ref="userIdMDCPutFilter" after="ANONYMOUS_FILTER"/>
    <sec:session-management />
    <sec:intercept-url pattern="/**" access="permitAll" /> <!-- ### 追加箇所 ### -->
</sec:http>

Note	Spring Securityでは、予期せぬパスに対し認可が通らないようにするために、一番最後に`denyAll`を設定することを推奨しています。上記例は説明の為に`permitAll`を追加していますが、業務要件に応じ適切に設定してください。

2.9. [Step 9] Spring Security のパス解析のデフォルトがMVCパターンマッチに変わったことに伴う対応

Spring Security#11899 による変更により、Spring MVCとSpring Securityを同時に使用する場合、Spring Securityのパス解析のデフォルトがMVCパターンマッチを使用するよう修正されました。パスパターンの解析に利用する仕組みの設定についてに記載されている通り、TERASOLUNAではAntPathRequestMatcherを使用します。

[手順が必要なケース]

この手順の適用は必須です。

[修正方法]

spring-sescurity.xmlのsec:httpタグに`request-matcher="ant"`を追加します。

spring-security.xml

    <sec:http pattern="/resources/**" request-matcher="ant" security="none"/> <!-- ### 追加対象 ### -->
    <sec:http request-matcher="ant"> <!-- ### 追加対象 ### -->
        <!-- omitted -->
    </sec:http>

2.10. [Step 10] 認可処理フィルターがFilterSecurityInterceptorからAuthorizationFilterに変更されたことに伴う対応

認可処理フィルターのデフォルト設定がFilterSecurityInterceptorからAuthorizationFilterに変更されたことに伴い、設定を修正する必要があります。

修正内容は以下の通りです。

画面項目の認可処理を実行できるように設定する
web.xmlのfilter-mappingに適切なDispatcherTypeを設定する

2.10.1. [Step 10-1] 画面項目の認可処理を実行できるように設定する

認可処理フィルターのデフォルト設定がFilterSecurityInterceptorからAuthorizationFilterに変更されたことに伴い、デフォルトで定義されていたExpressionHandlerがDefaultWebSecurityExpressionHandlerからDefaultHttpSecurityExpressionHandlerに変更されました。これにより、画面項目で認可処理を行っている場合、DefaultWebSecurityExpressionHandlerをBean定義する必要があります。

[手順が必要なケース]

以下のケースに当てはまる場合、修正を行ってください。

アプリケーションの画面項目で認可処理を行っている

例 : 以下の様にauthorizeタグを使用している場合

<sec:authorize access="hasRole('ADMIN')">
    <%-- omitted --%>
</sec:authorize>

[修正方法]

spring-security.xmlにorg.springframework.security.web.access.expression.DefaultWebSecurityExpressionHandlerをwebexpressionHandlerの名前でBean定義します。

spring-security.xml

<bean id="webexpressionHandler" class="org.springframework.security.web.access.expression.DefaultWebSecurityExpressionHandler" /> <!-- ### 追加箇所 ### -->

Note	Bean定義した`webexpressionHandler`を`expression-handler`に設定する必要はありません。 `webexpressionHandler`の名前でBean定義している場合、自動的に反映されます。

2.10.2. [Step 10-2] web.xmlのfilter-mappingに適切なDispatcherTypeを設定する

AuthorizationFilterの脆弱性 CVE-2022-31692 への対応により、フォワード先でも認可処理が行われるように修正されていますが、デフォルトのDispatcherTypeはREQUESTのみが設定されているため、DispatcherTypeの見直しが必要になります。

[手順が必要なケース]

以下のケースに当てはまる場合、修正を行ってください。

認可処理を必要とするパスに対しフォワードしている

[修正方法]

ガイドラインの web.xmlの<filter-mapping>には業務要件に応じて適切なDispatcherTypeを設定することを参照し、業務要件に応じ適切なDispatcherTypeを設定してください。

2.11. [Step 11] NestedServletExceptionの削除

NestedServletExceptionが非推奨となり、今までNestedServletExceptionとしてスローされていた例外はServletExceptionにネストされるようになりました。この修正により、Spring FrameworkからNestedServletExceptionがスローされなくなりました。

[手順が必要なケース]

この手順の適用は必須です。

[修正方法]

SystemExceptionResolverのexcludedExceptionsからNestedServletExceptionを削除します。

<!-- Exception Resolver. -->
<bean id="systemExceptionResolver"
    class="org.terasoluna.gfw.web.exception.SystemExceptionResolver">
    <!-- omitted -->
    <property name="excludedExceptions">
        <array>
            <value>org.springframework.web.util.NestedServletException</value> <!-- == 削除箇所 == -->
        </array>
    </property>
    <!-- omitted -->
</bean>

Caution	ブランクプロジェクトのデフォルト設定では、`NestedServletException`を`SystemExceptionResolver`で捕捉しないようにすることで`ServletException`や`IOException`以外の例外をサーブレットコンテナ側に通知していましたが、`NestedServletException`がスローされなくなり`ServletException`にネストされるようになったため、通知できなくなりました。以前の処理と同様にサーブレットコンテナ側に例外を通知したい場合は、業務処理で`ServletException`を継承した別クラスをスローし、スローした例外を`systemExceptionResolver`の除外設定に含める必要があります。詳しくは、ガイドラインのシステム、またはアプリケーションが、正常な状態でない事を通知する場合を参照してください。

2.12. [Step 12] PasswordEncorderのデフォルトコンストラクタ削除に伴う対応

PasswordEncorder のサブクラスからデフォルトコンストラクタが削除されました。

デフォルトコンストラクタの代わりにファクトリーメソッドが準備されたため、デフォルト設定で使用したい場合はファクトリーメソッドを使用してBean定義します。

[手順が必要なケース]

以下のケースに当てはまる場合、修正を行ってください。

アプリケーションでPasswordEncoderのサブクラスのデフォルトコンストラクタを使用している

Note	Spring Security が提供するファクトリーメソッドは、デフォルトコンストラクタと同じ設定のものと、ハッシュ化アルゴリズムが見直しされたものが存在しており、デフォルトコンストラクタと同じ定義のファクトリーメソッドは非推奨となっています。ただし、ハッシュ化アルゴリズムが変更されているため、ハッシュ化された文字列が88桁から124桁となるため、databaseのカラム長変更が必要になります。

2.12.1. データ移行が不可能な場合

データ移行が困難な場合は、デフォルトコンストラクタで設定していた値と同じ値を持つファクトリメソッドを使用します。
ただし、これらのファクトリメソッドは非推奨であるため、将来的に削除される可能性がある点に注意してください。

[修正方法]

デフォルトコンストラクタの代わりに、factory-methodを使用します。

applicationContext.xml

<!-- omitted -->
<bean id="passwordEncoder" class="org.springframework.security.crypto.password.DelegatingPasswordEncoder">
    <constructor-arg name="idForEncode" value="pbkdf2" />
    <constructor-arg name="idToPasswordEncoder">
        <map>
            <entry key="pbkdf2">
                <bean class="org.springframework.security.crypto.password.Pbkdf2PasswordEncoder" factory-method="defaultsForSpringSecurity_v5_5" /> <!-- ### 修正箇所 ### -->
            </entry>
            <entry key="bcrypt">
                <bean class="org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder" />
            </entry>
            <entry key="argon2">
                <bean class="org.springframework.security.crypto.argon2.Argon2PasswordEncoder" factory-method="defaultsForSpringSecurity_v5_2" /> <!-- ### 修正箇所 ### -->
            </entry>
            <entry key="scrypt">
                <bean class="org.springframework.security.crypto.scrypt.SCryptPasswordEncoder" factory-method="defaultsForSpringSecurity_v4_1" /> <!-- ### 修正箇所 ### -->
            </entry>
        </map>
    </constructor-arg>
</bean>
<!-- omitted -->

2.12.2. データ移行が可能な場合

既存の設定と新しい設定を併記することで、新規アカウント作成時もしくはパスワード変更時に新しい設定で値を作成することが可能となります。

[修正方法]

デフォルトコンストラクタの代わりに、factory-methodを使用します。

applicationContext.xml

<bean id="passwordEncoder" class="org.springframework.security.crypto.password.DelegatingPasswordEncoder">
    <constructor-arg name="idForEncode" value="pbkdf2@SpringSecurity_v5_8" /> <!-- ### 修正箇所 ### -->
    <constructor-arg name="idToPasswordEncoder">
        <map>
            <!-- ### 追加箇所 開始 ### -->
            <entry key="pbkdf2@SpringSecurity_v5_8">
                <bean class="org.springframework.security.crypto.password.Pbkdf2PasswordEncoder" factory-method="defaultsForSpringSecurity_v5_8" />
            </entry>
            <entry key="argon2@SpringSecurity_v5_8">
                <bean class="org.springframework.security.crypto.argon2.Argon2PasswordEncoder" factory-method="defaultsForSpringSecurity_v5_8" />
            </entry>
            <entry key="scrypt@SpringSecurity_v5_8">
                <bean class="org.springframework.security.crypto.scrypt.SCryptPasswordEncoder" factory-method="defaultsForSpringSecurity_v5_8" />
            </entry>
            <!-- ### 追加箇所 終了 ### -->
            <entry key="pbkdf2">
                <bean class="org.springframework.security.crypto.password.Pbkdf2PasswordEncoder" factory-method="defaultsForSpringSecurity_v5_5" /> <!-- ### 修正箇所 ### -->
            </entry>
            <entry key="bcrypt">
                <bean class="org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder" />
            </entry>
            <entry key="argon2">
                <bean class="org.springframework.security.crypto.argon2.Argon2PasswordEncoder" factory-method="defaultsForSpringSecurity_v5_2" /> <!-- ### 修正箇所 ### -->
            </entry>
            <entry key="scrypt">
                <bean class="org.springframework.security.crypto.scrypt.SCryptPasswordEncoder" factory-method="defaultsForSpringSecurity_v4_1" /> <!-- ### 修正箇所 ### -->
            </entry>
        </map>
    </constructor-arg>
</bean>

Note	ハッシュ化されているため、自動的にデータ移行はできません。上記設定を行ったうえで、ユーザに対し案内を出す等の対応をお願いします。

2.13. [Step 13] Tiles の削除

Jakarta EE 8 から Jakarta EE 10 に変更することに伴い、 Apache Tiles が使用できなくなりました。
Apache Tiles は代替ライブラリが存在していないことから、設定の削除及びJSPの修正が必要になります。

[手順が必要なケース]

この手順の適用は必須です。

[修正方法]

spring-mvc.xmlから、Tilesの設定を削除します
Tilesでレイアウトを実施していたJSPファイルを修正します
Tiles関連のファイルとフォルダを削除します

2.13.1. `spring-mvc.xml`の修正

spring-mvc.xmlから、Tilesの設定を削除します。

spring-mvc.xml

<!-- omitted -->
<mvc:view-resolvers>
    <mvc:bean-name />
    <mvc:tiles /> <!-- ### 削除対象 ### -->
    <mvc:jsp prefix="/WEB-INF/views/" />
</mvc:view-resolvers>

<!-- ### 削除対象 開始 ### -->
<mvc:tiles-configurer>
    <mvc:definitions location="/WEB-INF/tiles/tiles-definitions.xml" />
</mvc:tiles-configurer>
<!-- ### 削除対象 終了 ### -->
<!-- omitted -->

2.13.2. 各JSPファイルの修正

template.jspでTilesによって組み立てられていたJSPを実装し直します。
以下は、ブランクプロジェクト(5.7.1.RELEASE)のtemplate.jsp を対象とした例となります。

Tilesでレイアウトを行っている各JSP
template.jspをベースに、各JSPファイルを修正します。

template.jsp

<%-- omitted --%>
<body>
    <div class="container">
        <tiles:insertAttribute name="header" /> <%-- ### 修正対象 ### --%>
        <tiles:insertAttribute name="body" />   <%-- ### 修正対象 ### --%>
        <hr>
        <p style="text-align: center; background: #e5eCf9;">Copyright &copy; 20XX CompanyName</p>
    </div>
</body>
<%-- omitted --%>

tiles:insertAttributeでbodyをinsertしている箇所を各JSPの中身で置き換えます
tiles:insertAttributeでbody以外をinsertしている箇所を、jsp:includeで読み込むように修正します

各JSPファイル（例 : home.jsp）

<%-- omitted --%>
<body>
    <div class="container">
        <jsp:include page="/WEB-INF/views/layout/header.jsp" /> <%-- ### 修正箇所 ### --%>
        <%-- ### JSPの中身で置換 開始 ### --%>
        <div id="wrapper">
            <h1 id="title">Hello world!</h1>
            <p>The time on the server is ${serverTime}.</p>
        </div>
        <%-- ### JSPの中身で置換 終了 ### --%>
        <hr>
        <p style="text-align: center; background: #e5eCf9;">Copyright &copy; 20XX CompanyName</p>
    </div>
</body>
<%-- omitted --%>

2.13.3. Tiles関連のファイル・フォルダの削除

Tiles関連の設定を削除してください。
削除対象は以下の通りです。

project-web/src/main/webapp/WEB-INF/tiles
project-web/src/main/webapp/WEB-INF/views/layout/template.jsp

template.jspを増やしている場合は、そちらも削除してください。

2.14. [Step 14] Dozer から MapStruct への移行

Jakarta EE 8 から Jakarta EE 10 に変更することに伴い、 Dozer が使用できなくなりました。
Dozerの代替ライブラリとして MapStruct へ移行します。

[手順が必要なケース]

以下のケースに当てはまる場合、修正を行ってください。

アプリケーションでBean MappingにDozerを使用している

[修正方法]

MavenでMapStructを扱えるようにpom.xmlを修正する
Mapperインタフェースを作成する
業務ロジックを修正する
Dozer関連の設定およびファイルを削除する

2.14.1. MavenでMapStructを扱えるように`pom.xml`を修正する

Lombokを使用している場合と使用していない場合で設定内容が異なります。

2.14.1.1. Lombokを使用していない場合

mavenでMapStructを扱えるようにするため、maven-compiler-pluginにmapstruct-processorを設定します。

pom.xml

<!-- ### 追加箇所 開始 ### -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <annotationProcessorPaths>
      <path>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>${mapstruct.version}</version>
      </path>
    </annotationProcessorPaths>
    <compilerArgs>
      <arg>-Amapstruct.defaultComponentModel=spring</arg>
    </compilerArgs>
  </configuration>
</plugin>
<!-- ### 追加箇所 終了 ### -->

Note	上記設定の`${mapstruct.version}`はterasoluna-gfw-parentで定義されているため、再定義の必要はありません。

Note	MapStructそのものの定義は、 terasoluna-gfw-recommended-dependencies で定義しているため、terasoluna-gfw-recommended-dependenciesを依存関係として引き込んでいる場合は設定不要です。

2.14.1.2. Lombokを使用している場合

mavenでMapStructを扱えるようにするため、maven-compiler-pluginにmapstruct-processorを設定します。ただし、mapstruct-processorを設定することでLombokプロセッサが動作しなくなるため、MapStructとLombokの両方を使えるように追加でlombok及びlombok-mapstruct-bindingを設定します。

pom.xml

<!-- ### 追加箇所 開始 ### -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <annotationProcessorPaths>
      <path>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>${mapstruct.version}</version>
      </path>
      <path>
          <groupId>org.projectlombok</groupId>
          <artifactId>lombok</artifactId>
          <version>${lombok.version}</version>
      </path>
      <path>
          <groupId>org.projectlombok</groupId>
          <artifactId>lombok-mapstruct-binding</artifactId>
          <version>${lombok-mapstruct-binding.version}</version>
      </path>
    </annotationProcessorPaths>
    <compilerArgs>
      <arg>-Amapstruct.defaultComponentModel=spring</arg>
    </compilerArgs>
  </configuration>
</plugin>
<!-- ### 追加箇所 終了 ### -->

Note	上記設定の`${mapstruct.version}`、`${lombok.version}`及び`${lombok-mapstruct-binding.version}`はterasoluna-gfw-parentで定義されているため、再定義の必要はありません。

2.14.2. Mapperインタフェースを作成する

MapStructはコンパイル時にMapperインタフェースから実装クラスを生成するコードジェネレータであるため、Mapperインタフェースの実装が必要になります。
Mapperインタフェースの記載方法についてはガイドラインの Beanマッピング(MapStruct) を参照してください。

2.14.3. Dozerを使用している業務ロジックの修正

作成したMapperインタフェースを呼び出すよう修正します。
以下は、ガイドラインの 11.1.4.2.3. Create TODOの実装を例としています。

TodoController.java

import com.github.dozermapper.core.Mapper; // ### 削除箇所 ###

// omitted

@Controller
@RequestMapping("todo")
public class TodoController {
    @Inject
    TodoService todoService;

    @Inject
    TodoMapper beanMapper; // ### 修正箇所 ###

    // omitted

    @PostMapping("create")
    public String create(@Valid TodoForm todoForm, BindingResult bindingResult,
            Model model, RedirectAttributes attributes) {

       // omitted

       Todo todo = beanMapper.map(todoForm); // ### 修正箇所 ###

       // omitted
    }

    // omitted

}

Note	作成したMapperインタフェースにより修正内容は異なります。業務要件に応じ適切に修正してください。

2.14.4. Dozer関連の設定およびファイルを削除する

以下のフォルダを削除します。

project-domain/src/main/resources/dozer
project-web/src/main/resources/dozer

applicationContext.xmlからdozerの設定を削除します。

project-env/src/main/resources/META-INF/spring/applicationContext.xml

<!-- ### 削除箇所 開始 ### -->
<bean class="com.github.dozermapper.spring.DozerBeanMapperFactoryBean">
    <property name="mappingFiles"
        value="classpath*:/META-INF/dozer/**/*-mapping.xml" />
</bean>
<!-- ### 削除箇所 終了 ### -->

2.15. [Step 15] Joda Time から JSR-310 への移行

Jakarta EE 8 から Jakarta EE 10 に変更することに伴い、Joda Time の Tag Library が使用できなくなりました。また、Spring FrameworkからJoda Timeに関する機能が削除されたため、TERASOLUNAとしてもJoda Time関連の処理を非推奨とし、JSR-310を使用することを推奨します。

[手順が必要なケース]

この手順の適用は任意です。
ただし、共通ライブラリの機能としては使用可能ですが、前述の通りTag Libraryが使用できなくなっているため、手順の適用を推奨します。

[修正方法]

ブランクプロジェクトを例に説明します。

pom.xmlからterasoluna-gfw-jodatime-dependenciesを削除します。

pom.xml

<dependencies>
    <!-- omitted -->
    <!-- ### 削除箇所 開始 ### -->
    <dependency>
        <groupId>org.terasoluna.gfw</groupId>
        <artifactId>terasoluna-gfw-jodatime-dependencies</artifactId>
        <type>pom</type>
    </dependency>
    <!-- ### 削除箇所 開始 ### -->
    <!-- omitted -->
</dependencies>

project-env.xmlに定義しているDateFactoryの変更

project-env.xml

<bean id="dateFactory" class="org.terasoluna.gfw.common.date.jodatime.DefaultJodaTimeDateFactory" /> <!-- ### 削除 ### -->
<bean id="dateFactory" class="org.terasoluna.gfw.common.time.DefaultClockFactory" /> <!-- ### 追加 ### -->

Note	業務要件により修正内容は異なるため、ガイドラインのシステム時刻を参照してください。

Javaの修正

org.joda.timeを使用しているクラスをjava.timeに置き換えます。

Note

業務要件により修正内容は異なるため、ガイドラインのシステム時刻及び日付操作(JSR-310 Date and Time API) を参照してください。

JSPの修正

使用するタブライブラリを変更します。

include.jsp

<%@ taglib uri="http://www.joda.org/joda/time/tags" prefix="joda"%> <%== 削除 ==%>
<%@ taglib uri="http://sargue.net/jsptags/time" prefix="javatime" %> <%== 追加 ==%>

各JSPファイル

joda:formatをjavatime:formatへ修正します。

<joda:format value="${now}" pattern="yyyyMMdd" /> <%== 修正前 ==%>
<javatime:format value="${now}" pattern="yyyyMMdd" /> <%== 修正後 ==%>

Note	Java 8 java.time JSP tags の詳しい使い方は、ガイドラインの JSP Tag Library を参照してください。

2.16. [Step 16] JDBCドライバーの変更

ブランクプロジェクトのpomファイルで、 PostgreSQL JDBC Driver と Oracle JDBC のバージョン定義を更新しました。
これらのJDBCドライバーは上位互換性が保障されているため、最新バージョンを使用することを推奨します。

[手順が必要なケース]

この手順の適用は任意ですが、修正を行うことを推奨します。

2.16.1. [Step 16-1] PostgreSQLを使用する場合

以下の情報を参照し、適切なバージョンを設定してください。

PostgreSQL

以降では、 TERASOLUNA Server Framework for Java 5.8.1.RELEASE の動作検証環境に合わせる形での変更方法を示します。

[修正方法]

pomファイルのプロパティを修正してください。

pom.xml

<properties>
    <!-- omitted -->
    <postgresql.version>42.5.1</postgresql.version> <!-- ### 修正箇所 ### -->
    <!-- omitted -->
</properties>

2.16.2. [Step 16-2] Oracle Databaseを使用する場合

Java のベースラインが17に変更されることに伴い、OJDBCの見直しが必要となります。

以下の情報を参照し、適切なバージョンを設定してください。

以降では、 TERASOLUNA Server Framework for Java 5.8.1.RELEASE の動作検証環境に合わせる形での変更方法を示します。

[修正方法]

アプリケーション内で使用するOJDBCのバージョンを修正してください。

pom.xml

<dependencyManagement>
    <dependencies>
    <!-- omitted -->
        <dependency>
            <groupId>com.oracle.jdbc</groupId>
            <artifactId>ojdbc11</artifactId> <!-- ### 修正箇所 ### -->
            <version>${ojdbc.version}</version>
        </dependency>
    <!- omitted -->
    </dependencies>
</dependencyManagement>

<properties>
    <!-- omitted -->
    <ojdbc.version>21.8.0.0</ojdbc.version> <!-- ### 修正箇所 ### -->
    <!-- omitted -->
</properties>

2.17. [Step 17] Spring Data 3.0.0から非推奨となったAPIへの対応

Spring Data 3.0.0から下記のAPIが非推奨となりました。

JpaRepository#getById(ID)メソッド

Spring Data 3.0.0の非推奨APIについては、以下を参照してください。

Spring Data 3.0.0のDeprecated API

[手順が必要なケース]

以下のケースに当てはまる場合、必要に応じて修正を行ってください。

上記の非推奨APIを利用している

[修正方法]

Javadocを参考に、非推奨APIを代替APIに置き換えてください。

JpaRepository#getById(ID) メソッド

2.18. [Step 18] リクエストパスの末尾`/`がデフォルトで非許容となったことに伴う対応

Spring#28552の対応により、RequestMappingに対するアクセスが厳密化され、明示的に末尾に/がついていない限り末尾に/をつけてのアクセスができなくなりました。

例 : Echoアプリケーション

@Controller
@RequestMapping("echo")
public class EchoController {

    // omitted

    @GetMapping
    public String index(Model model) {
        return "echo/index";
    }

    // omitted
}

このようなハンドラメソッドがある場合、バージョンアップ前は以下の2パターンでアクセス可能でした。

一方で、バージョンアップ後は以下の1パターンのみでアクセス可能です。

http://localhost:8080/helloworld/echo

なお、上記のEchoアプリケーションの様なハンドラメソッドのpathが空であるメソッドに対し 3.4.3.1.5. リクエストURLを生成するで案内しているMvcUriComponentsBuilderを使用してリクエストURLを生成すると、末尾に必ず/が付与されるバグが報告されています。（ Spring#29897 ）このバグによりアクセスに失敗する場合は、MvcUriComponentsBuilderのバグへの対応方法を参照してください。

[手順が必要なケース]

以下のケースに当てはまる場合、必要に応じて修正を行ってください。

ハンドラメソッド(@RequestMappingまたは@GetMappingなど)で末尾に/をつけていないパスに対し末尾に/をつけてアクセスしている

[修正方法]

以下のパターンにより修正方法が異なります。

末尾/を許容しない
末尾/を許容する

2.18.1. [Step 18-1] 末尾`/`を許容しない

以下の方法で修正してください。

末尾の/なしのリクエストを前提にリクエストパスの仕様を変更し、それに合わせてコントローラクラスのハンドラメソッドも修正する

2.18.1.1. MvcUriComponentsBuilderのバグへの対応方法

上記で案内しているMvcUriComponentsBuilderのバグにより末尾/のパスが作られてアクセスに失敗する場合は、クラス単位で@RequestMappingのpathを指定するのではなく、メソッド単位で@RequestMappingのpathを指定することでバグによる挙動を回避することが出来ます。

@Controller
@RequestMapping
public class EchoController {

    // omitted

    @GetMapping("echo")
    public String index(Model model) {
        return "echo/index";
    }

    // omitted
}

2.18.2. [Step 18-2] 末尾`/`を許容する

以下のいずれかで修正します。

ハンドラメソッドを修正する
trailing-slashをtrueに設定する

2.18.2.1. ハンドラメソッドを修正する

以下の方法で修正してください。

末尾の/ありのリクエストを前提にリクエストパスの仕様を変更し、それに合わせてコントローラクラスのハンドラメソッドを修正する

2.18.2.2. `trailing-slash`を`true`に設定する

以下の方法で修正してください。

path-matchingにtrailing-slash="true"を設定する

path-matchingにtrailing-slash="true"を設定することで、 PathPatternParser#matchOptionalTrailingSeparatorがtrueに設定されます。これにより、末尾に/がつくリクエストパスを末尾に/がつかないリクエストパスに一致させるようになり、バージョンアップ前の挙動と一致するようになります。

Caution	PathPatternParser#setMatchOptionalTrailingSeparator は非推奨となっており、いずれ削除されることが明記されているため、暫定的な対応となる点に注意してください。

spring-mvc.xml

<mvc:annotation-driven>
    <mvc:argument-resolvers>
        <bean
            class="org.springframework.data.web.PageableHandlerMethodArgumentResolver" />
        <bean
            class="org.springframework.security.web.method.annotation.AuthenticationPrincipalArgumentResolver" />
    </mvc:argument-resolvers>
    <mvc:path-matching trailing-slash="true"/> <!-- ### 追加箇所 ### -->
</mvc:annotation-driven>

Migration Guide 5.8.1_ja

5.7.1(5.7.1.SP1)から5.8.1への移行ガイド

1. 5.8.1での主な変更点

1.1. 主要なライブラリのバージョンを更新

1.2. Java ベースの変更

1.3. Jakarta ベースの変更

1.4. Bean Mapping ライブラリの変更

1.5. Apache Tiles の削除

1.6. Joda Timeの非推奨化

1.7. 共通ライブラリの変更

1.8. ブランクプロジェクトの変更

2. 5.7.1から5.8.1への移行手順

2.1. [Step 1] 依存ライブラリを更新

2.1.1. [Step 1-1] オンライン環境でバージョン更新を実施する場合

2.1.2. [Step 1-2] オフライン環境でバージョン更新を実施する場合

2.2. [Step 2] Jakarta パッケージの修正

2.3. [Step 3] GroupIdまたはArtifactIdの変更に伴う対応

2.4. [Step 4] Logbackのバージョンアップに伴う対応

2.5. [Step 5] Apache POIのバージョンアップに伴う対応

2.6. [Step 6] 共通ライブラリが管理するMavenプラグインの最新化に伴う対応

2.7. [Step 7] サーブレットバージョンの変更

2.8. [Step 8] 認可処理のデフォルト値が変更されたことに伴う対応

2.9. [Step 9] Spring Security のパス解析のデフォルトがMVCパターンマッチに変わったことに伴う対応

2.10. [Step 10] 認可処理フィルターがFilterSecurityInterceptorからAuthorizationFilterに変更されたことに伴う対応

2.10.1. [Step 10-1] 画面項目の認可処理を実行できるように設定する

2.10.2. [Step 10-2] web.xmlのfilter-mappingに適切なDispatcherTypeを設定する

2.11. [Step 11] NestedServletExceptionの削除

2.12. [Step 12] PasswordEncorderのデフォルトコンストラクタ削除に伴う対応

2.12.1. データ移行が不可能な場合

2.12.2. データ移行が可能な場合

2.13. [Step 13] Tiles の削除

2.13.1. spring-mvc.xmlの修正

2.13.2. 各JSPファイルの修正

2.13.3. Tiles関連のファイル・フォルダの削除

2.14. [Step 14] Dozer から MapStruct への移行

2.14.1. MavenでMapStructを扱えるようにpom.xmlを修正する

2.14.1.1. Lombokを使用していない場合

2.14.1.2. Lombokを使用している場合

2.14.2. Mapperインタフェースを作成する

2.14.3. Dozerを使用している業務ロジックの修正

2.14.4. Dozer関連の設定およびファイルを削除する

2.15. [Step 15] Joda Time から JSR-310 への移行

2.16. [Step 16] JDBCドライバーの変更

2.16.1. [Step 16-1] PostgreSQLを使用する場合

2.16.2. [Step 16-2] Oracle Databaseを使用する場合

2.17. [Step 17] Spring Data 3.0.0から非推奨となったAPIへの対応

2.18. [Step 18] リクエストパスの末尾/がデフォルトで非許容となったことに伴う対応

2.18.1. [Step 18-1] 末尾/を許容しない

2.18.1.1. MvcUriComponentsBuilderのバグへの対応方法

2.18.2. [Step 18-2] 末尾/を許容する

2.18.2.1. ハンドラメソッドを修正する

2.18.2.2. trailing-slashをtrueに設定する

Clone this wiki locally

2.13.1. `spring-mvc.xml`の修正

2.14.1. MavenでMapStructを扱えるように`pom.xml`を修正する

2.18. [Step 18] リクエストパスの末尾`/`がデフォルトで非許容となったことに伴う対応

2.18.1. [Step 18-1] 末尾`/`を許容しない

2.18.2. [Step 18-2] 末尾`/`を許容する

2.18.2.2. `trailing-slash`を`true`に設定する