WebObjects 5.2.3

com.webobjects.eocontrol
Class EOCustomObject

java.lang.Object
  extended bycom.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

Nested Class Summary
 
Nested classes inherited from class com.webobjects.eocontrol.EOKeyValueCodingAdditions
EOKeyValueCodingAdditions.DefaultImplementation, EOKeyValueCodingAdditions.Utility
 
Nested classes inherited from class com.webobjects.foundation.NSKeyValueCoding
NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.ValueAccessor
 
Nested classes inherited from class com.webobjects.foundation.NSValidation
NSValidation.DefaultImplementation, NSValidation.Utility, NSValidation.ValidationException
 
Field Summary
 
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
See Also:
EOEnterpriseObject.attributeKeys(), EOEnterpriseObject.toOneRelationshipKeys(), EOEnterpriseObject.toManyRelationshipKeys()

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
See Also:
EOEnterpriseObject.toOneRelationshipKeys(), EOEnterpriseObject.toManyRelationshipKeys()

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
See Also:
EOEnterpriseObject.snapshot(), EOEnterpriseObject.reapplyChangesFromDictionary(NSDictionary changes), EOEditingContext.currentEventSnapshotForObject(EOEnterpriseObject object), EOEditingContext.committedSnapshotForObject(EOEnterpriseObject object)

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
See Also:
EOClassDescription.classDescriptionForClass(Class c), classDescription(), EOGenericRecord.classDescription()

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:

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
See Also:
EOEditingContext

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.
See Also:
EOEnterpriseObject.userPresentableDescription(), EOEnterpriseObject.eoDescription()

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

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.
See Also:
EOFaultHandler.handlerForFault(Object)

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

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.
See Also:
EOFaultHandler.isFault(Object)

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
See Also:
EOEnterpriseObject.toManyRelationshipKeys()

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
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
See Also:
EOEnterpriseObject.deleteRuleForRelationshipKey(String relationshipKey), EORelationship.ownsDestination()

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
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
See Also:
EOEnterpriseObject.snapshot(), EOEnterpriseObject.changesFromSnapshot(NSDictionary snapshot), EOEditingContext.currentEventSnapshotForObject(EOEnterpriseObject object), EOEditingContext.committedSnapshotForObject(EOEnterpriseObject object)

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
See Also:
EOEnterpriseObject.updateFromSnapshot(NSDictionary aSnapshot)

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:

Specified by:
storedValueForKey in interface EOKeyValueCoding
Parameters:
key - a property of receiver.
Returns:
the value of property identified by key
See Also:
NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.valueForKey(String), NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(String)

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:

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:

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.
See Also:
NSKeyValueCoding.NullValue, NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleTakeValueForUnboundKey(java.lang.Object, java.lang.String)

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
See Also:
NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

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.

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
See Also:
EOFaultHandler.makeObjectIntoFault(Object, EOFaultHandler)

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
See Also:
EOEnterpriseObject.eoDescription(), EOEnterpriseObject.eoShallowDescription(), EOEnterpriseObject.attributeKeys()

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:
value - 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:

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
See Also:
NSKeyValueCoding.NullValue, NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)

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
See Also:
NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

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
See Also:
NSKeyValueCoding.valueForKey(String)

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
See Also:
NSKeyValueCoding.valueForKey(String)

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
See Also:
EOFaultHandler.createFaultForDeferredFault(Object fault, EOEnterpriseObject eo)

Last updated Thu Oct 21 15:04:16 PDT 2004.

Copyright © 2004 Apple Computer, Inc.