api-docs / org.ktorm.entity / Entity

Entity

The super interface of all entity classes in Ktorm. This interface injects many useful functions into entities.

Ktorm requires us to define entity classes as interfaces extending from this interface. A simple example is
given as follows:

interface Department : Entity<Department> {
    val id: Int
    var name: String
    var location: String
}

Creating Entity Objects

As everyone knows, interfaces cannot be instantiated, so Ktorm provides a Entity.create function for us to
create entity objects. This function will generate implementations for entity interfaces via JDK dynamic proxy
and create their instances.

In case you don’t like creating objects by Entity.create, Ktorm also provides an abstract factory class
Entity.Factory. This class overloads the invoke operator of Kotlin, so we just need to add a companion
object to our entity class extending from Entity.Factory, then entity objects can be created just like there
is a constructor: val department = Department().

Getting and Setting Properties

Entity objects in Ktorm are proxies, that’s why Ktorm can intercept all the invocations on entities and listen
the status changes of them. Behind those entity objects, there is a value table that holds all the values of the
properties for each entity. Any operation of getting or setting a property is actually operating the underlying
value table. However, what if the value doesn’t exist while we are getting a property? Ktorm defines a set of
rules for this situation:

• If the value doesn’t exist and the property’s type is nullable (e.g. var name: String?), then we’ll return null.
• If the value doesn’t exist and the property’s type is not nullable (e.g. var name: String), then we can not
  return null anymore, because the null value here can cause an unexpected null pointer exception, we’ll return the
  type’s default value instead.

The default values of different types are well-defined:

• For Boolean type, the default value is false.
• For Char type, the default value is \u0000.
• For number types (such as Int, Long, Double, etc), the default value is zero.
• For String type, the default value is an empty string.
• For entity types, the default value is a new-created entity object which is empty.
• For enum types, the default value is the first value of the enum, whose ordinal is 0.
• For array types, the default value is a new-created empty array.
• For collection types (such as Set, List, Map, etc), the default value is a new created mutable collection
  of the concrete type.
• For any other types, the default value is an instance created by its no-args constructor. If the constructor
  doesn’t exist, an exception is thrown.

Moreover, there is a cache mechanism for default values, that ensures a property always returns the same default
value instance even if it’s called twice or more. This can avoid some counterintuitive bugs.

Non-abstract members

If we are using domain driven design, then entities are not only data containers that hold property values, there
are also some behaviors, so we need to add some business functions to our entities. Fortunately, Kotlin allows us
to define non-abstract functions in interfaces, that’s why we don’t lose anything even if Ktorm’s entity classes
are all interfaces. Here is an example:

interface Foo : Entity<Foo> {
    companion object : Entity.Factory<Foo>()
    val name: String
    fun printName() {
        println(name)
    }
}

Then if we call Foo().printName(), the value of the property name will be printed.

Besides of non-abstract functions, Kotlin also allows us to define properties with custom getters or setters in
interfaces. For example, in the following code, if we call Foo().upperName, then the value of the name property
will be returned in upper case:

interface Foo : Entity<Foo> {
    companion object : Entity.Factory<Foo>()
    val name: String
    val upperName get() = name.toUpperCase()
}

More details can be found in our website: https://www.ktorm.org/en/entities-and-column-binding.html#More-About-Entities

Serialization

The Entity interface extends from Serializable, so all entity objects are serializable by default. We can save
them to our disks, or transfer them between systems through networks.

Note that Ktorm only saves entities’ property values when serialization, any other data that used to track entity
status are lost (marked as transient). So we can not obtain an entity object from one system, then flush its changes
into the database in another system.

Java uses ObjectOutputStream to serialize objects, and uses ObjectInputStream to deserialize them, you can
refer to their documentation for more details.

Besides of JDK serialization, the ktorm-jackson module also supports serializing entities in JSON format. This
module provides an extension for Jackson, the famous JSON framework in Java word. It supports serializing entity
objects into JSON format and parsing JSONs as entity objects. More details can be found in its documentation.

Types

Properties

Functions

Companion Object Functions

Extension Functions