com.webobjects.eocontrol
Class EOCustomObject

java.lang.Object
  |
  +--com.webobjects.eocontrol.EOCustomObject

All Implemented Interfaces:

EODeferredFaulting, EOEnterpriseObject, EOFaulting, EOKeyValueCoding, EOKeyValueCodingAdditions, EORelationshipManipulation, EOValidation, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions, NSValidation, Serializable

Direct Known Subclasses:

EOGenericRecord

public abstract class EOCustomObject

extends Object

implements EOEnterpriseObject, EODeferredFaulting

The EOCustomObject class provides a default implementation of the EOEnterpriseObject interface. If a custom Enterprise Object class needs to be created, you can subclass EOCustomObject and inherit the framework's default implementations. Some of the methods are for subclasses to implement or override, but most are meant to be used as defined by EOCustomObject.

EOCustomObject's constructors are not meant to be invoked; an instance of EOCustomObject would never be created. EOCustomObject provides them to demonstrate the constructors that custom enterprise objects should implement.

See Also:

EOEnterpriseObject, Serialized Form

Inner classes inherited from class com.webobjects.eocontrol.EOKeyValueCodingAdditions

EOKeyValueCodingAdditions.DefaultImplementation, EOKeyValueCodingAdditions.Utility

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Inner classes inherited from class com.webobjects.eocontrol.EOKeyValueCoding

EOKeyValueCoding.DefaultImplementation, EOKeyValueCoding.Utility

Inner classes inherited from class com.webobjects.foundation.NSValidation

NSValidation.DefaultImplementation, NSValidation.Utility, NSValidation.ValidationException

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Constructor Summary

EOCustomObject()
Default constructor.

EOCustomObject(EOEditingContext editingContext, EOClassDescription classDescription, EOGlobalID gid)
Deprecated. the default or 0 argument constructor should be used instead

Method Summary

