WebObjects 5.2

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.

InnerJoin

public static final int InnerJoin
Produces results only for destinations of the join relationship that have non-null 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.

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.
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):

ValueDescription
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
Following copied from interface: com.webobjects.eoaccess.EOPropertyListEncoding
Parameters:
dic - 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.
Overrides:
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.
Overrides:
relationshipPath in class EOProperty
Returns:
the relationship path

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):
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:
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()
Overrides:
toString in class Object

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

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.