Entity (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.map, class: Entity

# Class Entity<E extends Entity<E,A,R>, A extends Attribute<E,A,R>, R extends Relationship<E,A,R>>

java.lang.Object
org.apache.cayenne.map.Entity<E,A,R>

All Implemented Interfaces:
  `Serializable, CayenneMapEntry, XMLSerializable`

Direct Known Subclasses:
  `DbEntity, ObjEntity`

public abstract class Entity<E extends Entity<E,A,R>, A extends Attribute<E,A,R>, R extends Relationship<E,A,R>> extends Object implements CayenneMapEntry, XMLSerializable, Serializable
An Entity is an abstract descriptor for an entity mapping concept. Entity can represent either a descriptor of database table or a persistent object.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Map<String,A>`
  `attributes`
  `protected DataMap`
  `dataMap`
  `protected String`
  `name`
  `static final String`
  `OUTER_JOIN_INDICATOR`
  A prefix or a suffix that can be used in a path component to indicate that an OUTER JOIN should be used when resolving the expression.
  `static final String`
  `PATH_SEPARATOR`
  `protected final Map<String,R>`
  `relationships`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Entity()`
  Creates an unnamed Entity.
  `Entity(String name)`
  Creates a named Entity.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addAttribute(A attribute)`
  Adds new attribute to the entity, setting its parent entity to be this object.
  `void`
  `addRelationship(R relationship)`
  Adds new relationship to the entity.
  `void`
  `clearAttributes()`
  `void`
  `clearRelationships()`
  `R`
  `getAnyRelationship(E targetEntity)`
  Returns a relationship that has a specified entity as a target.
  `A`
  `getAttribute(String attributeName)`
  Returns attribute with name `attributeName` or null if no attribute with this name exists.
  `Map<String,A>`
  `getAttributeMap()`
  Returns an unmodifiable sorted map of entity attributes.
  `Collection<A>`
  `getAttributes()`
  Returns an unmodifiable collection of entity attributes.
  `DataMap`
  `getDataMap()`
  `String`
  `getName()`
  Returns entity name.
  `Object`
  `getParent()`
  Returns the parent map.
  `R`
  `getRelationship(String relName)`
  Returns relationship with name `relName`.
  `Map<String,R>`
  `getRelationshipMap()`
  Returns an unmodifiable map of relationships sorted by name.
  `Collection<R>`
  `getRelationships()`
  Returns an unmodifiable collection of Relationships that exist in this entity.
  `PathComponent<A,R>`
  `lastPathComponent(Expression path, Map<String,String> aliasMap)`
  Convenience method returning the last component in the path iterator.
  `void`
  `removeAttribute(String attrName)`
  Removes an attribute named `attrName`.
  `void`
  `removeRelationship(String relName)`
  Removes a relationship named `attrName`.
  `abstract Iterable<PathComponent<A,R>>`
  `resolvePath(Expression pathExp, Map<String,String> aliasMap)`
  Returns an Iterable over the path components with elements represented as `PathComponent` instances, encapsulating a relationship, an attribute or a subpath alias.
  `Iterator<CayenneMapEntry>`
  `resolvePathComponents(String path)`
  Returns an Iterator over the path components that contains a sequence of Attributes and Relationships.
  `abstract Iterator<CayenneMapEntry>`
  `resolvePathComponents(Expression pathExp)`
  Processes expression `pathExp` and returns an Iterator of path components that contains a sequence of Attributes and Relationships.
  `Iterator<CayenneMapEntry>`
  `resolvePathComponents(CayennePath path)`
  `void`
  `setDataMap(DataMap dataMap)`
  Sets parent DataMap of this entity.
  `void`
  `setName(String name)`
  `void`
  `setParent(Object parent)`
  Stores the parent map.
  `String`
  `toString()`
  `Expression`
  `translateToRelatedEntity(Expression expression, String relationshipPath)`
  Translates Expression rooted in this entity to an analogous expression rooted in related entity.
  `abstract Expression`
  `translateToRelatedEntity(Expression expression, CayennePath relationshipPath)`
  Transforms Expression rooted in this entity to an analogous expression rooted in related entity.
  `void`
  `updateAttribute(A attribute)`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface XMLSerializable

  `encodeAsXML`
  Modifier and Type
  Method
  Description
  `void`
  `encodeAsXML(XMLEncoder encoder, ConfigurationNodeVisitor<?> delegate)`
  Prints itself as XML to the provided XMLEncoder.

- ## Field Details

  - ### PATH_SEPARATOR

    public static final String PATH_SEPARATOR
    See Also:
      - Constant Field Values

  - ### OUTER_JOIN_INDICATOR

    public static final String OUTER_JOIN_INDICATOR
    A prefix or a suffix that can be used in a path component to indicate that an OUTER JOIN should be used when resolving the expression.
    Since:
      3.0
    See Also:
      - Constant Field Values

  - ### name

    protected String name

  - ### dataMap

    protected DataMap dataMap

  - ### attributes

    protected final Map<String, A extends Attribute<E,A,R>> attributes

  - ### relationships

    protected final Map<String, R extends Relationship<E,A,R>> relationships

- ## Constructor Details

  - ### Entity

    public Entity()
    Creates an unnamed Entity.

  - ### Entity

    public Entity(String name)
    Creates a named Entity.

- ## Method Details

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### getName

    public String getName()
    Returns entity name. Name is a unique identifier of the entity within its DataMap.
    Specified by:
      `getName` in interface `CayenneMapEntry`
    Returns:
      name of this entry.

  - ### setName

    public void setName(String name)

  - ### getParent

    public Object getParent()
    Description copied from interface: `CayenneMapEntry`
    Returns the parent map.
    Specified by:
      `getParent` in interface `CayenneMapEntry`

  - ### setParent

    public void setParent(Object parent)
    Description copied from interface: `CayenneMapEntry`
    Stores the parent map.
    Specified by:
      `setParent` in interface `CayenneMapEntry`

  - ### getDataMap

    public DataMap getDataMap()
    Returns:
      parent DataMap of this entity.

  - ### setDataMap

    public void setDataMap(DataMap dataMap)
    Sets parent DataMap of this entity.

  - ### getAttribute

    public A getAttribute(String attributeName)
    Returns attribute with name `attributeName` or null if no attribute with this name exists.

  - ### addAttribute

    public void addAttribute(A attribute)
    Adds new attribute to the entity, setting its parent entity to be this object. If attribute has no name, IllegalArgumentException is thrown.

  - ### removeAttribute

    public void removeAttribute(String attrName)
    Removes an attribute named `attrName`.

  - ### updateAttribute

    public void updateAttribute(A attribute)
    Since:
      4.0

  - ### clearAttributes

    public void clearAttributes()

  - ### getRelationship

    public R getRelationship(String relName)
    Returns relationship with name `relName`. Will return null if no relationship with this name exists in the entity.

  - ### addRelationship

    public void addRelationship(R relationship)
    Adds new relationship to the entity.

  - ### removeRelationship

    public void removeRelationship(String relName)
    Removes a relationship named `attrName`.

  - ### clearRelationships

    public void clearRelationships()

  - ### getRelationshipMap

    public Map<String,R> getRelationshipMap()
    Returns an unmodifiable map of relationships sorted by name.

  - ### getAnyRelationship

    public R getAnyRelationship(E targetEntity)
    Returns a relationship that has a specified entity as a target. If there is more than one relationship for the same target, it is unpredictable which one will be returned.
    Since:
      1.1

  - ### getRelationships

    public Collection<R> getRelationships()
    Returns an unmodifiable collection of Relationships that exist in this entity.

  - ### getAttributeMap

    public Map<String,A> getAttributeMap()
    Returns an unmodifiable sorted map of entity attributes.

  - ### getAttributes

    public Collection<A> getAttributes()
    Returns an unmodifiable collection of entity attributes.

  - ### translateToRelatedEntity

    public Expression translateToRelatedEntity(Expression expression, String relationshipPath)
    Translates Expression rooted in this entity to an analogous expression rooted in related entity.
    Since:
      1.1

  - ### translateToRelatedEntity

    public abstract Expression translateToRelatedEntity(Expression expression, CayennePath relationshipPath)
    Transforms Expression rooted in this entity to an analogous expression rooted in related entity.
    Since:
      5.0

  - ### lastPathComponent

    public PathComponent<A,R> lastPathComponent(Expression path, Map<String,String> aliasMap)
    Convenience method returning the last component in the path iterator. If the last component is an alias, it is fully resolved down to the last ObjRelationship.
    Since:
      3.0

  - ### resolvePath

    public abstract Iterable<PathComponent<A,R>> resolvePath(Expression pathExp, Map<String,String> aliasMap)
    Returns an Iterable over the path components with elements represented as `PathComponent` instances, encapsulating a relationship, an attribute or a subpath alias. An optional "aliasMap" parameter is used to resolve subpaths from aliases.

    This method is lazy: if path is invalid and can not be resolved from this entity, this method will still return an Iterator, but an attempt to read the first invalid path component will result in ExpressionException.

    Since:
      3.0

  - ### resolvePathComponents

    public abstract Iterator<CayenneMapEntry> resolvePathComponents(Expression pathExp) throws ExpressionException
    Processes expression `pathExp` and returns an Iterator of path components that contains a sequence of Attributes and Relationships. Note that if path is invalid and can not be resolved from this entity, this method will still return an Iterator, but an attempt to read the first invalid path component will result in ExpressionException.
    Throws:
      `ExpressionException`

  - ### resolvePathComponents

    public Iterator<CayenneMapEntry> resolvePathComponents(String path) throws ExpressionException
    Returns an Iterator over the path components that contains a sequence of Attributes and Relationships. Note that if path is invalid and can not be resolved from this entity, this method will still return an Iterator, but an attempt to read the first invalid path component will result in ExpressionException.
    Throws:
      `ExpressionException`

  - ### resolvePathComponents

    public Iterator<CayenneMapEntry> resolvePathComponents(CayennePath path) throws ExpressionException
    Throws:
      `ExpressionException`