Migration Guide 5.10.1_ja - terasolunaorg/terasoluna-gfw GitHub Wiki

5.10.0から5.10.1への移行ガイド

目次
Note

5.10.0.RELEASEから5.10.1.RELEASEの移行手順として説明します。
Note

当移行ガイドと合わせて

を一読し、Spring Frameworkの変更を把握することを推奨します。

1. 5.10.1での主な変更点

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

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

  • 共通ライブラリの変更

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

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

  • Spring Boot Dependenciesを3.5.9へ更新

    • Spring Frameworkを6.2.15へ更新

    • Spring Securityを6.5.7へ更新

    • Spring Dataを3.5.6へ更新

    • Hibernate ORMを6.6.39.Finalへ更新

  • MyBatisを3.5.19、MyBatis Springを3.0.5へ更新

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

  • 共通ライブラリのライブラリ及びMavenプラグインのバージョンを変更

    • [#1432] plugin versionup.

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

  • ブランクプロジェクトのライブラリ及びMavenプラグインのバージョンを変更

  • 機能改善

  • logbackのフォーマット変更

    • [single#718] [multi#781] Vulnerability that may result in logs being output that exploit terminal (console) functionality

  • 軽微な修正

2. 5.10.0から5.10.1への移行手順

移行手順は、以下の通りです。
依存ライブラリを更新を実施後、必要に応じて手順を上から順に適用してください。

Note

凡例
必須 : 手順の適用は必須
条件付き必須 : 手順の適用は条件付きで必須
推奨 : 手順の適用を推奨
任意 : 必要に応じて手順の適用を実施
- : 手順の適用は必要なし
変更点 MavenMultiple Projects MavenSingle Project

依存ライブラリを更新

必須

必須

共通ライブラリが管理するMavenプラグインの最新化

任意

任意

JDBCドライバーのバージョンの変更

任意

任意

制御文字の出力抑止に対応したログフォーマットへの修正

必須

必須

DataSourceの設定方法を変更

任意

任意

Tomcatのパラメータ変更

条件付き必須

条件付き必須

Apache HttpComponents HttpClientのSSL(TLS)ハンドシェイクタイムアウトの設定方法の変更

条件付き必須

条件付き必須

RestTemplateに設定するHttpRequestFactoryの推奨設定の変更

任意

任意

2.1. 依存ライブラリを更新

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

ライブラリ名 更新前バージョン 更新後バージョン 備考

TERASOLUNA Server Framework for Java (5.x) Common Library

5.10.0.RELEASE

5.10.1.RELEASE

Spring Framework

6.2.1

6.2.15

Spring Data

3.4.1

3.5.7

Spring Security

6.4.2

6.5.7

Spring Test

6.2.1

6.2.15

MyBatis3

3.5.17

3.5.19

MyBatis3 Spring

3.0.4

3.0.5

Hibernate ORM

6.6.4.Final

6.6.39.Final

AOP

1.9.22.1

1.9.25.1

Logback

1.5.12

1.5.22

SLF4J

2.0.16

2.0.17

Jackson2

2.18.2

2.19.4

Hibernate Validator

8.0.2.Final

8.0.3.Final

Apache Commons DBCP

2.12.0

2.13.0

Open PDF

1.3.35

2.0.5

Apache POI

5.3.0

5.4.1

Apache HttpClient

5.4.2

5.5.1

Google Guava

33.3.1-jre

33.5.0-jre

Apache Commons Collections

4.4

4.5.0

Apache Commons IO

2.18.0

2.20.0

Lombok

1.18.36

1.18.42

JUnit4

4.13.1

4.13.2

Hamcrest

2.2

3.0

Mockito

5.14.2

5.17.0

[手順が必要なケース]

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

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

この更新手順は、Mavenをオンライン環境で使用しており、multi blankまたはsingle blankを使用して作成したプロジェクト向けです。

POMファイルのversionを5.10.1.RELEASEに修正してください。

  • ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)

  • ($YOUR_SINGLE_PROJECT/pom.xml)

<!-- omitted -->
<parent>
    <groupId>org.terasoluna.gfw</groupId>
    <artifactId>terasoluna-gfw-parent</artifactId>
    <version>5.10.1.RELEASE</version>                    <!-- ### 修正箇所 ### -->
</parent>
<!-- omitted -->

2.1.2. オフライン環境でバージョン更新を実施する場合

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

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

  1. オンライン環境

    1. ブランクプロジェクトを作成
      ガイドラインの記述を参考に、archetype:generateを実行し、5.10.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

  2. オンライン環境⇒オフライン環境

    1. オフライン環境へのコピー
      repositoryをオフライン環境の「ユーザのホームディレクトリ/.m2」へコピーしてください。

  3. オフライン環境

    1. POMの修正
      オフライン環境のプロジェクトにて、オンライン環境でバージョン更新を実施する場合に記載されている内容と同様に、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. 共通ライブラリが管理するMavenプラグインの最新化

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

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

上記ページに記載のプラグインについては、バージョン指定なしに使用することが可能です。

[手順が必要なケース]

以下のケースに当てはまる場合、ビルドや実行に問題がないことを確認しながら、必要に応じて修正を行ってください。

  • 共通ライブラリが提供するプラグインのバージョンから変更したい場合

[修正方法]

プラグインごとに対応方法が異なるため、各公式リファレンスを参照して対応してください。
なお、terasoluna-gfw-parentで定義しているプラグインのバージョンを変更したい場合は、terasoluna-gfw-parentのpom.xmlに定義されたプロパティを自アプリのpom.xmlで上書きします。
例えば Maven Dependency Plugin のバージョンを指定したい場合は以下のように、terasoluna-gfw-parentで定義されたプロパティを上書きします。

  • ($YOUR_PROJECT/pom.xml)

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

2.3. JDBCドライバーのバージョンの変更

ブランクプロジェクトのpomファイルに記載している PostgreSQL JDBC Driver と Oracle JDBC のバージョン定義を更新しました。
これらのJDBCドライバーは、利用するデータベースおよびJDKとの組み合わせを確認のうえ、適切なバージョンを選択してください。

[手順が必要なケース]

本手順は任意です。

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

2.3.1. PostgreSQLを使用する場合

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

[修正方法]

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

  • ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)

  • ($YOUR_SINGLE_PROJECT/pom.xml)

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

