com.webobjects.eocontrol
Class EOClassDescription

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

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

EODistributedClassDescription, EOEntityClassDescription

public abstract class EOClassDescription

extends Object

implements Serializable

EOClassDescription provides a mechanism for extending classes with additional meta-data useful for interacting with Enterprise Objects. It also allows this meta-information to be registered at runtime by an external source (e.g. an EOEntity). In effect, the EOClassDescription allows EOF to add useful behavior to your by EOs using information specified for the EO in the EOModel file.

For example, the Java runtime allows the list of methods and instance variables for a class to be queried ("introspected") at runtime (this is what makes possible the EOKeyValueCoding interface). However, it does not provide information on whether the property of an object is an attribute or relationship, nor whether that relationship points to one or to many objects -- this information is not available in the source code, but it is available in the EOModel (in EOAccess). Note, though, that although the EOModel is the most common source of an EOClassDescription for a class, it is not the only one. Objects that don't have a model can implement methods like relationshipKeys and attributeKeys directly as instance methods, and the rest of the Framework can treat them identically to EOs that have this information provided by an external model.

For more information on EOClassDescription, refer to:

• "EOClassDescription concepts"

See Also:

ClassDescriptionNeededForClassNotification, ClassDescriptionNeededForEntityNameNotification, EOEntity, EOClassDescription.ClassDelegate.shouldPropagateDeleteForObject(com.webobjects.eocontrol.EOEnterpriseObject, com.webobjects.eocontrol.EOEditingContext, java.lang.String), Serialized Form

Inner Class Summary

static interface

EOClassDescription.ClassDelegate The ClassDelegate interface defines a method that the EOClassDescription class can invoke in its delegate.

Field Summary

static String	ClassDescriptionNeededForClassNotification Used to extend the behavior of Enterprise Objects in classDescription.
static 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.
static int	DeleteRuleCascade Delete destination objects when the source object is deleted.
static int	DeleteRuleDeny Refuse delete operation if the source object has any destination objects.
static int	DeleteRuleNoAction When the source object is deleted, its relationship to destination objects is ignored.
static int	DeleteRuleNullify When the source object is deleted, any destination object's references back to it are set to null.

Constructor Summary

EOClassDescription()

Method Summary

NSArray	attributeKeys() Overridden by subclasses to return an array of attribute keys 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.
void	awakeObjectFromFetch(EOEnterpriseObject object, EOEditingContext editingContext) Overridden by subclasses to perform standard post fetch initialization for object in editingContext.
void	awakeObjectFromInsertion(EOEnterpriseObject object, EOEditingContext editingContext) Assigns empty arrays to to many relationship properties of newly inserted enterprise objects.
static Object	classDelegate()
static EOClassDescription	classDescriptionForClass(Class aClass) Invoked by the default implementations of the EOEnterpriseObject interface method classDescription.
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.
static EOClassDescription	classDescriptionForEntityName(String entityName) Gets the EOClassDescription registered under entityName.
EOClassDescription	classDescriptionForKeyPath(String key)
Class	classForAttributeKey(String key)
NSArray	clientAttributeKeys() Enables you to find attributes names that are bound to the client-side class that corresponds to the receiver's entity.
NSArray	clientToManyRelationshipKeys() Used to determine the to many relationships that are bound to the client side class that corresponds to the receiver's entity.
NSArray	clientToOneRelationshipKeys() Used to determine the to-one relationships that are bound to the client side class that corresponds to the receiver's entity.
EOEnterpriseObject	createInstanceWithEditingContext(EOEditingContext editingContext, EOGlobalID globalID) Overridden by subclasses to create an object of the appropriate class in editingContext with globalID.
Format	defaultFormatterForKey(String key) The EOAccess layer's EOEntityClassDescription's implementation returns a Format based on the Java value class specified for key in the associated model file.
Format	defaultFormatterForKeyPath(String keyPath) Similar to defaultFormatterForKey, except this method traverses keyPath before returning the formatter for the key at the end of the path.
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.
String	displayNameForKey(String key) Provides a means to display a key in the user interface.
String	entityName() Overridden by subclasses to obtain a unique type name for objects of this class.
EOFetchSpecification	fetchSpecificationNamed(String name) Overridden by subclasses to obtain the fetch specification associated with name.
void	finalize()
static void	invalidateClassDescriptionCache() Flushes the EOClassDescription cache.
String	inverseForRelationshipKey(String relationshipKey) Overridden by subclasses to obtain the name of the relationship back to the receiver from the destination of the relationship specified with relationshipKey.
boolean	ownsDestinationObjectsForRelationshipKey(String relationshipKey) Overridden by subclasses to determine whether the objects at the destination of the relationship specified by relationshipKey should be deleted if they are removed from the relationship.
void	propagateDeleteForObject(EOEnterpriseObject obj, EOEditingContext ec) Propagates a delete operation for an object in an EditingContext, according to the delete rules specified in the EOModel.
static void	registerClassDescription(EOClassDescription description, Class aClass) Registers an EOClassDescription object for a class in the EOClassDescription cache.
static void	setClassDelegate(Object delegate) Sets the delegate for the entire EOClassDescription class.
EOClassDescription	superClassDescription() Overridden by subclasses to return a super class's class description.
NSArray	toManyRelationshipKeys() Overridden by subclasses to determine the to-many relationship properties of the receiver.
NSArray	toOneRelationshipKeys() Overridden by subclasses to determine the to-one relationship properties of the receiver.
String	toString() Returns a String representation of the receiver, including its class name, the name of the entity it describes, and attribute keys and all relationship keys of that entity.
String	userPresentableDescriptionForObject(EOEnterpriseObject eo) Returns a short (no longer than 60 characters) description of an EOEnterpriseObject based on its data.
void	validateObjectForDelete(EOEnterpriseObject object) Overridden by subclasses to determine whether it's permissible to delete an object.
void	validateObjectForSave(EOEnterpriseObject object) Overridden by subclasses to determine whether the values being saved for an object are acceptable.
Object	validateValueForKey(Object value, String key) Overridden by subclasses to validate a value.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ClassDescriptionNeededForClassNotification

