EOClassDescription

Inherits from: Object

Implements: Serializable

Package: com.webobjects.eocontrol

Class Description

The EOClassDescription class provides a mechanism for extending classes by giving them access to metadata not available in the run-time system. This is achieved as follows:

EOClassDescription provides a bridge between enterprise objects and the metadata contained in an external source of information, such as an EOModel (EOAccess). It defines a standard API for accessing the information in an external source. It also manages the registration of EOClassDescription objects in your application.
The EOEnterpriseObject interface declares several EOClassDescription-related methods that define basic enterprise objects behavior, such as undo and validation. The EOCustomObject and EOGenericRecord classes implement the EOEnterpriseObject interface. An enterprise object class can either accept the default implementations by subclassing from EOCustomObject or it can provide its own implementation by overriding. This is discussed in more detail in the section "EOClassDescription" (page 41).

Enterprise Objects Framework implements a default subclass of EOClassDescription in EOAccess, EOEntityClassDescription. EOEntityClassDescription extends the behavior of enterprise objects by deriving information about them (such as NULL constraints and referential integrity rules) from an associated EOModel.

For more information on using EOClassDescription, see the sections

Constants

EOClassDescription defines the following int constants:

Constant Description

DeleteRuleNullify When the source object is deleted, any references a destination object has to the source are removed or "nullified." For example, suppose a department has a to-many relationship to multiple employees. When the department is deleted, any back references an employee has to the department are set to null.

DeleteRuleCascade When the source object (department) is deleted, any destination objects (employees) are also deleted.

DeleteRuleDeny If the source object (department) has any destination objects (employees), a delete operation is refused.

DeleteRuleNoAction When the source object is deleted, its relationship is ignored and no action is taken to propagate the deletion to destination objects.This rule is useful for tuning performance.To perform a deletion, Enterprise Objects Framework fires all the faults of the deleted object and then fires any to-many faults that point back to the deleted object. For example, suppose you have a simple application based on the sample Movies database. Deleting a Movie object has the effect of firing a to-one fault for the Movie's studio relationship, and then firing the to-many movies fault for that studio. In this scenario, it would make sense to set the delete rule DeleteRuleNoAction for Movie's studio relationship. However, you should use this delete rule with great caution since it can result in dangling references in your object graph.

EOClassDescription also defines string constants for the names of the notifications it posts. For more information, see the section "Notifications" (page 54).

Method Types

Managing EOClassDescriptions
invalidateClassDescriptionCache registerClassDescription
Getting EOClassDescriptions
classDescriptionForClass classDescriptionForEntityName

Creating new object instances
createInstanceWithEditingContext

Propagating delete
propagateDeleteForObject

Returning information from the EOClassDescription
entityName
attributeKeys
classDescriptionForDestinationKey
toManyRelationshipKeys
toOneRelationshipKeys
inverseForRelationshipKey
ownsDestinationObjectsForRelationshipKey
deleteRuleForRelationshipKey

Performing validation
validateObjectForDelete validateObjectForSave validateValueForKey

Providing default characteristics for key display
defaultFormatterForKey defaultFormatterForKeyPath displayNameForKey

Handling newly inserted and newly fetched objects
awakeObjectFromFetch awakeObjectFromInsertion

Setting the delegate
classDelegate setClassDelegate

Getting an object's description
userPresentableDescriptionForObject

Getting fetch specifications
fetchSpecificationNamed

Static Methods

classDelegate

public static Object classDelegate()

Returns the delegate for the EOClassDescription class (as opposed to EOClassDescription instances).

See Also: setClassDelegate

classDescriptionForClass

public static EOClassDescription classDescriptionForClass(Class aClass)

Invoked by the default implementations of the EOEnterpriseObject interface method classDescription to return the EOClassDescription for aClass. It's generally not safe to use this method directly-for example, individual EOGenericRecord instances can have different class descriptions. If a class description for aClass isn't found, this method posts an ClassDescriptionNeededForClassNotification on behalf of the receiver's class, allowing an observer to register a an EOClassDescription.

classDescriptionForEntityName

public static EOClassDescription classDescriptionForEntityName(String entityName)

Returns the EOClassDescription registered under entityName.

invalidateClassDescriptionCache

public static void invalidateClassDescriptionCache()

Flushes the EOClassDescription cache. Because the EOModel objects in an application supply and register EOClassDescriptions on demand, the cache continues to be repopulated as needed after you invalidate it. (The EOModel class is defined in EOAccess.)

You'd use this method when a provider of EOClassDescriptions (such as an EOModel) has newly become available, or is about to go away. However, you should rarely need to directly invoke this method unless you're using an external source of information other than an EOModel.

registerClassDescription

public static void registerClassDescription( EOClassDescription description, Class class)

Registers an EOClassDescription object for class in the EOClassDescription cache. You should rarely need to directly invoke this method unless you're using an external source of information other than an EOModel (EOAccess).

setClassDelegate

public static void setClassDelegate(Object delegate)

Sets the delegate for the EOClassDescription class (as opposed to EOClassDescription instances) to delegate. For more information on the class delegate, see the EOClassDescription.ClassDelegate interface specification.

See Also: classDelegate

Instance Methods

attributeKeys

public NSArray attributeKeys()

Overridden by subclasses to return an array of attribute keys (Strings) for objects described by the receiver. "Attributes" contain immutable data (such as Numbers and Strings), as opposed to "relationships" that are references to other enterprise objects. For example, a class description that describes Movie objects could return the attribute keys "title," "dateReleased," and "rating."

EOClassDescription's implementation of this method simply returns.

awakeObjectFromFetch

public void awakeObjectFromFetch( EOEnterpriseObject object, EOEditingContext anEditingContext)

Overridden by subclasses to perform standard post-fetch initialization for object in anEditingContext. EOClassDescription's implementation of this method does nothing.

awakeObjectFromInsertion

public void awakeObjectFromInsertion( EOEnterpriseObject object, EOEditingContext anEditingContext)

Assigns empty arrays to to-many relationship properties of newly inserted enterprise objects. Can be overridden by subclasses to propagate inserts for the newly inserted object in anEditingContext. More specifically, if object has a relationship (or relationships) that propagates the object's primary key and if no object yet exists at the destination of that relationship, subclasses should create the new object at the destination of the relationship. Use this method to put default values in your enterprise object.

classDescriptionForDestinationKey

public EOClassDescription classDescriptionForDestinationKey(String detailKey)

Overridden by subclasses to return the class description for objects at the destination of the to-one relationship identified by detailKey. For example, the statement:








movie.classDescriptionForDestinationKey("studio")

might return the class description for the Studio class. EOClassDescription's implementation of this method returns null.

clientAttributeKeys

public NSArray clientAttributeKeys()

Returns an array containing the names of the attributes that are bound to the client-side class that corresponds to the receiver's entity.

clientToManyRelationshipKeys

public NSArray clientToManyRelationshipKeys()

Returns an array containing the names of the to-many relationships that are bound to the client-side class that corresponds to the receiver's entity.

clientToOneRelationshipKeys

public NSArray clientToOneRelationshipKeys()

Returns an array containing the names of the to-one relationships that are bound to the client-side class that corresponds to the receiver's entity.

createInstanceWithEditingContext

public EOEnterpriseObject createInstanceWithEditingContext( EOEditingContext anEditingContext, EOGlobalID globalID)

Overridden by subclasses to create an object of the appropriate class in anEditingContext with globalID. In typical usage, both of the method's arguments are null. To create the object, the subclass should pass anEditingContext, itself, and globalID to the appropriate constructor. Implementations of this method should return an autoreleased object. Enterprise Objects Framework uses this method to create new instances of objects when fetching existing enterprise objects or inserting new ones in an interface layer EODisplayGroup. EOClassDescription's implementation of this method returns null.

defaultFormatterForKey

public java.text.Format defaultFormatterForKey(String key)

