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

Interface Entities

All Known Implementing Classes:
DefaultEntities
public interface Entities
A repository containing the EntityDefinitions for a given domain. Factory for Entity and Entity.Key instances.

The Entities instance serves as the central registry for all entity types within a domain, providing access to entity definitions and factory methods for creating entity instances and keys.

Typically accessed through a domain instance: 

// Define a domain
public class Store extends DefaultDomain {
    public static final DomainType DOMAIN = domainType(Store.class);

    public Store() {
        super(DOMAIN);
        // Define entities...
    }
}

// Access entities
Store store = new Store();
Entities entities = store.entities();

// Create entity instances
Entity customer = entities.builder(Customer.TYPE)
    .with(Customer.NAME, "John Doe")
    .with(Customer.EMAIL, "john@example.com")
    .build();

// Create primary keys
Entity.Key customerKey = entities.primaryKey(Customer.TYPE, 42);
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final PropertyValue<Boolean>
    STRICT_DESERIALIZATION
    Specifies whether strict deserialization should be used.
    static final PropertyValue<Boolean>
    VALIDATE_FOREIGN_KEYS
    Specifies whether foreign keys are validated when defined by asserting that the referenced entity has been defined.

  • Method Summary

    Modifier and Type
    Method
    Description
    Entity.Builder
    builder(EntityType entityType)
    Creates a new Entity.Builder instance for the given entityType 
    Entities entities = domain.entities();

// Build an entity with initial values
Entity customer = entities.builder(Customer.TYPE)
    .with(Customer.NAME, "John Doe")
    .with(Customer.EMAIL, "john@example.com")
    .with(Customer.ACTIVE, true)
    .build();

// Build with a foreign key reference
Entity order = entities.builder(Order.TYPE)
    .with(Order.CUSTOMER_FK, customer)
    .with(Order.DATE, LocalDate.now())
    .with(Order.TOTAL, 100.50)
    .build();
    boolean
    contains(EntityType entityType)
     
    EntityDefinition
    definition(EntityType entityType)
    Returns the EntityDefinition for the given entityType
    EntityDefinition
    definition(String entityTypeName)
    Returns the EntityDefinition for the given entityType name
    Collection<EntityDefinition>
    definitions()
    Returns all EntityDefinitions found in this Entities instance
    DomainType
    domainType()
     
    Entity
    entity(EntityType entityType)
    Creates a new empty Entity instance of the given entityType 
    Entities entities = domain.entities();

// Create an empty entity
Entity customer = entities.entity(Customer.TYPE);

// Set values individually
customer.set(Customer.NAME, "John Doe");
customer.set(Customer.EMAIL, "john@example.com");

// The entity is mutable and tracks changes
customer.set(Customer.NAME, "John Lennon");
customer.modified(Customer.NAME); // true
    <T> Entity.Key
    primaryKey(EntityType entityType, @Nullable T value)
    Creates a new Entity.Key instance of the given entityType, initialised with the given value 
    Entities entities = domain.entities();

// Create a single-value primary key
Entity.Key customerKey = entities.primaryKey(Customer.TYPE, 42);

// Use the key to fetch an entity
Entity customer = connection.selectSingle(customerKey);

// Keys can be compared
Entity.Key anotherKey = entities.primaryKey(Customer.TYPE, 42);
customerKey.equals(anotherKey); // true

// Null values are allowed
Entity.Key nullKey = entities.primaryKey(Customer.TYPE, null);
    <T> List<Entity.Key>
    primaryKeys(EntityType entityType, T... values)
    Creates new Entity.Key instances of the given entityType, initialised with the given values 
    Entities entities = domain.entities();

// Create multiple keys at once
List<Entity.Key> customerKeys = entities.primaryKeys(Customer.TYPE, 1, 2, 3, 4, 5);

// Fetch multiple entities
List<Entity> customers = connection.select(customerKeys);

