WebObjects 5.2

com.webobjects.eocontrol
Interface EOEnterpriseObject

All Superinterfaces:
EODeferredFaulting, EOFaulting, EOKeyValueCoding, EOKeyValueCodingAdditions, EORelationshipManipulation, EOValidation, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions, NSValidation, Serializable
All Known Implementing Classes:
EOCustomObject

public interface EOEnterpriseObject
extends Serializable, EOKeyValueCodingAdditions, EORelationshipManipulation, EOValidation, EODeferredFaulting

The EOEnterpriseObject interface identifies basic enterprise object behavior, defining methods for supporting operations common to all enterprise objects. Among these are methods for initializing instances, announcing changes, setting and retrieving property values, and performing validation of state. Some of these methods are for enterprise objects to implement or override, and some are meant to be used as defined by the Framework. Many methods are used internally by the Framework and are rarely invoked by application code.

Many of the functional areas are defined in smaller, more specialized interfaces and incorporated in the over-arching EOEnterpriseObject interface:

You rarely need to implement the EOEnterpriseObject interface from scratch. The Framework provides default implementations of the methods in EOCustomObject and EOGenericRecord. Use EOGenericRecord to represent enterprise objects that don't require custom behavior, and create subclasses of EOCustomObject to represent enterprise objects that do.

See EOEnterpriseObjectConcepts for more information.


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
 
Method Summary
 NSArray allPropertyKeys()
          Returns all of the receiver's property keys.
 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 an EOEditingContext.
 void awakeFromInsertion(EOEditingContext ec)
          Overridden by subclasses to perform additional initialization on the receiver upon its being inserted into an EOEditingContext.
 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.
 EOClassDescription classDescriptionForDestinationKey(String detailKey)
          Returns the EOClassDescription for the destination objects of the relationship identified by detailKey.
 void clearProperties()
          Sets all of the receiver's to-one and to-many relationships to null.
 int deleteRuleForRelationshipKey(String relationshipKey)
          Returns a value indicating how to handle the destination of the receiver's relationship named by relationshipKey when the receiver is deleted.
 EOEditingContext editingContext()
          Returns the EOEditingContext that holds the receiver.
 String entityName()
          Returns the name of the receiver's entity, or null if it does not have one.
 String eoDescription()
          Returns a String that describes the receiver.
 String eoShallowDescription()
          Similar to eoDescription, but doesn't descend into relationships.
 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 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 relationshipKey that owns its destination, 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.
 void reapplyChangesFromDictionary(NSDictionary changes)
          Similar to takeValuesFromDictionary, but the changes dictionary can contain arrays for to-many relationships.
 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.
 NSArray toManyRelationshipKeys()
          Returns the names of the receiver's to-many relationships.
 NSArray toOneRelationshipKeys()
          Returns the names of the receiver's to-one relationships.
 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.
 void willChange()
          Notifies any observers that the receiver's state is about to change, by sending each an objectWillChange message.
 
Methods inherited from interface com.webobjects.eocontrol.EOKeyValueCodingAdditions
takeValuesFromDictionary, takeValuesFromDictionaryWithMapping, valuesForKeys, valuesForKeysWithMapping
 
Methods inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions
takeValueForKeyPath, valueForKeyPath
 
Methods inherited from interface com.webobjects.foundation.NSKeyValueCoding
takeValueForKey, valueForKey
 
Methods inherited from interface com.webobjects.eocontrol.EOKeyValueCoding
storedValueForKey, takeStoredValueForKey
 
Methods inherited from interface com.webobjects.foundation.NSKeyValueCoding.ErrorHandling
handleQueryWithUnboundKey, handleTakeValueForUnboundKey, unableToSetNullForKey
 
Methods inherited from interface com.webobjects.eocontrol.EORelationshipManipulation
addObjectToBothSidesOfRelationshipWithKey, addObjectToPropertyWithKey, removeObjectFromBothSidesOfRelationshipWithKey, removeObjectFromPropertyWithKey
 
Methods inherited from interface com.webobjects.eocontrol.EOValidation
validateClientUpdate, validateForDelete, validateForInsert, validateForSave, validateForUpdate
 
Methods inherited from interface com.webobjects.foundation.NSValidation
validateTakeValueForKeyPath, validateValueForKey
 
Methods inherited from interface com.webobjects.eocontrol.EODeferredFaulting
willReadRelationship
 
