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

概要

コンパイル時、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を使った走査のコード も参照ください。

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

komapper.enableEntityProjection

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

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

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