Interface Entities


public sealed 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:

Domain domain = new ChinookImpl();
Entities entities = domain.entities();

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

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

Or via an EntityConnection:

Entities entities = connection.entities();
See Also:
  • 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

      Returns all EntityDefinitions found in this Entities instance
      Returns:
      all entity definitions
    • entity

      Entity.Builder entity(EntityType entityType)
      Creates a new Entity.Builder instance for the given entityType
      // Build an entity with initial values
      Entity customer = entities.entity(Customer.TYPE)
              .with(Customer.FIRSTNAME, "John")
              .with(Customer.LASTNAME, "Doe")
              .with(Customer.EMAIL, "john@example.com")
              .build();
      
      // Build with a foreign key reference
      Entity invoice = entities.entity(Invoice.TYPE)
              .with(Invoice.CUSTOMER_FK, customer)
              .with(Invoice.DATE, LocalDate.now())
              .build();
      Parameters:
      entityType - the entityType
      Returns:
      a new Entity.Builder
    • key

      Entity.Key.Builder key(EntityType entityType)
      Creates a new Entity.Key.Builder instance for the given entityType
      // A composite primary key
      Entity.Key languageKey = entities.key(CountryLanguage.TYPE)
              .with(CountryLanguage.COUNTRY_CODE, "ISL")
              .with(CountryLanguage.LANGUAGE, "Icelandic")
              .build();
      Parameters:
      entityType - the entityType
      Returns:
      a new Entity.Key.Builder
    • primaryKey

      Entity.Key primaryKey(EntityType entityType, @Nullable Object value)
      Creates a new Entity.Key instance of the given entityType, initialised with the given value
      // Create a single-value primary key
      Entity.Key customerKey = entities.primaryKey(Customer.TYPE, 42L);
      
      // Use the key to fetch an entity
      Entity customer = connection.select(customerKey);
      
      // Keys can be compared
      Entity.Key anotherKey = entities.primaryKey(Customer.TYPE, 42L);
      customerKey.equals(anotherKey); // true
      
      // Null values are allowed
      Entity.Key nullKey = entities.primaryKey(Customer.TYPE, null);
      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

      List<Entity.Key> primaryKeys(EntityType entityType, Object... values)
      Creates new Entity.Key instances of the given entityType, initialised with the given values
      // Create multiple keys at once
      List<Entity.Key> customerKeys = entities.primaryKeys(Customer.TYPE, 1L, 2L, 3L, 4L, 5L);
      
      // Fetch multiple entities
      Collection<Entity> customers = connection.select(customerKeys);
      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
    • primaryKeys

      List<Entity.Key> primaryKeys(EntityType entityType, Collection<?> values)
      Creates new Entity.Key instances of the given entityType, initialised with the given values
      // Create multiple keys at once
      List<Entity.Key> customerKeys = entities.primaryKeys(Customer.TYPE, List.of(1L, 2L, 3L, 4L, 5L));
      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
    • configurable

      static Entities.Configurable configurable(DomainType domainType)
      Creates a new Entities.Configurable instance for the given domain type.

      Used by DomainModel, which applications extend to define a domain.

      Parameters:
      domainType - the domain type
      Returns:
      a new Entities.Configurable Entities instance