Methods inherited from interface com.webobjects.eocontrol.EOFaulting
clearFault, faultHandler, isFault, turnIntoFault, willRead
 

Method Detail

allPropertyKeys

public NSArray allPropertyKeys()
Returns all of the receiver's property keys. EOCustomObject's implementation returns the union of the keys returned by attributeKeys, toOneRelationshipKeys and toManyRelationshipKeys.
Returns:
all of the receiver's property keys
See Also:
attributeKeys(), toOneRelationshipKeys(), toManyRelationshipKeys()

attributeKeys

public NSArray attributeKeys()
Returns the names of the receiver's attributes (not relationship properties). EOCustomObject's implementation simply invokes attributeKeys in the object's EOClassDescription and returns the results. You might wish to override this method to add keys for attributes not defined by the EOClassDescription. The EOAccess layer's subclass of EOClassDescription, EOEntityClassDescription, returns the names of attributes designated as class properties.
Returns:
the names of the receiver's attributes
See Also:
toOneRelationshipKeys(), 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.
Parameters:
ec - the editing context 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 an EOEditingContext. EOCustomObject's implementation merely sends an awakeObjectFromFetch to the receiver's EOClassDescription. Subclasses should invoke super's implementation before performing their own initialization.
Parameters:
ec - An EOEditingContext that the receiver was just fetched from

awakeFromInsertion

public void awakeFromInsertion(EOEditingContext ec)
Overridden by subclasses to perform additional initialization on the receiver upon its being inserted into an EOEditingContext. This is commonly used to assign default values or record the time of insertion. EOCustomObject's implementation sends an awakeObjectFromInsertion to the receiver's EOClassDescription. Subclasses should invoke super's implementation before performing their own initialization.
Parameters:
ec - An EOEditingContext that the receiver was just inserted into

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 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.
Parameters:
snapshot - a dictionary of values representing a snapshot of an object graph's state
Returns:
a dictionary of uncommitted changes relative to snapshot
See Also:
snapshot(), reapplyChangesFromDictionary(NSDictionary changes), EOEditingContext.currentEventSnapshotForObject(EOEnterpriseObject object), EOEditingContext.committedSnapshotForObject(EOEnterpriseObject object)

classDescription

public EOClassDescription classDescription()
Returns the EOClassDescription registered for the receiver's class. EOCustomObject's implementation invokes the static method EOClassDescription.classDescriptionForClass, for example. Refer to EOGenericRecord for more information about its implementation.
Returns:
the EOClassDescription registered for the receiver's class
See Also:
EOClassDescription.classDescriptionForClass(Class c), EOCustomObject.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.
Parameters:
detailKey - The input string embodying a relation.
Returns:
The EOClassDescription for the destination object(s) of the relationship identified by detailKey.

clearProperties

public void clearProperties()
Sets all of the receiver's to-one and to-many relationships to null. EOEditingContexts 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.

deleteRuleForRelationshipKey

public int deleteRuleForRelationshipKey(String relationshipKey)
Returns a value 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 (all found in EOClassDescription):

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.

Parameters:
relationshipKey - the receiver's relationship
Returns:
a rule indicating how to handle the destination of the receiver's relationship
See Also:
EOClassDescription, propagateDeleteWithEditingContext(EOEditingContext ec), EOCustomObject.validateForDelete()

editingContext

public EOEditingContext editingContext()
Returns the EOEditingContext that holds the receiver. An editing context tracks changes made to enterprise objects and synchronizes with a backing object store (normally a database).
Returns:
the editing context that holds the receiver, or null if the object is not registered in an editing context.
See Also:
EOEditingContext

entityName

public String entityName()
Returns the name of the receiver's entity, or null if it does not have one. EOCustomObject's implementation simply sends an entityName message to the receiver's EOClassDescription, as does EOGenericRecord.
Returns:
name of the receiver's entity

eoDescription

public String eoDescription()
Returns a String that describes the receiver. EOCustomObject's implementation returns a full description of the receiver's property values by extracting them using the key value coding methods. An object referenced through relationships is listed with the results of an eoShallowDescription message (to avoid infinite recursion through cyclical relationships).
Returns:
a String that describes the receiver
See Also:
userPresentableDescription(), eoShallowDescription()

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 globalID information.
Returns:
String containing the receiver's class and globalID information.
See Also:
userPresentableDescription(), eoDescription()

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 classes, 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.

