Module is.codion.framework.domain
Package is.codion.framework.domain.entity.attribute

Interface ForeignKeyDefinition.Builder

All Superinterfaces:
AttributeDefinition.Builder<Entity,ForeignKeyDefinition.Builder>
Enclosing interface:
ForeignKeyDefinition
public static sealed interface ForeignKeyDefinition.Builder extends AttributeDefinition.Builder<Entity,ForeignKeyDefinition.Builder>
Builds a ForeignKeyDefinition.

  • Method Details

    • comparator

      ForeignKeyDefinition.Builder comparator(Comparator<Entity> comparator)
      Specified by:
      comparator in interface AttributeDefinition.Builder<Entity,ForeignKeyDefinition.Builder>
      Parameters:
      comparator - the Comparator to use when comparing values for this attribute
      Returns:
      this builder instance
      Throws:
      UnsupportedOperationException - Foreign key values are compared using the comparator of the underlying entity

    • soft

      ForeignKeyDefinition.Builder soft(boolean soft)
      Marks this foreign key as being soft, that is, not based on a physical (table) foreign key and should not prevent deletion
      Parameters:
      soft - if true then this foreign key is marked as a non-physical soft key
      Returns:
      this instance

    • readOnly

      ForeignKeyDefinition.Builder readOnly(Column<?> column)
      Marks the given foreign key reference column as read-only, which causes an exception being thrown when the given column value is modified via this foreign key.
      Parameters:
      column - the reference column
      Returns:
      this instance

    • include

      ForeignKeyDefinition.Builder include(Attribute<?>... attributes)

      By default, all attributes are included when the referenced entity is selected. Use this method to restrict the included attributes.

      Note that the primary key attributes are always included and do not have to be specified when using this method.

      One thing to consider is to include the attributes used by the formatter for the referenced entity, to guarantee a correct string representation if required (such as in table column display).

      Parameters:
      attributes - the attributes to include in the referenced entity
      Returns:
      this instance

    • referenceDepth

      ForeignKeyDefinition.Builder referenceDepth(int referenceDepth)
      Specifies the query reference depth for this foreign key, that is, how many levels of the referenced entity's foreign key graph are fetched along with it. Foreign keys not specifying a depth use ForeignKeyDefinition.REFERENCE_DEPTH. 
       Reference depth:
 -1: the full foreign key graph of the referenced entity is fetched.
  0: the referenced entity not fetched.
  1: the referenced entity is fetched, without any foreign key references.
  2: the referenced entity is fetched, with a single level of foreign key references.
  3: the referenced entity is fetched, with two levels of foreign key references.
  etc...

      A depth greater than 1 is a budget for the whole subtree, not merely a limit on this foreign key: the referenced entity's own foreign keys are fetched to the same depth, whatever depth they specify. This is what makes a depth of 2 fetch the referenced entity's references, since those typically specify the default depth of 1, which on its own would stop the fetching.

      A depth of 0 is the exception, and is absolute: such a foreign key is never populated automatically, not even when reached via another foreign key specifying a greater depth. This is how a foreign key is kept from being fetched at all, whether to prevent a child from fetching its parent back, to leave an expensive reference alone or to break a reference cycle. It can still be fetched by asking for it explicitly, by specifying a reference depth for it when selecting.

      Warning: Using referenceDepth(-1) when the actual data contains circular references (e.g., record A references B, B references C, C references A) will cause infinite recursion and StackOverflowError. Self-referential foreign keys (like Employee.manager_id) are safe with unlimited depth as long as the data forms a tree/hierarchy without cycles.

      Parameters:
      referenceDepth - the number of levels of foreign key references to fetch for this foreign key
      Returns:
      this instance
      Throws:
      IllegalArgumentException - in case reference depth is less than -1
      See Also: