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の組み合わせである。

../_images/introduction-software-framework.png

2.1.2. Software Frameworkの主な構成要素

Macchinetta Server Framework (1.x)を構成するライブラリを以下に示す。

../_images/introduction-software-stack.png

2.1.2.1. DIコンテナ

DIコンテナとしてSpring Frameworkを利用する。


2.1.2.2. MVCフレームワーク

Web MVCフレームワークとしてSpring MVCを利用する。


2.1.2.3. O/R Mapper

本ガイドラインでは、以下を想定している。

Note

MyBatisは正確には「SQL Mapper」であるが、本ガイドラインでは「O/R Mapper」に分類する。


2.1.2.4. View

本ガイドラインでは、以下のいずれかを想定している。

  • JSP

  • Thymeleaf

Tip

Macchinetta Server Framework (1.x) 1.8 まではViewのレイアウトの共通化としてApache Tilesを利用していたが、Jakarta EE 9 以降のライブラリバージョンが存在しておらず、代替ライブラリも存在していない。そのため、Macchinetta Server Framework (1.x) 1.8以降では、JSPのレイアウトの共通化は行っていない。

画面レイアウトを行いたい場合は、Thymeleafの使用を検討されたい。


2.1.2.5. セキュリティ

認証・認可のフレームワークとしてSpring Securityを利用する。

Tip

Spring Security 3.2 から、認証・認可の仕組みの提供に加えて、悪意のある攻撃者からWebアプリケーションを守るための仕組みが強化されている。

悪意のある攻撃者からWebアプリケーションを守るための仕組みについては、

を参照されたい。


2.1.2.6. バリデーション


2.1.2.7. ロギング

  • ロガーのAPIはSLF4Jを使用する。

    • ロガーの実装は、Logbackを利用する。

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.2.8. 共通ライブラリ

Note

単体テストで利用するOSSライブラリについては、本章とは別に単体テスト概要で解説している。


2.1.3. 利用するOSSのバージョン

version 1.10.0.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.10.0.RELEASEではSpring Boot 3.2.2に依存しており、管理されるライブラリはSpring Boot Reference Guide - Appendix F. Dependency versionsの通りとなる。

Type

GroupId

ArtifactId

Version

Spring Boot

Remarks

Spring

org.springframework

spring-aop

6.1.3

*

Spring

org.springframework

spring-aspects

6.1.3

*

Spring

org.springframework

spring-beans

6.1.3

*

Spring

org.springframework

spring-context

6.1.3

*

Spring

org.springframework

spring-context-support

6.1.3

*

Spring

org.springframework

spring-core

6.1.3

*

Spring

org.springframework

spring-expression

6.1.3

*

Spring

org.springframework

spring-jdbc

6.1.3

*

Spring

org.springframework

spring-orm

6.1.3

*

Spring

org.springframework

spring-oxm

6.1.3

*

Spring

org.springframework

spring-tx

6.1.3

*

Spring

org.springframework

spring-web

6.1.3

*

Spring

org.springframework

spring-webmvc

6.1.3

*

Spring

org.springframework

spring-jms

6.1.3

*

Spring

org.springframework

spring-messaging

6.1.3

*

Spring

org.springframework.data

spring-data-commons

3.2.2

*

Spring

org.springframework.security

spring-security-acl

6.2.1

*

Spring

org.springframework.security

spring-security-config

6.2.1

*

Spring

org.springframework.security

spring-security-core

6.2.1

*

Spring

org.springframework.security

spring-security-taglibs

6.2.1

*

*1

Spring

org.springframework.security

spring-security-web

6.2.1

*

Spring

org.springframework.security

spring-security-oauth2-client

6.2.1

*

Spring

org.springframework.security

spring-security-oauth2-resource-server

6.2.1

*

Spring

org.springframework.security

spring-security-oauth2-jose

6.2.1

*

MyBatis3

org.mybatis

mybatis

3.5.15

*3

MyBatis3

org.mybatis

mybatis-spring

3.0.3

*3

DI

jakarta.inject

jakarta.inject-api

2.0.1

AOP

org.aspectj

aspectjrt

1.9.21

*

AOP

org.aspectj

aspectjweaver

1.9.21

*

ログ出力

ch.qos.logback

logback-classic

1.4.14

*

