2.1. Macchinetta Server Framework (1.x)のスタック¶
目次
2.1.1. Macchinetta Server Framework (1.x)のSoftware Framework概要¶
Macchinetta Server Framework (1.x)で使用するSoftware Frameworkは独自のフレームワークではなく、Spring Frameworkを中心としたOSSの組み合わせである。
2.1.2. Software Frameworkの主な構成要素¶
Macchinetta Server Framework (1.x)を構成するライブラリを以下に示す。
2.1.2.3. O/R Mapper¶
本ガイドラインでは、以下を想定している。
- MyBatis 3.5
- Spring Frameworkとの連携ライブラリとして、MyBatis-Springを使用する。
Note
MyBatisは正確には「SQL Mapper」であるが、本ガイドラインでは「O/R Mapper」に分類する。
2.1.2.5. セキュリティ¶
認証・認可のフレームワークとしてSpring Securityを利用する。
Tip
Spring Security 3.2 から、認証・認可の仕組みの提供に加えて、悪意のある攻撃者からWebアプリケーションを守るための仕組みが強化されている。
悪意のある攻撃者からWebアプリケーションを守るための仕組みについては、
を参照されたい。
2.1.2.6. バリデーション¶
- 単項目チェックにはBean Validation 3.0を利用する。
- 実装は、Hibernate Validator 8.0を利用する。
- 相関チェックにはBean Validation 3.0、もしくはSpring Validationを利用する。
- 使い分けについては入力チェックを参照されたい。
2.1.2.7. ロギング¶
Tip
CVE-2021-42550に対応するため、Logback1.2.8以降のバージョンではモジュール構成が変更されDBAppenderに関する機能は別モジュールとなった。
logback-classicやlogback-accessのDBAppenderを使用した機能を利用するためには、pom.xmlに以下のアーティファクトを追加する必要がある。
- ch.qos.logback.db:logback-classic-db:1.2.11.1
- ch.qos.logback.db:logback-access-db:1.2.11.1
2.1.3. 利用するOSSのバージョン¶
version 1.9.1.RELEASEで利用するOSSの一覧を以下に示す。
Note
version 1.6.1.RELEASEより、Spring Bootが提供するspring-boot-dependenciesの<dependencyManagement>をインポートする構成を採用している。
spring-boot-dependenciesの<dependencyManagement>をインポートすることで、
- Spring Frameworkが提供しているライブラリ
- Spring Frameworkが依存しているOSSライブラリ
- Spring Frameworkと相性のよいOSSライブラリ
への依存関係を解決しており、Macchinetta Server Framework (1.x)で使用するOSSのバージョンは、原則として、Spring Bootで管理されているバージョンに準ずる。
なお、version 1.9.1.RELEASEではSpring Boot 3.0.1に依存しており、管理されるライブラリはSpring Boot Reference Guide - Appendix F. Dependency versionsの通りとなる。
| Type | GroupId | ArtifactId | Version | Spring Boot | Remarks |
|---|---|---|---|---|---|
| Spring | org.springframework | spring-aop | 6.0.3 | * | |
| Spring | org.springframework | spring-aspects | 6.0.3 | * | |
| Spring | org.springframework | spring-beans | 6.0.3 | * | |
| Spring | org.springframework | spring-context | 6.0.3 | * | |
| Spring | org.springframework | spring-context-support | 6.0.3 | * | |
| Spring | org.springframework | spring-core | 6.0.3 | * | |
| Spring | org.springframework | spring-expression | 6.0.3 | * | |
| Spring | org.springframework | spring-jdbc | 6.0.3 | * | |
| Spring | org.springframework | spring-orm | 6.0.3 | * | |
| Spring | org.springframework | spring-oxm | 6.0.3 | * | |
| Spring | org.springframework | spring-tx | 6.0.3 | * | |
| Spring | org.springframework | spring-web | 6.0.3 | * | |
| Spring | org.springframework | spring-webmvc | 6.0.3 | * | |
| Spring | org.springframework | spring-jms | 6.0.3 | * | |
| Spring | org.springframework | spring-messaging | 6.0.3 | * | |
| Spring | org.springframework.data | spring-data-commons | 3.0.0 | * | |
| Spring | org.springframework.security | spring-security-acl | 6.0.1 | * | |
| Spring | org.springframework.security | spring-security-config | 6.0.1 | * | |
| Spring | org.springframework.security | spring-security-core | 6.0.1 | * | |
| Spring | org.springframework.security | spring-security-web | 6.0.1 | * | |
| Spring | org.springframework.security | spring-security-oauth2-client | 6.0.1 | * | |
| Spring | org.springframework.security | spring-security-oauth2-resource-server | 6.0.1 | * | |
| Spring | org.springframework.security | spring-security-oauth2-jose | 6.0.1 | * | |
| MyBatis3 | org.mybatis | mybatis | 3.5.11 | *1 | |
| MyBatis3 | org.mybatis | mybatis-spring | 3.0.1 | *1 | |
| DI | jakarta.inject | jakarta.inject-api | 2.0.1 | ||
| AOP | org.aspectj | aspectjrt | 1.9.19 | * | |
| AOP | org.aspectj | aspectjweaver | 1.9.19 | * | |
| ログ出力 | ch.qos.logback | logback-classic | 1.4.5 | * | |
| ログ出力 | org.slf4j | slf4j-api | 2.0.6 | * | |
| JSON | com.fasterxml.jackson.core | jackson-databind | 2.14.1 | * | |
| JSON | com.fasterxml.jackson.datatype | jackson-datatype-jsr310 | 2.14.1 | * | |
| Thymeleaf | org.thymeleaf | thymeleaf | 3.1.1.RELEASE | * | |
| Thymeleaf | org.thymeleaf | thymeleaf-spring6 | 3.1.1.RELEASE | * | |
| Thymeleaf | org.thymeleaf.extras | thymeleaf-extras-springsecurity6 | 3.1.1.RELEASE | * | |
| 入力チェック | org.hibernate.validator | hibernate-validator | 8.0.0.Final | * | |
| Bean変換 | commons-beanutils | commons-beanutils | 1.9.4 | ||
| Bean変換 | org.mapstruct | mapstruct | 1.5.3.Final | ||
| Bean変換 | org.apache.commons | commons-lang3 | 3.12.0 | * | |
| コネクションプール | org.apache.commons | commons-dbcp2 | 2.9.0 | * | |
| ファイルダウンロード | com.github.librepdf | openpdf | 1.3.30 | ||
| ファイルダウンロード | org.apache.poi | poi-ooxml | 5.2.3 | ||
| E-mail送信(SMTP) | org.eclipse.angus | jakarta.mail | 1.0.0 | * | |
| HTTP通信 | org.apache.httpcomponents.client5 | httpclient5 | 5.1.4 | * | |
| ユーティリティ | com.google.guava | guava | 31.1-jre | ||
| ユーティリティ | org.apache.commons | commons-collections4 | 4.4 | ||
| ユーティリティ | commons-io | commons-io | 2.11.0 | ||
| コーディングサポート | org.projectlombok | lombok | 1.18.24 | * |
- データアクセスに、MyBatis3を使用する場合に依存するライブラリ
2.1.4. 共通ライブラリの構成要素¶
Macchinetta Server Framework (1.x)では、TERASOLUNA Server Framework for Java (5.x)が提供する共通ライブラリを使用する。（以降「共通ライブラリ」と記載する。）
共通ライブラリは、Macchinetta Server Framework (1.x)やTERASOLUNA Server Framework for Java (5.x)が含むSpring Ecosystem や、その他依存ライブラリでは足りない+αな機能を提供するライブラリである。
基本的には、このライブラリがなくてもMacchinetta Server Framework (1.x)によるアプリケーション開発は可能であるが、”あると便利”な存在である。
また、提供している2種類の マルチプロジェクト構成のブランクプロジェクトおよび シングルプロジェクト構成のブランクプロジェクトの共通ライブラリの標準の組込状況は以下の通りである。
| 項番 | プロジェクト名 | 概要 | Javaソースコード有無 | マルチプロジェクト構成のブランクプロジェクト組込 | シングルプロジェクト構成のブランクプロジェクト組込 |
|---|---|---|---|---|---|
| (1) | terasoluna-gfw-parent | 依存ライブラリの管理とビルド用プラグインの推奨設定を提供する。 | 無 | 有*1 | 有*1 |
| (2) | terasoluna-gfw-common-libraries | 共通ライブラリのうち、Javaソースコードを含むプロジェクトの構成を定義する。依存関係としてpom.xmlに追加する必要はない。 | 無 | 無 | 無 |
| (3) | terasoluna-gfw-dependencies | 共通ライブラリのうち、依存関係定義のみを提供するプロジェクト(terasoluna-gfw-parent以外)の構成を定義する。依存関係としてpom.xmlに追加する必要はない。 | 無 | 無 | 無 |
| (4) | terasoluna-gfw-common | Webに依存しない汎用的に使用できる機能を提供する。本ライブラリを利用する場合は、依存関係としてterasoluna-gfw-common-dependenciesをpom.xmlに追加する。 | 有 | 有*2 | 有*2 |
| (5) | terasoluna-gfw-common-dependencies | terasoluna-gfw-commonプロジェクトが提供する機能を使用する場合の依存関係定義を提供する。 | 無 | 有 | 有 |
| (6) | terasoluna-gfw-jodatime | 非推奨*6
Joda Timeに依存する機能を提供する。本ライブラリを利用する場合は、依存関係としてterasoluna-gfw-jodatime-dependenciesをpom.xmlに追加する。
|
有 | 無 | 無 |
| (7) | terasoluna-gfw-jodatime-dependencies | 非推奨*6
terasoluna-gfw-jodatimeプロジェクトが提供する機能を使用する場合の依存関係定義を提供する。
|
無 | 無 | 無 |
| (8) | terasoluna-gfw-web | Webアプリケーションを作成する場合に使用する機能を提供する。Viewに依存しない機能を集約している。本ライブラリを利用する場合は、依存関係としてterasoluna-gfw-web-dependenciesをpom.xmlに追加する。 | 有 | 有*2 | 有*2 |
| (9) | terasoluna-gfw-web-dependencies | terasoluna-gfw-webプロジェクトが提供する機能を使用する場合の依存関係定義を提供する。 | 無 | 有 | 有 |
| (10) | terasoluna-gfw-web-jsp | ViewにJSPを採用するWebアプリケーションを作成する場合に使用する機能を提供する。本ライブラリを利用する場合は、依存関係としてterasoluna-gfw-web-jsp-dependenciesをpom.xmlに追加する。 | 有 | 無*2*6 | 無*2*6 |
| (11) | terasoluna-gfw-web-jsp-dependencies | terasoluna-gfw-web-jspプロジェクトが提供する機能を使用する場合の依存関係定義を提供する。 | 無 | 無*6 | 無*6 |
| (12) | terasoluna-gfw-security-web | Spring Securityの拡張部品を提供する。本ライブラリを利用する場合は、依存関係としてterasoluna-gfw-security-web-dependenciesをpom.xmlに追加する。 | 有 | 有*2 | 有*2 |
| (13) | terasoluna-gfw-security-web-dependencies | Spring Securityを使用する場合の依存関係定義(Web関連)と、terasoluna-gfw-security-webプロジェクトが提供する機能を使用する場合の依存関係定義を提供する。 | 無 | 有 | 有 |
| (14) | terasoluna-gfw-string | 文字列処理に関連する機能を提供する。 | 有 | 無 | 無 |
| (15) | terasoluna-gfw-codepoints | 対象の文字列を構成するコードポイントがコードポイント集合に含まれることをチェックする機能を提供する。 | 有 | 無*3 | 無*3 |
| (16) | terasoluna-gfw-validator | 汎用的なBean Validationの制約アノテーションを追加して提供する。 | 有 | 無 | 無 |
| (17) | terasoluna-gfw-security-core-dependencies | Spring Securityを使用する場合の依存関係定義(Web以外)を提供する。 | 無 | 有 | 有 |
| (18) | terasoluna-gfw-mybatis3-dependencies | MyBatis3を使用する場合の依存関係定義を提供する。 | 無 | 有*4 | 有*4 |
| (19) | terasoluna-gfw-jpa-dependencies | JPAを使用する場合の依存関係定義を提供する。 | 無 | 有*5 | 有*5 |
| (20) | terasoluna-gfw-recommended-dependencies | Webに依存しない推奨ライブラリへの依存関係定義を提供する。 | 無 | 有 | 有 |
| (21) | terasoluna-gfw-recommended-web-dependencies | Webに依存する推奨ライブラリへの依存関係定義を提供する。 | 無 | 有 | 有 |
<dependency>要素ではないが、各プロジェクトの<parent>要素として組み込まれる。<dependency>要素ではないが、<dependency>要素からの推移的依存関係として組み込まれる。- 使用するコードポイント集合に応じて複数のアーティファクトを提供している。詳細は共通ライブラリから提供しているコードポイント集合クラスを参照されたい。
- データアクセスに、MyBatis3を使用する場合に標準で組み込まれる共通ライブラリ
- データアクセスに、JPAを使用する場合に用いる共通ライブラリ。Macchinetta Server Framework (1.x)では使用しない
- Viewに、JSPを使用する場合に用いる共通ライブラリ。Macchinetta Server Framework (1.x) Thymeleaf版では使用しない
Javaソースコードを含まないものは、ライブラリの依存関係のみ定義しているプロジェクトである。
なお、プロジェクトの依存関係は以下の通りである。
Note
一部を除き、共通ライブラリにはプロジェクト名末尾に”dependencies”が付与されたプロジェクトが存在する。(例えば、terasoluna-gfw-commonに対応するterasoluna-gfw-common-dependenciesなどである)
このようなプロジェクトでは、共通ライブラリへの依存関係定義の他に、利用を推奨するOSSライブラリへの依存関係定義を提供している為、共通ライブラリを利用する際は”dependencies”が付与されたプロジェクトの方を、依存関係としてpom.xmlに追加することを推奨する。
Note
version 1.9.1.RELEASEでは TERASOLUNA Server Framework for Java 5.8.1.RELEASE の共通ライブラリを使用している。
2.1.4.1. terasoluna-gfw-common¶
terasoluna-gfw-commonは以下の部品を提供している。
| 分類 | 部品名 | 説明 |
|---|---|---|
| 例外ハンドリング | 例外クラス | 汎用的に使用できる例外クラスを提供する。 |
| 例外ロガー | アプリケーション内で発生した例外をログに出力するためのロガークラスを提供する。 | |
| 例外コード | 例外クラスに対応する例外コード(メッセージID)を解決するための仕組み(クラス)を提供する。 | |
| 例外ログ出力インターセプタ | ドメイン層で発生した例外をログ出力するためのインターセプタクラス(AOP)を提供する。 | |
| システム時刻 | システム時刻ファクトリ | JSR-310 Date and Time APIを利用してシステム時刻を取得するためのクラスを提供する。 |
| コードリスト | コードリスト | コードリストを生成するためのクラスを提供する。 |
| データベースアクセス（共通編） | クエリエスケープ | SQL及びJPQLにバインドする値のエスケープ処理を行うクラスを提供する。 |
| シーケンサ | シーケンス値を取得するためのクラスを提供する。 |
2.1.4.2. terasoluna-gfw-string¶
terasoluna-gfw-stringは以下の部品を提供している。
| 分類 | 部品名 | 説明 |
|---|---|---|
| 文字列処理 | 半角全角変換 | 半角文字列と全角文字列のマッピングテーブルに基づき、入力文字列の半角文字を全角に変換する処理と全角文字を半角に変換する処理を行うクラスを提供する。 |
2.1.4.3. terasoluna-gfw-codepoints¶
terasoluna-gfw-codepointsは以下の部品を提供している。
| 分類 | 部品名 | 説明 |
|---|---|---|
| 文字列処理 | コードポイントチェック | 対象の文字列を構成するコードポイントが、定義されたコードポイント集合に含まれることをチェックするクラスを提供する。 |
| 入力チェック | コードポイントチェック用Bean Validation制約アノテーション | コードポイントチェックをBean Validationで行うための制約アノテーションを提供する。 |
2.1.4.4. terasoluna-gfw-validator¶
terasoluna-gfw-validatorは以下の部品を提供している。
| 分類 | 部品名 | 説明 |
|---|---|---|
| 入力チェック | バイト長チェック用Bean Validation制約アノテーション | 入力文字列の文字コードにおけるバイト長が、指定した最大値以下であること、最小値以上であることのチェックをBean Validationで行うための制約アノテーションを提供する。 |
| プロパティ値比較チェック用Bean Validation制約アノテーション | 2つのプロパティ値の比較チェックをBean Validationで行うための制約アノテーションを提供する。 |
2.1.4.5. terasoluna-gfw-jodatime¶
terasoluna-gfw-jodatimeは以下の部品を提供している。
Note
Joda-Time は、Java SE 8以前の日付計算をサポートするための機能であり、Java SE 8以降はJSR-310 Date and Time APIを使用することが推奨されている。
詳しくは、日付操作(JSR-310 Date and Time API)およびシステム時刻を参照されたい。
| 分類 | 部品名 | 説明 |
|---|---|---|
| システム日時(1.8.1.SP1.RELEASE) | Joda Time用システム時刻ファクトリ | Joda TimeのAPIを利用してシステム時刻を取得するためのクラスを提供する。
非推奨の為、現バージョンのガイドラインでは案内していない。
|
2.1.4.6. terasoluna-gfw-web¶
terasoluna-gfw-webは以下の部品を提供している。
| 分類 | 部品名 | 説明 |
|---|---|---|
| 二重送信防止 | トランザクショントークンチェック | リクエストの二重送信からWebアプリケーションを守るための仕組み(クラス)を提供する。 |
| 例外ハンドリング | 例外ハンドラ | 共通ライブラリが提供する例外ハンドリングの部品と連携するための例外ハンドラクラス(Spring MVC提供のクラスのサブクラス)を提供する。 |
| 例外ログ出力インターセプタ | Spring MVCの例外ハンドラがハンドリングした例外をログ出力するためのインターセプタクラス(AOP)を提供する。 | |
| コードリスト | コードリスト埋込インターセプタ | Viewからコードリストを取得できるようにするために、コードリストの情報をリクエストスコープに格納するためのインターセプタクラス(Spring MVC Interceptor)を提供する。 |
| ファイルダウンロード | 汎用ダウンロードView | ストリームから取得したデータを、ダウンロード用のストリームに出力するための抽象クラスを提供する。 |
| ロギング | トラッキングID格納用サーブレットフィルタ | トレーサビリティを向上させるために、 クライアントから指定されたトラッキングIDを、ロガーのMDC(Mapped Diagnostic Context)、リクエストスコープ、レスポンスヘッダに設定するためのサーブレットフィルタクラスを提供する。 (クライアントからトラッキングIDの指定がない場合は、本クラスでトラッキングIDを生成する) |
| 汎用MDC格納用サーブレットフィルタ | ロガーのMDCに任意の値を設定するための抽象クラスを提供する。 | |
| MDCクリア用サーブレットフィルタ | ロガーのMDCに格納されている情報をクリアするためのサーブレットフィルタクラスを提供する。 |
2.1.4.7. terasoluna-gfw-web-jsp¶
terasoluna-gfw-web-jspは以下の部品を提供している。
| 分類 | 部品名 | 説明 |
|---|---|---|
| 二重送信防止 | トランザクショントークン出力用のJSPタグ | トランザクショントークンをhidden項目として出力するためのJSPタグライブラリを提供する。 |
| ページネーション | ページネーションリンク表示用のJSPタグ | Spring Data Commons提供のクラスと連携してページネーションリンクを表示するためのJSPタグライブラリを提供する。 |
| メッセージ管理 | 結果メッセージ表示用のJSPタグ | 処理結果を表示するためのJSPタグライブラリを提供する。 |
| EL Functions | XSS対策用EL関数 | XSS対策用のEL関数を提供する。 |
| URL用EL関数 | URLエンコーディングなどのURL用のEL関数を提供する。 | |
| DOM変換用EL関数 | DOM文字列に変換するためのEL関数を提供する。 | |
| ユーティリティEL関数 | 汎用的なユーティリティ処理を行うためのEL関数を提供する。 |
2.1.4.8. terasoluna-gfw-security-web¶
terasoluna-gfw-security-webは以下の部品を提供している。
| 分類 | 部品名 | 説明 |
|---|---|---|
| ロギング | 認証ユーザ名格納用サーブレットフィルタ | トレーサビリティを向上させるために、 認証ユーザ名をロガーのMDCに設定するためのサーブレットフィルタクラスを提供する。 |