You might override this method for reciprocal relationships that aren't defined using the same join attributes. For example, if a Member object has a relationship to CreditCard based on the card number, but a CreditCard has a relationship to Member based on the Member's primary key, both classes need to override this method. This is how Member might implement it.

public String inverseForRelationshipKey(String relationshipKey){ if (relationshipKey.equals("creditCard")) return( "member" ); else return( super.inverseForRelationshipKey(relationshipKey) ); }
Parameters:
relationshipKey - name of the input relation
Returns:
the name of the relationship pointing back to the receiver's class or entity

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. The return value of the method invocation must be cast into the expected class.
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.

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.
Parameters:
key - the String identifying a to-many relationship
Returns:
true if the receiver has a to-many relationship identified by key, false otherwise
See Also:
toManyRelationshipKeys()

opaqueState

public Object opaqueState()
This methods returns an opaque object which encapsulates state private to EOF. Developers should not use or interfere with that object.
Returns:
a private state object

ownsDestinationObjectsForRelationshipKey

public boolean ownsDestinationObjectsForRelationshipKey(String relationshipKey)
Returns true if the receiver has a relationship identified by relationshipKey that owns its destination, 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 former applies when the destination is removed and the latter applies when the source is deleted. EOCustomObject's implementation of this method simply sends an ownsDestinationObjectsForRelationshipKey message to the receiver's EOClassDescription.
Parameters:
relationshipKey - the input relation.
Returns:
true if the receiver has a relationship identified by relationshipKey that owns its destination, false otherwise.
See Also:
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.

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.
Parameters:
ec - the editing context that the receiver is in
See Also:
deleteRuleForRelationshipKey(String relationshipKey)

reapplyChangesFromDictionary

public void reapplyChangesFromDictionary(NSDictionary changes)
Similar to takeValuesFromDictionary, but the changes dictionary can contain arrays for to-many relationships. Where a key represents a to-many relationship, the dictionary's value is an NSArray containing two other NSArrays: the first is an array of objects to be added to the relationship property, and the second is an array of objects to be removed. EOCustomObject's implementation should be sufficient for all purposes; you shouldn't have to override this method. NSKeyValueCoding.NullValue is used in the changes dictionary as a placeholder for null.
Parameters:
changes - dictionary containing arrays for to many relationships
See Also:
snapshot(), changesFromSnapshot(NSDictionary snapshot), EOEditingContext.currentEventSnapshotForObject(EOEnterpriseObject object), EOEditingContext.committedSnapshotForObject(EOEnterpriseObject object)

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.
Returns:
a dictionary whose keys are those of the receiver's attributes
See Also:
updateFromSnapshot(NSDictionary aSnapshot)

toManyRelationshipKeys

public NSArray toManyRelationshipKeys()
Returns the names of the receiver's to-many relationships. EOCustomObject's implementation simply invokes toManyRelationshipKeys in the object's EOClassDescription and returns the results. You might wish to override this method to add keys for relationships not defined by the EOClassDescription, but it's rarely necessary: the access layer's subclass of EOClassDescription, EOEntityClassDescription, returns the names of to-many relationships designated as class properties.
Returns:
the names of the receiver's to-many relationships
See Also:
attributeKeys(), toOneRelationshipKeys()

toOneRelationshipKeys

public NSArray toOneRelationshipKeys()
Returns the names of the receiver's to-one relationships. EOCustomObject's implementation simply invokes toOneRelationshipKeys in the object's EOClassDescription and returns the results. You might wish to override this method to add keys for relationships not defined by the EOClassDescription, but it's rarely necessary: The access layer's subclass of EOClassDescription, EOEntityClassDescription, returns the names of to-one relationships designated as class properties.
Returns:
the names of the receiver's to-one relationships
See Also:
attributeKeys(), toManyRelationshipKeys()

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.
Parameters:
snapshot - the immutable array of values
See Also:
snapshot()

userPresentableDescription

public String userPresentableDescription()
Returns a short (no longer than 60 characters) description of an enterprise object based on its data. EOCustomObject's implementation enumerates the object's attributeKeys and returns the values of all of its properties, separated by commas (applying the default formatter for numbers and dates).
Returns:
description of an enterprise object based on its data
See Also:
eoDescription(), eoShallowDescription(), attributeKeys()

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; }
See Also:
EOObserverCenter, EOEditingContext.objectWillChange(Object object)

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

Copyright © 2003 Apple Computer, Inc.