com.webobjects.eoaccess
Class EORelationship

java.lang.Object
  com.webobjects.eoaccess.EOProperty
      com.webobjects.eoaccess.EORelationship

All Implemented Interfaces:

EOPropertyListEncoding, EOSQLExpression.SQLValue

public class EORelationship

extends EOProperty

implements EOPropertyListEncoding, EOSQLExpression.SQLValue

An EORelationship describes an association between two entities, based on attributes of those two entities. By defining EORelationships in the 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 appear in a Movie Enterprise Object only 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 can define relationships in your EOModel with the EOModeler application. 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.

See EORelationshipConcepts for more information.

See Also:

setJoinSemantic(int joinSemantic), InnerJoin, FullOuterJoin, LeftOuterJoin, RightOuterJoin

Field Summary

static int	FullOuterJoin Produces results for all source records, regardless of the values of the relationships.
static int	InnerJoin Produces results only for destinations of the join relationship that have non-null values.
static int	LeftOuterJoin Preserves rows in the left (source) table, keeping them even if there's no corresponding row in the right table.
static int	RightOuterJoin Preserves rows in the right (destination) table, keeping them even if there's no corresponding row in the left table.

Constructor Summary

EORelationship()
Creates an empty EORelationship.

EORelationship(NSDictionary plist, EOEntity owner)
Creates and returns a new EORelationship initialized from plist-a dictionary containing only property list data types (that is, NSDictionaries, Strings, NSArrays, and NSData).

Method Summary

void	addJoin(EOJoin join) Adds a source-destination attribute pair to the relationship.
EORelationship	anyInverseRelationship() Searches the relationship's destination entity for any back- referencing relationship joining on the same keys.
void	awakeWithPropertyList(NSDictionary plist) Finishes initializing the receiver from plist.
void	beautifyName() Makes the relationship's name conform to a standard convention.
NSArray	componentRelationships() Returns an NSArray of base relationships making up a flattened relationship, or null if the relationship isn't flattened.
String	definition() Returns the data path of a flattened relationship; for example "department.facility".
int	deleteRule() Returns a rule that describes the action to take when an object is being deleted.
NSArray	destinationAttributes() Returns an NSArray of destination attributes of the relationship.
EOEntity	destinationEntity() Returns the relationship's destination entity, which is determined by the destination entity of its joins for a simple relationship, and by whatever ends the data path for a flattened relationship.
void	encodeIntoPropertyList(NSMutableDictionary result) Encodes the receiver as a property list.
EOEntity	entity() Returns the relationship's entity.
EORelationship	inverseRelationship() Searches the relationship's destination entity for a user-created, back- referencing relationship joining on the same keys.
boolean	isCompound() Returns true if the relationship contains more than one join (that is, if it joins more than one pair of attributes), false if it has only one join.
boolean	isFlattened() Returns true if the relationship has a definition that traverses another relationship, false otherwise.
boolean	isMandatory() Returns true if the target of the relationship is required, false if it can be null.
boolean	isToMany() Returns true if the relationship is to-many, false if it's to-one.
NSArray	joins() Returns all joins used by relationship.
int	joinSemantic() Returns the semantic used to create SQL expressions for this relationship.
String	name() Returns the relationship's name.
int	numberOfToManyFaultsToBatchFetch() Returns the number of to-many faults that are triggered at one time.
boolean	ownsDestination() Returns true if the receiver's source object owns its destination objects, false otherwise.
boolean	propagatesPrimaryKey() Returns true if objects should propagate their primary key to related objects through this relationship.
EOQualifier	qualifierWithSourceRow(NSDictionary sourceRow) Returns a qualifier that can be used to fetch the destination of the receiving relationship given sourceRow.
boolean	referencesProperty(Object property) Returns true if property is in the relationship's data path or is an attribute belonging to one of the relationship's joins; otherwise, it returns false.
String	relationshipPath() Returns the full relationship path for a flattened relationship.
void	removeJoin(EOJoin join) Deletes join from the relationship.
void	setDefinition(String definition) Changes the relationship to a flattened relationship by releasing any joins and attributes (both source and destination) associated with the relationship and setting definition as its data path.
void	setDeleteRule(int deleteRule) Set a rule describing the action to take when object is being deleted.
void	setEntity(EOEntity entity) Sets the entity of the relationship to entity.
void	setIsMandatory(boolean isMandatory) Specifies according to isMandatory whether the target of the relationship must be supplied or can be null.
void	setJoinSemantic(int semantic) Sets the semantic used to create SQL expressions for this relationship.
void	setName(String name) Sets the relationship's name to name.
void	setNumberOfToManyFaultsToBatchFetch(int size) Sets the number of "toMany" faults that are fired at one time to size.
void	setOwnsDestination(boolean bool) Sets according to bool whether a receiver's source object owns its destination objects.
void	setPropagatesPrimaryKey(boolean bool) Specifies according to bool whether objects should propagate their primary key to related objects through this relationship.
void	setToMany(boolean bool) Sets a simple relationship as to-many according to bool.
void	setUserInfo(NSDictionary dictionary) Sets the dictionary of auxiliary data, which the application can use for whatever it needs.
NSArray	sourceAttributes() Returns the source attributes of a simple (non-flattened) relationship.
String	toString()
NSDictionary	userInfo() Returns a dictionary of user data.
Object	validateValue(Object valueP) For relationships marked as mandatory, throws a ValidationException if the receiver is to-one and valueP is null, or if the receiver is to-many and valueP has a count of 0.
String	valueForSQLExpression(EOSQLExpression context) Returns the value to use in SQL expressions.

