com.webobjects.eocontrol
Interface EOEnterpriseObject

All Superinterfaces:

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

All Known Implementing Classes:

EOCustomObject, EOGenericRecord

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:

• EOKeyValueCoding defines the Enterprise Objects Framework's main data transport mechanism, in which the properties of an object are accessed indirectly by name (or "key"), rather than directly through invocation of an accessor method or as instance variables.
• EOKeyValueCodingAdditions defines extensions to the basic EOKeyValueCoding interface, giving access to groups of properties and to properties across relationships.
• EORelationshipManipulation builds on the basic EOKeyValueCoding interface to allow the modification of to-many relationship properties.
• EOValidation defines the way that enterprise objects validate their values.
• EOFaulting and EODeferredFaulting define mechanisms for postponing an object's initialization until its actually needed.

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.

Nested Class Summary

Nested classes/interfaces inherited from interface com.webobjects.eocontrol.EOKeyValueCodingAdditions

EOKeyValueCodingAdditions.DefaultImplementation, EOKeyValueCodingAdditions.Utility

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.MapImplementation, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.ValueAccessor

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.MapImplementation, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.ValueAccessor

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSValidation

NSValidation.ValidationException

Field Summary

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

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	isReadOnly() Returns true if the receiver can not be modified, false if it can.
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

takeValueForKey, valueForKey

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

editingContext

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

willChange

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:

 <blockquote>
 public void setRoleName(String value){
   willChange();
   roleName = value;
 }
 </blockquote>
 

See Also:

EOObserverCenter, EOEditingContext.objectWillChange(Object object)

classDescription

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

entityName

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

attributeKeys

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:

EOEnterpriseObject.toOneRelationshipKeys(), EOEnterpriseObject.toManyRelationshipKeys()

toOneRelationshipKeys

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:

EOEnterpriseObject.attributeKeys(), EOEnterpriseObject.toManyRelationshipKeys()

toManyRelationshipKeys

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:

EOEnterpriseObject.attributeKeys(), EOEnterpriseObject.toOneRelationshipKeys()

inverseForRelationshipKey

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.

 <blockquote>
 public String inverseForRelationshipKey(String relationshipKey){
     if (relationshipKey.equals("creditCard"))
         return( "member" );
     else
         return( super.inverseForRelationshipKey(relationshipKey) );
 }
 </blockquote>
 

Parameters:

relationshipKey - name of the input relation

Returns:

the name of the relationship pointing back to the receiver's class or entity

deleteRuleForRelationshipKey

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

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

Parameters:

relationshipKey - the receiver's relationship

Returns:

a rule indicating how to handle the destination of the receiver's relationship

See Also:

EOClassDescription, EOEnterpriseObject.propagateDeleteWithEditingContext(EOEditingContext ec), EOCustomObject.validateForDelete()

ownsDestinationObjectsForRelationshipKey

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:

EOEnterpriseObject.deleteRuleForRelationshipKey(String relationshipKey), EORelationship.ownsDestination()

classDescriptionForDestinationKey

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.

awakeFromInsertion

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

awakeFromFetch

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

snapshot

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:

EOEnterpriseObject.updateFromSnapshot(NSDictionary aSnapshot)

updateFromSnapshot

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:

EOEnterpriseObject.snapshot()

changesFromSnapshot

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:

EOEnterpriseObject.snapshot(), EOEnterpriseObject.reapplyChangesFromDictionary(NSDictionary changes), EOEditingContext.currentEventSnapshotForObject(EOEnterpriseObject object), EOEditingContext.committedSnapshotForObject(EOEnterpriseObject object)

reapplyChangesFromDictionary

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:

EOEnterpriseObject.snapshot(), EOEnterpriseObject.changesFromSnapshot(NSDictionary snapshot), EOEditingContext.currentEventSnapshotForObject(EOEnterpriseObject object), EOEditingContext.committedSnapshotForObject(EOEnterpriseObject object)

isToManyKey

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:

EOEnterpriseObject.toManyRelationshipKeys()

allPropertyKeys

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:

EOEnterpriseObject.attributeKeys(), EOEnterpriseObject.toOneRelationshipKeys(), EOEnterpriseObject.toManyRelationshipKeys()

clearProperties

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.

propagateDeleteWithEditingContext

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:

EOEnterpriseObject.deleteRuleForRelationshipKey(String relationshipKey)

userPresentableDescription

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:

EOEnterpriseObject.eoDescription(), EOEnterpriseObject.eoShallowDescription(), EOEnterpriseObject.attributeKeys()

eoShallowDescription

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:

EOEnterpriseObject.userPresentableDescription(), EOEnterpriseObject.eoDescription()

eoDescription

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:

EOEnterpriseObject.userPresentableDescription(), EOEnterpriseObject.eoShallowDescription()

invokeRemoteMethod

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.

prepareValuesForClient

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.

awakeFromClientUpdate

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.

opaqueState

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

isReadOnly

boolean isReadOnly()

Returns true if the receiver can not be modified, false if it can. If an entity is read-only, then Enterprise Objects fetched for that entity are also read-only (that is, can not be inserted, deleted, or updated).

Returns:

true if the entity can't be modified.