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: setting this foreign key, to an entity or to null, leaves the column as it is, and setting it to an entity whose value for the column differs from the one the column holds throws an IllegalArgumentException.

      A column shared by foreign keys must be read-only in all of them but one at most, the definition failing to build otherwise: the foreign key it belongs with sets it, the others reading it, or none does, the column then set on its own. A count on a line, say, referencing the line by its visit and number and the visit by the visit column alone, the visit's foreign key setting that column, the line's reading it.

      Parameters:
      column - the reference column
      Returns:
      this instance
      Throws:
      IllegalArgumentException - in case the column is not part of this foreign key

    • 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: