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 old 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 for which to retrieve the value
      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. If the value has not been modified the current value is returned.
      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 for which to retrieve the value
      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. 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 attribute(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 attribute(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

    • referencedEntity

      Entity referencedEntity(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

    • referencedKey

      Entity.Key referencedKey(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

    • valuesEqual

      boolean valuesEqual(Entity entity)
      Compares the values of all attributes in the given entity to the values in this entity instance. Returns true if these two entities contain values for the same attributes and all the values are equal.
      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

    • valuesEqual

      boolean valuesEqual(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 same 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()
      Returns a mutable copy of this entity.
      Returns:
      a copy of this entity

    • copyBuilder

      Entity.Builder copyBuilder()
      Returns a new Entity.Builder instance initialized with the values and original values from this entity.
      Returns:
      a Entity.Builder instance.

    • deepCopy

      Entity deepCopy()
      Returns a mutable copy of this entity, with new copied instances of all foreign key value entities.
      Returns:
      a deep copy of 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:

    • castTo

      <T extends Entity> T castTo(Class<T> entityClass)
      Casts this entity to the given type. If the entity is already of the given type it is returned as is.
      Type Parameters:
      T - the entity class type
      Parameters:
      entityClass - the entity class to cast to
      Returns:
      a typed entity
      Throws:
      IllegalArgumentException - in case the given entity class has not been associated with the underlying EntityType.

    • primaryKey

      Entity.Key primaryKey()
      Returns the primary key of this entity. If the entity has no primary key attribute defined, this key contains no values.
      Returns:
      the primary key of this entity

    • 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<? extends 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

    • referencedKeys

      static Collection<Entity.Key> referencedKeys(ForeignKey foreignKey, Collection<? extends 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<? extends 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<? extends 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<? extends 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.

    • castTo

      static <T extends Entity> Collection<T> castTo(Class<T> entityClass, Collection<Entity> entities)
      Casts the given entities to the given type. If an entity is already of the given type it is returned as is.
      Type Parameters:
      T - the entity class type
      Parameters:
      entityClass - the entity class to cast to
      entities - the entities
      Returns:
      typed entities
      Throws:
      IllegalArgumentException - in case the given entity class has not been associated with the underlying EntityType.

    • mapToPrimaryKey

      static <T extends Entity> Map<Entity.Key,T> mapToPrimaryKey(Collection<T> entities)
      Maps the given entities to their primary key
      Type Parameters:
      T - the entity type
      Parameters:
      entities - the entities to map
      Returns:
      the mapped entities

    • mapToValue

      static <T, E extends Entity> LinkedHashMap<T,List<E>> mapToValue(Attribute<T> attribute, Collection<E> 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
      E - the entity 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

    • mapToType

      static <T extends Entity> LinkedHashMap<EntityType,List<T>> mapToType(Collection<? extends T> entities)
      Returns a LinkedHashMap containing the given entities mapped to their entityTypes, respecting the iteration order of the given collection
      Type Parameters:
      T - the entity type
      Parameters:
      entities - the entities to map by entityType
      Returns:
      a Map of entities mapped to entityType

    • mapKeysToType

      static LinkedHashMap<EntityType,List<Entity.Key>> mapKeysToType(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

    • valuesAsString

      static List<List<String>> valuesAsString(List<Attribute<?>> attributes, List<Entity> entities)
      Creates a two-dimensional list containing the values of the given attributes for the given entities in string format.
      Parameters:
      attributes - the attributes
      entities - the entities
      Returns:
      the values of the given attributes from the given entities in a two-dimensional list

    • entitiesByValue

      static <T extends Entity> Collection<T> entitiesByValue(Map<Attribute<?>,Object> values, Collection<T> entities)
      Finds entities according to attribute values
      Type Parameters:
      T - the entity type
      Parameters:
      values - the attribute values to use as condition mapped to their respective attributes
      entities - the entities to search
      Returns:
      the entities having the exact same attribute values as in the given value map

    • valuesEqual

      static boolean valuesEqual(Entity entityOne, Entity entityTwo)
      Returns true if all attribute values available in the first entity are available and equal in the second entity.
      Parameters:
      entityOne - the first entity
      entityTwo - the second entity
      Returns:
      true if the values of the second entity are equal to all values in the first entity

    • valuesEqual

      static boolean valuesEqual(Entity entityOne, Entity entityTwo, Attribute<?>... attributes)
      Returns true if the values of the given attributes are equal in the given entities.
      Parameters:
      entityOne - the first entity
      entityTwo - the second entity
      attributes - the attributes which values to compare
      Returns:
      true if the values of the given attributes are equal in the given entities