Defining relations

Creating new relations between entities is as easy as in most other ORM's.

1. Add a public property with the desired entity type or list
2. Add the relation annotation
3. Add Rooms @Ignore annotation
   
   

For example, to create a new relation between a Person, and an Address:

@Entity
class Address(
    var streetName: String,
    var city: String,
    var houseNumber: String

): RoomExEntity() { }

@Entity
class User(
    var userName: String,
    var email: String

): RoomExEntity() { 

    @Ignore 
    @OneToOneEx(cascade = Cascade.All) // Here, a 1:1 relation will be created, with create, read, update and delete cascade
    var address: Address? = null
}

Note: Not only entities, but also properties targeting an interface can be used for relations.

Defining inverse relations

Inverse relations are given when the relation should be resolvable from both entities. For example, when extending the example from defining relations, we simply add the mappedWith argument:

@Entity
class Address(
    var streetName: String,
    var city: String,
    var houseNumber: String

): RoomExEntity() { 
    @Ignore 
    @OneToOneEx(mappedWith = "address") // Inverse relationship to user, mapped by the property name
    var user: User? = null
}

Different relationship types

@OneToOneEx

Defines a 1:1 relation between 2 Entities.

@Entity
class User(
    var userName: String,
    var email: String

): RoomExEntity() { 

    @Ignore 
    @OneToOneEx(cascade = Cascade.All) // A user has only one address, and there can be only one user with that address.
    var address: Address? = null
}

@OneToManyEx

Defines a 1:n relation between 2 Entities.

@Entity
class User(
    var userName: String,
    var email: String

): RoomExEntity() { 

    @Ignore 
    @OneToManyEx(cascade = Cascade.All) // A user can have mutliple addresses, but there can be only one user with that address.
    var addresses: MutableList<Address>? = null
}

@ManyToOneEx

Defines a n:1 relation between 2 Entities.

@Entity
class User(
    var userName: String,
    var email: String

): RoomExEntity() { 

    @Ignore 
    @ManyToOneEx(cascade = Cascade.All) // A user has only one address, but there can be mutliple users with that address.
    var address: Address? = null
}

@ManyToManyEx

Defines a m:n relation between 2 Entities.

@Entity
class User(
    var userName: String,
    var email: String

): RoomExEntity() { 

    @Ignore 
    @ManyToOneEx(cascade = Cascade.All) // A user has multiple addresses, and there can be multiple users for each address.
    var addresses: MutableList<Address>? = null
}

Relationship options

As of now, RoomEx support the following options when defining relations:

Argument	Type	Default	Description
mappedWith	String	Empty	Can be used to define inverse relationships.
cascade	Cascade	Cascade.None	Defines which cascade operations should be used for this relation.
entityKClass	KClass<out RoomExEntity>	RoomExEntity::class	Informs RoomEx which entity to use for this relation. Is only needed when using interfaces as field type.
name	String	Empty	Name to use for the created relationship entity and table. Useful when changing the property name.