void	addObjectToBothSidesOfRelationshipWithKey(EORelationshipManipulation object, String key) Sets or adds object as the destination for the receiver's relationship identified by key, and also sets or adds the receiver for object's reciprocal relationship if there is one.
void	addObjectToPropertyWithKey(Object eo, String key) Adds to the relationship named key the object eo without setting inverse relationships.
NSArray	allPropertyKeys() 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).
void	awakeFromClientUpdate(EOEditingContext ec) Invoked on a server-side enterprise object after it has been updated with changes from a client application.
void	awakeFromFetch(EOEditingContext ec) Overridden by subclasses to perform additional initialization on the receiver upon its being fetched from the external repository into ec.
void	awakeFromInsertion(EOEditingContext ec) Overridden by subclasses to perform additional initialization on the receiver upon its being inserted into ec.
static boolean	canAccessFieldsDirectly() Returns true.
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.
EOClassDescription	classDescription() Returns the EOClassDescription registered for the receiver's class by invoking the EOClassDescription static method classDescriptionForClass.
EOClassDescription	classDescriptionForDestinationKey(String detailKey) Returns the EOClassDescription for the destination objects of the relationship identified by detailKey.
void	clearFault() Sets the faultHandler to null.
void	clearProperties() Sets all of the receiver's to-one and to-many relationships to null.
int	deleteRuleForRelationshipKey(String relationshipKey) Returns a rule indicating how to handle the destination of the receiver's relationship named by relationshipKey when the receiver is deleted.
EOEditingContext	editingContext() Returns the editing context that contains the receiver or null if none is set.
String	entityName() Returns the name of the receiver's entity, or null if it doesn't have one by sending an entityName message to the receiver's EOClassDescription.
String	eoDescription() Returns a full description of the receiver's property values by extracting them using the key-value coding methods.
String	eoShallowDescription() Similar to eoDescription, but doesn't descend into relationships.
boolean	equals(Object other) EOF requires all EOs define equality as (this == other) To compare EOs in different EOEditingContexts, consider instead comparing their EOGlobalIDs with equals()
protected void	excludeObjectFromPropertyWithKey(Object eo, String key) Removes the object eo from the to-many relationship named key without affecting inverse relationships, by directly modifying the property storing the to-many relationship.
EOFaultHandler	faultHandler() Returns the receiver's fault handler.
Object	handleQueryWithUnboundKey(String key) Invoked from valueForKey when it finds no property binding for key.
void	handleTakeValueForUnboundKey(Object value, String key) Invoked from takeValueForKey when it finds no property binding for key.
int	hashCode() This method must adhere to the contract specified in java.lang.Object.hashCode
protected void	includeObjectIntoPropertyWithKey(Object eo, String key) Adds to the relationship named key the object eo without affecting inverse relationships, by directly modifying the property storing the to-many relationship.
String	inverseForRelationshipKey(String relationshipKey) Returns the name of the relationship pointing back to the receiver's class or entity from that named by relationshipKey, or null if there isn't one.
Object	invokeRemoteMethod(String methodName, Class[] argumentTypes, Object[] arguments) Invokes a method on the server-side equivalent of the enterprise object.
boolean	isFault() Returns true if the object's values haven't yet been fetched from the database.
boolean	isToManyKey(String key) Returns true if the receiver has a to-many relationship identified by key, false otherwise.
Object	opaqueState() This methods returns an opaque object which encapsulates state private to EOF.
boolean	ownsDestinationObjectsForRelationshipKey(String relationshipKey) Returns true if the receiver has a relationship identified by key that owns its destination, and false otherwise.
void	prepareValuesForClient() Invoked on a server-side enterprise object before the values of it are distributed to a client application.
void	propagateDeleteWithEditingContext(EOEditingContext ec) Deletes the destination objects of the receiver's relationships according to the delete rule for each relationship.
protected Object	readResolve()
void	reapplyChangesFromDictionary(NSDictionary changes) Similar to takeValuesFromDictionary, but the changes dictionary can contain arrays for to-many relationships.
void	removeObjectFromBothSidesOfRelationshipWithKey(EORelationshipManipulation object, String key) Removes object from the receiver's relationship identified by key, and also removes the receiver from objects's reciprocal relationship if there is one.
void	removeObjectFromPropertyWithKey(Object eo, String key) Removes the object eo from the to-many relationship named key without affecting inverse relationships.
static boolean	shouldUseStoredAccessors() Returns true.
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 EONullValue substituted for null.
Object	storedValueForKey(String key) Returns the value for the property identified by key.
void	takeStoredValueForKey(Object value, String key) Sets the property identified by key to value.
void	takeValueForKey(Object value, String key) Sets the receiver's value for the property identified by key to value.
void	takeValueForKeyPath(Object value, String keyPath) Sets the receiver's property identified by keyPath to value.
void	takeValuesFromDictionary(NSDictionary dictionary) Sets properties of the receiver with values from dictionary, using its keys to identify the properties.
void	takeValuesFromDictionaryWithMapping(NSDictionary dictionary, NSDictionary mapping) Sets properties of the receiver with values from dictionary, using its keys and mapping to identify the properties.
NSArray	toManyRelationshipKeys() Returns the names of the receiver's to-many relationships.
NSArray	toOneRelationshipKeys() Returns the names of the receiver's to-one relationships.
String	toString() String representation of the object.
void	turnIntoFault(EOFaultHandler handler) Converts the receiver into a fault, assigning handler as the object that stores its original state and later converts the fault back into a normal object (typically by fetching data from an external repository).
void	unableToSetNullForKey(String key) Invoked from takeValueForKey when it's given a null value for a scalar property (such as an int or a float).
void	updateFromSnapshot(NSDictionary snapshot) Takes the values from snapshot, and sets the receiver's properties to them.
String	userPresentableDescription() Returns a short (no longer than 60 characters) description of an enterprise object based on its data by calling EOClassDescription's userPresentableDescriptionForObject method
static boolean	usesDeferredFaultCreation() Conformance to EODeferredFaulting.
void	validateClientUpdate() Validate whether object is in an consistent state after being updated from a client.
void	validateForDelete() Confirms that the receiver can be deleted in its current state, throwing an NSValidation.ValidationException if it can't.
void	validateForInsert() Confirms that the receiver can be inserted in its current state, throwing an NSValidation.ValidationException if it can't.
void	validateForSave() Confirms that the receiver can be saved in its current state, throwing an NSValidation.ValidationException if it can't.
void	validateForUpdate() Confirms that the receiver can be saved in its current state, throwing a NSValidation.ValidationException if it can't.
Object	validateTakeValueForKeyPath(Object value, String keyPath) Confirms that value is valid for the receiver's property named by keyPath, and assigns the value to the property (if value is different from the current value), or throws an NSValidation.ValidationException if value isn't valid.
Object	validateValueForKey(Object value, String key) Validates a property indirectly by name.
Object	valueForKey(String key) Returns the receiver's value for the property identified by key.
Object	valueForKeyPath(String keyPath) Returns the value for the derived property identified by keyPath.
NSDictionary	valuesForKeys(NSArray keys) Returns an NSDictionary containing the property values identified by each element in keys.
NSDictionary	valuesForKeysWithMapping(NSDictionary mapping) Returns an NSDictionary containing the property values identified by each of the key-value pairs in mapping.
void	willChange() Notifies any observers that the receiver's state is about to change, by sending each an objectWillChange message.
void	willRead() Fills the receiver with values fetched from the database.
Object	willReadRelationship(Object object) Enterprise object instances that use deferred faulting invoke this method before accessing a relationship to ensure that the relationship isn't a deferred fault.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EOCustomObject

public EOCustomObject(EOEditingContext editingContext,
                      EOClassDescription classDescription,
                      EOGlobalID gid)

Deprecated. the default or 0 argument constructor should be used instead

EOCustomObject

public EOCustomObject()

Default constructor.

Method Detail

addObjectToBothSidesOfRelationshipWithKey

public void addObjectToBothSidesOfRelationshipWithKey(EORelationshipManipulation object,
                                                      String key)

Sets or adds object as the destination for the receiver's relationship identified by key, and also sets or adds the receiver for object's reciprocal relationship if there is one. For a to-one relationship, object is set using takeValueForKey. For a to-many relationship, object is added using addObjectToPropertyWithKey. This method also properly handles removing this and object from their previous relationship as needed. For example, if an Employee object belongs to the Research department, invoking this method with the Maintenance department removes the Employee from the Research department as well as setting the Employee's department to Maintenance.