Methods inherited from class java.lang.Object

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

Field Detail

FullOuterJoin

public static final int FullOuterJoin

Produces results for all source records, regardless of the values of the relationships.

See Also:

Constant Field Values

InnerJoin

public static final int InnerJoin

Produces results only for destinations of the join relationship that have non-null values.

See Also:

Constant Field Values

LeftOuterJoin

public static final int LeftOuterJoin

Preserves rows in the left (source) table, keeping them even if there's no corresponding row in the right table.

See Also:

Constant Field Values

RightOuterJoin

public static final int RightOuterJoin

Preserves rows in the right (destination) table, keeping them even if there's no corresponding row in the left table.

See Also:

Constant Field Values

Constructor Detail

EORelationship

public EORelationship(NSDictionary plist,
                      EOEntity owner)

Creates and returns a new EORelationship initialized from plist-a dictionary containing only property list data types (that is, NSDictionaries, Strings, NSArrays, and NSData). 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 awakeWithPropertyList message should be deferred until after all of the other objects in the model have also been created.

Parameters:

plist - dictionary containing property list

owner - specify entity as owner

EORelationship

public EORelationship()

Creates an empty EORelationship.

Method Detail

addJoin

public void addJoin(EOJoin join)

Adds a source-destination attribute pair to the relationship. Throws an exception if the relationship is flattened, if either the source or destination attributes are flattened, or if either of join's attributes already belongs to another join of the relationship.

Parameters:

join - specifies joins used by relationship

Throws:

exception - if the relationship is flattened

See Also:

joins(), isFlattened(), setDefinition(String definition)

anyInverseRelationship

public EORelationship anyInverseRelationship()

Searches the relationship's destination entity for any back- referencing relationship joining on the same keys. It first looks for a relationship defined in the model. If none is found, it looks for a "hidden" inverse relationship that was manufactured by the Framework. If none is found, the Framework creates a "hidden" inverse relationship for internal use and returns that.

Returns:

"hidden" inverse relationship

See Also:

inverseRelationship()

awakeWithPropertyList

public void awakeWithPropertyList(NSDictionary plist)

Finishes initializing the receiver from plist.

The receiver must have been created with a constructor of the form:

public ClassName(NSDictionary propertyList, Object owner)

awakeWithPropertyList is responsible for restoring references to other objects. It should not be invoked until all other objects that the receiver might reference have been created from plist.

Specified by:

awakeWithPropertyList in interface EOPropertyListEncoding

Parameters:

plist - dictionary containing property list

beautifyName

public void beautifyName()

Makes the relationship's name conform to a standard convention. Names that conform to this style are all lower-case except for the initial letter of each embedded word other than the first, which is upper case. Thus, "NAME" becomes "name", and "FIRST_NAME" becomes "firstName". This method is used in reverse-engineering a model.

See Also:

setName(String name), EOModel.beautifyNames()

componentRelationships

public NSArray componentRelationships()

Returns an NSArray of base relationships making up a flattened relationship, or null if the relationship isn't flattened.

Returns:

NSArray of base relationships making up a flattened relationship

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.

Returns:

the data path of a flattened relationship

See Also:

componentRelationships()

deleteRule

public int deleteRule()

Returns a rule that describes the action to take when an object is being deleted. The returned rule is one of the following integers (defined in the EOControl layer's EOClassDescription class):

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.

Returns:

a rule that describes the action to take when an object is being deleted

See Also:

EOClassDescription

destinationAttributes

public NSArray destinationAttributes()

Returns an NSArray of destination attributes of the relationship. These correspond one-to-one with the attributes returned by sourceAttributes.

Returns:

NSArray of destination attributes

See Also:

sourceAttributes()

destinationEntity

public EOEntity destinationEntity()

Returns the relationship's destination entity, which is determined by the destination entity of its joins for a simple relationship, and by whatever ends the data path for a flattened relationship. For example, if a flattened relationship's definition is "department.facility", the destination entity is the Facility entity.

Returns:

the relationship's destination entity

See Also:

entity()

encodeIntoPropertyList

public void encodeIntoPropertyList(NSMutableDictionary result)

Description copied from interface: EOPropertyListEncoding

Encodes the receiver as a property list. Property lists are NSDictionary objects whose values are String, NSDictionary, NSArray, and NSData objects.

Specified by:

encodeIntoPropertyList in interface EOPropertyListEncoding

Parameters:

result - A dictionary into which to encode the receiver.

entity

public EOEntity entity()

Returns the relationship's entity.

Returns:

the relationship's entity

See Also:

EODatabaseOperation.EODatabaseOperation(EOGlobalID aGlobalID, Object anObject, EOEntity anEntity)

inverseRelationship

public EORelationship inverseRelationship()

Searches the relationship's destination entity for a user-created, back- referencing relationship joining on the same keys. Returns the inverse relationship if one is found, null otherwise.

Returns:

the inverse relationship if one is found, null otherwise

isCompound

public boolean isCompound()

Returns true if the relationship contains more than one join (that is, if it joins more than one pair of attributes), false if it has only one join.

Returns:

true if the relationship contains more than one join, false if it has only one join

isFlattened

public boolean isFlattened()

Returns true if the relationship has a definition that traverses another relationship, false otherwise. A flattened relationship gives the source entity access to the relationships in a destination entity.

Returns:

true if the relationship is flattened, false otherwise

isMandatory

public boolean isMandatory()

Returns true if the target of the relationship is required, false if it can be null.

Returns:

true if the target of the relationship is required, false if it can be null

See Also:

setIsMandatory(boolean flag)

isToMany

public boolean isToMany()

Returns true if the relationship is to-many, false if it's to-one.

Returns:

true if the relationship is to-many, false if it's to-one.

See Also:

setToMany(boolean flag)

joinSemantic

public int joinSemantic()

Returns the semantic used to create SQL expressions for this relationship. The returned join semantic is one of the following:

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.

Returns:

the semantic used to create SQL expressions for this relationship

See Also:

joins()

joins

public NSArray joins()

Returns all joins used by relationship.

Returns:

NSArray of all joins used by relationship

See Also:

destinationAttributes(), joinSemantic(), sourceAttributes()

name

public String name()

Returns the relationship's name.

Specified by:

name in class EOProperty

Returns:

the relationship's name

numberOfToManyFaultsToBatchFetch

public int numberOfToManyFaultsToBatchFetch()

Returns the number of to-many faults that are triggered at one time.

Returns:

the number of to-many faults that are triggered at one time

ownsDestination

public boolean ownsDestination()

Returns true if the receiver's source object owns its destination objects, false otherwise.

Returns:

true if the receiver's source object owns its destination objects, false otherwise

See Also:

setOwnsDestination(boolean flag), destinationAttributes()

propagatesPrimaryKey

public boolean propagatesPrimaryKey()

Returns true if objects should propagate their primary key to related objects through this relationship. Objects only propagate their primary key values if the corresponding values in the destination object aren't already set.

Returns:

true if objects should propagate their primary key to related objects through this relationship

qualifierWithSourceRow

public EOQualifier qualifierWithSourceRow(NSDictionary sourceRow)

Returns a qualifier that can be used to fetch the destination of the receiving relationship given sourceRow.

Parameters:

sourceRow - row data (or "snapshot") for source object

Returns:

a qualifier that can be used to fetch the destination of the receiving relationship

referencesProperty

public boolean referencesProperty(Object property)

Returns true if property is in the relationship's data path or is an attribute belonging to one of the relationship's joins; otherwise, it returns false.

Parameters:

property - specifies property of the relationship

Returns:

true if property is in the relationship's data path or is an attribute belonging to one of the relationship's joins; otherwise, it returns false.

See Also:

EOEntity.referencesProperty(Object aProperty)

relationshipPath

public String relationshipPath()

Returns the full relationship path for a flattened relationship. For a non-flattened relationship, the result is the same as name.

Specified by:

relationshipPath in class EOProperty

Returns:

the relationship path

See Also:

EOAttribute, EOAttribute.relationshipPath(), EORelationship, relationshipPath()

removeJoin

public void removeJoin(EOJoin join)

Deletes join from the relationship. Does nothing if the relationship is flattened.

Parameters:

join - joins used by relationship.

Returns:

addJoin(EOJoin aJoin)

setDefinition

public void setDefinition(String definition)

Changes the relationship to a flattened relationship by releasing any joins and attributes (both source and destination) associated with the relationship and setting definition as its data path. For example, a relationship have the definitions "department.facility". If the relationship's entity hasn't been set, this method won't work correctly.

Parameters:

definition - a key path String

See Also:

addJoin(EOJoin aJoin), setEntity(EOEntity anEntity)

setDeleteRule

public void setDeleteRule(int deleteRule)

Set a rule describing the action to take when object is being deleted. deleteRule can be one of the following (defined in the control layer's EOClassDescription):

• EOClassDescription.DeleteRuleNullify
• EOClassDescription.DeleteRuleCascade
• EOClassDescription.DeleteRuleDeny
• EOClassDescription.DeleteRuleNoAction

Parameters:

deleteRule - specifies rule describing the action to take when object is being deleted

setEntity

public void setEntity(EOEntity entity)

Sets the entity of the relationship to entity. If the relationship is currently owned by a different entity, this method will remove the relationship from that entity. This method doesn't add the relationship to the new entity. EOEntity's addRelationship method invokes this method. You only need to use this method when creating a flattened relationship; use EOEntity's addRelationship to associate an existing relationship with an entity.

Parameters:

entity - specifies entity

See Also:

EOEntity.addRelationship(EORelationship aRelationship), setDefinition(String definition)

setIsMandatory

public void setIsMandatory(boolean isMandatory)

Specifies according to isMandatory whether the target of the relationship must be supplied or can be null.

Parameters:

isMandatory - specifies flag

setJoinSemantic

public void setJoinSemantic(int semantic)

Sets the semantic used to create SQL expressions for this relationship. joinSemantic should be one of the following:

• InnerJoin
• FullOuterJoin
• LeftOuterJoin
• RightOuterJoin

Parameters:

semantic - specifies semantic used to create SQL expressions

See Also:

InnerJoin, FullOuterJoin, LeftOuterJoin, RightOuterJoin, addJoin(EOJoin aJoin), joinSemantic()

setName

public void setName(String name)

Sets the relationship's name to name. Throws a verification exception if name is not a valid relationship name, and an invalid argument exception if name is already in use by an attribute or another relationship in the same entity. This method forces all objects in the model to be loaded into memory.

Parameters:

name - specifies relationship's name

Throws:

exception - if name is not a valid relationship name

See Also:

beautifyName()

setNumberOfToManyFaultsToBatchFetch

public void setNumberOfToManyFaultsToBatchFetch(int size)

Sets the number of "toMany" faults that are fired at one time to size.

Parameters:

size - specifies number of faults

See Also:

isToMany(), numberOfToManyFaultsToBatchFetch()

setOwnsDestination

public void setOwnsDestination(boolean bool)

Sets according to bool whether a receiver's source object owns its destination objects. The default is false. When a source object owns its destination objects, it means that the destination objects can't exist independently. For example, in a personnel database, dependents can't exist without having an associated employee. Removing a dependent from an employee's dependents array would have the effect of also deleting the dependent from the database, unless you transferred the dependent to a different employee.

Parameters:

bool - specifies flag

See Also:

deleteRule(), setDeleteRule(int deleteRule), ownsDestination()

setPropagatesPrimaryKey

public void setPropagatesPrimaryKey(boolean bool)

Specifies according to bool whether objects should propagate their primary key to related objects through this relationship. For example, an Employee object might propagate its primary key to an EmployeePhoto object. Objects only propagate their primary key values if the corresponding values in the destination object aren't already set.

Parameters:

bool - specifies flag

setToMany

public void setToMany(boolean bool)

Sets a simple relationship as to-many according to bool. Throws an exception if the receiver is flattened.

Parameters:

bool - specifies flag

Throws:

exception - if the receiver is flattened

See Also:

isFlattened()

setUserInfo

public void setUserInfo(NSDictionary dictionary)

Sets the dictionary of auxiliary data, which the application can use for whatever it needs. dictionary can only contain property list data types (that is, NSDictionary, String, NSArray, and NSData).

Parameters:

dictionary - specifies dictionary of auxiliary data

sourceAttributes

public NSArray sourceAttributes()

Returns the source attributes of a simple (non-flattened) relationship. These correspond one-to-one with the attributes returned by destinationAttributes. Returns null if the relationship is flattened.

Returns:

the source attributes of a simple (non-flattened) relationship

See Also:

destinationAttributes(), joins(), EOJoin.sourceAttribute()

toString

public String toString()

userInfo

public NSDictionary userInfo()

Returns a dictionary of user data. An application can use this data for whatever it needs.

Returns:

an NSDictionary of user data

validateValue

public Object validateValue(Object valueP)
                     throws NSValidation.ValidationException

For relationships marked as mandatory, throws a ValidationException if the receiver is to-one and valueP is null, or if the receiver is to-many and valueP has a count of 0. A mandatory relationship is one in which the target of the relationship is required. Returns the validated value (usually valueP).

Parameters:

valueP - specifies value

Returns:

the validated value

Throws:

NSValidation.ValidationException - if the receiver is to-one and valueP is null or if the receiver is to-many an valueP has a count of 0.

See Also:

isMandatory(), setIsMandatory(boolean flag)

valueForSQLExpression

public String valueForSQLExpression(EOSQLExpression context)

Returns the value to use in SQL expressions.

Specified by:

valueForSQLExpression in interface EOSQLExpression.SQLValue

Parameters:

context - SQL expression context

Returns:

value for SQL expression

See Also:

EOSQLExpression.SQLValue