// Varargs syntax allows flexible usage
List<Entity.Key> keys = entities.primaryKeys(Order.TYPE,
    "ORD-001", "ORD-002", "ORD-003");

  • Field Details

    • VALIDATE_FOREIGN_KEYS

      static final PropertyValue<Boolean> VALIDATE_FOREIGN_KEYS
      Specifies whether foreign keys are validated when defined by asserting that the referenced entity has been defined. This can be disabled in cases where entities have circular references
      • Value type: Boolean
      • Default value: true

    • STRICT_DESERIALIZATION

      static final PropertyValue<Boolean> STRICT_DESERIALIZATION
      Specifies whether strict deserialization should be used. This means that when an unknown attribute
      is encountered during deserialization, an exception is thrown, instead of silently dropping the associated value.
      • Value type: Boolean
      • Default value: true

  • Method Details

    • domainType

      DomainType domainType()
      Returns:
      the DomainType this Entities instance is associated with

    • definition

      EntityDefinition definition(EntityType entityType)
      Returns the EntityDefinition for the given entityType
      Parameters:
      entityType - the entityType
      Returns:
      the entity definition
      Throws:
      IllegalArgumentException - in case the definition is not found

    • definition

      EntityDefinition definition(String entityTypeName)
      Returns the EntityDefinition for the given entityType name
      Parameters:
      entityTypeName - the name of the entityType
      Returns:
      the entity definition
      Throws:
      IllegalArgumentException - in case the definition is not found

    • contains

      boolean contains(EntityType entityType)
      Parameters:
      entityType - the entityType
      Returns:
      true if this domain contains a definition for the given type

    • definitions

      Collection<EntityDefinition> definitions()
      Returns all EntityDefinitions found in this Entities instance
      Returns:
      all entity definitions

    • entity

      Entity entity(EntityType entityType)
      Creates a new empty Entity instance of the given entityType 
      Entities entities = domain.entities();

// Create an empty entity
Entity customer = entities.entity(Customer.TYPE);

// Set values individually
customer.set(Customer.NAME, "John Doe");
customer.set(Customer.EMAIL, "john@example.com");

// The entity is mutable and tracks changes
customer.set(Customer.NAME, "John Lennon");
customer.modified(Customer.NAME); // true
      Parameters:
      entityType - the entityType
      Returns:
      a new Entity instance

    • builder

      Entity.Builder builder(EntityType entityType)
      Creates a new Entity.Builder instance for the given entityType 
      Entities entities = domain.entities();

// Build an entity with initial values
Entity customer = entities.builder(Customer.TYPE)
    .with(Customer.NAME, "John Doe")
    .with(Customer.EMAIL, "john@example.com")
    .with(Customer.ACTIVE, true)
    .build();

// Build with a foreign key reference
Entity order = entities.builder(Order.TYPE)
    .with(Order.CUSTOMER_FK, customer)
    .with(Order.DATE, LocalDate.now())
    .with(Order.TOTAL, 100.50)
    .build();
      Parameters:
      entityType - the entityType
      Returns:
      a new Entity.Builder

    • primaryKey

      <T> Entity.Key primaryKey(EntityType entityType, @Nullable T value)
      Creates a new Entity.Key instance of the given entityType, initialised with the given value 
      Entities entities = domain.entities();

// Create a single-value primary key
Entity.Key customerKey = entities.primaryKey(Customer.TYPE, 42);

// Use the key to fetch an entity
Entity customer = connection.selectSingle(customerKey);

// Keys can be compared
Entity.Key anotherKey = entities.primaryKey(Customer.TYPE, 42);
customerKey.equals(anotherKey); // true

// Null values are allowed
Entity.Key nullKey = entities.primaryKey(Customer.TYPE, null);
      Type Parameters:
      T - the key value type
      Parameters:
      entityType - the entityType
      value - the key value, assumes 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
      NullPointerException - in case entityType is null

    • primaryKeys

      <T> List<Entity.Key> primaryKeys(EntityType entityType, T... values)
      Creates new Entity.Key instances of the given entityType, initialised with the given values 
      Entities entities = domain.entities();

// Create multiple keys at once
List<Entity.Key> customerKeys = entities.primaryKeys(Customer.TYPE, 1, 2, 3, 4, 5);

// Fetch multiple entities
List<Entity> customers = connection.select(customerKeys);

// Varargs syntax allows flexible usage
List<Entity.Key> keys = entities.primaryKeys(Order.TYPE,
    "ORD-001", "ORD-002", "ORD-003");
      Type Parameters:
      T - the key value type
      Parameters:
      entityType - the entityType
      values - the key values, assumes a single value key
      Returns:
      new Entity.Key instances
      Throws:
      IllegalStateException - in case the given primary key is a composite key
      IllegalArgumentException - in case any of the values is not of the correct type
      NullPointerException - in case entityType or values is null