Returns the default NSFormatter to use when parsing values for assignment to key. EOClassDescription's implementation returns null. The access layer's EOEntityClassDescription's implementation returns an NSFormatter based on the Java value class specified for key in the associated model file. Code that creates a user interface, like a wizard, can use this method to assign formatters to user interface elements.

defaultFormatterForKeyPath

public java.text.Format defaultFormatterForKeyPath(String key)

Similar to defaultFormatterForKey, except this method traverses keyPath and returns the formatter for the key at the end of the path (using defaultFormatterForKey).

deleteRuleForRelationshipKey

public int deleteRuleForRelationshipKey(String relationshipKey)

Overridden by subclasses to return a delete rule indicating how to treat the destination of the given relationship when the receiving object is deleted. The delete rule is one of:

DeleteRuleCascade
DeleteRuleDeny
DeleteRuleNullify
DeleteRuleNoAction

EOClassDescription's implementation of this method returns the delete rule EODeleteRuleNullify. In the common case, the delete rule for an enterprise object is defined in its EOModel. (The EOModel class is defined in EOAccess.)

See Also: propagateDeleteWithEditingContext (EOEnterpriseObject)

displayNameForKey

public String displayNameForKey(String key)

Returns the default string to use in the user interface when displaying key. By convention, lowercase words are capitalized (for example, "revenue" becomes "Revenue"), and spaces are inserted into words with mixed case (for example, "firstName" becomes "First Name"). This method is useful if you're creating a user interface from only a class description, such as with a wizard or a Direct To Web application.

entityName

public String entityName()

Overridden by subclasses to return a unique type name for objects of this class. For example, the access layer's EOEntityClassDescription returns its EOEntity's name. EOClassDescription's implementation of this method returns null.

fetchSpecificationNamed

public EOFetchSpecification fetchSpecificationNamed(String name)

Overridden by subclasses to return the fetch specification associated with name. For example, the access layer's EOEntityClassDescription returns the fetch specification in its EOEntity named name (if any). EOClassDescription's implementation returns nil.

finalize

public void finalize() throws Throwable

Description forthcoming.

inverseForRelationshipKey

public String inverseForRelationshipKey(String relationshipKey)

Overridden by subclasses to return the name of the relationship pointing back at the receiver from the destination of the relationship specified by relationshipKey. For example, suppose an Employee object has a relationship called department to a Department object, and Department has a relationship called employees back to Employee. The statement:








employee.inverseForRelationshipKey("department");

returns the string "employees".

EOClassDescription's implementation of this method returns null.

ownsDestinationObjectsForRelationshipKey

public boolean ownsDestinationObjectsForRelationshipKey(String relationshipKey)

Overridden by subclasses to return true or false to indicate whether the objects at the destination of the relationship specified by relationshipKey should be deleted if they are removed from the relationship (and not transferred to the corresponding relationship of another object). For example, an Invoice object owns its line items. If a LineItem object is removed from an Invoice it should be deleted since it can't exist outside of an Invoice. EOClassDescription's implementation of this method returns false.In the common case, this behavior for an enterprise object is defined in its EOModel. (The EOModel class is defined in EOAccess.)

propagateDeleteForObject

public void propagateDeleteForObject( EOEnterpriseObject object, EOEditingContext anEditingContext)

Propagates a delete operation for object in anEditingContext, according to the delete rules specified in the EOModel. This method is invoked whenever a delete operation needs to be propagated, as indicated by the delete rule specified for the corresponding EOEntity's relationship key. (The EOModel and EOEntity classes are defined in EOAccess.) For more discussion of delete rules, see the EOEnterpriseObject interface specification.

See Also: deleteRuleForRelationshipKey

superClassDescription

public EOClassDescription superClassDescription()

Description forthcoming.

toManyRelationshipKeys

public NSArray toManyRelationshipKeys()

Overridden by subclasses to return the keys for the to-many relationship properties of the receiver. To-many relationship properties contain arrays of enterprise objects. EOClassDescription's implementation of this method returns null.