public static final String ClassDescriptionNeededForClassNotification

Used to extend the behavior of Enterprise Objects in 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. An individual 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.

See Also:

EOEnterpriseObject.classDescription()

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. Subscribers can call registerClassDescription() to register the class description.

See Also:

classDescriptionForEntityName(String entityName)

DeleteRuleCascade

public static final int DeleteRuleCascade

Delete destination objects when the source object is deleted.

DeleteRuleDeny

public static final int DeleteRuleDeny

Refuse delete operation if the source object has any destination objects.

DeleteRuleNoAction

public static final int DeleteRuleNoAction

When the source object is deleted, its relationship to destination objects is ignored.

This rule is useful in performance tuning. You should however, use this with caution since it can result in dangling references in the object graph.

DeleteRuleNullify

public static final int DeleteRuleNullify

When the source object is deleted, any destination object's references back to it are set to null. For example, suppose a department has a relationship to multiple employees. When the department is deleted, any references an employee has to the department are set to null.

Constructor Detail

EOClassDescription

public EOClassDescription()

Method Detail

attributeKeys

public NSArray attributeKeys()

Overridden by subclasses to return an array of attribute keys 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.

Returns:

an array of attribute keys;default implementation returns NSArray.EmptyArray

See Also:

entityName(), toOneRelationshipKeys(), toManyRelationshipKeys()

awakeObjectFromFetch

public void awakeObjectFromFetch(EOEnterpriseObject object,
                                 EOEditingContext editingContext)

Overridden by subclasses to perform standard post fetch initialization for object in editingContext. The default implementation simply returns.

Parameters:

object - the object to be initialized

editingContext - EOEditingContext object that manages a graph of enterprise objects

awakeObjectFromInsertion

public void awakeObjectFromInsertion(EOEnterpriseObject object,
                                     EOEditingContext editingContext)

Assigns empty arrays to to many relationship properties of newly inserted enterprise objects. Subclasses can override this 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. This method is used to put default values in the enterprise object.

Parameters:

object - newly inserted enterprise objects

editingContext - EOEditingContext object that manages a graph of enterprise objects in an application

classDelegate

public static Object classDelegate()

Returns:

the delegate for the EOClassDescription class

See Also:

setClassDelegate(Object delegate)

classDescriptionForClass

public static EOClassDescription classDescriptionForClass(Class aClass)

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

Parameters:

aClass - receiver's class whose description is to be returned

Returns:

the EOClassDescription for aClass

See Also:

ClassDescriptionNeededForClassNotification, EOEnterpriseObject.classDescription()

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. The default implementation of this method returns null.

Parameters:

detailKey - identifies the to-one relationship

Returns:

the class description for the class described in detailKey; it may not return anything

classDescriptionForEntityName

public static EOClassDescription classDescriptionForEntityName(String entityName)

Gets the EOClassDescription registered under entityName.

Parameters:

entityName - registration key for the EOClassDescription

Returns:

the EOClassDescription registered under entityName

classDescriptionForKeyPath

public EOClassDescription classDescriptionForKeyPath(String key)

classForAttributeKey

public Class classForAttributeKey(String key)

clientAttributeKeys

public NSArray clientAttributeKeys()

Enables you to find attributes names that are bound to the client-side class that corresponds to the receiver's entity.

Returns:

an array containing the names of the attributes

clientToManyRelationshipKeys

public NSArray clientToManyRelationshipKeys()

Used to determine the to many relationships that are bound to the client side class that corresponds to the receiver's entity.

Returns:

an array containing the names of the to-many relationships

clientToOneRelationshipKeys

public NSArray clientToOneRelationshipKeys()

Used to determine the to-one relationships that are bound to the client side class that corresponds to the receiver's entity.

Returns:

an array containing the names of the to-one relationships

createInstanceWithEditingContext

public EOEnterpriseObject createInstanceWithEditingContext(EOEditingContext editingContext,
                                                           EOGlobalID globalID)

Overridden by subclasses to create an object of the appropriate class in editingContext 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. 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.

Parameters:

editingContext - an EOEditingContext object manages a graph of enterprise objects in an application.

globalID - a compact, universal identifier for a persistent object.

Returns:

default implementation returns null

defaultFormatterForKey

public Format defaultFormatterForKey(String key)

The EOAccess layer's EOEntityClassDescription's implementation returns a Format based on the Java value class specified for key in the associated model file. Code that creates a user interface, like an assistant, can use this method to assign formatters to user interface elements. The default implementation of this method returns null.

Parameters:

key - values are assigned to this

Returns:

the default Format to use; default implementation returns null

defaultFormatterForKeyPath

public Format defaultFormatterForKeyPath(String keyPath)

Similar to defaultFormatterForKey, except this method traverses keyPath before returning the formatter for the key at the end of the path.

Parameters:

keyPath - the path to traverse

Returns:

the Format for the key

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. For example, an Invoice might return DeleteRuleCascade for the relationship "lineItems" (when an invoice is removed from an external store, its line items should be as well).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 the EOAccess layer.)

Parameters:

relationshipKey - the given relationship whose destination is to be treated with the delete rule

Returns:

delete rule indicatingh how to treat the destination;default implementation returns DeleteRuleNullify of the given relationship

See Also:

EOEnterpriseObject.propagateDeleteWithEditingContext( EOEditingContext ec), DeleteRuleCascade, DeleteRuleDeny, DeleteRuleNullify, DeleteRuleNoAction

displayNameForKey

public String displayNameForKey(String key)

Provides a means to display a key in the user interface. By convention, lowercase words are capitalized (for example, "revenue" becomes "Revenue"), and spaces are inserted into words with mixed case (for example, "first Name" becomes "First Name"). This method is useful if a user interface is created from only a class description, such as with an assistant or a Direct To Web application.

Parameters:

key - the key to be displayed

Returns:

the default string to use in the user interface

entityName

public String entityName()

Overridden by subclasses to obtain a unique type name for objects of this class. For example, the EOAccess layer's EOEntityClassDescription returns its EOEntity's name. The default implementation returns null.

Returns:

type name

See Also:

attributeKeys(), toOneRelationshipKeys(), toManyRelationshipKeys()

fetchSpecificationNamed

public EOFetchSpecification fetchSpecificationNamed(String name)

Overridden by subclasses to obtain the fetch specification associated with name. For example, the EOAccess layer's EOEntityClassDescription returns the fetch specification in its EOEntity named name. The default implementation of this method returns null.

Parameters:

name - the name attribute of the object

Returns:

the fetch specification

finalize

public void finalize()
              throws Throwable

Overrides:

finalize in class Object

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 it is invalidated. This method would be used when a provider of EOClassDescriptions (such as an EOModel) has newly become available, or is about to go away. You should rarely need to directly invoke this method unless an external source of information other than an EOModel is used.

inverseForRelationshipKey

public String inverseForRelationshipKey(String relationshipKey)