Specified by:

addObjectToBothSidesOfRelationshipWithKey in interface EORelationshipManipulation

Parameters:

object - instance to be added to the destination relationship

key - name of relationship

See Also:

(Object anObject, String key)

addObjectToPropertyWithKey

public void addObjectToPropertyWithKey(Object eo,
                                       String key)

Adds to the relationship named key the object eo without setting inverse relationships. Attempts to invoke a method of the form addToKey. If the receiver doesn't have such a method, this method gets the property array using valueForKey and operates directly on that (adds the object to the array).

Specified by:

addObjectToPropertyWithKey in interface EORelationshipManipulation

Parameters:

eo - the object to add to the relationship

key - the name of the relationship

allPropertyKeys

public NSArray allPropertyKeys()

Returns the union of the keys returned by attributeKeys, toOneRelationshipKeys, and toManyRelationshipKeys.

Specified by:

allPropertyKeys in interface EOEnterpriseObject

Returns:

all of the receiver's property keys

attributeKeys

public NSArray attributeKeys()

Returns the names of the receiver's attributes (not relationship properties). 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.

Specified by:

attributeKeys in interface EOEnterpriseObject

Returns:

an NSArray containing the names of the receiver's attributes

awakeFromClientUpdate

public void awakeFromClientUpdate(EOEditingContext ec)

Invoked on a server-side enterprise object after it has been updated with changes from a client application. This method is invoked when changes to an object graph are pushed or saved from the client to the server.

Specified by:

awakeFromClientUpdate in interface EOEnterpriseObject

Parameters:

ec - the EOEditingContext of the enterprise object.

awakeFromFetch

public void awakeFromFetch(EOEditingContext ec)

Overridden by subclasses to perform additional initialization on the receiver upon its being fetched from the external repository into ec. EOCustomObject's implementation merely sends an awakeObjectFromFetch to the receiver's EOClassDescription. Subclasses should invoke super's implementation before performing their own initialization.

Specified by:

awakeFromFetch in interface EOEnterpriseObject

Parameters:

ec - An EOEditingContext object.

awakeFromInsertion

public void awakeFromInsertion(EOEditingContext ec)

Overridden by subclasses to perform additional initialization on the receiver upon its being inserted into ec. This is commonly used to assign default values or record the time of insertion. EOCustomObject's implementation merely sends an awakeObjectFromInsertion to the receiver's EOClassDescription. Subclasses should invoke super's implementation before performing their own initialization.

Specified by:

awakeFromInsertion in interface EOEnterpriseObject

Parameters:

ec - An EOEditingContext object.

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

Returns true. Subclasses implement this method to return false if the key-value coding methods should never access the corresponding instance variable directly on finding no accessor method for a property.

Returns:

true

See Also:

valueForKey(String key), takeValueForKey(Object value, String key)

changesFromSnapshot

public 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 a 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.

Specified by:

changesFromSnapshot in interface EOEnterpriseObject

Parameters:

snapshot - An NSDictionary whose keys are those of the receiver's attributes.

Returns:

An NSDictionary of uncommitted changes relative to snapshot

classDescription

public EOClassDescription classDescription()

Returns the EOClassDescription registered for the receiver's class by invoking the EOClassDescription static method classDescriptionForClass.

Specified by:

classDescription in interface EOEnterpriseObject

Returns:

the EOClassDescription registered for the receiver's class

classDescriptionForDestinationKey

public EOClassDescription classDescriptionForDestinationKey(String detailKey)

Returns the EOClassDescription for the destination objects of the relationship identified by detailKey. EOCustomObject's implementation sends a classDescriptionForDestinationKey message to the receiver's EOClassDescription.

Specified by:

classDescriptionForDestinationKey in interface EOEnterpriseObject

Parameters:

detailKey - Identifies relationship of the destination objects.

Returns:

the EOClassDescription for the destination objects

clearFault

public void clearFault()

Sets the faultHandler to null. This method is rarely used directly. Rather, it's invoked by an EOFaultHandler during the process of firing the fault.

Specified by:

clearFault in interface EOFaulting

See Also:

EOFaultHandler

clearProperties

public void clearProperties()

Sets all of the receiver's to-one and to-many relationships to null. EOEditingContext's use this method to break cyclic references among objects when they're finalized. EOCustomObject's implementation should be sufficient for all purposes. If the 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 finalized.

Specified by:

clearProperties in interface EOEnterpriseObject

deleteRuleForRelationshipKey

