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

# Class ObjRelationship

java.lang.Object
org.apache.cayenne.map.Relationship<ObjEntity, ObjAttribute, ObjRelationship>
org.apache.cayenne.map.ObjRelationship

All Implemented Interfaces:
  `Serializable, ConfigurationNode, CayenneMapEntry, XMLSerializable`

public class ObjRelationship extends Relationship<ObjEntity, ObjAttribute, ObjRelationship> implements ConfigurationNode
Describes an association between two Java classes mapped as source and target ObjEntity. Maps to a path of DbRelationships.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected String`
  `collectionType`
  Stores the type of collection mapped by a to-many relationship.
  `protected List<DbRelationship>`
  `dbRelationships`
  `static final String`
  `DEFAULT_COLLECTION_TYPE`
  Denotes a default type of to-many relationship collection which is a Java List.
  `protected int`
  `deleteRule`
  `protected String`
  `mapKey`
  Stores a property name of a target entity used to create a relationship map.
  `protected boolean`
  `usedForLocking`

  ### Fields inherited from class Relationship

  `name, runtime, sourceEntity, targetEntityName, toMany`
  Modifier and Type
  Field
  Description
  `protected String`
  `name`
  `protected boolean`
  `runtime`
  A flag that specifies whether a Relationship was mapped by the user or added dynamically by Cayenne runtime.
  `protected ObjEntity`
  `sourceEntity`
  `protected String`
  `targetEntityName`
  `protected boolean`
  `toMany`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ObjRelationship()`
  `ObjRelationship(String name)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T> T`
  `acceptVisitor(ConfigurationNodeVisitor<T> visitor)`
  `void`
  `addDbRelationship(DbRelationship dbRel)`
  Appends a DbRelationship to the existing list of DbRelationships.
  `void`
  `clearDbRelationships()`
  `ObjRelationship`
  `createReverseRelationship()`
  Creates a complimentary reverse relationship from target entity to the source entity.
  `void`
  `encodeAsXML(XMLEncoder encoder, ConfigurationNodeVisitor<?> delegate)`
  Prints itself as XML to the provided XMLEncoder.
  `String`
  `getCollectionType()`
  Returns the interface of collection mapped by a to-many relationship.
  `CayennePath`
  `getDbRelationshipPath()`
  Returns a dot-separated path over mapped DbRelationships.
  `List<DbRelationship>`
  `getDbRelationships()`
  Returns an immutable list of underlying DbRelationships.
  `int`
  `getDeleteRule()`
  Returns the deleteRule.
  `String`
  `getMapKey()`
  Returns a property name of a target entity used to create a relationship map.
  `CayennePath`
  `getReverseDbRelationshipPath()`
  Returns a reversed dbRelationship path.
  `ObjRelationship`
  `getReverseRelationship()`
  Returns a "complimentary" ObjRelationship going in the opposite direction.
  `String`
  `getReverseRelationshipName()`
  Returns the name of a complimentary relationship going in the opposite direction or null if it doesn't exist.
  `ObjEntity`
  `getSourceEntity()`
  Returns relationship source entity.
  `ObjEntity`
  `getTargetEntity()`
  Returns a target ObjEntity of this relationship.
  `boolean`
  `isFlattened()`
  Returns true if the relationship is a "flattened" relationship.
  `boolean`
  `isMandatory()`
  Returns if relationship is mandatory
  `boolean`
  `isOptional()`
  Returns a boolean indicating whether the presence of a non-null source key(s) will not guarantee a presence of a target record.
  `boolean`
  `isReadOnly()`
  Returns true if the relationship is flattened, but is not of the single case that can have automatic write support.
  `boolean`
  `isSourceDefiningTargetPrecenseAndType(EntityResolver entityResolver)`
  Returns true if the relationship is non-optional and target has no subclasses.
  `boolean`
  `isSourceIndependentFromTargetChange()`
  Returns a boolean indicating whether modifying a target of such relationship in any way will not change the underlying table row of the source.
  `boolean`
  `isToDependentEntity()`
  Returns true if underlying DbRelationships point to dependent entity.
  `boolean`
  `isToMany()`
  Returns a boolean value that determines relationship multiplicity.
  `boolean`
  `isToPK()`
  Returns true if the underlying DbRelationships point to a at least one of the columns of the target entity.
  `boolean`
  `isUsedForLocking()`
  Returns whether this attribute should be used for locking.
  `void`
  `recalculateReadOnlyValue()`
  Deprecated.
  since 4.2
  `void`
  `recalculateToManyValue()`
  Recalculates whether a relationship is toMany or toOne, based on the underlying db relationships.
  `void`
  `removeDbRelationship(DbRelationship dbRel)`
  Removes the relationship `dbRel` from the list of relationships.
  `void`
  `setCollectionType(String collectionType)`
  `void`
  `setDbRelationshipPath(String relationshipPath)`
  Sets mapped DbRelationships as a dot-separated path.
  `void`
  `setDbRelationshipPath(CayennePath relationshipPath)`
  Sets mapped DbRelationships as a dot-separated path.
  `void`
  `setDeferredDbRelationshipPath(String relationshipPath)`
  Sets relationship path, but does not trigger its conversion to `List<DbRelationship>`.
  `void`
  `setDeleteRule(int value)`
  Sets the delete rule of the relationship.
  `void`
  `setMapKey(String mapKey)`
  `void`
  `setUsedForLocking(boolean usedForLocking)`
  Sets whether this attribute should be used for locking.
  `String`
  `toString()`
  Overrides Object.toString() to return informative description.

  ### Methods inherited from class Relationship

  `getName, getParent, getTargetEntityName, isRuntime, setName, setParent, setRuntime, setSourceEntity, setTargetEntityName, setTargetEntityName`
  Modifier and Type
  Method
  Description
  `String`
  `getName()`
  Returns the name property of this object.
  `Object`
  `getParent()`
  Returns the parent map.
  `String`
  `getTargetEntityName()`
  Returns the name of a target entity.
  `boolean`
  `isRuntime()`
  `void`
  `setName(String name)`
  `void`
  `setParent(Object parent)`
  Stores the parent map.
  `void`
  `setRuntime(boolean synthetic)`
  `void`
  `setSourceEntity(ObjEntity sourceEntity)`
  Sets relationship source entity.
  `void`
  `setTargetEntityName(String targetEntityName)`
  Sets the name of relationship target entity.
  `void`
  `setTargetEntityName(Entity<ObjEntity, ObjAttribute, ObjRelationship> targetEntity)`
  Sets relationship target entity.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### DEFAULT_COLLECTION_TYPE

    public static final String DEFAULT_COLLECTION_TYPE
    Denotes a default type of to-many relationship collection which is a Java List.
    Since:
      3.0
    See Also:
      - Constant Field Values

  - ### deleteRule

    protected int deleteRule

  - ### usedForLocking

    protected boolean usedForLocking

  - ### dbRelationships

    protected List<DbRelationship> dbRelationships

  - ### collectionType

    protected String collectionType
    Stores the type of collection mapped by a to-many relationship. Null for to-one relationships.
    Since:
      3.0

  - ### mapKey

    protected String mapKey
    Stores a property name of a target entity used to create a relationship map. Only has effect if collectionType property is set to "java.util.Map".
    Since:
      3.0

