アノテーションプロセッシング

概要

コンパイル時、Komapperはマッピング定義内のアノテーションを処理し、結果をメタモデルのソースコードとして生成します。アノテーションの処理とコードの生成には Kotlin Symbol Processing API (KSP)を利用します。

KSPを実行するためには、Gradleビルドスクリプトを次のように記述します。

plugins {
  id("com.google.devtools.ksp") version "1.9.23-1.0.19"
  kotlin("jvm") version "1.9.23"
}

dependencies {
  val komapperVersion = "1.17.0"
  ksp("org.komapper:komapper-processor:$komapperVersion")
}

komapper-processorモジュールにはKSPのアノテーションプロセッサが含まれます。

上記設定後、Gradleのbuildタスクを実行するとbuild/generated/ksp/main/kotlinディレクトリ以下にコードが生成されます。

オプション

オプションによりアノテーションプロセッサの挙動を変更できます。利用可能なオプションは以下の通りです。

komapper.prefix
komapper.suffix
komapper.enumStrategy
komapper.namingStrategy
komapper.metaObject
komapper.alwaysQuote
komapper.enableEntityMetamodelListing
komapper.enableEntityStoreContext
komapper.enableEntityProjection

オプションを指定するにはGradleのビルドスクリプトで次のように記述します。

ksp {
  arg("komapper.prefix", "")
  arg("komapper.suffix", "Metamodel")
  arg("komapper.enumStrategy", "ordinal")
  arg("komapper.namingStrategy", "UPPER_SNAKE_CASE")
  arg("komapper.metaObject", "example.Metamodels")
  arg("komapper.alwaysQuote", "true")
  arg("komapper.enableEntityMetamodelListing", "true")
  arg("komapper.enableEntityStoreContext", "true")
  arg("komapper.enableEntityProjection", "true")  
}

komapper.prefix

生成されるメタモデルクラスのプレフィックスです。デフォルト値は_（アンダースコア）です。

komapper.suffix

生成されるメタモデルクラスのサフィックスです。デフォルト値は空文字です。

komapper.enumStrategy

Enum型のプロパティをデータベースのカラムどうマッピングするかの戦略です。値にはnameまたはordinalのいずれかを選択できます。デフォルト値はnameです。なお、@KomapperEnumによる指定はこの戦略よりも優先されます。

komapper.enumStrategyオプションに指定可能な値の定義は次の通りです。

name: Enumクラスのnameプロパティを文字列型のカラムにマッピングする。
ordinal: Enumクラスのordinalプロパティを整数型のカラムにマッピングする。
type: Enumクラスをenum型のカラムにマッピングする。 Enumクラスに対応するユーザー定義のデータ型が必要であることに注意してほしい。

komapper.namingStrategy

Kotlinのエンティクラスとプロパティからデータベースのテーブルとカラムの名前をどう解決するのかの戦略です。値にはimplicit、lower_snake_case、UPPER_SNAKE_CASEのいずれかを選択できます。デフォルト値はlower_snake_caseです。解決されたデータベースのテーブルとカラムの名前は生成されるメタモデルのコードの中に含まれます。なお、@KomapperTableや@KomapperColumnで名前が指定される場合この戦略で決定される名前よりも優先されます。

komapper.namingStrategyオプションに指定可能な値の定義は次の通りです。

implicit: エンティティクラスやプロパティの名前をそのままテーブルやカラムの名前とする。
lower_snake_case: エンティティクラスやプロパティの名前をキャメルケースからスネークケースに変換した上で全て小文字にしテーブルやカラムの名前とする。
UPPER_SNAKE_CASE: エンティティクラスやプロパティの名前をキャメルケースからスネークケースに変換した上で全て大文字にしテーブルやカラムの名前とする。

komapper.metaObject

メタモデルのインスタンスを拡張プロパティとして提供するobjectを指定します。デフォルト値はorg.komapper.core.dsl.Metaです。

komapper.alwaysQuote

SQL文の中でテーブル名やカラム名をクォートするかどうかです。デフォルト値はfalseです。

komapper.enableEntityMetamodelListing

エンティティメタモデルの一覧を取得できるようにするかどうかです。デフォルト値はfalseです。

trueを設定すると、次のような方法で一覧を取得できます。

val metamodels: List<EntityMetamodel<*, *, *>> = Meta.all()

val metamodels: List<EntityMetamodel<*, *, *>> = EntityMetamodels.list(Meta)

komapper.enableEntityStoreContext

EntityStoreのコンテキストを有効にするかどうかです。デフォルト値はfalseです。

trueを設定すると、context receiver を利用するAssociation APIのコードを生成します。

context receiverを使った走査のコードも参照ください。

Note

このオプションを有効にするには、合わせて以下のコードをGradleのビルドスクリプトに追加してください。

tasks {
    withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
        kotlinOptions.freeCompilerArgs += listOf("-Xcontext-receivers")
    }
}

komapper.enableEntityProjection

クエリの結果をエンティティへ射影することを有効にするかどうかです。有効にすると全てのエンティティクラスについてSelectQueryとTemplateSelectQueryBuilderの拡張関数が生成されます。デフォルト値はfalseです。

拡張関数の名前はselectAsAddressのようにselectAs + エンティティクラスの単純名となります。

拡張関数の名前を変更したり、特定のエンティティクラスについてのみ射影を有効にしたい場合は@KomapperProjectionを使ってください。

最終更新 March 8, 2024: Release v1.17 (08bccf8)