public int deleteRuleForRelationshipKey(String 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:

• DeleteRuleNullify
• DeleteRuleCascade
• DeleteRuleDeny
• DeleteRuleNoAction

For example, an Invoice object might return DeleteRuleNullify for the relationship named "lineItems", since when an invoice is deleted, its line items should be deleted as well.

EOCustomObject's implementation of this method simply sends a deleteRuleForRelationshipKey message to the receiver's EOClassDescription.

Specified by:

deleteRuleForRelationshipKey in interface EOEnterpriseObject

Parameters:

relationshipKey - identifies the receiver's relationship.

Returns:

an int constant indicating how to handle the destination of the receiver's relationship when deleted

See Also:

EOClassDescription.deleteRuleForRelationshipKey(String relationshipKey)

editingContext

public EOEditingContext editingContext()

Returns the editing context that contains the receiver or null if none is set.

Specified by:

editingContext in interface EOEnterpriseObject

Returns:

the EOEditingContext that holds the receiver

entityName

public String entityName()

Returns the name of the receiver's entity, or null if it doesn't have one by sending an entityName message to the receiver's EOClassDescription.

Specified by:

entityName in interface EOEnterpriseObject

Returns:

the name of the receiver's entity

eoDescription

public String eoDescription()

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

Specified by:

eoDescription in interface EOEnterpriseObject

Returns:

a string that describes the receiver

See Also:

eoShallowDescription(), userPresentableDescription()

eoShallowDescription

public String eoShallowDescription()

Similar to eoDescription, but doesn't descend into relationships. eoDescription invokes this method for relationship destinations to avoid infinite recursion through cyclical relationships. EOCustomObject's implementation simply returns a String containing the receiver's class and entity names.

Specified by:

eoShallowDescription in interface EOEnterpriseObject

Returns:

a string containing the receiver's class and entity names.

equals

public final boolean equals(Object other)

EOF requires all EOs define equality as (this == other) To compare EOs in different EOEditingContexts, consider instead comparing their EOGlobalIDs with equals()

Overrides:

equals in class Object

Parameters:

other - input object against which this object is compared

Returns:

true if the objects are equal; false otherwise

See Also:

Object.equals(java.lang.Object), EOGlobalID.equals(java.lang.Object)

excludeObjectFromPropertyWithKey

protected void excludeObjectFromPropertyWithKey(Object eo,
                                                String key)

Removes the object eo from the to-many relationship named key without affecting inverse relationships, by directly modifying the property storing the to-many relationship. This method can be used from inside of methods of the form removeFromKey. The method throws an IllegalArgumentException when attempting to remove an object not contained in the relationship array.

Parameters:

eo - the object to remove from the relationship.

key - the name of the relationship

Throws:

IllegalArgumentException - if eo is not in relationship key

faultHandler

public EOFaultHandler faultHandler()

Returns the receiver's fault handler.

Specified by:

faultHandler in interface EOFaulting

Returns:

the receiver's EOFaultHandler if the receiver is a fault; else returns null.

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Invoked from valueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfokey) in the user info. An NSKeyValueCoding.ErrorHandling class can override this method to handle the query in some other way. The method can return a value, in which case that value is returned by the corresponding valueForKey invocation.

Specified by:

handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - the key that was not found

Returns:

a substitute value to return in the valueForKey invocation

See Also:

valueForKey(String key), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.UnknownKeyException.TargetObjectUserInfoKey, NSKeyValueCoding.UnknownKeyException.UnknownUserInfoKey

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Invoked from takeValueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfoKey) in the user info.

Specified by:

handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

value - the value that was attempted to be set for key

key - they key whose property binding wasn't found in takeValueForKey

See Also:

takeValueForKey(Object value, String key), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.UnknownKeyException.TargetObjectUserInfoKey, NSKeyValueCoding.UnknownKeyException.UnknownUserInfoKey

hashCode

public int hashCode()

This method must adhere to the contract specified in java.lang.Object.hashCode

Overrides:

hashCode in class Object

Returns:

an numeric hash code for this object

See Also:

Object.hashCode(), equals(java.lang.Object)

includeObjectIntoPropertyWithKey

protected void includeObjectIntoPropertyWithKey(Object eo,
                                                String key)

Adds to the relationship named key the object eo without affecting inverse relationships, by directly modifying the property storing the to-many relationship. This method can be used from inside of methods of the form addToKey.

Parameters:

eo - the object to add to the relationship

key - the name of the relationship

inverseForRelationshipKey

public String inverseForRelationshipKey(String relationshipKey)

Returns the name of the relationship pointing back to the receiver's class or entity from that named by relationshipKey, or null 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. EOCustomObject's implementation simply sends an inverseForRelationshipKey message to the receiver's EOClassDescription.

Specified by:

inverseForRelationshipKey in interface EOEnterpriseObject

Parameters:

relationshipKey - the String name of the relationship

Returns:

the String name of the inverse relationship, or null

invokeRemoteMethod

public Object invokeRemoteMethod(String methodName,
                                 Class[] argumentTypes,
                                 Object[] arguments)

Invokes a method on the server-side equivalent of the enterprise object. This method has the side effect that the changes from the receiver's editing context (on the client) are saved to the editing context in the server's session. Note also that none of the arguments nor the result of this invocation should be CustomObjects. If you want to pass reference to EOs, pass globalIDs. The return value of the method invocation must be cast into the expected class.

Specified by:

invokeRemoteMethod in interface EOEnterpriseObject

Parameters:

methodName - the name of the method to be invoked

argumentTypes - Array containing the types of arguments

arguments - Array containing the arguments.

Returns:

the return value of the remote method invocation.

isFault

public boolean isFault()

Returns true if the object's values haven't yet been fetched from the database.

Specified by:

isFault in interface EOFaulting

Returns:

true if the receiver is a fault, false otherwise.

isToManyKey

public boolean isToManyKey(String key)

