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

Interface Entity

All Superinterfaces:
Comparable<Entity>
public interface Entity extends Comparable<Entity>
Represents a row in a table or query result, encapsulating the data and state of a domain entity.

An Entity instance maintains both current and original values for all attributes, tracks modifications, and provides type-safe access to column values and foreign key relationships.

Entity instances can be mutable or immutable. Mutable entities track value modifications and support operations like set(Attribute, Object), revert(), and save(). Immutable entities throw UnsupportedOperationException for modification operations.

Thread Safety

Mutable entities are NOT thread-safe. They should not be shared between threads without external synchronization. Concurrent modifications may result in data corruption or inconsistent state.

Immutable entities ARE thread-safe. Created via immutable(), they can be safely shared between threads. All referenced entities are also made immutable to ensure complete thread safety.

Recommended patterns for concurrent use:

  • Use immutable() to create thread-safe snapshots for sharing
  • Implement external synchronization when sharing mutable entities
  • Consider using immutable entities for read-only operations across threads
  • Create defensive copies with copy() when passing entities between threads

 // Creating and working with entities
 Entity customer = entities.entity(Customer.TYPE)
     .with(Customer.ID, 42)
     .with(Customer.NAME, "John Doe")
     .with(Customer.EMAIL, "john@example.com")
     .build();

 // Accessing values
 String name = customer.get(Customer.NAME);
 Optional<String> email = customer.optional(Customer.EMAIL);

 // Modifying values (if mutable)
 customer.set(Customer.EMAIL, "newemail@example.com");
 boolean isModified = customer.modified(Customer.EMAIL); // true

 // Reverting changes
 customer.revert(Customer.EMAIL); // back to "john@example.com"


 // Working with foreign keys
 Entity invoice = connection.selectSingle(Invoice.ID.equalTo(123));

 // Access the referenced entity (automatically loaded if configured)
 Entity customer = invoice.get(Invoice.CUSTOMER_FK);

 // Access foreign key attributes directly
 String customerName = invoice.get(Invoice.CUSTOMER_FK).get(Customer.NAME);

 // Get the foreign key value
 Key customerKey = invoice.key(Invoice.CUSTOMER_FK);