2.3.2. Oracle Databaseを使用する場合

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

[修正方法]

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

  • ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)

  • ($YOUR_SINGLE_PROJECT/pom.xml)

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

2.4. 制御文字の出力抑止に対応したログフォーマットへの修正

ログフォーマットを変更することで、制御文字の出力抑止を行ってください。
本手順を行うことで、ログをコンソール(ターミナル)で閲覧(表示)する際に、ユーザの悪意のある入力等によって、コンソール(ターミナル)が持つ特殊な機能が呼び出されることを防ぐことができるようになります。

[手順が必要なケース]

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

[修正方法]

logback.xmlに設定されているログフォーマット上、外部からの入力値が埋め込まれる可能性がある部分に対し、一部(水平タブ, CR, LF)を除く制御文字(C0制御文字(ASCII制御文字)とC1制御文字(U+0080～U+009F))を別の文字(あるいは文字列)に置換するよう設定してください。制御文字の置換は、

%replace(…){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}
※「…」は、外部からの入力値が埋め込まれる可能性がある部分(「%msg」等)
のような記法で設定できます。

ブランクプロジェクトがデフォルトで提供しているlogback.xmlでは、

  • %X{X-Track}

  • %msg

  • %xEx

を置換の対象としています。これら以外に外部からの入力値が埋め込まれる可能性がある部分がある場合は、適宜修正してください。

  • ($YOUR_MULTIPLE_PROJECT_ENV/src/main/resources/logback.xml)

  • ($YOUR_SINGLE_PROJECT/src/main/resources/logback.xml)

<configuration>

