EOControl Framework Objective–C API Reference COPYRIGHT PAGE Apple Computer, Inc. © 1999 Apple Computer, Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Computer, Inc., except to make a backup copy of any documentation provided on CD-ROM. The Apple logo is a trademark of Apple Computer, Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this book. Apple retains all intellectual property rights associated with the technology described in this book. This book is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Macintosh, and WebObjects are trademarks of Apple Computer, Inc., registered in the United States and other countries. Enterprise Objects is a trademark of Apple Computer, Inc. NeXT, the NeXT logo, OPENSTEP, Enterprise Objects Framework, Objective–C, and WEBSCRIPT are trademarks of NeXT Software, Inc. Adobe, Acrobat, and PostScript are trademarks of Adobe Systems Incorporated or its subsidiaries and may be registered in certain jurisdictions. Helvetica and Palatino are registered trademarks of Linotype-Hell AG and/or its subsidiaries. ITC Zapf Dingbats is a registered trademark of International Typeface Corporation. ORACLE is a registered trademark of Oracle Corporation, Inc. SYBASE is a registered trademark of Sybase, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. Windows NT is a trademark of Microsoft Corporation. All other trademarks mentioned belong to their respective owners. Simultaneously published in the United States and Canada. Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD “AS IS,” AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. 2 FRAMEWORK The EOControl Framework Framework: System/Library/Frameworks/EOControl.framework Header File Directories: System/Library/Frameworks/EOControl.framework/Headers Introduction The EOControl framework defines one of the layers of the Enterprise Objects Framework architecture—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: I Tracking changes to enterprise objects I Prompting the user interface to change when object values change I Prompting the database to change when changes to objects are committed I Managing undo in the object graph I Managing uniquing (the mechanism by which Enterprise Objects Framework uniquely identifies enterprise objects and maintains their mapping to stored data in the database) 3 FRAMEWORK The EOControl Framework The control layer’s major areas of responsibility and the key classes involved are described in the following table: Responsibility Classes “Tracking Enterprise Objects EOObserverCenter Changes” EODelayedObserverQueue EODelayedObserver EOObserverProxy EOObserving (protocol) “Object Storage Abstraction” EOObjectStore EOCooperatingObjectStore EOObjectStoreCoordinator EOGlobalID EOKeyGlobalID EOTemporaryGlobalID Query specification EOFetchSpecification EOQualifier EOSortOrdering Interaction with enterprise EOEnterpriseObject (basic enterprise object behavior) objects EOClassDescription (validation support) EOGenericRecord Simple source of objects (for EODataSource display groups) EODetailDataSource The following sections describe each responsibility in greater detail. 4 FRAMEWORK The EOControl Framework Tracking Enterprise Objects Changes EOControl provides four classes and a protocol 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 protocol, 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 Enterprise Objects Framework 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. 5 FRAMEWORK The EOControl Framework 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 Framework’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. Object store subclasses cooperate with one another as illustrated in the following: EOEditing EOEditing EOEditing Context Context Context EOObjectStore Coordinator EODatabase EODatabase Context Context Registering Enterprise Objects An object store identifies its objects in two ways: I By reference for identification within a specific editing context 6 FRAMEWORK The EOControl Framework I 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