PATH
Documentation > WebObjects 4.5 >
EOControl Reference
(informal protocol)
Declared in: - EOControl/EOClassDescription.h
- EOControl/EOEditingContext.h
- EOControl/EOKeyValueCoding.h
- EOControl/EOObserver.h
Protocol Description
The EOEnterpriseObject informal protocol identifies basic
enterprise object behavior, defining methods for supporting operations
common to all enterprise objects. Among these are methods for initializing instances,
announcing changes, setting and retrieving property values, and
performing validation of state. Some of these methods are for enterprise
objects to implement or override, and some are meant to be used
as defined by the Framework. Many methods are used internally by
the Framework and rarely invoked by application code.
Many of the functional areas are defined in smaller, more
specialized informal protocols and incorporated in the over arching
EOEnterpriseObject informal protocol:
- EOKeyValueCoding defines
Enterprise Objects Framework's main data transport mechanism,
in which the properties of an object are accessed indirectly by
name (or "key"), rather than directly through invocation of
an accessor method or as instance variables.
- EOKeyBindingCreation defines a mechanism for binding class/key
pairs with a method for accessing the key, which maximizes the performance
of EOKeyValueCoding.
- EOKeyValueCodingAdditions defines
extensions to the basic EOKeyValueCoding informal protocol, giving
access to groups of properties and to properties across relationships.
- EORelationshipManipulation builds
on the basic EOKeyValueCoding informal protocol to allow you to
modify to-many relationship properties.
- EOValidation defines
the way that enterprise objects validate their values.
The remaining methods are introduced in the EOEnterpriseObject informal
protocol itself and can be broken down into three functional groups
discussed in the following sections:
You rarely need to implement the EOEnterpriseObject informal
protocol from scratch. The Framework provides default implementations
of the methods in categories on NSObject. Use EOGenericRecords to represent
enterprise objects that don't require custom behavior, and create
subclasses of NSObject to represent enterprise objects that do.
The section "Writing an Enterprise Object Class" highlights
the methods that you typically provide or override in a custom enterprise
object class.
Adopted Protocols
EOKeyValueCoding
- + accessInstanceVariablesDirectly
- + flushAllKeyBindings
- + useStoredAccessor
- - handleQueryWithUnboundKey:
- - handleTakeValue:forUnboundKey:
- - storedValueForKey:
- - takeStoredValue:forKey:
- - takeValue:forKey:
- - unableToSetNullForKey:
- - valueForKey:
EOKeyValueCodingAdditions
- - takeValue:forKeyPath:
- - takeValuesFromDictionary:
- - valueForKeyPath:
- - valuesForKeys:
EORelationshipManipulation
- - addObject:toBothSidesOfRelationshipWithKey:
- - addObject:toPropertyWithKey:
- - removeObject:fromBothSidesOfRelationshipWithKey:
- - removeObject:fromPropertyWithKey:
EOValidation
- - validateForDelete
- - validateForInsert
- - validateForSave
- - validateForUpdate
- - validateValue:forKey:
Method Types
- Initializing enterprise
objects
- - initWithEditingContext:classDescription:globalID:
- - awakeFromFetchInEditingContext:
- - awakeFromInsertionInEditingContext:
- Announcing changes
- - willChange
- Getting an object's
EOEditingContext
- - editingContext
- Getting class description
information
- - allPropertyKeys
- - attributeKeys
- - classDescription
- - classDescriptionForDestinationKey:
- - deleteRuleForRelationshipKey:
- - entityName
- - inverseForRelationshipKey:
- - isToManyKey:
- - ownsDestinationObjectsForRelationshipKey:
- - toManyRelationshipKeys
- - toOneRelationshipKeys
- Modifying relationships
- - propagateDeleteWithEditingContext:
- - clearProperties
- Working with snapshots
- - snapshot
- - updateFromSnapshot:
- Merging values
- - changesFromSnapshot
- - reapplyChangesFromDictionary:
- Getting descriptions
- - eoDescription
- - eoShallowDescription
- - userPresentableDescription
Instance Methods
- (NSArray *)allPropertyKeys
Returns all of the receiver's property keys. NSObject's
implementation returns the union of the keys returned by attributeKeys, toOneRelationshipKeys,
and toManyRelationshipKeys.
- (NSArray *)attributeKeys
Returns the names of the receiver's attributes
(not relationship properties). NSObject's implementation simply
invokes attributeKeys in the object's EOClassDescription
and returns the results. You might wish to override this method
to add keys for attributes not defined by the EOClassDescription.
The access layer's subclass of EOClassDescription, EOEntityClassDescription,
returns the names of attributes designated as class properties.
See Also:
- toOneRelationshipKeys, - toManyRelationshipKeys
- (void)awakeFromFetchInEditingContext:(EOEditingContext
*)anEditingContext
Overridden by subclasses to perform additional
initialization on the receiver upon its being fetched from the external
repository into anEditingContext. NSObject's
implementation merely sends an awakeObject:fromFetchInEditingContext: to
the receiver's EOClassDescription. Subclasses should invoke super's
implementation before performing their own initialization.
- (void)awakeFromInsertionInEditingContext:(EOEditingContext
*)anEditingContext
Overridden by subclasses to perform additional
initialization on the receiver upon its being inserted into anEditingContext.
This is commonly used to assign default values or record the time
of insertion. NSObject's implementation merely sends an awakeObject:fromInsertionInEditingContext: to
the receiver's EOClassDescription. Subclasses should invoke super's
implementation before performing their own initialization.
- (NSDictionary *)changesFromSnapshot:(NSDictionary
*)snapshot
Returns a dictionary whose keys correspond
to the receiver's properties with uncommitted changes relative
to snapshot, and whose values are
the uncommitted values. In both snapshot and
the returned dictionary, where a key represents a to-many relationship,
the corresponding value is an NSArray containing two other NSArrays:
the first is an array of objects to be added to the relationship
property, and the second is an array of objects to be removed.
See Also:
- reapplyChangesFromDictionary:
- (EOClassDescription *)classDescription
Returns the EOClassDescription registered for
the receiver's class.NSObject's implementation invokes the EOClassDescription class method
a classDescriptionForClass:.
- (EOClassDescription *)classDescriptionForDestinationKey:(NSString
*)key
Returns the EOClassDescription for the destination
objects of the relationship identified by key. NSObject's
implementation sends a classDescriptionForDestinationKey: message
to the receiver's EOClassDescription.
- (void)clearProperties
Sets all of the receiver's to-one and to-many
relationships to nil. EOEditingContexts use this method to break
cyclic references among objects when they're deallocated. NSObject's
implementation should be sufficient for all purposes. If your enterprise
object maintains references to other objects and these references
are not to-one or to-many keys, then you should probably subclass
this method ensure unused objects can be deallocated.
- (EODeleteRule)deleteRuleForRelationshipKey:(NSString
*)relationshipKey
Returns a rule indicating how to handle the
destination of the receiver's relationship named by relationshipKey when
the receiver is deleted. The delete rule is one of:
For example, an Invoice object might return EODeleteRuleNullify
for
the relationship named "lineItems", since when an invoice is
deleted, its line items should be deleted as well. For more information
on the delete rules, see the method description for EOClassDescription's deleteRuleForRelationshipKey: in
the class specification for EOClassDescription.
NSObject's implementation of this method simply sends a deleteRuleForRelationshipKey: message
to the receiver's EOClassDescription.
See Also:
- propagateDeleteWithEditingContext:, - validateForDelete (EOValidation)
- (EOEditingContext *)editingContext
Returns the EOEditingContext that holds the
receiver.
- (NSString *)entityName
Returns the name of the receiver's entity,
or nil if it doesn't have one. NSObject's implementation simply
sends an entityName message to the receiver's
EOClassDescription.
- (NSString *)eoDescription
Returns a string that describes the receiver. NSObject's
implementation returns a full description of the receiver's property
values by extracting them using the key-value coding methods. An
object referenced through relationships is listed with the results
of an eoShallowDescription message
(to avoid infinite recursion through cyclical relationships).
This method is useful for debugging. You can implement a description method
that invokes this one, and the debugger's print-object command
(po on the command line) automatically
displays this description. You can also invoke this method directly
on the command line of the debugger.
See Also:
- userPresentableDescription
- (NSString *)eoShallowDescription
Similar to eoDescription, but doesn't descend
into relationships. eoDescription invokes
this method for relationship destinations to avoid infinite recursion
through cyclical relationships. NSObject's implementation simply
returns a string containing the receiver's class and entity names,
along with the memory address of its id
.
See Also:
- userPresentableDescription
- initWithEditingContext:(EOEditingContext
*)anEditingContext classDescription:(EOClassDescription
*)aClassDescription
globalID:(EOGlobalID *)globalID
Initializes the receiver with the arguments
provided. NSObject's implementation simply invokes init, and
ignores anEditingContext.
See Also:
- createInstanceWithEditingContext:globalID:zone: (EOClassDescription)
- (NSString *)inverseForRelationshipKey:(NSString
*)relationshipKey
Returns the name of the relationship pointing
back to the receiver's class or entity from that named by relationshipKey,
or nil if there isn't one. With the access layer's EOEntity
and EORelationship, for example, reciprocality is determined by
the join attributes of the two EORelationships. NSObject's implementation
simply sends an inverseForRelationshipKey: message
to the receiver's EOClassDescription.
You might override this method for reciprocal relationships
that aren't defined using the same join attributes. For example,
if a Member object has a relationship to CreditCard based on the
card number, but a CreditCard has a relationship to Member based
on the Member's primary key, both classes need to override this
method. This is how Member might implement it:
- (NSString *)inverseForRelationshipKey:(NSString *)relationshipKey
{
if ([relationshipKey isEqual:@"creditCard"]) return @"member";
return [super inverseForRelationshipKey:relationshipKey];
}
- (BOOL)isToManyKey:(NSString
*)key
Returns YES if the receiver has a to-many relationship
identified by key, NO otherwise. NSObject's implementation
of this method simply checks its toManyRelationshipKeys array for key.
- (BOOL)ownsDestinationObjectsForRelationshipKey:(NSString
*)key
Returns YES if the receiver has a relationship
identified by key that owns its destination, NO otherwise.
If an object owns the destination for a relationship, then when
that destination object is removed from the relationship, it's
automatically deleted. Ownership of a relationship thus contrasts
with a delete rule, in that the first applies when the destination
is removed and the second applies when the source is deleted. NSObject's
implementation of this method simply sends an ownsDestinationObjectsForRelationshipKey: message
to the receiver's EOClassDescription.
See Also:
- deleteRuleForRelationshipKey:, - ownsDestination (EOAccess'
EORelationship)
- (void)propagateDeleteWithEditingContext:(EOEditingContext
*)anEditingContext
Deletes the destination objects of the receiver's
relationships according to the delete rule for each relationship. NSObject's
implementation simply sends a propagateDeleteForObject:editingContext: message
to the receiver's EOClassDescription. For more information on
delete rules, see the method description for deleteRuleForRelationshipKey: in
the EOClassDescription class specification.
See Also:
- deleteRuleForRelationshipKey:
- (void)reapplyChangesFromDictionary:(NSDictionary
*)changes
Similar to takeValuesFromDictionary:, but the changes dictionary
can contain arrays for to-many relationships. Where a key represents
a to-many relationship, the dictionary's value is an NSArray containing
two other NSArrays: the first is an array of objects to be added
to the relationship property, and the second is an array of objects
to be removed. NSObject's implementation should be sufficient
for all purposes; you shouldn't have to override this method.
See Also:
- changesFromSnapshot
- (NSDictionary *)snapshot
Returns a dictionary whose keys are those of
the receiver's attributes, to-one relationships, and to-many relationships,
and whose values are the values of those properties, with EONull substituted
for nil. For to-many relationships, the dictionary contains shallow
copies of the arrays to preserve the ids of the contents. NSObject's
implementation should be sufficient for all purposes; you shouldn't
have to override this method.
See Also:
- updateFromSnapshot:
- (NSArray *)toManyRelationshipKeys
Returns the names of the receiver's to-many
relationships. NSObject's implementation simply invokes toManyRelationshipKeys in
the object's EOClassDescription and returns the results. You might
wish to override this method to add keys for relationships not defined
by the EOClassDescription, but it's rarely necessary: The access
layer's subclass of EOClassDescription, EOEntityClassDescription,
returns the names of to-many relationships designated as class properties.
See Also:
- attributeKeys, - toOneRelationshipKeys
- (NSArray *)toOneRelationshipKeys
Returns the names of the receiver's to-one
relationships. NSObject's implementation simply invokes toOneRelationshipKeys in
the object's EOClassDescription and returns the results. You might
wish to override this method to add keys for relationships not defined
by the EOClassDescription, but it's rarely necessary: The access
layer's subclass of EOClassDescription, EOEntityClassDescription,
returns the names of to-one relationships designated as class properties.
See Also:
- attributeKeys, - toManyRelationshipKeys
- (void)updateFromSnapshot:(NSDictionary
*)aSnapshot
Takes the values from aSnapshot,
and sets the receiver's properties to them. NSObject's implementation sets
each one using takeStoredValue:forKey:. In the process, EONull
values are converted to nil, and array values are set as shallow
mutable copies to preserve the ids of the contents.
See Also:
- snapshot
- (NSString *)userPresentableDescription
Returns a short (no longer than 60 characters)
description of an enterprise object based on its data. NSObject's
implementation enumerates the object's attributeKeys and returns the values
of all of its properties, separated by commas (applying the default
formatter for numbers and dates).
See Also:
- eoDescription, - eoShallowDescription
- (void)willChange
Notifies any observers that the receiver's
state is about to change, by sending each an objectWillChange: message
(see the EOObserverCenter class specification
for more information). A subclass should not override this method,
but should invoke it prior to altering the subclass's state, most
typically in "set" methods such as the following:
- (void)setRoleName:(NSString *)value {
[self willChange];
[roleName autorelease];
roleName = [value retain];
}