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:

• Tracking changes to enterprise objects
• Prompting the user interface to change when object values change
• Prompting the database to change when changes to objects are committed
• Managing undo in the object graph
• Managing uniquing (the mechanism by which the Enterprise Objects technology uniquely identifies enterprise objects and maintains their mapping to stored data)

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:

• By reference for identification within a specific editing context.
• By global ID for universal identification of the same record among multiple stores.

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.