ログ出力

org.slf4j

slf4j-api

2.0.12

*4

JSON

com.fasterxml.jackson.core

jackson-databind

2.15.3

*

JSON

com.fasterxml.jackson.datatype

jackson-datatype-jsr310

2.15.3

*

Thymeleaf

org.thymeleaf

thymeleaf

3.1.2.RELEASE

*

*2

Thymeleaf

org.thymeleaf

thymeleaf-spring6

3.1.2.RELEASE

*

*2

Thymeleaf

org.thymeleaf.extras

thymeleaf-extras-springsecurity6

3.1.2.RELEASE

*

*2

入力チェック

org.hibernate.validator

hibernate-validator

8.0.1.Final

*

Bean変換

commons-beanutils

commons-beanutils

1.9.4

Bean変換

org.mapstruct

mapstruct

1.5.5.Final

Bean変換

org.apache.commons

commons-lang3

3.13.0

*

日付操作

net.sargue

java-time-jsptags

2.0.0

コネクションプール

org.apache.commons

commons-dbcp2

2.10.0

*

ファイルダウンロード

com.github.librepdf

openpdf

1.3.35

ファイルダウンロード

org.apache.poi

poi-ooxml

5.2.5

E-mail送信(SMTP)

org.eclipse.angus

jakarta.mail

2.0.2

*

HTTP通信

org.apache.httpcomponents.client5

httpclient5

5.2.3

*

ユーティリティ

com.google.guava

guava

33.0.0-jre

ユーティリティ

org.apache.commons

commons-collections4

4.4

ユーティリティ

commons-io

commons-io

2.15.1

サーブレット

org.glassfish.web

jakarta.servlet.jsp.jstl

3.0.1

*

*1

コーディングサポート

org.projectlombok

lombok

1.18.30

*
  1. Viewに、JSPを使用する場合に依存するライブラリ
  2. VIEWに、Thymeleafを使用する場合に依存するライブラリ
  3. データアクセスに、MyBatis3を使用する場合に依存するライブラリ
  4. Spring Bootで管理されているバージョンから、Macchinetta Server Framework (1.x)で使用するバージョンを変更しているライブラリ

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ソースコード有無

ViewにJSPを使用したブランクプロジェクトの組込

ViewにThymeleafを使用したブランクプロジェクトの組込

(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

無

(11)

terasoluna-gfw-web-jsp-dependencies

terasoluna-gfw-web-jspプロジェクトが提供する機能を使用する場合の依存関係定義を提供する。

無

有

無

(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に依存する推奨ライブラリへの依存関係定義を提供する。

無

有

有
  1. <dependency>要素ではないが、各プロジェクトの<parent>要素として組み込まれる。
  2. <dependency>要素ではないが、<dependency>要素からの推移的依存関係として組み込まれる。
  3. 使用するコードポイント集合に応じて複数のアーティファクトを提供している。詳細は共通ライブラリから提供しているコードポイント集合クラスを参照されたい。
  4. データアクセスに、MyBatis3を使用する場合に標準で組み込まれる共通ライブラリ
  5. データアクセスに、JPAを使用する場合に用いる共通ライブラリ。Macchinetta Server Framework (1.x)では使用しない
  6. terasoluna-gfw-commonが提供するJSR-310用の機能を使用されたい。詳細は日付操作(JSR-310 Date and Time API)およびシステム時刻を参照されたい。

Javaソースコードを含まないものは、ライブラリの依存関係のみ定義しているプロジェクトである。

なお、プロジェクトの依存関係は以下の通りである。

../_images/FrameworkStackProjectDependencies.png

Note

一部を除き、共通ライブラリにはプロジェクト名末尾に”dependencies”が付与されたプロジェクトが存在する。(例えば、terasoluna-gfw-commonに対応するterasoluna-gfw-common-dependenciesなどである)

このようなプロジェクトでは、共通ライブラリへの依存関係定義の他に、利用を推奨するOSSライブラリへの依存関係定義を提供している為、共通ライブラリを利用する際は”dependencies”が付与されたプロジェクトの方を、依存関係としてpom.xmlに追加することを推奨する。

Note

version 1.10.0.RELEASEでは TERASOLUNA Server Framework for Java 5.9.0.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に設定するためのサーブレットフィルタクラスを提供する。