Version v0.18 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Entity Class

エンティティクラス

概要

Komapperでは、データベースのテーブルに対応するKotlinクラスをエンティティクラスと呼びます。

エンティティクラスをテーブルにマッピングさせるには別途アノテーションを用いたマッピング定義が必要です。

マッピング定義はコンパイル時に解析されその結果がメタモデルとなりメタモデルがクエリの構築や実行で利用されます。

エンティティクラスの定義

エンティティクラスは次の要件を満たさなければいけません。

Data Classである
可視性がprivateでない
型パラメータを持っていない

例えば、次のようなテーブル定義があるとします。

create table if not exists ADDRESS (
  ADDRESS_ID integer not null auto_increment,
  STREET varchar(500) not null,
  VERSION integer not null,
  CREATED_AT timestamp,
  UPDATED_AT timestamp,
  constraint pk_ADDRESS primary key(ADDRESS_ID)
);

上記のテーブル定義に対応するエンティティクラス定義は次のようになります。

data class Address(
  val id: Int = 0,
  val street: String,
  val version: Int = 0,
  val createdAt: LocalDateTime? = null,
  val updatedAt: LocalDateTime? = null,
)

プロパティの型（Kotlinの型）とカラムの型（データベースの型）の対応関係は Dialect で定義されます。

エンティティクラスのマッピング定義

マッピング定義の作成方法は2種類あります。

エンティティクラス自身がマッピング定義を持つ方法
エンティティクラスとは別にエンティティ定義クラスを作成する方法

同一のエンティティクラスに対して1つの方法のみ適用できます。

エンティティクラス自身がマッピング定義を持つ方法

このときエンティティクラスは前のセクションで説明した要件に加えて次の条件を満たさなければいけません。

@KomapperEntityで注釈される
companion objectを持つ

例えば、前のセクションで示したAddressクラスにこの方法を適用すると次のように変更できます。

@KomapperEntity
data class Address(
  @KomapperId
  @KomapperAutoIncrement
  @KomapperColumn(name = "ADDRESS_ID")
  val id: Int = 0,
  val street: String,
  @KomapperVersion
  val version: Int = 0,
  @KomapperCreatedAt
  val createdAt: LocalDateTime? = null,
  @KomapperUpdatedAt
  val updatedAt: LocalDateTime? = null,
) {
  companion object
}

エンティティクラスとは別にエンティティ定義クラスを作成する方法

エンティティ定義クラスは次の要件を満たさなければいけません。

Data Classである
可視性がprivateでない
型パラメータを持っていない
@KomapperEntityDefで注釈され引数でエンティティクラスを受け取る
companion objectを持つ
エンティティクラスに定義されたプロパティと異なる名前のプロパティを持たない

例えば、前のセクションで示したAddressクラスに対するエンティティ定義クラスは次のように記述できます。

@KomapperEntityDef(Address::class)
data class AddressDef(
  @KomapperId
  @KomapperAutoIncrement
  @KomapperColumn(name = "ADDRESS_ID")
  val id: Nothing,
  @KomapperVersion
  val version: Nothing,
  @KomapperCreatedAt
  val createdAt: Nothing,
  @KomapperUpdatedAt
  val updatedAt: Nothing,
) {
  companion object
}

エンティティ定義クラスは、参照するエンティティクラスに定義された同名のプロパティに対し様々な設定ができます。定義されないプロパティに対してはデフォルトのマッピング定義が適用されます。上記の例ではエンティティクラスに登場するstreetプロパティがエンティティ定義クラスには登場しませんが、 streetプロパティにはテーブル上のSTREETカラムにマッピングされます。

エンティティ定義クラスのプロパティの型に制約はありません。上記の例ではNothingを使っています。

アノテーション一覧

ここで説明するアノテーションは全てorg.komapper.annotationパッケージに属します。

クラスに付与するアノテーション

@KomapperEntity

エンティティクラスがマッピング定義を持つことを表します。

@KomapperEntityDef

エンティティマッピング定義クラスであることを表します。

@KomapperTable

エンティティクラスとマッピングするテーブルの名前を明示的に指定します。