Overridden by subclasses to obtain the name of the relationship back to the receiver from the destination of the relationship specified with 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"(such that this employee would appear in employee.valueForKey("department").valueForKey("employees")).

Parameters:

relationshipKey - specifies the relationship to evaluate

Returns:

the name of the relationship; default implementation returns null

ownsDestinationObjectsForRelationshipKey

public boolean ownsDestinationObjectsForRelationshipKey(String relationshipKey)

Overridden by subclasses to determine whether the objects at the destination of the relationship specified by relationshipKey should be deleted if they are removed from the relationship. The alternative is that they would be 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.

Parameters:

relationshipKey - specifies the relationship

Returns:

true or false to indicate whether the objects should be deleted; default implementation returns false

propagateDeleteForObject

public void propagateDeleteForObject(EOEnterpriseObject obj,
                                     EOEditingContext ec)

Propagates a delete operation for an object in an EditingContext, according to the delete rules specified in the EOModel. This method is invoked whenever a delete operation needs to be propagated. This is indicated by the delete rule specified in the corresponding EOEntity's relationship key.

Parameters:

obj - object for which the delete operation is to be propagated

ec - an editing context

See Also:

EOEnterpriseObject, deleteRuleForRelationshipKey(String relationshipKey)

registerClassDescription

public static void registerClassDescription(EOClassDescription description,
                                            Class aClass)

Registers an EOClassDescription object for a class in the EOClassDescription cache. You should rarely need to directly invoke this method unless an external source of information other than an EOModel is being used.

Parameters:

description - the EOClassDescription cache

aClass - EOClassDescription object is registered for this

setClassDelegate

public static void setClassDelegate(Object delegate)

Sets the delegate for the entire EOClassDescription class. You can assign a delegate to the EOClassDescription class. EOClassDescription then sends the message to this delegate when delete propagation is about to take place for a particular object. The delegate can either allow or deny the operation for a specified relationship key.

Parameters:

delegate - the delegate for the EOClassDescription class

See Also:

EOClassDescription.ClassDelegate, classDelegate()

superClassDescription

public EOClassDescription superClassDescription()

Overridden by subclasses to return a super class's class description. The default implementation returns null.

toManyRelationshipKeys

public NSArray toManyRelationshipKeys()

Overridden by subclasses to determine the to-many relationship properties of the receiver. To-many relationship properties contain arrays of Enterprise Objects.

Returns:

an NSArray of keys for the to-many relationship properties;default implementation returns NSArray.EmptyArray

See Also:

entityName(), toOneRelationshipKeys(), attributeKeys()

toOneRelationshipKeys

public NSArray toOneRelationshipKeys()

Overridden by subclasses to determine the to-one relationship properties of the receiver. To-one relationship properties are other Enterprise Objects.

Returns:

an array of keys for the to-one relationship properties;default implementation returns NSArray.EmptyArray

See Also:

entityName(), attributeKeys(), toManyRelationshipKeys()

toString

public String toString()

Returns a String representation of the receiver, including its class name, the name of the entity it describes, and attribute keys and all relationship keys of that entity.

Overrides:

toString in class Object

Returns:

returns a String representation of the receiver

See Also:

entityName(), attributeKeys(), toOneRelationshipKeys(), toManyRelationshipKeys()

userPresentableDescriptionForObject

public String userPresentableDescriptionForObject(EOEnterpriseObject eo)

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

Parameters:

eo - an EOEnterpriseObject

Returns:

short description of an object

validateObjectForDelete

public void validateObjectForDelete(EOEnterpriseObject object)
                             throws NSValidation.ValidationException

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

Parameters:

object - the object to be deleted

Throws:

NSValidation.ValidationException - if the delete operation should not proceed.

validateObjectForSave

public void validateObjectForSave(EOEnterpriseObject object)
                           throws NSValidation.ValidationException

Overridden by subclasses to determine whether the values being saved for an object are acceptable. Subclasses should complete normally if the values are acceptable and the save operation should proceed. Otherwise they should throw an exception containing a user presentable (localized) error message.

Parameters:

object - object whose values are to be accepted when it is saved

Throws:

NSValidation.ValidationException - if the values are not acceptable

validateValueForKey

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

Overridden by subclasses to validate a 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.

Parameters:

value - the value to be validated

key - identifies the property of an object

Returns:

null if the value is acceptable; throws exception if unacceptable

Throws:

NSValidation.ValidationException - if the value is unacceptable.

See Also:

EOValidation