EORelationship
Inherits from: NSObject
Implements: EOPropertyListEncoding
Package: com.apple.yellow.eoaccess
Class Description
An EORelationship describes an association between two entities, based on attributes of those two entities. By defining EORelationships in your application's EOModel, you can cause the relationships defined in the database to be automatically resolved as enterprise objects are fetched. For example, a Movie entity may contain its studioId as an attribute, but without an EORelationship studioId will only appear in a movie enterprise object as a number. With an EORelationship explicitly connecting the Movie entity to a Studio entity, a movie enterprise object will automatically be given its studio enterprise object when an EODatabaseChannel fetches it from the database. The two entities that make up a relationship can be in the same model or two different models, as long as they are in the same model group.
You usually define relationships in your EOModel with the EOModeler application, which is documented in Enterprise Objects Framework Tools and Techniques. EORelationships are primarily for use by the Enterprise Objects Framework; unless you have special needs you shouldn't need to access them in your application's code. If you have such a need, you can create your own EORelationship objects as outlined in the sections "Creating a Simple Relationship" and "Creating a Flattened Relationship" .
A relationship is directional: One entity is considered the source, and the other is considered the destination. The relationship belongs to the source entity, and may only be traversed from source to destination. To simulate a two-way relationship you have to create an EORelationship for each direction. Although the relationship is directional, no inverse is implied (although an inverse relationship may exist).
A relationship maintains an array of joins identifying attributes from the related entities (see the EOJoin class specification for more information). Most relationships simply relate the objects of one entity to those of another by comparing attribute values between them. Such a relationship must be defined as to-one or to-many based on how many objects of the destination match each object of the source. This is called the cardinality of the relationship. In a to-one relationship, there must be exactly one destination object for each source object; in a to-many relationship there can be any number of destination objects for each source object. See "Creating a Simple Relationship" for more information.
A chain of relationships across several entities can be flattened, creating a single relationship that spans them all. For example, suppose you have a relationship between movies and directors, and a relationship between directors and talent. You can traverse these relationships to create a flattened relationship going directly from movies to talent. A flattened relationship is determined to be to-many or to-one based on the relationships it spans; if all are to-one, then the flattened relationship is to-one, but if any of them is to-many the flattened relationship is to-many. See "Creating a Flattened Relationship" for more information.
Like the other major modeling classes, EORelationship provides a user dictionary that the application can use to store application-specific information related to the relationship.
Specifying the Join Semantic
The relationship holds the join semantic; you specify this semantic with setJoinSemantic. There are four types of join semantic: InnerJoin, FullOuterJoin, LeftOuterJoin, and RightOuterJoin. An inner join produces results only for destinations of the join relationship that have non-NULL values. A full outer join produces results for all source records, regardless of the values of the relationships. A left outer join preserves rows in the left (source) table, keeping them even if there's no corresponding row in the right table, while a right outer join preserves rows in the right (destination) table. Note that not all join semantics are supported by all database servers.
Constants
EORelationship defines the following int
constants
to specify the manner in which a join should be made:
Interfaces Implemented
EOPropertyListEncodingawakeWithPropertyList encodeIntoPropertyList
Method Types
- Constructors
- EORelationship
- Accessing the relationship name
- beautifyName
- name
- setName
- validateName
- Using joins
- addJoin
- joins
- joinSemantic
- removeJoin
- setJoinSemantic
- Accessing attributes joined on
- destinationAttributes
- sourceAttributes
- Accessing the definition
- componentRelationships
- definition
- setDefinition
- Accessing the entities joined
- anyInverseRelationship
- destinationEntity
- entity
- inverseRelationship
- setEntity
- Checking the relationship type
- isCompound
- isFlattened
- isMandatory
- setIsMandatory
- validateValue
- Accessing whether the relationship is to-many
- isToMany
- setToMany
- Relationship qualifiers
- qualifierWithSourceRow
- Checking references
- referencesProperty
- Controlling batch fetches
- numberOfToManyFaultsToBatchFetch
- setNumberOfToManyFaultsToBatchFetch
- Taking action upon a change
- deleteRule
- propagatesPrimaryKey
- setDeleteRule
- setPropagatesPrimaryKey
- ownsDestination
- setOwnsDestination
- Accessing the user dictionary
- setUserInfo
- userInfo
Constructors
EORelationship
public EORelationship(
NSDictionary propertyList,
Object owner)
Creates and returns a new EORelationship is initialized from propertyList-a dictionary containing only property list data types (that is, NSDictionaries, Strings, NSArrays, and next.util.ImmutableBytes). This constructor is used by EOModeler when it reads in a Model from a file, for example. The owner argument should be the EORelationship's Entity. EORelationships created from a property list must receive an awakeWithPropertyList message immediately after creation before they are fully functional, but the awake... message should be deferred until the all of the other objects in the model have also been created.
See Also: encodeIntoPropertyList (EOPropertyListEncoding interface)
Instance Methods
addJoin
public void addJoin(EOJoin aJoin)
See Also: joins, isFlattened, setDefinition
anyInverseRelationship
public EORelationship anyInverseRelationship()
See Also: inverseRelationship
beautifyName
See Also: setName, validateName, beautifyNames (EOModel)
componentRelationships
public NSArray componentRelationships()
See Also: definition
definition
public String definition()
Returns the data path of a flattened relationship; for example "department.facility". If the relationship isn't flattened, definition returns null.
See Also: componentRelationships
deleteRule
public int deleteRule()
Value | Description |
EOClassDescription.
DeleteRuleNullify |
Delete the department and remove any back reference the employee has to the department. |
EOClassDescription.
DeleteRuleCascade |
Delete the department and all of the employees it contains. |
EOClassDescription.
DeleteRuleDeny |
Refuse the deletion if the department contains employees. |
EOClassDescription.
DeleteRuleNoAction |
Delete the department, but ignore the department's employees relationship. You should use this delete rule with caution since it can leave dangling references in your object graph. |
destinationAttributes
public NSArray destinationAttributes()
See Also: joins, destinationAttribute (EOJoin)
destinationEntity
public EOEntity destinationEntity()
See Also: entity
entity
public EOEntity entity()
See Also: destinationEntity, addRelationship (EOEntity)
inverseRelationship
public EORelationship inverseRelationship()
See Also: anyInverseRelationship
isCompound
public boolean isCompound()
See Also: joins, joinSemantic
isFlattened
public boolean isFlattened()
isMandatory
public boolean isMandatory()
See Also: setIsMandatory
isToMany
public boolean isToMany()
See Also: setToMany
joinSemantic
public int joinSemantic()
Constant | Description |
InnerJoin |
Produces results only for destinations of the join relationship that have non-NULL values. |
FullOuterJoin |
Produces results for all source records, regardless of the values of the relationships. |
LeftOuterJoin |
Preserves rows in the left (source) table, keeping them even if there's no corresponding row in the right table. |
RightOuterJoin |
Preserves rows in the right (destination) table, keeping them even if there's no corresponding row in the left table. |
See Also: joins
joins
public NSArray joins()
See Also: destinationAttributes, joinSemantic, sourceAttributes
name
public String name()
numberOfToManyFaultsToBatchFetch
public int numberOfToManyFaultsToBatchFetch()
ownsDestination
public boolean ownsDestination()
See Also: destinationAttributes
propagatesPrimaryKey
public boolean propagatesPrimaryKey()
qualifierWithSourceRow
public EOQualifier qualifierWithSourceRow(NSDictionary sourceRow)
referencesProperty
public boolean referencesProperty(Object aProperty)
See Also: referencesProperty (EOEntity)
removeJoin
public void removeJoin(EOJoin aJoin)
See Also: addJoin
setDefinition
public void setDefinition(String definition)
If the relationship's entity hasn't been set, this method won't work correctly. See "Creating a Flattened Relationship" for more information on flattened relationships.
setDeleteRule
public void setDeleteRule(int deleteRule)
EOClassDescription.DeleteRuleNullify
EOClassDescription.DeleteRuleCascade
EOClassDescription.DeleteRuleDeny
EOClassDescription.DeleteRuleNoAction
For more discussion of what these rules mean, see the method description for deleteRule.
setEntity
public void setEntity(EOEntity anEntity)
You only need to use this method when creating a flattened relationship; use EOEntity's addRelationship to associate an existing relationship with an entity.
See Also: setDefinition
setIsMandatory
public void setIsMandatory(boolean flag)
setJoinSemantic
public void setJoinSemantic(int joinSemantic)
See Also: addJoin, joinSemantic
setName
public void setName(String name)
This method forces all objects in the model to be loaded into memory.
See Also: beautifyName, validateName
setNumberOfToManyFaultsToBatchFetch
public void setNumberOfToManyFaultsToBatchFetch(int size)
See Also: isToMany, numberOfToManyFaultsToBatchFetch
setOwnsDestination
public void setOwnsDestination(boolean flag)
See Also: deleteRule, setDeleteRule, ownsDestination
setPropagatesPrimaryKey
public void setPropagatesPrimaryKey(boolean flag)
setToMany
public void setToMany(boolean flag)
See Also: isFlattened
setUserInfo
public void setUserInfo(NSDictionary dictionary)
sourceAttributes
public NSArray sourceAttributes()
See Also: joins, sourceAttribute (EOJoin)
userInfo
public NSDictionary userInfo()
validateName
public void validateName(String name)
setName uses this method to validate its argument.
validateValue
public Object validateValue(Object value)
See Also: isMandatory, setIsMandatory