Package io.ran

Annotation Interface Relation

@Retention(RUNTIME) @Target(FIELD) public @interface Relation
Used to indicate a field that represents a relation to another object, instead of an actual column in the table corresponding to its class.

One-to-one or many-to-one relation is represented by a single object. One-to-many and many-to-many relation is represented by a collection, with the latter specifying the junction table by the via() parameter. List and Set collections are supported at the moment.

By default, relation fields are lazy-loaded. To load relation field eagerly, use CrudRepository.InlineQuery.withEager(java.util.function.Function<T, ?>).

Ordering of relation collections is currently dependent on the underlying database and subject to change.

Usage example: 


 @Mapper(dbType = ModuleDbConfig.class)
 public class Person {
   @PrimaryKey
   Long id;
   @Relation(fields = "id", relationFields = "personId")
   List<Phone> phones;
   @Relation(via = Residency.class, fields = "id", relationFields = "personId")
   List<Home> homes;
   // getters and setters...
 }

 @Mapper(dbType = ModuleDbConfig.class)
 public class Phone {
   @PrimaryKey
   Long id;
   Long personId;
   @Relation(fields = "personId", relationFields = "id")
   Person owner;
   // getters and setters...
 }

 @Mapper(dbType = ModuleDbConfig.class)
 public class Home {
   @PrimaryKey
   Long id;
   @Relation(via = Residency.class, fields = "id", relationFields = "homeId")
   List<Person> residents;
   // getters and setters...
 }

 @Mapper(dbType = ModuleDbConfig.class)
 public class Residency {
   @PrimaryKey
   Long personId;
   @PrimaryKey
   Long homeId;
 }

The database schema for the above example would be: 


  CREATE TABLE person (
   id BIGINT NOT NULL,
   PRIMARY KEY (id)
  );
  CREATE TABLE phone (
   id BIGINT NOT NULL,
   person_id BIGINT NOT NULL,
   PRIMARY KEY (id)
  );
  CREATE TABLE home (
   id BIGINT NOT NULL,
   PRIMARY KEY (id)
  );
  CREATE TABLE residency (
   person_id BIGINT NOT NULL,
   home_id BIGINT NOT NULL,
   PRIMARY KEY (personId, homeId)
  );

Note the conversion from camelCase to snake_case in the column names.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    autoSave
    If true, the relation will be automatically saved when the object containing it is saved.
    Class<?>
    collectionElementType
    Deprecated.
    No longer used, it is automatically determined if the field is a collection.
    String[]
    fields
    Name of local field(s) referencing the related object(s).
    String[]
    relationFields
    Name of field(s) in the related object(s) that are referenced by this relation.
    Class<?>
    via
    Class representing the junction table.

  • Element Details

    • collectionElementType

      @Deprecated Class<?> collectionElementType
      Deprecated.
      No longer used, it is automatically determined if the field is a collection.
      Default:
      io.ran.None.class

    • via

      Class<?> via
      Class representing the junction table. Only used by many-to-many relations. For usage example, see Relation.
      Returns:
      Class representing the junction table used by many-to-many relation.
      Default:
      io.ran.None.class

    • fields

      String[] fields
      Name of local field(s) referencing the related object(s). For usage example, see Relation.

      Use the field names as they appear in the class, not the column names in the database.

      Multiple fields can be specified in case of a compound key. The order has to match relationFields().

      If not specified, the system will assume the field name. Does not work for compound keys. Currently, it uses "id" for primary keys and "<otherClass>Id" for foreign keys, where <OtherClass> is the class being referenced. This is subject to change.

      Returns:
      An array containing the name(s) of the local field(s) referencing the related object(s).
      Default:
      {}

    • relationFields

      String[] relationFields
      Name of field(s) in the related object(s) that are referenced by this relation. For usage example, see Relation.

      Use the field names as they appear in the class, not the column names in the database.

      Multiple fields can be specified in case of a compound key. The order has to match fields().

      If not specified, the system will assume the field name. Does not work for compound keys. Currently, it uses "id" for primary keys and "<otherClass>Id" for foreign keys, where <OtherClass> is the class being referenced. This is subject to change.

      Returns:
      An array containing the name(s) of the field(s) in the related object(s) that are referenced by this relation.
      Default:
      {}

    • autoSave

      boolean autoSave
      If true, the relation will be automatically saved when the object containing it is saved.

      This only affects saving/updating, this does not affect deletions.

      Returns:
      true if the relation should be automatically saved, defaults to false
      Default:
      false