<!-- omitted -->

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern><![CDATA[date:%d{yyyy-MM-dd HH:mm:ss}\tthread:%thread\tX-Track:%X{X-Track}\tlevel:%-5level\tlogger:%-48logger{48}\tmessage:%replace(%msg){'(\r\n|\r|\n)','$1  '}%n%replace(%replace(%xEx){'(\r\n|\r|\n)','$1  '}){'  $',''}%nopex]]></pattern> <!-- ### 修正前 ### -->
            <pattern><![CDATA[date:%d{yyyy-MM-dd HH:mm:ss}\tthread:%thread\tX-Track:%replace(%X{X-Track}){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}\tlevel:%-5level\tlogger:%-48logger{48}\tmessage:%replace(%replace(%msg){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}){'(\r\n|\r|\n)','$1  '}%n%replace(%replace(%replace(%xEx){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}){'(\r\n|\r|\n)','$1  '}){'  $',''}%nopex]]></pattern> <!-- ### 修正後 ### -->
        </encoder>
    </appender>

    <appender name="APPLICATION_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <!-- omitted -->
        <encoder>
            <charset>UTF-8</charset>
            <pattern><![CDATA[date:%d{yyyy-MM-dd HH:mm:ss}\tthread:%thread\tX-Track:%X{X-Track}\tlevel:%-5level\tlogger:%-48logger{48}\tmessage:%replace(%msg){'(\r\n|\r|\n)','$1  '}%n%replace(%replace(%xEx){'(\r\n|\r|\n)','$1  '}){'  $',''}%nopex]]></pattern> <!-- ### 修正前 ### -->
            <pattern><![CDATA[date:%d{yyyy-MM-dd HH:mm:ss}\tthread:%thread\tX-Track:%replace(%X{X-Track}){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}\tlevel:%-5level\tlogger:%-48logger{48}\tmessage:%replace(%replace(%msg){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}){'(\r\n|\r|\n)','$1  '}%n%replace(%replace(%replace(%xEx){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}){'(\r\n|\r|\n)','$1  '}){'  $',''}%nopex]]></pattern> <!-- ### 修正後 ### -->
        </encoder>
    </appender>

    <appender name="MONITORING_LOG_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <!-- omitted -->
        <encoder>
            <charset>UTF-8</charset>
            <pattern><![CDATA[date:%d{yyyy-MM-dd HH:mm:ss}\tX-Track:%X{X-Track}\tlevel:%-5level\tmessage:%replace(%msg){'(\r\n|\r|\n)','$1  '}%n%replace(%replace(%xEx){'(\r\n|\r|\n)','$1  '}){'  $',''}%nopex]]></pattern> <!-- ### 修正前 ### -->
            <pattern><![CDATA[date:%d{yyyy-MM-dd HH:mm:ss}\tX-Track:%replace(%X{X-Track}){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}\tlevel:%-5level\tmessage:%replace(%replace(%msg){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}){'(\r\n|\r|\n)','$1  '}%n%replace(%replace(%replace(%xEx){'[\p{IsControl}&&[^\t\r\n]]','<CTRL>'}){'(\r\n|\r|\n)','$1  '}){'  $',''}%nopex]]></pattern> <!-- ### 修正後 ### -->
        </encoder>
    </appender>

<!-- omitted -->

</configuration>

2.5. DataSourceの設定方法を変更

DataSourceInitializerおよびTransactionManagerに設定するDataSourceをメソッド参照から@Beanメソッド引数による依存性注入へ変更しました。

[手順が必要なケース]

本手順の適用は任意です。

[修正方法]

以下のように修正してください。

  • ($YOUR_MULTIPLE_PROJECT_ENV/src/main/java/com/example/sample/config/app/ProjectNameEnvConfig.java)

  • ($YOUR_SINGLE_PROJECT/src/main/java/com/example/sample/config/app/ProjectNameEnvConfig.java)

@Configuration
public class ProjectNameEnvConfig {

    // omitted

