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

Interface ForeignKeyDefinition

All Superinterfaces:
AttributeDefinition<Entity>
public sealed interface ForeignKeyDefinition extends AttributeDefinition<Entity>
Represents a reference to another entity, typically but not necessarily based on a foreign key.

ForeignKeyDefinition configures how foreign key relationships behave, including reference depth for automatic loading, soft references for logical relationships, and attribute selection for referenced entities.

Foreign key definitions control the loading strategy and behavior of entity relationships: 

// Reference depth 0, the invoice is not loaded
InvoiceLine.INVOICE_FK.as()
				.foreignKey()
				.referenceDepth(0);

// The default reference depth of 1 loads the artist
Album.ARTIST_FK.as()
				.foreignKey();

// Foreign key with deeper reference depth, loading the album AND its artist.
// Note that only the foreign keys among the included attributes are populated,
// so ARTIST_FK must be included for the reference depth of 2 to reach the artist.
Track.ALBUM_FK.as()
				.foreignKey()
				.referenceDepth(2)
				.include(Album.ARTIST_FK, Album.TITLE);

// Reference depth behavior examples:

// Reference depth 0: No automatic loading
List<Entity> tracks = connection.select(
				Select.all(Track.TYPE)
								.referenceDepth(0));

Entity track = tracks.get(0);
Entity album = track.get(Track.ALBUM_FK); // null - not loaded
Entity albumEntity = track.entity(Track.ALBUM_FK); // Contains only primary key

// Reference depth 2, as defined: Load the referenced entity and its references
List<Entity> tracksWithAlbums = connection.select(all(Track.TYPE));

Entity trackWithAlbum = tracksWithAlbums.get(0);
Entity loadedAlbum = trackWithAlbum.get(Track.ALBUM_FK); // Album is loaded
Entity artist = loadedAlbum.get(Album.ARTIST_FK);         // Artist is also loaded

// WARNING: an unlimited reference depth, -1, with a cyclic foreign key reference
// in the data, causes infinite recursion, since no cycle detection is performed
See Also:

  • Field Details

  • Method Details

    • attribute

      ForeignKey attribute()
      Description copied from interface: AttributeDefinition
      The Attribute this definition is based on, should be unique within an Entity. By default, the Attribute.name() serves as column name for database columns.
      Specified by:
      attribute in interface AttributeDefinition<Entity>
      Returns:
      the foreign key attribute this foreign key is based on.

    • referenceDepth

      OptionalInt referenceDepth()
      Returns the reference depth specified for this foreign key, an empty OptionalInt if none was specified, in which case REFERENCE_DEPTH applies.

      A specified depth of 0 means this foreign key is never populated automatically, not even when it is reached via another foreign key specifying a greater depth.

      Returns:
      the reference depth specified for this foreign key
      See Also:

    • soft

      boolean soft()
      Returns:
      true if this foreign key is not based on a physical (table) foreign key and should not prevent deletion

    • readOnly

      boolean readOnly(Column<?> referenceColumn)
      Returns true if the given foreign key reference column is read-only, as in, not updated when the foreign key value is set.
      Parameters:
      referenceColumn - the reference column
      Returns:
      true if the given foreign key reference column is read-only

    • references

      List<ForeignKey.Reference<?>> references()
      Returns:
      the ForeignKey.References that comprise this foreign key

    • attributes

      List<Attribute<?>> attributes()
      Returns:
      the attributes to select when fetching entities referenced via this foreign key, an empty list in case of all attributes

    • validate

      void validate(Entity entity, boolean nullable) throws AttributeValidationException
      Validates the value of this attribute as found in the given entity.
      Parameters:
      entity - the entity containing the value to validate
      nullable - true if null values are allowed in this validation context, false if null should trigger a null validation exception
      Throws:
      AttributeValidationException - in case of an invalid value