WebObjects 5.2

Package com.webobjects.eocontrol

Provides infrastructure for creating and manging enterprise objects.

See:
          Description

Interface Summary
EOClassDescription.ClassDelegate The ClassDelegate interface defines a method that the EOClassDescription class can invoke in its delegate.
EODeferredFaulting The EODeferredFaulting interface defines the methods enterprise objects use to manage deferred faulting.
EOEditingContext.Delegate The EOEditingContext.Delegate interface defines methods that an EOEditingContext can invoke in its delegate.
EOEditingContext.Editor An interface for objects that act as higher-level editors of the objects an EOEditingContext contains.
EOEditingContext.MessageHandler This interface is used for error reporting and determining fetch limits.
EOEnterpriseObject The EOEnterpriseObject interface identifies basic enterprise object behavior, defining methods for supporting operations common to all enterprise objects.
EOEventCenter.EventRecordingHandler The EOEventCenter.EventRecordingHandler interface declares the setLoggingEnabled method, which is invoked by the event-logging system when logging is enabled or disabled for an event class.
EOFaulting The EOFaulting interface together with the EOFaultHandler class forms a general mechanism for postponing an object's initialization until it is actually needed.
EOKeyValueArchiver.Delegate The EOKeyValueArchiver.Delegate interface defines methods which can be used by a delegate object of an EOKeyValueArchiver to control the behavior of the archiver object.
EOKeyValueArchiving The EOKeyValueArchiving interface declares the methods that a class must implement so that instances of that class can be encoded and decoded with EOKeyValueArchiver and EOKeyValueUnarchiver objects.
EOKeyValueArchiving.Awaking EOKeyValueArchiving.Awaking is an interface which can be optionally implemented by EOKeyValueArchiving objects if they need to be awaken explicitly at the end of an unarchiving process of an EOKeyValueUnarchiver.
EOKeyValueArchiving.FinishInitialization EOKeyValueArchiving.FinishInitialization is an interface which can be optionally implemented by EOKeyValueArchiving objects if they have special initialization needs at the end of an unarchiving process of an EOKeyValueUnarchiver.
EOKeyValueCoding The EOKeyValueCoding interface defines an extension to the basic NSKeyValueCoding and NSKeyValueCoding.ErrorHandling interfaces.
EOKeyValueCodingAdditions The EOKeyValueCodingAdditions combines (extends) the NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions and EOKeyValueCoding and adds two more methods--takeValuesFromDictionary and valuesForKeys-- which are useful when working with groups of properties.
EOKeyValueUnarchiver.Delegate The EOKeyValueUnarchiver.Delegate interface defines methods which can be used by a delegate object of an EOKeyValueUnarchiver to control the behavior of the unarchiver object.
EOObserving The EOObserving interface, a part of EOControl's change tracking mechanism, declares the objectWillChange method, used by observers to receive notifications that an object has changed.
EOQualifier.Comparison The EOQualifierComparison interface defines methods for comparing values.
EOQualifierEvaluation The EOQualifierEvaluation interface defines a method, evaluateWithObject, that performs in memory evaluation of qualifiers.
EOQualifierVisitor The EOQualifierVisitor interface is intended for internal use only.
EORelationshipManipulation The EORelationshipManipulation interface builds on the basic EOKeyValueCoding interface to allow you to modify to-many relationship properties.
EOSortOrdering.Comparison The Comparison interface defines methods for comparing values.
EOValidation The EOValidation interface in an extension of the NSValidation interface (which defines key-value based validation methods).
 

