WebObjects Enterprise Objects Programming Guide (Legacy) 2007-07-11 EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, Apple Inc. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR © 2002, 2007 Apple Inc. PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE All rights reserved. ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. No part of this publication may be reproduced, IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, stored in a retrieval system, or transmitted, in INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY any form or by any means, mechanical, DEFECT OR INACCURACY IN THIS DOCUMENT, even electronic, photocopying, recording, or if advised of the possibility of such damages. otherwise, without prior written permission of THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL Apple Inc., with the following exceptions: Any OR WRITTEN, EXPRESS OR IMPLIED. No Apple person is hereby authorized to store dealer, agent, or employee is authorized to make documentation on a single computer for any modification, extension, or addition to this warranty. personal use only and to print copies of Some states do not allow the exclusion or limitation documentation for personal use provided that of implied warranties or liability for incidental or the documentation contains Apple’s copyright consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives notice. you specific legal rights, and you may also have The Apple logo is a trademark of Apple Inc. other rights which vary from state to state. 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 document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Cocoa, Logic, Mac, Mac OS, WebObjects, and Xcode are trademarks of Apple Inc., registered in the United States and other countries. Enterprise Objects is a trademark of Apple Inc. Java is a registered trademark of Oracle and/or its affiliates. Times is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. Simultaneously published in the United States and Canada. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, Contents Introduction Introduction to WebObjects Enterprise Objects Programming Guide 9 Who Should Read This Document 9 Terminology 10 How to Learn About Enterprise Objects 10 Road Map to Concepts 11 Road Map to Tasks 11 See Also 12 Chapter 1 Enterprise Objects Overview 13 What Does Enterprise Objects Do? 13 Why Enterprise Objects? 14 What Is an Enterprise Object? 15 Core Layers 17 Key Concepts of Object-Oriented Programming 18 Key-Value Coding 19 Delegation 19 Notification 20 Principal Methods of Enterprise Objects 21 Chapter 2 Business Objects 23 Reference Entity 24 Designing a Schema 24 Defining the Model 25 Which Enterprise Object Class? 25 Choosing Class Properties 26 Relationships With Other Enterprise Objects 27 Referential Integrity 28 Implementing an Enterprise Object 29 Generating Source Files 29 Fields 32 Change Notification 32 Faulting 33 Accessing an Enterprise Object’s Data 33 Error Handling for Accessors 35 Common Programming Errors 35 Overriding equals or hashcode 36 Immutable Primary Keys 36 Primary Keys and Allows Null 36 Synchronizing Model Changes to Class Files 36 3 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. CONTENTS Instantiating Enterprise Objects 37 Chapter 3 Business Logic 39 Custom Classes 39 Providing Initial Values 40 Adding Validation 41 Validating Before Certain Operations 41 Validating Individual Properties 42 Writing Business Methods 42 Manipulating Relationships 44 Building a Reusable Framework 45 Chapter 4 Core Framework Stack 47 Roles 47 Important Objects 48 How It Stacks Up 49 The Access-Control Divide 49 Object Store Coordinator 50 When to Use Multiple Object Store Coordinators 50 Why So Many Object Stores? 51 Providing Separate Stacks 51 Accessing Lower-Level Objects 53 Chapter 5 Fetching Data 55 Objects Involved in Fetching 55 Flow of Data During a Fetch 56 Enterprise Object Initialization 58 Faulting and Relationship Resolution 60 Data Integrity Mechanisms 62 Uniquing 62 Snapshotting 63 Uniquing and Faulting 64 Ensuring Fresh Data 64 When Does Database Fetching Occur? 64 Distributed Change Notification? 65 Fetch Timestamp 65 Timestamp Lag 65 Other Mechanisms to Ensure Freshness 66 Advanced Faulting 66 Deferred Faulting 66 Batch Faulting 67 Advanced Fetching 68 Prefetching 68 4 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. CONTENTS Entity Caching 69 Raw Row Fetching 70 Raw SQL Fetching 71 Common Delegate Usage 71 Constructing Fetch Specifications 72 Qualifiers 72 Simple String Qualifier 73 Simple Integer Qualifier 73 Wildcard Qualifiers 73 Compound Qualifiers 74 Filtering Fetch Results in Memory 74 Sorting Fetch Results in Memory 74 Accessing Database Keys 75 Chapter 6 Working With the Object Graph 77 Objects Involved in Managing the Object Graph 77 Getting Information About Changed Objects 78 Undoing Changes 78 Discarding Changes 79 Discarding Cached Objects 79 Refreshing Cached Data 80 Working With Objects in Multiple Editing Contexts 81 Memory Management 81 Chapter 7 Saving Data 83 Objects Involved in Saving 83 Phases of Saving 84 Flow of Data During a Save 84 Key Generation 86 Common Delegate Usage 87 Generating Custom Primary Keys 88 Using a Delegate 88 Using Binary Keys 89 Using Compound Primary Keys 90 Chapter 8 Update Strategies 91 Choosing a Strategy 91 Inside Optimistic Locking 92 Multiple Coordinators and Optimistic Locking 93 Using Optimistic Locking 94 Prevention 94 Recovery 95 Recovering and Refaulting 95 5 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. CONTENTS Recovering and Last Write Wins 97 Chapter 9 Connecting to a Database 99 Objects Involved in a Database Connection 99 When Database Connections Are Opened 101 When Database Connections Are Closed 101 Connection Dictionary 101 Storing in a Model File 101 Storing in Code 102 Connecting to Multiple Data Stores 103 Database Channels 103 Providing a Connection Dictionary in Code 104 Providing Multiple Database Channels 104 Closing Database Channels 105 Chapter 10 Concurrency 107 Determining Requirements 107 Maintaining Thread Integrity 108 Appendix A Enterprise Objects in WebObjects 111 Accessing WebObjects in Enterprise Objects 111 Enterprise Objects in WebObjects Builder 112 Appendix B Principal Methods 115 Creating and Initializing Objects 115 Fetching and Accessing Data 115 Identifying and Tracking Objects 116 Working With Fetch Results 117 Manipulating and Changing Objects 117 Document Revision History 119 Glossary 121 6 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. Figures, Tables, and Listings Chapter 1 Enterprise Objects Overview 13 Figure 1-1 High-level view of Enterprise Objects 14 Figure 1-2 Mapping between a database table and an enterprise object 16 Figure 1-3 Mapping between two joined tables and enterprise object instances 17 Figure 1-4 Java method invocations map to SQL expressions 18 Figure 1-5 Notification center and its clients 20 Listing 1-1 Pseudocode illustrating delegation 20 Chapter 2 Business Objects 23 Figure 2-1 A simplified version of the Listing entity 24 Figure 2-2 Key value-coding and relationships as key paths 28 Figure 2-3 Custom classes for entities 29 Listing 2-1 Generated class for simplified Listing entity (EOGenericRecord) 30 Listing 2-2 Generated class for simplified Listing entity (EOCustomObject) 31 Listing 2-3 Comparing two enterprise objects using equals on their global IDs 36 Chapter 3 Business Logic 39 Table 3-1 NSArray operators 44 Listing 3-1 Business method to determine information about the properties sold by a particular agent (assuming EOGenericRecord) 43 Listing 3-2 Business method to determine information about the properties sold by a particular agent (assuming EOCustomObject) 43 Listing 3-3 A business method using an NSArray operator 44 Chapter 4 Core Framework Stack 47 Figure 4-1 Default core objects interaction 48 Figure 4-2 One database context per data source 50 Figure 4-3 Per-session object store coordinators 52 Listing 4-1 Providing separate object store coordinators 52 Listing 4-2 Accessing lower-level objects 53 Chapter 5 Fetching Data 55 Figure 5-1 Flow of data during a fetch 56 Figure 5-2 Relationship between rows, snapshots, and enterprise objects 60 Figure 5-3 Enterprise object as a fault and as fully formed 61 Figure 5-4 Unique enterprise objects in an editing context 63 Figure 5-5 Configure batch faulting for an entity 67 7 Legacy Document | 2007-07-11 | © 2002, 2007 Apple Inc. All Rights Reserved. FIGURES, TABLES, AND LISTINGS Figure 5-6 Configure batch faulting for a relationship 68 Figure 5-7 Enable entity caching 70 Table 5-1 Database type to Java