@KomapperEntityDef(Address::class)
@KomapperTable("ADDRESS", schema = "ACCOUNT", alwaysQuote = true)
data class AddressDef(
  ...
)

catalogプロパティやschemaプロパティにはテーブルが属するカタログやスキーマの名前を指定できます。

alwaysQuoteプロパティにtrueを設定すると生成されるSQLの識別子が引用符で囲まれます。

このアノテーションでテーブルの名前を指定しない場合、アノテーション処理のkomapper.namingStrategyオプションに従って名前が解決されます。以下のドキュメントも参照ください。

オプション

プロパティに付与するアノテーション

@KomapperId

プライマリーキーであることを表します。エンティティクラスのマッピングを行う上でこのアノテーションの存在は必須です。

@KomapperSequence

プライマリキーがデータベースのシーケンスで生成されることを表します。必ず@KomapperIdと一緒に付与する必要があります。

このアノテーションを付与するプロパティの型は次のいずれかでなければいけません。

Int
Long
UInt
上述の型をプロパティとして持つValue Class

@KomapperId
@KomapperSequence(name = "ADDRESS_SEQ", startWith = 1, incrementBy = 100)
val id: Int

nameプロパティにはシーケンスの名前を指定しなければいけません。カタログやスキーマの指定もできます。

startWithプロパティとincrementByプロパティの値はシーケンス定義に合わせなければいけません。

alwaysQuoteプロパティにtrueを設定すると生成されるSQLの識別子が引用符で囲まれます。

@KomapperAutoIncrement

プライマリーキーがデータベースの自動インクリメント機能で生成されることを表します。必ず@KomapperIdと一緒に付与する必要があります。

このアノテーションを付与するプロパティの型は次のいずれかでなければいけません。

Int
Long
UInt
上述の型をプロパティとして持つValue Class

@KomapperVersion

楽観的排他制御に使われるバージョン番号であることを表します。

このアノテーションを付与すると、 EntityDsl のUPDATE処理やDELETE処理で楽観的排他制御が行われます。つまり、WHERE句にバージョン番号チェックが含まれ処理件数が0の場合に例外がスローされます。

このアノテーションを付与するプロパティの型は次のいずれかでなければいけません。

Int
Long
UInt
上述の型をプロパティとして持つValue Class

@KomapperCreatedAt

生成時のタイムスタンプであることを表します。

このアノテーションを付与すると、 EntityDsl のINSERT処理にてタイムスタンプがプロパティに設定されます。

このアノテーションを付与するプロパティの型は次のいずれかでなければいけません。

java.time.LocalDateTime
java.time.OffsetDateTime
上述の型をプロパティとして持つValue Class

@KomapperUpdatedAt

更新時のタイムスタンプであることを表します。

このアノテーションを付与すると、 EntityDsl のINSERT処理とUPDATE処理にてタイムスタンプがプロパティに設定されます。

このアノテーションを付与するプロパティの型は次のいずれかでなければいけません。

java.time.LocalDateTime
java.time.OffsetDateTime
上述の型をプロパティとして持つValue Class

@KomapperColumn

プロパティとマッピングするカラムの名前を明示的に指定します。

@KomapperColumn(name = "ADDRESS_ID", alwaysQuote = true)
val id: Nothing

alwaysQuoteプロパティにtrueを設定すると生成されるSQLの識別子が引用符で囲まれます。

このアノテーションでカラムの名前を指定しない場合、アノテーション処理のkomapper.namingStrategyオプションに従って名前が解決されます。以下のドキュメントも参照ください。

オプション

@KomapperIgnore

マッピングの対象外であることを表します。

アノテーション処理

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

KSPを実行するには、KSPのGradleプラグインの設定と下記のGradleの依存関係の宣言が必要です。

val komapperVersion: String by project
dependencies {
  ksp("org.komapper:komapper-processor:$komapperVersion")
}

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

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

オプション

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

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

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

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

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

ksp {
  arg("komapper.prefix", "")
  arg("komapper.suffix", "Metamodel")
  arg("komapper.namingStrategy", "UPPER_SNAKE_CASE")
}

最終更新 August 15, 2021 : Add content for annotation processing (bd0a917)