PATH
Documentation > WebObjects 4.5 >
EOControl Reference
- Inherits
from:
- (com.apple.client.eocontrol) Object
(com.apple.yellow.eocontrol) NSObject
- Package:
- com.apple.client.eocontrol
- com.apple.yellow.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 "Using EOClassDescription".
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".
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
public static Object classDelegate()
Returns the delegate for the EOClassDescription
class (as opposed to EOClassDescription instances).See
Also: setClassDelegate
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.
public static EOClassDescription classDescriptionForEntityName(String entityName)
Returns the EOClassDescription registered under entityName.
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
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).
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
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.
See Also: entityName, toOneRelationshipKeys, toManyRelationshipKeys
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.
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.
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.
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.
public NSFormatter 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.
public NSFormatter defaultFormatterForKey(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).
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: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)
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.
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.See
Also: attributeKeys, toOneRelationshipKeys, toManyRelationshipKeys
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.
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.
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.)
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
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. See
Also: entityName, toOneRelationshipKeys, attributeKeys
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.See
Also: entityName, toManyRelationshipKeys, attributeKeys
public String userPresentableDescriptionForObject(Object 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.
public void validateObjectForDelete(EOEnterpriseObject object)
Overridden by subclasses to determine whether
it's permissible to delete object.
Subclasses should complete normally if the delete operation should
proceed, or raise an exception containing a user-presentable (localized)
error message if not. EOClassDescription's implementation of this
method completes normally.
public void validateObjectForSave(EOEnterpriseObject object)
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 raise an exception
containing a user-presentable (localized) error message if not. EOClassDescription's
implementation of this method completes normally.
public Object validateValueForKey(
Object value,
String key)
Overridden by subclasses to validate value.
Subclasses should return null if the value is acceptable, or raise 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 validate Key .
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 |