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

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

目次
Note

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

1. 5.7.2での主な変更点

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

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

  • 共通ライブラリの仕様を一部変更

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

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

  • Spring Boot Dependencies 2.7.7へ更新

    • Spring Framework 5.3.24へ更新

    • Spring Security 5.7.6へ更新

  • MyBatis 3.5.11へ更新

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

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

    • [#1176] Update Guava version from 30.1.1-jre to 31.1-jre.

    • [#1202] Apply MyBatis 3.5.11, MyBatis Spring 2.1.0

    • [#1209] Update the library version

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

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

  • spring-security.xmlにおける<sec:http>タグのonce-per-request属性をfalseに設定

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

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

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

ステップ 手順 MavenMultiple Projects MavenSingle Project

1.

依存ライブラリを更新

Required

Required

2.

GroupIdまたはArtifactIdの変更に伴う対応

Required by case

Required by case

3.

Logbackのバージョンアップに伴う対応

Required by case

Required by case

4.

Apache POIのバージョンアップに伴う対応

Required by case

Required by case

5.

共通ライブラリが管理するMavenプラグインの更新に伴う対応

Required by case

Required by case

6.

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

Optional

Optional

7.

SecurityFilterChainの設定変更

Required

Required

8.

Spring Data 2.5.0から非推奨となったAPIへの対応

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.7.2.RELEASE

Spring Framework

5.3.13

5.3.24

Spring Data

2.6.0

2.7.6

Spring Security

5.6.0

5.7.6

MyBatis3

3.5.7

3.5.11

MyBatis3 Spring

2.0.6

2.1.0

Hibernate ORM

5.6.1.Final

5.6.14.Final

Logback

1.2.7

1.2.11

SLF4J

1.7.32

1.7.36

Jackson

2.13.0

2.13.4.2

Hibernate Validator

6.2.0.Final

6.2.5.Final

Joda Time

2.10.9

2.12.2

Commons Fileupload

1.3.3

1.4

OpenPDF

1.0.5

1.3.20

Apache POI

4.1.2

5.2.3

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 Commons IO

2.6

2.11.0

Apache Commons Compress

1.21

1.22

Lombok

1.18.22

1.18.24

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.7.2.RELEASEに修正してください。

    • ($YOUR_MULTIPLE_PROJECT_ROOT/pom.xml)

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

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

    プロジェクトのPOMファイルのversionを5.7.2.RELEASEに修正してください。

    • ($YOUR_SINGLE_PROJECT/pom.xml)

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

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

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

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

  1. オンライン環境

    1. ブランクプロジェクトを作成
      ガイドラインの記述を参考に、archetype:generateを実行し、5.7.2.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の修正
      オフライン環境のプロジェクトにて、[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] 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.3. [Step 3] 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.4. [Step 4] 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.5. [Step 5] 共通ライブラリが管理するMavenプラグインの更新に伴う対応

共通ライブラリが管理するMavenプラグインのバージョンを更新しました。

アプリケーションで独自にプラグインのバージョンを指定していない場合、自動的にアップグレードされビルドの挙動に変更が生じる可能性があります。なお、本手順ではApache Mavenのバージョンを3.8.6で使用することを前提としています。

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

[手順が必要なケース]

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

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

[修正方法]

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

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

  • pom.xml

<properties>
    <!-- omitted -->
    <org.apache.maven.plugins.maven-install-plugin.version>3.0.0-M1</org.apache.maven.plugins.maven-install-plugin.version>  <!-- ### 追加箇所 ### -->
</properties>

2.6. [Step 6] JDBCドライバーのバージョンの変更

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

[手順が必要なケース]

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

2.6.1. [Step 6-1] PostgreSQLを使用する場合

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

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

[修正方法]

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

  • pom.xml

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

2.6.2. [Step 6-2] Oracle Databaseを使用する場合

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

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

[修正方法]

プロジェクトのpom.xmlを更新します。利用するJDKのバージョンによってドライバが異なるため、注意してください。

[Step 6-2-1] JDK8の場合

  • pom.xml

<dependencyManagement>
    <dependencies>
    <!-- omitted -->
        <dependency>
            <groupId>com.oracle.jdbc</groupId>
            <artifactId>ojdbc8</artifactId>
            <version>${ojdbc.version}</version>
        </dependency>
    <!- omitted -->
    </dependencies>
</dependencyManagement>
<properties>
    <!-- omitted -->
    <ojdbc.version>21.8.0.0</ojdbc.version> <!-- ### 修正箇所 ### -->
    <!-- omitted -->
</properties>
[Step 6-2-2] JDK11/JDK17の場合

  • 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.7. [Step 7] SecurityFilterChainの設定変更

AuthorizationFilterの脆弱性 CVE-2022-31692で説明されている内容と同様の問題が SecurityFilterChainでも発生する可能性があるため、設定の修正が必要となります。

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

  • spring-security.xmlの<sec:http>タグの設定を修正する

  • web.xmlのfilter-mappingに適切なDispatcherTypeを設定する

2.7.1. [Step 7-1] spring-security.xmlの<sec:http>タグの設定を修正する

spring-security.xmlの<sec:http>タグのonce-per-request属性はデフォルトではtrueとなっているため、リクエストがservletによってディスパッチされた先では認可処理が実施されず、ディスパッチ先がディスパッチ元よりも上位の権限を必要とする場合に認可処理がバイパスされてしまいます。このような認可処理のバイパスを防ぐため、ブランクプロジェクトのonce-per-request属性をfalseに設定しました。

[手順が必要なケース]

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

[修正方法]

spring-security.xmlの<sec:http>タグのonce-per-request属性をfalseに設定します。

  • spring-security.xml

    <sec:http pattern="/resources/**" security="none"/> <!-- ### security="none"のため修正不要 ### -->
    <sec:http once-per-request="false"> <!-- ### 修正箇所 ### -->
        <sec:form-login/>
        <sec:logout/>
        <sec:access-denied-handler ref="accessDeniedHandler"/>
        <sec:custom-filter ref="userIdMDCPutFilter" after="ANONYMOUS_FILTER"/>
        <sec:session-management />
    </sec:http>

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

デフォルトのDispatcherTypeはREQUESTのみが設定されているため、DispatcherTypeの見直しが必要になります。

[手順が必要なケース]

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

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

[修正方法]

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

2.8. [Step 8] Spring Data 2.7.0から非推奨となったAPIへの対応

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

  • JpaRepository#getById(ID)メソッド

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

[手順が必要なケース]

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

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

[修正方法]

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

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️