org.apache.cayenne.map
Class ObjRelationship

java.lang.Object
  extended by org.apache.cayenne.map.Relationship
      extended by org.apache.cayenne.map.ObjRelationship
All Implemented Interfaces:
Serializable, CayenneMapEntry, XMLSerializable

public class ObjRelationship
extends Relationship

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
protected  String collectionType
          Stores the type of collection mapped by a to-many relationship.
protected  List<DbRelationship> dbRelationships
           
static 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 org.apache.cayenne.map.Relationship
name, runtime, sourceEntity, targetEntityName, toMany
 
Constructor Summary
ObjRelationship()
           
ObjRelationship(String name)
           
 
Method Summary
 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 dbRelationshipDidChange(RelationshipEvent event)
          Deprecated. since 3.0 as ObjRelationship no longer reacts to DbRelationship events.
 void encodeAsXML(XMLEncoder encoder)
          Prints itself as XML to the provided XMLEncoder.
 ObjRelationship getClientRelationship()
          Returns an ObjAttribute stripped of any server-side information, such as DbAttribute mapping.
 String getCollectionType()
          Returns the interface of collection mapped by a to-many relationship.
 String 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.
 String 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.
 Entity getTargetEntity()
          Returns a target ObjEntity of this relationship.
 boolean isFlattened()
          Returns true if the relationship is a "flattened" relationship.
 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()
          Recalculates a new readonly value based on the underlying DbRelationships.
 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 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 org.apache.cayenne.map.Relationship
getName, getParent, getSourceEntity, getTargetEntityName, isRuntime, setName, setParent, setRuntime, setSourceEntity, setTargetEntity, setTargetEntityName
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

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 Detail

ObjRelationship

public ObjRelationship()

ObjRelationship

public ObjRelationship(String name)
Method Detail

encodeAsXML

public void encodeAsXML(XMLEncoder encoder)
Prints itself as XML to the provided XMLEncoder.

Since:
1.1

getTargetEntity

public Entity getTargetEntity()
Returns a target ObjEntity of this relationship. Entity is looked up in the parent DataMap using "targetEntityName".

Specified by:
getTargetEntity in class Relationship

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.


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

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

dbRelationshipDidChange

@Deprecated
public void dbRelationshipDidChange(RelationshipEvent event)
Deprecated. since 3.0 as ObjRelationship no longer reacts to DbRelationship events.


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 String getDbRelationshipPath()
Returns a dot-separated path over mapped DbRelationships.

Since:
1.1

getReverseDbRelationshipPath

public String getReverseDbRelationshipPath()
                                    throws ExpressionException
Returns a reversed dbRelationship path.

Throws:
ExpressionException
Since:
1.2

setDbRelationshipPath

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


recalculateToManyValue

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


recalculateReadOnlyValue

public void recalculateReadOnlyValue()
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

getClientRelationship

public ObjRelationship getClientRelationship()
Returns an ObjAttribute stripped of any server-side information, such as DbAttribute mapping.

Since:
1.2

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


Copyright © 2001-2011 Apache Cayenne. All Rights Reserved.