WebObjects 5.2.3

com.webobjects.eocontrol
Class EOClassDescription

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


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

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

See Also:
Constant Field Values

DeleteRuleDeny

public static final int DeleteRuleDeny
Refuse delete operation if the source object has any destination objects.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values
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: 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
Throws:
Throwable

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.

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.
NSValidation.ValidationException

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
NSValidation.ValidationException

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.
NSValidation.ValidationException
See Also:
EOValidation

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

Copyright © 2004 Apple Computer, Inc.