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. Helper class for working with Entity instances and related classes.
See Also:

  • Method Details

    • entityType

      EntityType entityType()
      Returns:
      the entity type

    • definition

      EntityDefinition definition()
      Returns:
      the entity definition

    • put

      <T> T put(Attribute<T> attribute, 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> 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> T original(Attribute<T> attribute)
      Returns the original value associated with attribute, or the current one if it has not been modified..
      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

    • string

      <T> String string(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> 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.
      Parameters:
      attribute - the attribute
      Returns:
      true if the value mapped to the given attribute is null or no value is mapped

    • isNotNull

      boolean isNotNull(Attribute<?> attribute)
      Returns true if this Entity contains a non-null value mapped to the given attribute. In case of foreign keys the value of the underlying reference column(s) is checked.
      Parameters:
      attribute - the attribute
      Returns:
      true if a non-null value is mapped to the given attribute

    • 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

      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.
      Parameters:
      foreignKey - the foreign key for which to retrieve the value
      Returns:
      the entity associated with foreignKey

    • key

      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.
      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:

    • clearPrimaryKey

      Entity clearPrimaryKey()
      Clears the primary key values from this entity, current as well as original values if any
      Returns:
      this Entity instance
      Throws:
      UnsupportedOperationException - in case this entity is immutable

    • 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 the this entity are available and equal in the comparison entity
      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.
      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(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 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.
      Returns:
      an immutable version of this entity

    • mutable

      boolean mutable()
      Returns:
      true if this is a mutable instance
      See Also:

    • primaryKey

      Entity.Key primaryKey()
      Returns the primary key of this entity. If the entity has no defined primary key, this key contains all column values and Entity.Key.primaryKey() returns false.
      Returns:
      the primary key of this entity
      See Also:

    • originalPrimaryKey

      Entity.Key originalPrimaryKey()
      Returns the primary key of this entity, in its original state. If the entity has no primary key attributes defined, this key contains no values.
      Returns:
      the primary key of this entity in its original state

    • entrySet

      Set<Map.Entry<Attribute<?>,Object>> entrySet()
      Returns an unmodifiable view of the entries in this Entity, note that attributes based on derived values are not included.
      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 List 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 foreign key
      Parameters:
      foreignKey - the foreign key
      entities - the entities
      Returns:
      the non-null keys referenced by the given foreign key

    • 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<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 the given 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
      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<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
      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 Map of entities mapped to 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 Map of entities mapped to entityType

    • groupKeysByType

      static LinkedHashMap<EntityType,List<Entity.Key>> groupKeysByType(Collection<Entity.Key> keys)
      Returns a LinkedHashMap containing the given entity keys mapped to their entityTypes, respecting the iteration order of the given collection
      Parameters:
      keys - the entity keys to map by entityType
      Returns:
      a Map of entity keys mapped to entityType