toOneRelationshipKeys

public NSArray toOneRelationshipKeys()

Overridden by subclasses to return the keys for the to-one relationship properties of the receiver. To-one relationship properties are other enterprise objects. EOClassDescription's implementation of this method returns null.

toString

public String toString()

Returns a String representation of the receiver.

userPresentableDescriptionForObject

public String userPresentableDescriptionForObject(EOEnterpriseObject anObject)

Returns a short (no longer than 60 characters) description of anObject based on its data. This method enumerates anObject's attributeKeys and returns each attribute's value, separated by commas and with the default formatter applied for numbers and dates.

validateObjectForDelete

public void validateObjectForDelete(EOEnterpriseObject object) throws NSValidation.ValidationException

Overridden by subclasses to determine whether it's permissible to delete object. Subclasses should complete normally if the delete operation should proceed, or throw an exception containing a user-presentable (localized) error message if not. EOClassDescription's implementation of this method completes normally.

validateObjectForSave

public void validateObjectForSave(EOEnterpriseObject object) throws NSValidation.ValidationException

Overridden by subclasses to determine whether the values being saved for object are acceptable. Subclasses should complete normally if the values are acceptable and the save operation should proceed, or throw exception containing a user-presentable (localized) error message if not. EOClassDescription's implementation of this method completes normally.

validateValueForKey

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

Overridden by subclasses to validate value. Subclasses should return null if the value is acceptable, or throw an exception containing a user-presentable (localized) error message if not. Implementations can replace value by returning a new value. EOClassDescription's implementation of this method returns null.

An enterprise object performs custom attribute specific validation with a method of the form validateKey. See the EOValidation interface specification for more information.

Notifications

The following notifications are declared by EOClassDescription and posted by enterprise objects in your application.

ClassDescriptionNeededForClassNotification

public static final String ClassDescriptionNeededForClassNotification

One of the EOClassDescription-related methods in the EOEnterpriseObject interface to extend the behavior of enterprise objects is classDescription. The first time an enterprise object receives a classDescription message (for example, when changes to the object are being saved to the database), it posts ClassDescriptionNeededForClassNotification to notify observers that a class description is needed. The observer then locates the appropriate class description and registers it in the application. By default, EOModel objects are registered as observers for this notification and register EOClassDescriptions on demand.

Notification Object Enterprise object class

userInfo Dictionary None

ClassDescriptionNeededForEntityNameNotification

public static final String ClassDescriptionNeededForEntityNameNotification

When classDescriptionForEntityName is invoked for a previously unregistered entity name, this notification is broadcast with the requested entity name as the object of the notification. By default, EOModel objects are registered as observers for this notification and register EOClassDescriptions on demand.

Notification Object Entity name (String)

userInfo Dictionary None

Constant	Description
`DeleteRuleNullify`	When the source object is deleted, any references a destination object has to the source are removed or "nullified." For example, suppose a department has a to-many relationship to multiple employees. When the department is deleted, any back references an employee has to the department are set to `null`.
`DeleteRuleCascade`	When the source object (department) is deleted, any destination objects (employees) are also deleted.
`DeleteRuleDeny`	If the source object (department) has any destination objects (employees), a delete operation is refused.
`DeleteRuleNoAction`	When the source object is deleted, its relationship is ignored and no action is taken to propagate the deletion to destination objects.This rule is useful for tuning performance.To perform a deletion, Enterprise Objects Framework fires all the faults of the deleted object and then fires any to-many faults that point back to the deleted object. For example, suppose you have a simple application based on the sample Movies database. Deleting a Movie object has the effect of firing a to-one fault for the Movie's studio relationship, and then firing the to-many movies fault for that studio. In this scenario, it would make sense to set the delete rule `DeleteRuleNoAction` for Movie's studio relationship. However, you should use this delete rule with great caution since it can result in dangling references in your object graph.

Notification Object	Enterprise object class
userInfo Dictionary	None

Notification Object	Entity name (String)
userInfo Dictionary	None