Returns true if the receiver has a to-many relationship identified by key, false otherwise. EOCustomObject's implementation of this method simply checks its toManyRelationshipKeys array for key.

Specified by:

isToManyKey in interface EOEnterpriseObject

Parameters:

key - Identifies the to-many relationship of the receiver.

Returns:

true if the receiver has a to-many relationship identified by key, false otherwise

opaqueState

public final Object opaqueState()

Description copied from interface: EOEnterpriseObject

This methods returns an opaque object which encapsulates state private to EOF. Developers should not use or interfere with that object.

Specified by:

opaqueState in interface EOEnterpriseObject

Following copied from interface: com.webobjects.eocontrol.EOEnterpriseObject

Returns:

a private state object

ownsDestinationObjectsForRelationshipKey

public boolean ownsDestinationObjectsForRelationshipKey(String relationshipKey)

Returns true if the receiver has a relationship identified by key that owns its destination, and false 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. EOCustomObject's implementation of this method simply sends an ownsDestinationObjectsForRelationshipKey message to the receiver's EOClassDescription.

Specified by:

ownsDestinationObjectsForRelationshipKey in interface EOEnterpriseObject

Parameters:

relationshipKey - Identifies the relationship of the receiver.

Returns:

true if the receiver has a relationship identified by key that owns its destination, false otherwise

prepareValuesForClient

public void prepareValuesForClient()

Invoked on a server-side enterprise object before the values of it are distributed to a client application. You can override this method to compute client side only properties before the object is encoded.

Specified by:

prepareValuesForClient in interface EOEnterpriseObject

propagateDeleteWithEditingContext

public void propagateDeleteWithEditingContext(EOEditingContext ec)

Deletes the destination objects of the receiver's relationships according to the delete rule for each relationship. EOCustomObject's implementation simply sends a propagateDeleteForObject message to the receiver's EOClassDescription.

Specified by:

propagateDeleteWithEditingContext in interface EOEnterpriseObject

Parameters:

ec - the EOEditingContext containing the objects

See Also:

EOClassDescription.deleteRuleForRelationshipKey(String relationshipKey)

readResolve

protected Object readResolve()
                      throws ObjectStreamException

reapplyChangesFromDictionary

public void reapplyChangesFromDictionary(NSDictionary changes)

Similar to takeValuesFromDictionary, but the changes dictionary can contain arrays for to-many relationships. 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. EOCustomObject's implementation should be sufficient for all purposes; you shouldn't have to override this method.

Specified by:

reapplyChangesFromDictionary in interface EOEnterpriseObject

Parameters:

changes - an NSDictionary that contain arrays for to-many relationships

removeObjectFromBothSidesOfRelationshipWithKey

public void removeObjectFromBothSidesOfRelationshipWithKey(EORelationshipManipulation object,
                                                           String key)

Removes object from the receiver's relationship identified by key, and also removes the receiver from objects's reciprocal relationship if there is one. For a to-one relationship, object is removed using takeValueForKey with null as the value. For a to-many relationship, object is removed using removeObjectFromPropertyWithKey.

Specified by:

removeObjectFromBothSidesOfRelationshipWithKey in interface EORelationshipManipulation

Parameters:

object - object to be removed from the receiver's relationship

key - name of the relationship.

See Also:

(Object anObject, String key)

removeObjectFromPropertyWithKey

public void removeObjectFromPropertyWithKey(Object eo,
                                            String key)

Removes the object eo from the to-many relationship named key without affecting inverse relationships. Attempts to invoke a method of the form removeFromKey. If the receiver doesn't have such a method, this method gets the property array using valueForKey and removes the object if present. The method throws an IllegalArgumentException when attempting to remove an object not contained in the relationship array.

Specified by:

removeObjectFromPropertyWithKey in interface EORelationshipManipulation

Parameters:

eo - the object to remove from the relationship.

key - the name of the relationship

Throws:

IllegalArgumentException - if eo is not in relationship key

shouldUseStoredAccessors

public static boolean shouldUseStoredAccessors()

Returns true. Subclasses implement this method to return false if the stored value methods (storedValueForKey and takeStoredValueForKey) should not use private accessor methods in preference to public accessors. Returning false causes the stored value methods to use the same accessor method instance variable search order as the corresponding basic key-value coding methods (valueForKey and takeValueForKey). This method doesn't have to be implemented if the default stored value search order is correct for the objects.

Returns:

true

snapshot

public 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 EONullValue substituted for null. For to-many relationships, the dictionary contains shallow copies of the arrays. EOCustomObject's implementation should be sufficient for all purposes; you shouldn't have to override this method.

Specified by:

snapshot in interface EOEnterpriseObject

Returns:

a NSDictionary whose keys are those of the receiver's attributes

storedValueForKey

public Object storedValueForKey(String key)

Returns the value for the property identified by key. This method is used when the value is retrieved for storage in an object store (generally, this is ultimately in a database) or for inclusion in a snapshot. The default implementation provided by EOCustomObject is similar to the implementation of valueForKey, but it resolves key with a different method instance variable search order:

• Searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", storedValueForKey looks for a method named _getLastName or _lastName.
• If a private accessor isn't found, searches for an instance variable based on key and returns its value directly. For example, with a key of "lastName", storedValueForKey looks for an instance variable named _lastName or lastName.
• If neither a private accessor or an instance variable is found, storedValueForKey searches for a public accessor method based on key. For the key "lastName", this would be getLastName or lastName.
• If key is unknown, storedValueForKey calls handleTakeValueForUnboundKey.

Specified by:

storedValueForKey in interface EOKeyValueCoding

Parameters:

key - a property of receiver.

Returns:

the value of property identified by key

takeStoredValueForKey

public void takeStoredValueForKey(Object value,
                                  String key)

Sets the property identified by key to value. This method is used to initialize the receiver with values from an object store (generally, this is ultimately from a database) or to restore a value from a snapshot. The default implementation provided by EOCustomObject is similar to the implementation of takeValueForKey, but it resolves key with a different method instance variable search order:

• Searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", takeStoredValueForKey looks for a method named _setLastName.
• If a private accessor isn't found, searches for an instance variable based on key and sets its value directly. For example, with a key of "lastName", takeStoredValueForKey looks for an instance variable named _lastName or lastName.
• If neither a private accessor or an instance variable is found, takeStoredValueForKey searches for a public accessor method based on key. For the key "lastName", this would be setLastName.
• If key is unknown, takeStoredValueForKey calls handleTakeValueForUnboundKey.

This different search order allows an object to bypass processing that is performed before setting a value through public API. However, if it is always wanted to use the search order in takeValueForKey, you can implement the static method shouldUseStoredAccessors to return false. And as with valueForKey, you can prevent direct access of an instance variable with the static method canAccessFieldsDirectly.

Specified by:

takeStoredValueForKey in interface EOKeyValueCoding

Parameters:

value - the property identified by key is set to this.

key - a property of receiver.

See Also:

shouldUseStoredAccessors(), canAccessFieldsDirectly()

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Sets the receiver's value for the property identified by key to value.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

• Searches for a public accessor method of the form setKey, and invokes it if there is one.
• If a public accessor method isn't found, searches for a private accessor method of the form _setKey, and invokes it if there is one.
• If an accessor method isn't found and the static method canAccessFieldsDirectly returns true, searches for an instance variable based on key and sets its value directly. For the key "lastName", this would be _lastName or lastName.
• If neither an accessor method nor an instance variable is found, it's an error condition. It invokes handleTakeValueForUnboundKey if the object implements NSKeyValueCoding.ErrorHandling or throws NSKeyValueCoding.UnknownKeyException if the object doesn't.

Note: The default implementation of NSKeyValueCoding provided by the Foundation package should always be used. The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding.DefaultImplementation; or if the class inherits from an WebObjects class that implements NSKeyValueCoding, the inherited implementation is not to be overridden. Using a custom implementation incurs significant performance penalties.

Specified by:

takeValueForKey in interface NSKeyValueCoding

Parameters:

value - The receiver's value for the property key is set to this.

key - Identifies the property of the receiver.

Throws:

NSKeyValueCoding.UnknownKeyException - if the object doesn't implements NSKeyValueCoding.ErrorHandling.

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Sets the receiver's property identified by keyPath to value. A key path as the form relationship.property (with one or more relationships).

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

value - the receiver's property identified by keyPath is set to this

keyPath - a property of an object

takeValuesFromDictionary

public void takeValuesFromDictionary(NSDictionary dictionary)

Sets properties of the receiver with values from dictionary, using its keys to identify the properties. EOCustomObject's implementation invokes takeValueForKey for each key-value pair, substituting null for EONullValues in aDictionary.

Specified by:

takeValuesFromDictionary in interface EOKeyValueCodingAdditions

Parameters:

dictionary - values from this are taken to set properties of the receiver

See Also:

takeValueForKey(Object value, String key)

takeValuesFromDictionaryWithMapping

public void takeValuesFromDictionaryWithMapping(NSDictionary dictionary,
                                                NSDictionary mapping)

Sets properties of the receiver with values from dictionary, using its keys and mapping to identify the properties. mapping associates the keys of dictionary, which are arbitrary external names for the properties to be set, with the internal or EOModel names for those properties. If a key in dictionary does not have a corresponding entry in mapping, the external key (i.e., the key from dictionary) is used.

Invokes takeValueForKey for each key-value pair of dictionary, substituting null for NSKeyValueCoding.NullValue values in the dictionary.

Specified by:

takeValuesFromDictionaryWithMapping in interface EOKeyValueCodingAdditions

Parameters:

dictionary - the key-value pairs to be set

mapping - the dictionary that maps arbitrary external names to internal property names

See Also:

takeValueForKey(Object value, String key)

toManyRelationshipKeys

public NSArray toManyRelationshipKeys()

Returns the names of the receiver's to-many relationships. 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.

Specified by:

toManyRelationshipKeys in interface EOEnterpriseObject

Returns:

an NSArray with the names of the receiver's to-many relationships

See Also:

toOneRelationshipKeys(), attributeKeys()

toOneRelationshipKeys

public NSArray toOneRelationshipKeys()

Returns the names of the receiver's to-one relationships. 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.

Specified by:

toOneRelationshipKeys in interface EOEnterpriseObject

Returns:

an NSArray with the names of the receiver's to-one relationships

