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:

// Define entity types
interface Genre {
  EntityType TYPE = DOMAIN.entityType("chinook.genre");

  Column<Long> ID = TYPE.longColumn("id");
  Column<String> NAME = TYPE.stringColumn("name");
}

// Define the entity structure
EntityDefinition genre() {
  return Genre.TYPE.as()
          .attributes(
                  Genre.ID.as()
                          .primaryKey(),
                  Genre.NAME.as()
                          .column()
                          .caption("Name")
                          .nullable(false)
                          .maximumLength(120))
          .caption("Genres")
          .orderBy(ascending(Genre.NAME))
          .formatter(Genre.NAME)
          .smallDataset(true)
          .build();
}

A definition a client receives from a server comes without what the server alone uses: the table names, the select query, the condition strings and the optimistic locking setting, and for its columns the names, expressions, converters and generators. The methods providing these throw IllegalStateException in such a definition.

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
      Throws:
      IllegalStateException - in case this definition was received from a server
    • 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
      IllegalStateException - in case this definition was received from a server
      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
      Throws:
      IllegalStateException - in case this definition was received from a server
    • 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
      Throws:
      IllegalStateException - in case this definition was received from a server
    • selectQuery

      Optional<EntitySelectQuery> selectQuery()
      Returns:
      the select query to use when selecting entities of this type, an empty Optional if none is available
      Throws:
      IllegalStateException - in case this definition was received from a server
    • 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.FIRSTNAME.as()
                              .column()
                              .caption("First name"),
                      Customer.LASTNAME.as()
                              .column()
                              .caption("Last name"),
                      Customer.EMAIL.as()
                              .column()
                              .caption("Email"))
              .formatter(customer ->
                      customer.get(Customer.LASTNAME) + ", " +
                              customer.get(Customer.FIRSTNAME) +
                              " (" + customer.get(Customer.EMAIL) + ")")
              .build();
      
      // Usage
      Entity customer = entities.entity(Customer.TYPE)
              .with(Customer.FIRSTNAME, "John")
              .with(Customer.LASTNAME, "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

      Returns:
      the EntityDefinition.Attributes instance
    • columns

      Returns:
      the EntityDefinition.Columns instance
    • foreignKeys

      Returns:
      the EntityDefinition.ForeignKeys instance
    • 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<? extends Attribute<?>, ?> 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<? extends Attribute<?>, ?> values, Map<? extends Attribute<?>, ?> 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.
    • 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