EOClassDescription.Concepts

As noted above, Enterprise Objects Framework implements a default subclass of EOClassDescription in EOAccess, EOEntityClassDescription. In the typical scenario in which an enterprise object has a corresponding model file, a particular operation (such as validating a value) results in the broadcast of an EOClassDescriptionNeeded... notification (an or an ). When an EOModel object receives such a notification, it registers the metadata (class description) for the EOEntity on which the enterprise object is based. (EOModel and EOEntity are defined in EOAccess.)

An enterprise object takes advantage of the metadata registered for it by using the EOClassDescription-related methods defined in the EOEnterpriseObject interface (and implemented in EOCustomObject and EOGenericRecord). Primary among these methods is , which returns the class description associated with the enterprise object. Through this class description the enterprise object has access to all of the information relating to its entity in a model file.

In addition to methods that return information based on an enterprise object's class description, the EOClassDescription-related methods the interface defines include methods that are automatically invoked when a particular operation occurs. These include validation methods and methods that are invoked whenever an enterprise object is inserted or fetched.

All of this comes together in your running application. When a user tries to perform a particular operation on an enterprise object (such as attempting to delete it), the EOEditingContext sends these validation messages to your enterprise object, which in turn (by default) forwards them to its EOClassDescription. Based on the result, the operation is either accepted or refused. For example, referential integrity constraints in your model might state that you can't delete a department object that has employees. If a user attempts to delete a department that has employees, an exception is returned and the deletion is refused.

For the most part, you don't need to programmatically interact with EOClassDescription. It extends the behavior of your enterprise objects transparently. However, there are two cases in which you do need to programmatically interact with it:

As described above, EOEnterpriseObject defines several EOClassDescription-related methods. It's common for enterprise object classes to override the following methods to either perform validation, to assign default values (), or to provide additional initialization to newly fetched objects ().

For example, an enterprise object class can implement a validateForSave method that checks the values of salary and jobLevel properties before allowing the values to be saved to the database:

public void validateForSave() throw EOValidation.Exception {if (salary > 1500 && jobLevel < 2) {throw new EOValidation.Exception("The salary is too high for that position!");}// pass the check on to the EOClassDescriptionsuper.validateForSave();}

For more discussion of this subject, see the chapter "Designing Enterprise Objects" in the Enterprise Objects Framework Developer's Guide , and the interface specification.

Although an EOModel is the most common source of an EOClassDescription for a class, it isn't the only one. Objects that don't have an EOModel can implement EOClassDescription methods directly as instance methods, and the rest of the Framework will treat them just as it does enterprise objects that have this information provided by an external EOModel.

There are a few reasons you might want to do this. First of all, if your object implements the methods , , , and , EOEditingContexts can snapshot the object and thereby provide undo for it.

Secondly, you might want to implement EOClassDescription's validation or referential integrity methods to add these features to your classes.

Implementing EOClassDescription methods on a per-class basis in this way is a good alternative to creating a subclass of EOClassDescription.

You create a subclass of EOClassDescription when you want to use an external source of information other than an EOModel to extend your objects. Another possible scenario is if you've added information to an EOModel (such as in its user dictionary) and you want that information to become part of your class description--in that case, you'd probably want to create a subclass of the access layer's EOEntityClassDescription.

When you create a subclass of EOClassDescription, you only need to implement the methods that have significance for your subclass.

If you're using an external source of information other than an EOModel, you need to decide when to register class descriptions, which you do by invoking the method . You can either register class descriptions in response to a EOClassDescriptionNeeded... notification (an or an ), or you can register class descriptions at the time you initialize your application (in other words, you can register all potential class descriptions ahead of time). The default implementation in Enterprise Objects Framework is based on responding to the EOClassDescriptionNeeded... notifications. When an EOModel receives one of these notifications, it supplies a class description for the specified class or entity name by invoking

There are only three methods in EOClassDescription that have meaningful implementations (that is, that don't either return null or simply return without doing anything): , , and . The default behavior of the rest of the methods in Enterprise Objects Framework comes from the implementation in the access layer's EOClassDescription subclass EOEntityClassDescription. For more information, see the EOEntityClassDescription class specification.

You can assign a delegate to the EOClassDescription class. EOClassDescription sends the message to its 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. For more information, see the method description for.