See Also:

attributeKeys(), toOneRelationshipKeys()

toString

public String toString()

String representation of the object. This method simply calls eoDescription.

Overrides:

toString in class Object

Returns:

the String result of calling eoDescription

turnIntoFault

public void turnIntoFault(EOFaultHandler handler)

Converts the receiver into a fault, assigning handler as the object that stores its original state and later converts the fault back into a normal object (typically by fetching data from an external repository). The receiver becomes the owner of handler; it shouldn't be assigned to another object.

Specified by:

turnIntoFault in interface EOFaulting

Parameters:

handler - an EOFaultHandler that stores receiver's original state and later converts the fault back into a normal object

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Invoked from takeValueForKey when it's given a null value for a scalar property (such as an int or a float). The default implementation throws an IllegalArgumentException. You might want to implement the method (or override the inherited implementation) to handle the request in some other way, such as by substituting zero or a sentinel value and invoking takeValueForKey again.

Specified by:

unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - a property of the receiver.

Throws:

IllegalArgumentException - when it's given a null value for a scalar property.

See Also:

NSKeyValueCoding.DefaultImplementation

updateFromSnapshot

public void updateFromSnapshot(NSDictionary snapshot)

Takes the values from snapshot, and sets the receiver's properties to them. EOCustomObject's implementation sets each one using takeStoredValueForKey. In the process, EONullValues are converted to null, and array values are set as shallow mutable copies.

Specified by:

updateFromSnapshot in interface EOEnterpriseObject

Parameters:

snapshot - the receiver's properties are set to the values taken from this

See Also:

EOEnterpriseObject.snapshot()

userPresentableDescription

public String userPresentableDescription()

Returns a short (no longer than 60 characters) description of an enterprise object based on its data by calling EOClassDescription's userPresentableDescriptionForObject method

Specified by:

userPresentableDescription in interface EOEnterpriseObject

Returns:

a short description of an enterprise object

usesDeferredFaultCreation

public static boolean usesDeferredFaultCreation()

Conformance to EODeferredFaulting. EOCustomObject returns false by default.

Returns:

false

validateClientUpdate

public void validateClientUpdate()
                          throws NSValidation.ValidationException

Validate whether object is in an consistent state after being updated from a client. EOCustomObject's implementation does nothing, and should be overridden if necessary.

Specified by:

validateClientUpdate in interface EOValidation

Throws:

NSValidation.ValidationException -

validateForDelete

public void validateForDelete()
                       throws NSValidation.ValidationException

Confirms that the receiver can be deleted in its current state, throwing an NSValidation.ValidationException if it can't. For example, an object can't be deleted if it has a relationship with a delete rule of EOClassDescription.DeleteRuleDeny and that relationship has a destination object.

EOCustomObject's implementation sends the receiver's EOClassDescription a message (which performs basic checking based on the presence or absence of values). Subclasses should invoke super's implementation before performing their own validation, and should combine any Exception thrown by super's implementation with their own.

Specified by:

validateForDelete in interface EOValidation

Throws:

NSValidation.ValidationException - if the receiver can't be deleted in its current state.

See Also:

EOEnterpriseObject.propagateDeleteWithEditingContext( EOEditingContext ec)

validateForInsert

public void validateForInsert()
                       throws NSValidation.ValidationException

Confirms that the receiver can be inserted in its current state, throwing an NSValidation.ValidationException if it can't. EOCustomObject's implementation simply invokes validateForSave.

The method validateForSave is the generic validation method for when an object is written to the external store. If an object performs validation that isn't specific to insertion, it should go in validateForSave.

Specified by:

validateForInsert in interface EOValidation

Throws:

NSValidation.ValidationException - if the receiver can't be inserted in its current state.

See Also:

validateForSave()

validateForSave

public void validateForSave()
                     throws NSValidation.ValidationException

Confirms that the receiver can be saved in its current state, throwing an NSValidation.ValidationException if it can't. EOCustomObject's implementation sends the receiver's EOClassDescription a validateObjectForSave message, then iterates through all of the receiver's properties. If this results in more than one exception, the Exception returned contains the additional ones in its userInfo dictionary under NSValidation.ValidationException.AdditionalExceptionsKey. Subclasses should invoke super's implementation before performing their own validation, and should combine any Exception thrown by super's implementation with their own.

Specified by:

validateForSave in interface EOValidation

Throws:

NSValidation.ValidationException - if the receiver can't be saved in its current state.

See Also:

NSValidation.ValidationException

validateForUpdate

public void validateForUpdate()
                       throws NSValidation.ValidationException

Confirms that the receiver can be saved in its current state, throwing a NSValidation.ValidationException if it can't. EOCustomObject's implementation simply invokes validateForSave.

The method validateForSave is the generic validation method for when an object is written to the external store. If an object performs validation that isn't specific to updating, it should go in validateForSave.

Specified by:

validateForUpdate in interface EOValidation

Throws:

NSValidation.ValidationException - if the receiver can't be saved in its current state.

See Also:

validateForSave()

validateTakeValueForKeyPath

public Object validateTakeValueForKeyPath(Object value,
                                          String keyPath)
                                   throws NSValidation.ValidationException

