Entity definition

Defining an Entity

You define an entity instance by creating a class. In the following example, StarWarsFilmEntity is the entity class linked to the table StarWarsFilmsTable:

package org.example.entities

import org.example.tables.StarWarsFilmsTable
import org.jetbrains.exposed.dao.IntEntity
import org.jetbrains.exposed.dao.IntEntityClass
import org.jetbrains.exposed.dao.id.EntityID

class StarWarsFilmEntity(id: EntityID<Int>) : IntEntity(id) {
    companion object : IntEntityClass<StarWarsFilmEntity>(StarWarsFilmsTable)

    var sequelId by StarWarsFilmsTable.sequelId
    var name by StarWarsFilmsTable.name
    var director by StarWarsFilmsTable.director
}

Entity class

The EntityClass in the companion object block is responsible for managing Entity instances, such as creating, querying, and deleting records. It also maintains the relationship between the entity class (StarWarsFilmEntity in this example) and the database table (StarWarsFilmsTable).

Each entity type is supported by a corresponding EntityClass, which accepts the following parameters:

In the example above, IntEntityClass is specified in the companion object:

companion object : IntEntityClass<StarWarsFilmEntity>(StarWarsFilmsTable)

This setup enables you to use functions provided by IntEntityClass to manage instances of StarWarsFilmEntity effectively.

Properties

Each column in the table is represented as a property in the entity class, where the by keyword ensures the data is fetched or updated from the corresponding column when accessed.

var sequelId by StarWarsFilmsTable.sequelId
var name by StarWarsFilmsTable.name
var director by StarWarsFilmsTable.director

Immutable entities

The ImmutableCachedEntityClass uses an internal cache to store entity loading states by the associated database. This ensures that entity updates are synchronized with this class as the lock object.

To create an immutable entity, use either ImmutableEntityClass or ImmutableCachedEntityClass as a companion object in your entity class. For example, here’s how to define a CityEntity class:

package org.example.entities

import org.example.tables.CitiesTable
import org.jetbrains.exposed.dao.ImmutableEntityClass
import org.jetbrains.exposed.dao.IntEntity
import org.jetbrains.exposed.dao.id.EntityID

class CityEntity(id: EntityID<Int>) : IntEntity(id) {
    val name by CitiesTable.name

    companion object : ImmutableEntityClass<Int, CityEntity>(CitiesTable)
}

Class method overrides

You can use override methods in both the Entity class and the EntityClass companion object to extend functionality or manage entity behavior.

For example, here’s how to override the delete() method in a User entity:

package org.example.entities

import org.example.tables.UsersTable
import org.jetbrains.exposed.dao.IntEntity
import org.jetbrains.exposed.dao.IntEntityClass
import org.jetbrains.exposed.dao.id.EntityID

class UserEntityWithOverride(id: EntityID<Int>) : IntEntity(id) {
    companion object : IntEntityClass<UserEntityWithOverride>(UsersTable)

    var name by UsersTable.name
    var city by CityEntity referencedOn UsersTable.cityId

    override fun delete() {
        println("Deleting user $name with ID: $id")
        super.delete()
    }
}

In this example, a custom message is printed before the .delete() function of the superclass (IntEntity) completes the deletion.

Field transformations

For example, you might need to parse JSON from a VARCHAR column, or retrieve values from a cache based on data from the database. In such cases, we recommend to use column transformations.

Example: Defining an Unsigned Integer field

package org.example.entities

import org.jetbrains.exposed.dao.IntEntity
import org.jetbrains.exposed.dao.IntEntityClass
import org.jetbrains.exposed.dao.id.EntityID
import org.jetbrains.exposed.dao.id.IntIdTable

object TableWithUnsignedInteger : IntIdTable() {
    val uint = integer("uint")
}

class EntityWithUInt(id: EntityID<Int>) : IntEntity(id) {
    var uint: UInt by TableWithUnsignedInteger.uint.transform({ it.toInt() }, { it.toUInt() })

    companion object : IntEntityClass<EntityWithUInt>(TableWithUnsignedInteger)
}

The .transform() function accepts two lambdas that convert values to and from the original column type. In this case, you make sure to store only UInt instances in the uint field.

Memoized transformations

package org.example.entities

import org.jetbrains.exposed.dao.IntEntity
import org.jetbrains.exposed.dao.IntEntityClass
import org.jetbrains.exposed.dao.id.EntityID
import org.jetbrains.exposed.dao.id.IntIdTable
import java.util.Base64

object TableWithText : IntIdTable() {
    val text = varchar("text", length = 2048)
}

class EntityWithBase64(id: EntityID<Int>) : IntEntity(id) {
    var base64: String by TableWithText.text
        .memoizedTransform(
            wrap = { Base64.getEncoder().encodeToString(it.toByteArray()) },
            unwrap = { Base64.getDecoder().decode(it).toString() }
        )

    companion object :
        IntEntityClass<EntityWithBase64>(TableWithText)
}

Entity definition﻿

Defining an Entity﻿

Entity type﻿

Entity class﻿

Properties﻿

Immutable entities﻿

Class method overrides﻿

Field transformations﻿

Example: Defining an Unsigned Integer field﻿

Memoized transformations﻿