See Also:

  • Method Details

    • type

      EntityType type()
      Returns:
      the entity type

    • definition

      EntityDefinition definition()
      Returns:
      the entity definition

    • set

      <T> @Nullable T set(Attribute<T> attribute, @Nullable T value)
      Sets the value of the given attribute, returning the previous value if any
      Type Parameters:
      T - the value type
      Parameters:
      attribute - the attribute
      value - the value
      Returns:
      the previous value
      Throws:
      UnsupportedOperationException - in case this entity is immutable

    • get

      <T> @Nullable T get(Attribute<T> attribute)
      Returns the value associated with attribute.
      Type Parameters:
      T - the value type
      Parameters:
      attribute - the attribute for which to retrieve the value
      Returns:
      the value of the given attribute

    • optional

      <T> Optional<T> optional(Attribute<T> attribute)
      Returns the value associated with attribute, wrapped in an Optional.
      Type Parameters:
      T - the value type
      Parameters:
      attribute - the attribute which value to retrieve
      Returns:
      the value of the given attribute, wrapped in an Optional

    • original

      <T> @Nullable T original(Attribute<T> attribute)
      Returns the original value associated with attribute, or the current one if it is unmodified.
      Type Parameters:
      T - the value type
      Parameters:
      attribute - the attribute for which to retrieve the original value
      Returns:
      the original value of the given attribute

    • formatted

      <T> String formatted(Attribute<T> attribute)
      This method returns a String representation of the value associated with the given attribute, if the associated attribute has a format it is used.
      Type Parameters:
      T - the value type
      Parameters:
      attribute - the attribute which value to retrieve
      Returns:
      a String representation of the value associated with attribute

    • revert

      void revert(Attribute<?> attribute)
      Reverts the value associated with the given attribute to its original value. If the value has not been modified then calling this method has no effect.
      Parameters:
      attribute - the attribute for which to revert the value
      Throws:
      UnsupportedOperationException - in case this entity is immutable

    • revert

      void revert()
      Reverts all value modifications that have been made. This entity will be unmodified after a call to this method. If no modifications have been made then calling this method has no effect.
      Throws:
      UnsupportedOperationException - in case this entity is immutable

    • save

      void save(Attribute<?> attribute)
      Saves the value associated with the given attribute, that is, removes the original value. If the value has not been modified calling this method has no effect.
      Parameters:
      attribute - the attribute for which to save the value
      Throws:
      UnsupportedOperationException - in case this entity is immutable

    • save

      void save()
      Saves all the value modifications that have been made, that is, removes all original values. This entity will be unmodified after a call to this method.
      Throws:
      UnsupportedOperationException - in case this entity is immutable
      See Also:

    • remove

      <T> @Nullable T remove(Attribute<T> attribute)
      Removes the given value from this Entity along with the original value if any. If no value is mapped to the given attribute, this method has no effect.
      Type Parameters:
      T - the value type
      Parameters:
      attribute - the attribute to remove
      Returns:
      the previous value mapped to the given attribute
      Throws:
      UnsupportedOperationException - in case this entity is immutable

    • isNull

      boolean isNull(Attribute<?> attribute)
      Returns true if a null value is mapped to the given attribute or if no mapping is found.

      In case of foreign keys the value of the underlying reference column(s) is checked. If the key is a single column key, true is returned if the associated value is null, but in case of composite keys then true is returned if one or more non-nullable key columns are associated with a null value.

      Parameters:
      attribute - the attribute
      Returns:
      true if the value mapped to the given attribute is null or no value is mapped

    • contains

      boolean contains(Attribute<?> attribute)
      Returns true if this Entity contains a value for the given attribute, that value can be null.
      Parameters:
      attribute - the attribute
      Returns:
      true if a value is mapped to this attribute

    • entity

      @Nullable Entity entity(ForeignKey foreignKey)
      Returns the Entity instance referenced by the given ForeignKey. If the underlying reference contains a value, that is, a foreign key value exists but the actual referenced entity has not been loaded, an "empty" entity is returned, containing only the referenced key value(s). Null is returned only if the actual foreign key is null. 
       // Assuming Invoice has a foreign key to Customer
 Entity invoice = connection.selectSingle(Invoice.ID.equalTo(42));

 // Get the customer entity - may be fully loaded or just contain the key
 Entity customer = invoice.entity(Invoice.CUSTOMER_FK);

 if (customer != null) {
     // This is always available - the foreign key value
     Integer customerId = customer.get(Customer.ID);

     // This may return null if customer wasn't loaded
     // and the foreign key entity doesn't contain Customer.NAME
     String customerName = customer.get(Customer.NAME);
 }
      Parameters:
      foreignKey - the foreign key for which to retrieve the referenced entity
      Returns:
      the entity associated with foreignKey

    • key

      @Nullable Entity.Key key(ForeignKey foreignKey)
      Returns the key referenced by the given ForeignKey, if the reference is null this method returns null.
      Parameters:
      foreignKey - the foreign key for which to retrieve the underlying Entity.Key
      Returns:
      the key for the underlying entity, null if no entity is referenced

    • modified

      boolean modified(Attribute<?> attribute)
      Returns true if the value associated with the given attribute has been modified since first set, note that this does not apply to attributes based on derived values. 
       Entity customer = entities.entity(Customer.TYPE)
     .with(Customer.NAME, "John")
     .with(Customer.EMAIL, "john@example.com")
     .build();

 customer.modified(Customer.NAME); // false

 customer.set(Customer.NAME, "Jane");
 customer.modified(Customer.NAME); // true

 customer.save();
 customer.modified(Customer.NAME); // false
      Parameters:
      attribute - the attribute
      Returns:
      true if the value associated with the given attribute has been modified

    • modified

      boolean modified()
      Returns true if one or more writable attributes have been modified from their initial value, non-insertable and non-updatable attributes are excluded unless they are transient and modify the entity.
      Returns:
      true if one or more writable attributes have been modified since they were first set
      See Also:

    • exists

      boolean exists()
      Returns:
      true if this entity has been persisted
      See Also:

    • equalValues

      boolean equalValues(Entity entity)
      Compares the values of all attributes in the given entity to the values in this entity instance. Returns true if all attribute values available in this entity are available and equal in the comparison entity 
       Entity customer1 = entities.entity(Customer.TYPE)
     .with(Customer.ID, 42)
     .with(Customer.NAME, "John Doe")
     .with(Customer.EMAIL, "john@example.com")
     .build();

 Entity customer2 = entities.entity(Customer.TYPE)
     .with(Customer.ID, 42)
     .with(Customer.NAME, "John Doe")
     .with(Customer.EMAIL, "john@example.com")
     .with(Customer.PHONE, "555-1234") // Extra attribute
     .build();

 customer1.equalValues(customer2); // true - all values in customer1 exist and are equal in customer2
 customer2.equalValues(customer1); // false - customer2 has PHONE which customer1 doesn't have
      Parameters:
      entity - the entity to compare to
      Returns:
      true if all values in this entity instance are present and equal to the values in the given entity
      Throws:
      IllegalArgumentException - in case the entity is not of the same type

    • equalValues

      boolean equalValues(Entity entity, Collection<? extends Attribute<?>> attributes)
      Compares the values of the given attributes in the given entity to the values in this entity instance. Returns true if these two entities contain values for the given attributes and all the values are equal. 
       Entity customer1 = entities.entity(Customer.TYPE)
     .with(Customer.ID, 42)
     .with(Customer.NAME, "John Doe")
     .with(Customer.EMAIL, "john@example.com")
     .build();

 Entity customer2 = entities.entity(Customer.TYPE)
     .with(Customer.ID, 42)
     .with(Customer.NAME, "John Doe")
     .with(Customer.EMAIL, "different@example.com")
     .build();

 // Compare only specific attributes
 Set<Attribute<?>> nameAttributes = Set.of(Customer.ID, Customer.NAME);
 customer1.equalValues(customer2, nameAttributes); // true - ID and NAME are equal

 Set<Attribute<?>> allAttributes = Set.of(Customer.ID, Customer.NAME, Customer.EMAIL);
 customer1.equalValues(customer2, allAttributes); // false - EMAIL differs
      Parameters:
      entity - the entity to compare to
      attributes - the attributes to compare
      Returns:
      true if all the given values in this entity instance are present and equal to the values in the given entity
      Throws:
      IllegalArgumentException - in case the entity is not of the same type

    • set

      Map<Attribute<?>,Object> set(@Nullable Entity entity)
      After a call to this method this Entity contains the same values and original values as the source entity. A null argument to this method clears this entity instance of all values and original values.
      Parameters:
      entity - the entity to copy or null for clearing all values in this instance
      Returns:
      the affected attributes and their previous values, that is, attributes which values changed
      Throws:
      IllegalArgumentException - in case the entity is not of the same type
      UnsupportedOperationException - in case this entity is immutable

    • copy

      Entity.Copy copy()
      Returns a Entity.Copy instance providing ways to create copies of this entity. 
       Entity customer = entities.entity(Customer.TYPE)
     .with(Customer.ID, 42)
     .with(Customer.NAME, "John Doe")
     .with(Customer.EMAIL, "john@example.com")
     .build();

 // Create a mutable copy
 Entity mutableCopy = customer.copy().mutable();
 mutableCopy.set(Customer.EMAIL, "new@example.com");

 // Original remains unchanged
 customer.get(Customer.EMAIL); // "john@example.com"
 mutableCopy.get(Customer.EMAIL); // "new@example.com"

 // Create a builder initialized with entity values
 Entity newCustomer = customer.copy().builder()
     .with(Customer.ID, 43) // Different ID
     .with(Customer.PHONE, "555-1234") // Additional field
     .build();
      Returns:
      a Entity.Copy instance for this entity

    • immutable

      Entity immutable()
      Returns an immutable version of this entity, all foreign key entities are also immutable. Note that this may be the same instance in case this instance is already immutable.

      Thread Safety: The returned immutable entity is thread-safe and can be safely shared between threads without external synchronization. All referenced entities are also made immutable to ensure complete thread safety throughout the object graph.

      This method is particularly useful for:

      • Creating thread-safe snapshots for sharing between threads
      • Ensuring data integrity in concurrent read operations
      • Caching entities safely in multi-threaded environments
      Returns:
      an immutable, thread-safe version of this entity

    • mutable

      boolean mutable()
      Returns whether this entity instance is mutable (can be modified).

      Thread Safety: Mutable entities (returning true) are NOT thread-safe and should not be shared between threads without external synchronization. Immutable entities (returning false) are thread-safe and can be safely shared between threads.

      Returns:
      true if this is a mutable instance, false if immutable
      See Also:

    • primaryKey

      Entity.Key primaryKey()
      Returns the primary key of this entity.

      Entities Without Defined Primary Keys:

      If the entity has no defined primary key, this method returns a pseudo primary key containing all column values, and Entity.Key.primary() returns false. This enables working with entities based on views or legacy tables that lack proper primary keys.

      Pseudo Primary Key Behavior:

      • Update/Delete: Operations work correctly when the pseudo key uniquely identifies a single row
      • Identical Rows: If multiple rows have identical column values, delete by key throws DeleteException since the pseudo key cannot distinguish between them
      • Workaround: Use condition-based delete instead of key-based delete for tables with potentially identical rows

      Typical Use Cases:

      • Read-only entities based on denormalized views (most common)
      • Legacy tables without proper primary keys (rare)
      • Temporary or staging tables where unique constraints aren't enforced
      Returns:
      the primary key of this entity, or a pseudo primary key if no primary key is defined
      See Also:

    • originalPrimaryKey

      Entity.Key originalPrimaryKey()
      Returns the primary key of this entity, in its original state.

      If the entity has no defined primary key, this method returns a pseudo primary key containing all original column values, and Entity.Key.primary() returns false.

      Returns:
      the primary key of this entity in its original state, or a pseudo primary key if no primary key is defined
      See Also:

    • entrySet

      Set<Map.Entry<Attribute<?>,Object>> entrySet()
      Returns an unmodifiable view of the entries in this Entity, note that derived attributes are included if the value has been cached.
      Returns:
      an unmodifiable view of the entries in this Entity

    • originalEntrySet

      Set<Map.Entry<Attribute<?>,Object>> originalEntrySet()
      Returns:
      an unmodifiable view of the original entries values in this Entity, that is, the original values of attributes that have been modified

    • entity

      static Entity entity(Entity.Key key)
      Parameters:
      key - the key
      Returns:
      an Entity instance based on the given key

    • builder

      static Entity.Builder builder(Entity.Key key)
      Parameters:
      key - the key
      Returns:
      a builder instance based on the given key

    • primaryKeys

      static Collection<Entity.Key> primaryKeys(Collection<Entity> entities)
      Returns the primary keys of the given entities.
      Parameters:
      entities - the entities
      Returns:
      a Collection containing the primary keys of the given entities

    • keys

      static Collection<Entity.Key> keys(ForeignKey foreignKey, Collection<Entity> entities)
      Returns the non-null keys referenced by the given ForeignKey
      Parameters:
      foreignKey - the foreign key
      entities - the entities
      Returns:
      a Collection containing the non-null keys referenced by the given ForeignKey

    • originalPrimaryKeys

      static Collection<Entity.Key> originalPrimaryKeys(Collection<Entity> entities)
      Returns the primary keys of the given entities with their original values.
      Parameters:
      entities - the entities
      Returns:
      a Collection containing the primary keys of the given entities with their original values

    • values

      static <T> Collection<@Nullable T> values(Collection<Entity.Key> keys)
      Retrieves the values of the given keys, assuming they are single column keys.
      Type Parameters:
      T - the value type
      Parameters:
      keys - the keys
      Returns:
      the attribute values of the given keys
      Throws:
      IllegalStateException - in case of a composite key

    • values

      static <T> Collection<T> values(Attribute<T> attribute, Collection<Entity> entities)
      Returns the non-null values associated with attribute from the given entities.
      Type Parameters:
      T - the value type
      Parameters:
      attribute - the attribute which values to retrieve
      entities - the entities from which to retrieve the attribute value
      Returns:
      the non-null values of the given attribute from the given entities.

    • distinct

      static <T> Collection<T> distinct(Attribute<T> attribute, Collection<Entity> entities)
      Returns the distinct non-null values of attribute from the given entities.
      Type Parameters:
      T - the value type
      Parameters:
      attribute - the attribute which values to retrieve
      entities - the entities from which to retrieve the values
      Returns:
      the distinct non-null values of the given attribute from the given entities.

    • primaryKeyMap

      static Map<Entity.Key,Entity> primaryKeyMap(Collection<Entity> entities)
      Maps the given entities to their primary key, assuming each entity appears only once in the given collection. 
       List<Entity> customers = connection.select(Customer.ID.in(1, 2, 3));

 // Create a map for fast lookup by primary key
 Map<Key, Entity> customerMap = Entity.primaryKeyMap(customers);

 // Later, quick lookup by key
 Key customerKey = entities.primaryKey(Customer.TYPE, 2);
 Entity customer = customerMap.get(customerKey);
      Parameters:
      entities - the entities to map
      Returns:
      the mapped entities
      Throws:
      IllegalArgumentException - in case a non-unique primary key is encountered

    • groupByValue

      static <T> LinkedHashMap<@Nullable T,List<Entity>> groupByValue(Attribute<T> attribute, Collection<Entity> entities)
      Returns a LinkedHashMap containing the given entities mapped to the value of attribute, respecting the iteration order of the given collection 
       List<Entity> orders = connection.select(all(Order.TYPE));

 // Group orders by status
 LinkedHashMap<String, List<Entity>> ordersByStatus =
     Entity.groupByValue(Order.STATUS, orders);

 // Process orders by status
 ordersByStatus.forEach((status, statusOrders) -> {
     System.out.println("Status: " + status + ", Count: " + statusOrders.size());
 });

 // Groups can contain entities with null values
 List<Entity> pendingOrders = ordersByStatus.get("PENDING");
 List<Entity> nullStatusOrders = ordersByStatus.get(null);
      Type Parameters:
      T - the key type
      Parameters:
      attribute - the attribute which value should be used for mapping
      entities - the entities to map by attribute value
      Returns:
      a LinkedHashMap of the given entities mapped to the attribute value

    • groupByType

      static LinkedHashMap<EntityType,List<Entity>> groupByType(Collection<Entity> entities)
      Returns a LinkedHashMap containing the given entities mapped to their entityTypes, respecting the iteration order of the given collection
      Parameters:
      entities - the entities to map by entityType
      Returns:
      a LinkedHashMap of the given entities mapped to their EntityType