Class Summary
EOAccountEvent EOAccountEvent class is intended for internal use only.
EOAggregateEvent An instance of the EOAggregateEvent class is used to aggregate multiple EOEvent objects with the same aggregate signature into one event.
EOAndQualifier EOAndQualifier is a subclass of EOQualifier that contains multiple qualifiers.
EOArrayDataSource EOArrayDataSource is a concrete subclass of EODataSource that can be used to provide enterprise objects to a display group (EODisplayGroup from EOInterface or WODisplayGroup from WebObjects) without having to fetch them from the database.
EOClassDescription EOClassDescription provides a mechanism for extending classes with additional meta-data useful for interacting with Enterprise Objects.
EOCooperatingObjectStore EOCooperatingObjectStore is a part of the control layer's object storage abstraction.
EOCustomObject The EOCustomObject class provides a default implementation of the EOEnterpriseObject interface.
EODataSource EODataSource is an abstract class that defines a basic API for providing enterprise objects.
EODelayedObserver The EODelayedObserver class is a part of EOControl's change tracking mechanism.
EODelayedObserverQueue The EODelayedObserverQueue class is a part of EOControl's change tracking mechanism.
EODetailDataSource EODetailDataSource defines a data source for use in master-detail configurations, where operations in the detail data source are applied directly to properties of a master object.
EOEditingContext An EOEditingContext object manages a graph of enterprise objects in an application; this object graph represents an internally consistent view of one or more external stores (most often a database).
EOEditingContext.EditingContextEvent A subclass provided to track events triggered by EOEditingContexts.
EOEvent EOEvent is an abstract class that provides concrete subclasses with a structure for storing information about a logged event.
EOEventCenter EOEventCenter collects and manages EOEvents to measure the duration of operations in any applications.
EOFaultHandler EOFaultHandler is an abstract class that defines the mechanisms that create faults and help them to fire.
EOFetchSpecification An EOFetchSpecification collects the criteria needed to select and order a group of records or enterprise objects, whether from an external repository such as a relational database or an internal store such as an EOEditingContext.
EOGenericRecord EOGenericRecord is a generic enterprise object class that can be used in place of custom classes when custom behavior is not needed.
EOGlobalID An EOGlobalID is a compact, universal, identifier for a persistent object.
EOKeyComparisonQualifier EOKeyComparisonQualifier is a subclass of EOQualifier that compares a named property of an object with a named value of another object.
EOKeyGlobalID EOKeyGlobalID is a concrete subclass of EOGlobalID whose instances, an entity and the primary key values for the object being identified, represent persistent IDs based on EOModel information.
EOKeyValueArchiver EOKeyValueArchiver objects are used to archive a graph of objects into a "property list" with a key-value mechanism.
EOKeyValueArchiving.Support EOKeyValueArchiving.Support is an abstract class that defines a mechanism for one class to provide EOKeyValueArchiving behavior on behalf of another class.
EOKeyValueCoding.DefaultImplementation The EOKeyValueCoding.DefaultImplementation class provides the WebObjects default implementation of the EOKeyValueCoding interface.
EOKeyValueCoding.Utility The EOKeyValueCoding.Utility class is a convenience that allows you to access the properties of EOKeyValueCoding objects and non-EOKeyValueCoding objects using the same code.
EOKeyValueCodingAdditions.DefaultImplementation The EOKeyValueCodingAdditions.DefaultImplementation class provides the WebObjects default implementation of the EOKeyValueCodingAdditions interface.
EOKeyValueCodingAdditions.Utility The EOKeyValueCodingAdditions.Utility class is a convenience that allows you to access the properties of EOKeyValueCodingAdditions objects and non-EOKeyValueCodingAdditions objects using the same code.
EOKeyValueQualifier EOKeyValueQualifier is a subclass of EOQualifier that compares a named property of an object with a supplied value, for example, "salary > 1500".
EOKeyValueUnarchiver EOKeyValueUnarchiver objects are used to re(create) an object graph which was archived into a "property list" with a EOKeyValueArchiver.
EONotQualifier EONotQualifier is a subclass of EOQualifier that contains a single qualifier.
EOObjectStore EOObjectStore is the abstract class that defines the API for an "intelligent" repository of objects, the control layer's object storage abstraction.
EOObjectStoreCoordinator EOObjectStoreCoordinator provides the abstraction of a single object store by coordinating one or more EOCooperatingObjectStores.
EOObserverCenter EOObserverCenter is the central player in EOControl's change tracking mechanism.
EOObserverProxy The EOObserverProxy class is a part of EOControl's change tracking mechanism.
EOOrQualifier EOOrQualifier is a subclass of EOQualifier that contains multiple qualifiers.
EOQualifier EOQualifier is an abstract class for objects that hold information used to restrict selections on objects or database rows according to specified criteria.
EOQualifier.ComparisonSupport The Java Client EOQualifier.ComparisonSupport class provides default implementations of the EOQualifierComparison interface.
EOQualifierVariable EOQualifierVariable defines objects that serve as placeholders in the qualifier.
EOSharedEditingContext The EOSharedEditingContext class defines a mechanism that allows EOEditingContexts to share enterprise objects for reading.
EOSortOrdering An EOSortOrdering object specifies the way that a group of objects should be sorted, using a property key and a method selector for comparing values of that property.
EOSortOrdering.ComparisonSupport ComparisonSupport provides default implementations of the EOSortOrdering.Comparison interface and a registry for support objects.
EOTemporaryGlobalID An EOTemporaryGlobalID object identifies a newly created enterprise object before it's saved to an external store.
 

Exception Summary
 

Package com.webobjects.eocontrol Description

Provides infrastructure for creating and manging enterprise objects.

Introduction

The EOControl framework defines one of the layers of the Enterprise Objects technology--the control layer. It provides an infrastructure for enterprise objects that is independent of your application's user interface and its storage mechanism. The control layer dynamically manages the interaction between enterprise objects, the access layer, and the interface layer by:

The control layer's major areas of responsibility and the key classes involved are described in the following table:


Responsibility Classes
"Tracking Enterprise Objects Changes" EOObserverCenter EODelayedObserverQueue EODelayedObserver EOObserverProxy EOObserving (interface)
"Object Storage Abstraction" EOObjectStore EOCooperatingObjectStore EOObjectStoreCoordinator EOGlobalID EOKeyGlobalID EOTemporaryGlobalID
Query specification EOFetchSpecification EOQualifier EOSortOrdering
Interaction with enterprise objects EOEnterpriseObject (basic enterprise object behavior) EOClassDescription (validation support) EOGenericRecord EOCustomObject
Simple source of objects (for display groups) EODataSource EODetailDataSource

The following sections describe each responsibility in greater detail.


Tracking Enterprise Objects Changes

EOControl provides four classes and an interface that form an efficient, specialized mechanism for tracking changes to enterprise objects and for managing the notification of those changes to interested observers. EOObserverCenter is the central manager of change notification. It records observers and the objects they observe, and it distributes notifications when the observable objects change. Observers implement the EOObserving interface, which defines one method, objectWillChange. Observable objects (generally enterprise objects) invoke their willChange method before altering their state, which causes all observers to receive an objectWillChange message.

The other three classes add to the basic observation mechanism. EODelayedObserverQueue alters the basic, synchronous change notification mechanism by offering different priority levels, which allows observers to specify the order in which they're notified of changes. EODelayedObserver is an abstract superclass for objects that observe other objects (such as the EOInterface layer's EOAssociation classes). Finally, EOObserverProxy is a subclass of EODelayedObserver that forwards change messages to a target object, allowing objects that don't inherit from EODelayedObserver to take advantage of this mechanism.

The major observer in the Enterprise Objects technology is EOEditingContext, which implements its objectWillChange method to record a snapshot for the object about to change, register undo operations in an NSUndoManager, and record the changes needed to update objects in its EOObjectStore. Because some of these actions--such as examining the object's new state--can only be performed after the object has changed, an EOEditingContext sets up a delayed message to itself, which it gets at the end of the run loop. Observers that only need to examine an object after it has changed can use the delayed observer mechanism, described in the EODelayedObserver and EODelayedObserverQueue class specifications.


Object Storage Abstraction

The control layer provides an infrastructure that's independent of your application's storage mechanism (typically a database) by defining an API for an "intelligent" repository of objects, whether it's based on external data or whether it manages objects entirely in memory. EOObjectStore is an abstract class that defines that basic API, setting up the framework for constructing and registering enterprise objects, servicing object faults, and committing changes made in an EOEditingContext. Subclasses of EOObjectStore implement the API in terms of their specific storage mechanism.


Subclasses of EOObjectStore

EOEditingContext is the principal subclass of EOObjectStore and is used for managing objects in memory. For stores based on external data, there are several subclasses. EOCooperatingObjectStore defines stores that work together to manage data from several distinct sources (such as different databases). The access layer's EODatabaseContext is actually a subclass of this class. A group of cooperating stores is managed by another subclass of EOObjectStore, EOObjectStoreCoordinator. If you're defining a subclass of EOObjectStore, it's probably one based on an external data repository, and it should therefore inherit from EOCooperatingObjectStore so as to work well with an EOObjectStoreCoordinator--though this isn't required.

EODatabaseContext provides objects from relational databases and is therefore provided by Enterprise Objects's access layer. It is the class that defines the interaction between the control and access layers. Database contexts and other object stores based on external data are often shared by several editing contexts to conserve database connections.



Registering Enterprise Objects

An object store identifies its objects in two ways:

A global ID is defined by three classes: EOGlobalID, EOKeyGlobalID, and EOTemporaryGlobalID. EOGlobalID is an abstract class that forms the basis for uniquing in the Enterprise Objects technology. EOKeyGlobalID is a concrete subclass of EOGlobalID whose instances represent persistent IDs based on the access layer's EOModel information: An entity and the primary key values for the object being identified. An EOTemporaryGlobalID object is used to identify a newly created enterprise object before it's saved to an external store. For more information, see the EOGlobalID class specification.


Servicing Faults

For external repositories, an object store might delay fetching an object's data, instead creating an empty enterprise object (called a fault). When a fault is accessed (sent a message), it triggers its object store to fetch its data and fill the fault with its data. This preserves both the object's reference and its EOGlobalID, while saving the cost of fetching data that might not be used. Faults are typically created for the destinations of relationships for objects that are explicitly fetched. See the EOFaultHandler class specification for more information.


Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.