- ## Constructor Details

  - ### ObjRelationship

    public ObjRelationship()

  - ### ObjRelationship

    public ObjRelationship(String name)

- ## Method Details

  - ### getSourceEntity

    public ObjEntity getSourceEntity()
    Description copied from class: `Relationship`
    Returns relationship source entity.
    Overrides:
      `getSourceEntity` in class `Relationship<ObjEntity, ObjAttribute, ObjRelationship>`

  - ### acceptVisitor

    public <T> T acceptVisitor(ConfigurationNodeVisitor<T> visitor)
    Specified by:
      `acceptVisitor` in interface `ConfigurationNode`
    Since:
      3.1

  - ### encodeAsXML

    public void encodeAsXML(XMLEncoder encoder, ConfigurationNodeVisitor<?> delegate)
    Prints itself as XML to the provided XMLEncoder.
    Specified by:
      `encodeAsXML` in interface `XMLSerializable`
    Since:
      1.1

  - ### getTargetEntity

    public ObjEntity getTargetEntity()
    Returns a target ObjEntity of this relationship. Entity is looked up in the parent DataMap using "targetEntityName".
    Specified by:
      `getTargetEntity` in class `Relationship<ObjEntity, ObjAttribute, ObjRelationship>`

  - ### getReverseRelationshipName

    public String getReverseRelationshipName()
    Returns the name of a complimentary relationship going in the opposite direction or null if it doesn't exist.
    Since:
      1.2

  - ### getReverseRelationship

    public ObjRelationship getReverseRelationship()
    Returns a "complimentary" ObjRelationship going in the opposite direction. Returns null if no such relationship is found.
    Specified by:
      `getReverseRelationship` in class `Relationship<ObjEntity, ObjAttribute, ObjRelationship>`

  - ### createReverseRelationship

    public ObjRelationship createReverseRelationship()
    Creates a complimentary reverse relationship from target entity to the source entity. A new relationship is created regardless of whether one already exists. Returned relationship is not attached to the source entity and has no name. Throws a `CayenneRuntimeException` if reverse DbRelationship is not mapped.
    Since:
      3.0

  - ### getDbRelationships

    public List<DbRelationship> getDbRelationships()
    Returns an immutable list of underlying DbRelationships.

  - ### addDbRelationship

    public void addDbRelationship(DbRelationship dbRel)
    Appends a DbRelationship to the existing list of DbRelationships.

  - ### removeDbRelationship

    public void removeDbRelationship(DbRelationship dbRel)
    Removes the relationship `dbRel` from the list of relationships.

  - ### clearDbRelationships

    public void clearDbRelationships()

  - ### isOptional

    public boolean isOptional()
    Returns a boolean indicating whether the presence of a non-null source key(s) will not guarantee a presence of a target record. PK..FK relationships are all optional, but there are other more subtle cases, such as PK..PK, etc.
    Since:
      3.0

  - ### isSourceDefiningTargetPrecenseAndType

    public boolean isSourceDefiningTargetPrecenseAndType(EntityResolver entityResolver)
    Returns true if the relationship is non-optional and target has no subclasses.
    Since:
      3.0

  - ### isSourceIndependentFromTargetChange

    public boolean isSourceIndependentFromTargetChange()
    Returns a boolean indicating whether modifying a target of such relationship in any way will not change the underlying table row of the source.
    Since:
      1.1

  - ### isToDependentEntity

    public boolean isToDependentEntity()
    Returns true if underlying DbRelationships point to dependent entity.

  - ### isToPK

    public boolean isToPK()
    Returns true if the underlying DbRelationships point to a at least one of the columns of the target entity.
    Since:
      1.1

  - ### isFlattened

    public boolean isFlattened()
    Returns true if the relationship is a "flattened" relationship. A relationship is considered "flattened" if it maps to more than one DbRelationship. Such chain of DbRelationships is also called "relationship path". All flattened relationships are at least readable, but only those formed across a many-many join table (with no custom attributes other than foreign keys) can be automatically written.
    Returns:
      flag indicating if the relationship is flattened or not.
    See Also:
      - `isReadOnly()`

  - ### isReadOnly

    public boolean isReadOnly()
    Returns true if the relationship is flattened, but is not of the single case that can have automatic write support. Otherwise, it returns false.
    Returns:
      flag indicating if the relationship is read only or not

  - ### isToMany

    public boolean isToMany()
    Description copied from class: `Relationship`
    Returns a boolean value that determines relationship multiplicity. This defines semantics of the connection between two nodes described by the source and target entities. E.g. to-many relationship between two Persistent object classes means that a source object would have a collection of target objects. This is a read-only property.
    Overrides:
      `isToMany` in class `Relationship<ObjEntity, ObjAttribute, ObjRelationship>`

  - ### getDeleteRule

    public int getDeleteRule()
    Returns the deleteRule. The delete rule is a constant from the DeleteRule class, and specifies what should happen to the destination object when the source object is deleted.
    Returns:
      int a constant from DeleteRule
    See Also:
      - `setDeleteRule(int)`

  - ### setDeleteRule

    public void setDeleteRule(int value)
    Sets the delete rule of the relationship.
    Parameters:
      `value` - New delete rule. Must be one of the constants defined in DeleteRule class.
    Throws:
      `IllegalArgumentException` - if the value is not a valid delete rule.
    See Also:
      - `DeleteRule`

  - ### isUsedForLocking

    public boolean isUsedForLocking()
    Returns whether this attribute should be used for locking.
    Since:
      1.1

  - ### setUsedForLocking

    public void setUsedForLocking(boolean usedForLocking)
    Sets whether this attribute should be used for locking.
    Since:
      1.1

  - ### getDbRelationshipPath

    public CayennePath getDbRelationshipPath()
    Returns a dot-separated path over mapped DbRelationships.
    Returns:
      path or `null` if no db relationships set
    Since:
      1.1, 5.0 returns `CayennePath` instead of a plain `String`

  - ### getReverseDbRelationshipPath

    public CayennePath getReverseDbRelationshipPath() throws ExpressionException
    Returns a reversed dbRelationship path.
    Throws:
      `ExpressionException`
    Since:
      1.2, 5.0 returns `CayennePath` instead of a plain `String`

  - ### setDbRelationshipPath

    public void setDbRelationshipPath(String relationshipPath)
    Sets mapped DbRelationships as a dot-separated path.

  - ### setDbRelationshipPath

    public void setDbRelationshipPath(CayennePath relationshipPath)
    Sets mapped DbRelationships as a dot-separated path.
    Since:
      5.0

  - ### setDeferredDbRelationshipPath

    public void setDeferredDbRelationshipPath(String relationshipPath)
    Sets relationship path, but does not trigger its conversion to `List<DbRelationship>`.
    NOTE: this method is intended for internal usage, primarily datamap loading.
    Since:
      4.1 this method is public as it is used by new XML loaders

  - ### recalculateToManyValue

    public void recalculateToManyValue()
    Recalculates whether a relationship is toMany or toOne, based on the underlying db relationships.

  - ### recalculateReadOnlyValue

    @Deprecated(since="4.2") public void recalculateReadOnlyValue()
    Deprecated.
    since 4.2
    Recalculates a new readonly value based on the underlying DbRelationships.

  - ### toString

    public String toString()
    Description copied from class: `Relationship`
    Overrides Object.toString() to return informative description.
    Overrides:
      `toString` in class `Relationship<ObjEntity, ObjAttribute, ObjRelationship>`

  - ### getCollectionType

    public String getCollectionType()
    Returns the interface of collection mapped by a to-many relationship. Returns null for to-one relationships. Default for to-many is "java.util.List". Other possible values are "java.util.Set", "java.util.Collection", "java.util.Map".
    Since:
      3.0

  - ### setCollectionType

    public void setCollectionType(String collectionType)
    Since:
      3.0

  - ### getMapKey

    public String getMapKey()
    Returns a property name of a target entity used to create a relationship map. Only has effect if collectionType property is set to "java.util.Map".
    Returns:
      The attribute name used for the map key or `null` if the default (PK) is used as the map key.
    Since:
      3.0

  - ### setMapKey

    public void setMapKey(String mapKey)
    Since:
      3.0

  - ### isMandatory

    public boolean isMandatory()
    Description copied from class: `Relationship`
    Returns if relationship is mandatory
    Specified by:
      `isMandatory` in class `Relationship<ObjEntity, ObjAttribute, ObjRelationship>`