Confirms that value is valid for the receiver's property named by keyPath, and assigns the value to the property (if value is different from the current value), or throws an NSValidation.ValidationException if value isn't valid.

A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName".

Specified by:

validateTakeValueForKeyPath in interface NSValidation

Parameters:

value - the value to validate

keyPath - the keypath that will contain the value

Returns:

the destination object

Throws:

NSValidation.ValidationException - if value isn't legal

See Also:

NSKeyValueCoding.valueForKey(String key)

validateValueForKey

public Object validateValueForKey(Object value,
                                  String key)
                           throws NSValidation.ValidationException

Validates a property indirectly by name. This method is responsible for two things: coercing the value into an appropriate type for the object, and validating it according to the object's rules. The default implementation provided by EOCustomObject consults the object's EOClassDescription to coerce the value and to check for basic errors, such as a null value when that isn't allowed. If no basic errors exist, this default implementation then validates the value according to the object itself.

It searches for a method of the form validateKey and invokes it if it exists. These are the methods that your custom classes can implement to validate individual properties, such as validateAge to check that the value the user entered is within acceptable limits. The validateAge method should raise an EOValidation.Exception if it finds an unacceptable value.

Specified by:

validateValueForKey in interface NSValidation

Parameters:

the - value to validate

key - the key corresponding to the object property that will hold the value

Returns:

the validated value

Throws:

NSValidation.ValidationException - if value isn't legal

See Also:

NSKeyValueCoding.valueForKey(String key)

valueForKey

public Object valueForKey(String key)

Returns the receiver's value for the property identified by key.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

• Searches for a public accessor method based on key. For example, with a key of "lastName", the method looks for a method named getLastName or lastName.
• If a public accessor method isn't found, searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", the method looks for a method named _getLastName or _lastName
• If an accessor method isn't found and the static method canAccessFieldsDirectly returns true, the method searches for an instance variable based on key and returns its value directly. For the key "lastName", this would be _lastName or lastName.
• If neither an accessor method nor an instance variable is found, the method invokes handleQueryWithUnboundKey (defined in NSKeyValueCoding.ErrorHandling).

Note: The default implementation of NSKeyValueCoding provided by the Foundation package should always be used. The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding.DefaultImplementation; or if the class inherits from an WebObjects class that implements NSKeyValueCoding, the inherited implementation is not to be overridden. Using a custom implementation incurs significant performance penalties.

Specified by:

valueForKey in interface NSKeyValueCoding

Parameters:

key - a property of the receiver

Returns:

the receiver's value for the property identified by key

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Returns the value for the derived property identified by keyPath. A key path has the form relationship.property (with one or more relationships). For example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and returns the result of a valueForKey message to the final object.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - Identifies the derived property for the receiver.

Returns:

the value for the derived property identified by keyPath

valuesForKeys

public NSDictionary valuesForKeys(NSArray keys)

Returns an NSDictionary containing the property values identified by each element in keys. EOCustomObject's implementation invokes valueForKey for each key in keys, substituting EONullValues into the NSDictionary for returned nulls.

Specified by:

valuesForKeys in interface EOKeyValueCodingAdditions

Parameters:

keys - an NSArray of property names in the receiver

Returns:

an NSDictionary containing the property values

valuesForKeysWithMapping

public NSDictionary valuesForKeysWithMapping(NSDictionary mapping)

Returns an NSDictionary containing the property values identified by each of the key-value pairs in mapping. The keys of the mapping dictionary represent arbitrary external names for properties of an Enterprise Object and the values are the internal or EOModel names for these properties. Invokes valueForKey for each value in mapping, substituting NSKeyValueCoding.NullValue in the returned dictionary for returned nulls.

Specified by:

valuesForKeysWithMapping in interface EOKeyValueCodingAdditions

Parameters:

mapping - the dictionary that maps arbitrary external names to internal property names

Returns:

a dictionary containing the property values identified by each of keys (external names) in mapping

willChange

public void willChange()

Notifies any observers that the receiver's state is about to change, by sending each an objectWillChange message. 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:

 public void setRoleName(String value){
      willChange();
      roleName =value;
 }
 

Specified by:

willChange in interface EOEnterpriseObject

See Also:

EOObserverCenter

willRead

public void willRead()

Fills the receiver with values fetched from the database. Before the application attempts to message an object, you must ensure that it has been filled with its data. To do this, enterprise objects invoke the method willRead prior to any attempt to access the object's state, most typically in "get" methods such as the following:

 public String roleName(){
    willRead();
   return roleName;
 }
 

This methods locks the parent EOObjectStore of the EOEditingContext this EO is contained within for the duration of this method.

Specified by:

willRead in interface EOFaulting

willReadRelationship

public Object willReadRelationship(Object object)

Enterprise object instances that use deferred faulting invoke this method before accessing a relationship to ensure that the relationship isn't a deferred fault. EOCustomObject and EOGenericRecord's implementations check if object is a deferred fault, and create and return a regular fault if it is. This methods locks the parent EOObjectStore of the EOEditingContext this EO is contained within for the duration of this method.

Specified by:

willReadRelationship in interface EODeferredFaulting

Parameters:

object - the object that is checked

Returns:

a regular fault if object is a deferred fault