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

Interface EntityDefinition

public sealed interface EntityDefinition
Specifies an entity definition, encapsulating the metadata for an entity type.

An EntityDefinition contains all information about an entity's structure including:

  • The underlying table name and database mapping
  • All attributes (columns, foreign keys, derived attributes)
  • Primary key definition
  • Validation rules and behavior settings
  • Display properties (caption, description, ordering)

Entity definitions are typically created using the builder pattern during domain initialization: 

 public class Store extends DomainModel {

     // Define entity types
     interface Customer {
         EntityType TYPE = DOMAIN.entityType("store.customer");

         Column<Integer> ID = TYPE.integerColumn("id");
         Column<String> NAME = TYPE.stringColumn("name");
         Column<String> EMAIL = TYPE.stringColumn("email");
     }

     // Define the entity structure
     void defineCustomer() {
         EntityDefinition definition = Customer.TYPE.as()
             .attributes(
                 Customer.ID.as()
                     .primaryKey(),
                 Customer.NAME.as()
                     .column()
                     .caption("Name")
                     .nullable(false)
                     .maximumLength(100),
                 Customer.EMAIL.as()
                     .column()
                     .caption("Email")
                     .maximumLength(255))
             .table("customer")
             .caption("Customer")
             .orderBy(ascending(Customer.NAME))
             .smallDataset(true)
             .build();
     }
 }
See Also:

  • Field Details

    • OPTIMISTIC_LOCKING

      static final PropertyValue<Boolean> OPTIMISTIC_LOCKING
      Specifies whether optimistic locking should be enabled by default for entities. This is the per-entity default; the connection-level switch is the separate codion.db.optimisticLocking property on LocalEntityConnection.
      • Value type: Boolean
      • Default value: true

  • Method Details

    • type

      EntityType type()
      Returns:
      the entity type

    • table

      String table()
      Returns:
      the name of the underlying table, with schema prefix if applicable

    • condition

      ConditionString condition(ConditionType conditionType)
      Returns the ConditionString associated with the given type
      Parameters:
      conditionType - the condition type
      Returns:
      the ConditionString associated with the given ConditionType
      Throws:
      IllegalArgumentException - in case no ConditionString is associated with the given ConditionType
      See Also:

    • validator

      EntityValidator validator()
      Returns:
      the validator for this entity type

    • exists

      Predicate<Entity> exists()
      The default exists predicate returns true if the entity has a non-null original primary key, which is a best-guess about an entity existing in a database.
      Returns:
      the predicate to use to check if an entity of this type exists in the database

    • caption

      String caption()
      Returns the caption, resolved in the following order of precedence:
      1. the caption specified via EntityDefinition.Builder.caption(String), if any
      2. the caption from the entity resource bundle, if a matching key is available
      3. the entity type name (EntityType.name())
      Returns:
      the caption to use when presenting entities of this type
      See Also:

    • description

      Optional<String> description()
      Returns:
      the entity description

    • smallDataset

      boolean smallDataset()
      Returns:
      true if the underlying table is small enough for displaying the contents in a combo box

    • readOnly

      boolean readOnly()
      Returns:
      true if this entity type is read only

    • optimisticLocking

      boolean optimisticLocking()
      Returns:
      true if optimistic locking should be used during updates

    • orderBy

      Optional<OrderBy> orderBy()
      Returns:
      the default order by clause to use when querying entities of this type, an empty Optional if none is available

    • selectTable

      String selectTable()
      Returns:
      the name of the table to use when selecting entities of this type

    • selectQuery

      Optional<EntitySelectQuery> selectQuery()
      Returns:
      the select query to use when selecting entities of this type, an empty Optional if none is available

    • formatter

      Function<Entity,String> formatter()
      Returns the formatter responsible for providing toString values for this entity type. 
       // Define custom string representation
 Customer.TYPE.as()
     .attributes(
         Customer.ID.as()
             .primaryKey(),
         Customer.FIRST_NAME.as()
             .column(),
         Customer.LAST_NAME.as()
             .column(),
         Customer.EMAIL.as()
             .column())
     .formatter(customer ->
         customer.get(Customer.LAST_NAME) + ", " +
         customer.get(Customer.FIRST_NAME) +
         " (" + customer.get(Customer.EMAIL) + ")")
     .build();

 // Usage
 Entity customer = entities.entity(Customer.TYPE)
     .with(Customer.FIRST_NAME, "John")
     .with(Customer.LAST_NAME, "Doe")
     .with(Customer.EMAIL, "john@example.com")
     .build();

 System.out.println(customer); // "Doe, John (john@example.com)"
      Returns:
      the function responsible for formatting entities of this type

    • cacheToString

      boolean cacheToString()
      True by default.
      Returns:
      true if the result of toString() is cached

    • comparator

      Comparator<Entity> comparator()
      Returns:
      the comparator used when comparing this entity type to other entities

    • attributes

      EntityDefinition.Attributes attributes()
      Returns:
      the EntityDefinition.Attributes instance

    • columns

      EntityDefinition.Columns columns()
      Returns:
      the EntityDefinition.Columns instance

    • foreignKeys

      EntityDefinition.ForeignKeys foreignKeys()
      Returns:
      the EntityDefinition.ForeignKeys instance

    • primaryKey

      EntityDefinition.PrimaryKey primaryKey()
      Returns:
      the EntityDefinition.PrimaryKey instance

    • entity

      Entity entity()
      Creates a new Entity instance based on this definition
      Returns:
      a new Entity instance

    • entity

      Entity entity(Map<Attribute<?>,Object> values)
      Creates a new Entity instance based on this definition
      Parameters:
      values - the initial values, an empty map in case of no values
      Returns:
      a new Entity instance
      Throws:
      IllegalArgumentException - in case any of the value attributes are not part of the entity.

    • entity

      Entity entity(Map<Attribute<?>,Object> values, Map<Attribute<?>,Object> originalValues)
      Creates a new Entity instance based on this definition
      Parameters:
      values - the initial values, an empty map in case of no values
      originalValues - the original values, an empty map in case of no original values
      Returns:
      a new Entity instance
      Throws:
      IllegalArgumentException - in case any of the value attributes are not part of the entity.

    • primaryKey

      <T> Entity.Key primaryKey(T value)
      Creates a new Entity.Key instance based on this definition, initialised with the given value
      Type Parameters:
      T - the key value type
      Parameters:
      value - the key value, assuming a single value key
      Returns:
      a new Entity.Key instance
      Throws:
      IllegalStateException - in case the given primary key is a composite key
      IllegalArgumentException - in case the value is not of the correct type

    • entity

      Entity entity(String caption)
      Creates an empty, immutable entity with a custom string representation. This is useful for placeholder entities such as null items in combo boxes.

      The returned entity has no attribute values set and cannot be modified.

      Parameters:
      caption - the string to return when toString() is called
      Returns:
      an empty entity with the specified caption