    @Bean
    public DataSourceInitializer dataSourceInitializer() {                      // ### 修正前 ###
    public DataSourceInitializer dataSourceInitializer(DataSource dataSource) { // ### 修正後 ###
        DataSourceInitializer bean = new DataSourceInitializer();
        bean.setDataSource(dataSource()); // ### 修正前 ###
        bean.setDataSource(dataSource);   // ### 修正後 ###

        // omitted
    }

    // omitted

    @Bean("transactionManager")
    public TransactionManager transactionManager() {                      // ### 修正前 ###
    public TransactionManager transactionManager(DataSource dataSource) { // ### 修正後 ###
        DataSourceTransactionManager bean = new DataSourceTransactionManager();
        bean.setDataSource(dataSource()); // ### 修正前 ###
        bean.setDataSource(dataSource);   // ### 修正後 ###
        bean.setRollbackOnCommitFailure(true);
        return bean;
    }

    // omitted

    @Bean("dataSource")
    public DataSource dataSource() {
        // omitted
    }
}

2.6. Tomcatのパラメータ変更

DoS攻撃への対応のため、マルチパート数の最大数及びヘッダサイズが段階的に調整されました。

  • Tomcat 10.1.8

    • CVE-2023-28709が対応されました。

    • maxParameterCountのデフォルト値が10000から1000に変更されました。

  • Tomcat 10.1.42

    • CVE-2025-48988の対応でmaxPartCountが追加されました。デフォルト値は10です。（次のTomcat10.1.43で変更されています。）

    • CVE-2025-48976の対応でmaxPartHeaderSizeが追加されました。パラメータ追加前は10KB固定でしたが、デフォルト値は512Bとなりました。

  • Tomcat 10.1.43

    • maxPartCountのデフォルト値が10から50に変更されました

また、これらのパラメータを制御するためにParameterLimitValveが追加されました。

[手順が必要なケース]

アプリケーションサーバーとしてTomcatを使用している場合は、上記のパラメータについて、必要に応じて見直しを行ってください。
なお、使用するTomcatのバージョンに応じてデフォルト値が異なるため、使用するTomcatのデフォルト値を確認してください。

[修正方法]

ParameterLimitValveの設定を追加またはConnectorの設定を変更し、マルチパートリクエストに関する上限値を見直してください。

2.7. Apache HttpComponents HttpClientのSSL(TLS)ハンドシェイクタイムアウトの設定方法の変更

Apache HttpComponents HttpClientのHTTPCLIENT-2386の対応により、SSL(TLS)ハンドシェイクタイムアウトの設定方法が変更されました。
この対応に伴い、SocketConfig.Builder#setSoTimeoutを使用してSSL(TLS)ハンドシェイクタイムアウトを設定することができなくなりました。 SSL(TLS)ハンドシェイクタイムアウトを設定するには、TlsConfig.Builder#setHandshakeTimeoutを使用して設定する必要があります。

[手順が必要なケース]

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

  • SocketConfig.Builder#setSoTimeoutを使用して、SSL(TLS)ハンドシェイクタイムアウトを設定している。

[修正方法]

HttpComponentsClientHttpRequestFactoryを生成する際に設定するPoolingHttpClientConnectionManagerの定義を修正します。
SocketConfig.Builder#setSoTimeoutに記載していた設定を、TlsConfig.Builder#setHandshakeTimeoutに追加してください。
なお、SoTimeoutはソケットタイムアウトとして引き続き設定する必要があります。(デフォルト値は3分です。)

下記のコードはガイドラインで案内している設定例となります。業務要件に応じ適切な値を設定してください。

PoolingHttpClientConnectionManager connectionManager = PoolingHttpClientConnectionManagerBuilder.create()
        .setTlsSocketStrategy(new DefaultClientTlsStrategy(sslContext))
        .setDefaultTlsConfig(
                TlsConfig.custom()
                .setSupportedProtocols(TLS.V_1_3, TLS.V_1_2)
                .setHandshakeTimeout(Timeout.ofMilliseconds(1L))  // ### 追加箇所 ###
                .build())
        .setDefaultSocketConfig(
                SocketConfig.custom()
                .setSoTimeout(Timeout.ofMinutes(1L))              // ### 修正箇所 ###
                .build())
        .setMaxConnTotal(1)
        .setMaxConnPerRoute(1)
        .setPoolConcurrencyPolicy(PoolConcurrencyPolicy.STRICT)
        .setConnPoolPolicy(PoolReusePolicy.LIFO)
        .setDefaultConnectionConfig(
                ConnectionConfig.custom()
                .setTimeToLive(TimeValue.ofMinutes(1L))
                .setConnectTimeout(Timeout.ofSeconds(5L))
                .build())
        .build();

2.8. RestTemplateに設定するHttpRequestFactoryの推奨設定の変更

RestTemplateの実装方法としてSimpleClientHttpRequestFactoryを利用した実装をガイドラインで紹介していましたが、他のClientHttpRequestFactoryの実装と比較すると機能が限定されているため、HttpComponentsClientHttpRequestFactoryを推奨設定に変更しました。
それに伴い、ガイドラインの実装例もHttpComponentsClientHttpRequestFactoryを利用した実装に変更しています。

[手順が必要なケース]

この手順は任意です。
現時点の実装で通信要件を満たせている場合は、本手順の適用は不要です。

[修正方法]

RestTemplateのコンストラクタに、HttpComponentsClientHttpRequestFactoryを設定するように変更してください。
HttpComponentsClientHttpRequestFactoryを利用した通信設定に関しては、ガイドラインを参照してください。

@Bean("restTemplate")
public RestTemplate restTemplate() {
	return new RestTemplate();                                               // ### 修正前 ###
    return new RestTemplate(new HttpComponentsClientHttpRequestFactory());   // ### 修正後 ###
}

3. ブランクプロジェクトの軽微な修正

ブランクプロジェクトに軽微な修正を行いました。
通常のアプリケーションプロジェクトではこれらの修正は必要ないと思われるため、移行ガイドラインの手順からは外していますが、必要に応じてご参照ください。

3.1. org.springframework.web.servlet.view.BeanNameViewResolverの追加

ViewResolverの設定がmulti blankとsingle blankで異なっていたため、BeanNameViewResolverを追加して統一しました。

  • SpringMvcConfig.java

@EnableAspectJAutoProxy
@EnableWebMvc
@Configuration
public class SpringMvcConfig implements WebMvcConfigurer {

    // omitted

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.beanName();
        // omitted
    }

  • spring-mvc.xml

<mvc:view-resolvers>
    <mvc:bean-name />
    <!-- omitted -->
</mvc:view-resolvers>

3.2. HelloController.javaの修正

ブランクプロジェクトのHelloController.javaで使用している日付関連のクラスを、java.util.Dateからjava.time.LocalDateTimeへ変更しました。

  • HelloController.java

@Controller
public class HelloController {
    // omitted

    @GetMapping(value = "/")
    public String home(Locale locale, Model model) {
        logger.info("Welcome home! The client locale is {}.", locale);

        // ### 修正前 ###
        Date date = new Date();
        DateFormat dateFormat =
                DateFormat.getDateTimeInstance(DateFormat.LONG, DateFormat.LONG, locale);
        String formattedDate = dateFormat.format(date);
        // ### 修正前 ###

        // ### 修正後 ###
        LocalDateTime dateTime = LocalDateTime.now();
        DateTimeFormatter formatter = DateTimeFormatter
                .ofLocalizedDateTime(FormatStyle.LONG, FormatStyle.MEDIUM).withLocale(locale);
        String formattedDate = dateTime.format(formatter);
        // ### 修正後 ###

        model.addAttribute("serverTime", formattedDate);

        return "welcome/home";
    }

  • application-messages.properties

### 修正前 ###
typeMismatch.java.util.Date="{0}" is not a date.

### 修正後 ###
typeMismatch.java.time.LocalDateTime="{0}" is not a date.

3.3. UserIdMDCPutFilterの定義を修正

冗長となっていた</bean>を修正しました。

  • spring-security.xml

<!-- ## 修正前 ## -->
<bean id="userIdMDCPutFilter" class="org.terasoluna.gfw.security.web.logging.UserIdMDCPutFilter">
</bean>

<!-- ## 修正後 ## -->
<bean id="userIdMDCPutFilter" class="org.terasoluna.gfw.security.web.logging.UserIdMDCPutFilter" />
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️