Coverage Report - net.wotonomy.control.EOObjectStore
 
Classes in this File Line Coverage Branch Coverage Complexity
EOObjectStore
0% 
N/A 
1
 
 1  
 /*
 2  
 Wotonomy: OpenStep design patterns for pure Java applications.
 3  
 Copyright (C) 2000 Michael Powers
 4  
 
 5  
 This library is free software; you can redistribute it and/or
 6  
 modify it under the terms of the GNU Lesser General Public
 7  
 License as published by the Free Software Foundation; either
 8  
 version 2.1 of the License, or (at your option) any later version.
 9  
 
 10  
 This library is distributed in the hope that it will be useful,
 11  
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 12  
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 13  
 Lesser General Public License for more details.
 14  
 
 15  
 You should have received a copy of the GNU Lesser General Public
 16  
 License along with this library; if not, see http://www.gnu.org
 17  
 */
 18  
 
 19  
 package net.wotonomy.control;
 20  
 
 21  
 import java.util.List;
 22  
 import java.util.Map;
 23  
 
 24  
 import net.wotonomy.foundation.NSArray;
 25  
 
 26  
 /**
 27  
 * EOObjectStore defines an object repository that tracks
 28  
 * object creations, deletions, and updates made by 
 29  
 * EOEditingContexts. <br><br>
 30  
 *
 31  
 * A concrete implementation would probably write these 
 32  
 * changes to some kind of persistent storage, like a
 33  
 * database. <br><br>
 34  
 *
 35  
 * EOEditingContext is itself a subclass of EOObjectStore
 36  
 * that requires an EOObjectStore parent for committing
 37  
 * its changes.  This means that EOEditingContexts can
 38  
 * use other EOEditingContexts as their parent, but there
 39  
 * still must exist an EOObjectStore as the root of the 
 40  
 * editing graph.
 41  
 *
 42  
 * @author michael@mpowers.net
 43  
 * @author $Author: cgruber $
 44  
 * @version $Revision: 894 $
 45  
 */
 46  
 public abstract class EOObjectStore
 47  
 {
 48  
     /**
 49  
     * Key for the user info of ObjectsChangedInStoreNotifications.
 50  
     * The key should retrieve an array of deleted EOGlobalIDs.
 51  
     */
 52  
     public static final String DeletedKey = "deleted";
 53  
 
 54  
     /**
 55  
     * Key for the user info of ObjectsChangedInStoreNotifications.
 56  
     * The key should retrieve an array of inserted EOGlobalIDs.
 57  
     */
 58  
     public static final String InsertedKey = "inserted";
 59  
 
 60  
     /**
 61  
     * Key for the user info of ObjectsChangedInStoreNotifications.
 62  
     * The key should retrieve an array of updated EOGlobalIDs.
 63  
     * EOEditingContexts should refault their copies of these objects.
 64  
     */
 65  
     public static final String UpdatedKey = "updated";
 66  
 
 67  
     /**
 68  
     * Key for the user info of ObjectsChangedInStoreNotification.
 69  
     * The key should retrieve an array of EOGlobalIDs.
 70  
     */
 71  
     public static final String InvalidatedKey = "invalidated";
 72  
 
 73  
     /**
 74  
     * Key for the NSNotification posted when this object store
 75  
     * is asked to invalidate all objects.  Object of the notification
 76  
     * will be this object store, and user info will contain the
 77  
     * InvalidatedKey.
 78  
     */
 79  
     public static final String 
 80  
         InvalidatedAllObjectsInStoreNotification = 
 81  
         "EOInvalidatedAllObjectsInStoreNotification";
 82  
 
 83  
     /**
 84  
     * Key for the NSNotification posted when this object store
 85  
     * is changed.  Object of the notification will be this object 
 86  
     * store, and user info will contain InsertedKey, UpdatedKey,
 87  
     * DeletedKey, and InvalidatedKey.
 88  
     */
 89  
     public static final String  
 90  
         ObjectsChangedInStoreNotification = 
 91  
         "EOObjectsChangedInStoreNotification";
 92  
  
 93  
     /**
 94  
     * Default constructor is responsible for initializing
 95  
     * internal state.
 96  
     */ 
 97  0
         public EOObjectStore ()
 98  0
     {
 99  0
     }
 100  
 
 101  
     /**
 102  
     * Called by editing contexts when they no longer
 103  
     * need to track the specified id.  You will not need
 104  
     * to call this method, but you use use it for a hint
 105  
     * that the specified global id is not in use by that
 106  
     * child editing context.
 107  
     */
 108  
     public void editingContextDidForgetObjectWithGlobalID ( 
 109  
         EOEditingContext aContext,
 110  
         EOGlobalID aGlobalID )
 111  
     {
 112  0
     }   
 113  
         
 114  
     /**
 115  
     * Returns a List of objects associated with the object 
 116  
     * with the specified id for the specified property 
 117  
     * relationship, or may return a placeholder array that
 118  
     * will defer the fetch until accessed (an array fault).
 119  
     * All objects must be registered the specified editing context.
 120  
     * The specified relationship key must produce a result of
 121  
     * type Collection for the source object or an exception is thrown.
 122  
     */
 123  
     public abstract NSArray arrayFaultWithSourceGlobalID ( 
 124  
         EOGlobalID aGlobalID,
 125  
         String aRelationship,
 126  
         EOEditingContext aContext );
 127  
      
 128  
     /**
 129  
     * Returns the object for the specified id.
 130  
     * The returned object may be a fault.
 131  
     * The object will be registered in the
 132  
     * specified editing context.
 133  
     */
 134  
     public abstract /*EOEnterpriseObject*/ Object faultForGlobalID ( 
 135  
         EOGlobalID aGlobalID,
 136  
         EOEditingContext aContext );
 137  
         
 138  
     /**
 139  
     * Returns a fault representing an object of 
 140  
     * the specified entity type with values from 
 141  
     * the specified dictionary.  The fault should
 142  
     * belong to the specified editing context.
 143  
     */        
 144  
     public abstract /*EOEnterpriseObject*/ Object faultForRawRow ( 
 145  
         Map aDictionary,
 146  
         String anEntityName,
 147  
         EOEditingContext aContext );
 148  
         
 149  
     /**
 150  
     * Given a newly instantiated object, this method 
 151  
     * initializes its properties to values appropriate
 152  
     * for the specified id.  The object should already
 153  
     * belong to the specified editing context.  
 154  
     * This method is called to populate faults.
 155  
     */        
 156  
     public abstract void initializeObject ( 
 157  
         /*EOEnterpriseObject*/ Object eo,
 158  
         EOGlobalID aGlobalID,
 159  
         EOEditingContext aContext );
 160  
         
 161  
     /**
 162  
     * Remove all values from all objects in memory,
 163  
     * turning them into faults, and posts an NSNotification
 164  
     * that all objects have been invalidated.
 165  
     * The notification should be named with the string
 166  
     * constant InvalidatedAllObjectsInStoreNotification
 167  
     * with this object store as the object and no user info.
 168  
     */
 169  
     public abstract void invalidateAllObjects ();
 170  
     
 171  
     /**
 172  
     * Removes values with the specified ids from memory,
 173  
     * turning them into faults, and posts a notification
 174  
     * that those objects have been invalidated.
 175  
     * The notification should be named with the string
 176  
     * constant ObjectsChangedInStoreNotification
 177  
     * with this object store as the object and user info
 178  
     * containing a key named InvalidateKey that returns
 179  
     * a List of the EOGlobalIDs of the invalidated objects.
 180  
     */
 181  
     public abstract void invalidateObjectsWithGlobalIDs ( 
 182  
         List aList );
 183  
         
 184  
     /**
 185  
     * Returns whether the object corresponding to the
 186  
     * specified id is locked.  The concept of object
 187  
     * locking is implementation-specific.
 188  
     */
 189  
     public abstract boolean isObjectLockedWithGlobalID ( 
 190  
         EOGlobalID aGlobalID,
 191  
         EOEditingContext aContext );
 192  
         
 193  
     /**
 194  
     * Locks the object corresponding to the
 195  
     * specified id is locked.  The concept of object
 196  
     * locking is implementation-specific.
 197  
     * The lock may be released when objects are
 198  
     * invalidated or commited, but this behavior
 199  
     * is not required.
 200  
     */
 201  
     public abstract void lockObjectWithGlobalID ( 
 202  
         EOGlobalID aGlobalID,
 203  
         EOEditingContext aContext );
 204  
         
 205  
     /**
 206  
     * Returns a List of objects associated with the object 
 207  
     * with the specified id for the specified property 
 208  
     * relationship.  This method may not return an array fault
 209  
     * because array faults call this method to fetch on demand.
 210  
     * All objects must be registered the specified editing context.
 211  
     * The specified relationship key must produce a result of
 212  
     * type Collection for the source object or an exception is thrown.
 213  
     */
 214  
     public abstract NSArray objectsForSourceGlobalID ( 
 215  
         EOGlobalID aGlobalID,
 216  
         String aRelationship,
 217  
         EOEditingContext aContext );
 218  
         
 219  
     /**
 220  
     * Returns a List of objects the meet the criteria of
 221  
     * the supplied specification.  Faults are not allowed in the array.
 222  
     * Each object is registered with the specified editing context.
 223  
     * If any object is already fetched in the specified context, 
 224  
     * it is not refetched and that object should be used in the array.
 225  
     */
 226  
     public abstract NSArray objectsWithFetchSpecification ( 
 227  
         EOFetchSpecification aFetchSpec,
 228  
         EOEditingContext aContext );
 229  
         
 230  
     /**
 231  
     * Removes all values from the specified object, 
 232  
     * converting it into a fault for the specified id.
 233  
     * New or deleted objects should not be refaulted.
 234  
     */
 235  
     public abstract void refaultObject ( 
 236  
         Object anObject,
 237  
         EOGlobalID aGlobalID,
 238  
         EOEditingContext aContext );
 239  
         
 240  
     /**
 241  
     * Writes all changes in the specified editing context
 242  
     * to the respository.  The object store is expected to
 243  
     * post a notification that should be named with the string
 244  
     * constant ObjectsChangedInStoreNotification
 245  
     * with this object store as the object and user info
 246  
     * containing keys named UpdatedKey, InsertedKey, and 
 247  
     * DeletedKey that return Lists of the EOGlobalIDs of the 
 248  
     * corresponding objects.
 249  
     */
 250  
     public abstract void saveChangesInEditingContext ( 
 251  
         EOEditingContext aContext ); 
 252  
 }
 253  
 
 254  
 /*
 255  
  * $Log$
 256  
  * Revision 1.2  2006/02/16 16:47:14  cgruber
 257  
  * Move some classes in to "internal" packages and re-work imports, etc.
 258  
  *
 259  
  * Also use UnsupportedOperationExceptions where appropriate, instead of WotonomyExceptions.
 260  
  *
 261  
  * Revision 1.1  2006/02/16 13:19:57  cgruber
 262  
  * Check in all sources in eclipse-friendly maven-enabled packages.
 263  
  *
 264  
  * Revision 1.15  2003/12/18 15:37:38  mpowers
 265  
  * Changes to retain ability to work with objects that don't necessarily
 266  
  * implement EOEnterpriseObject.  I would still like to preserve this case
 267  
  * for general usage, however the access package is free to assume that
 268  
  * those objects will be EOs and cast appropriately.
 269  
  *
 270  
  * Revision 1.14  2003/08/19 01:53:12  chochos
 271  
  * EOObjectStore had some incompatible return types (Object instead of EOEnterpriseObject, in fault methods mostly). It's internally consistent but I hope it doesn't break anything based on this, even though fault methods mostly throw exceptions for now.
 272  
  *
 273  
  * Revision 1.13  2002/02/13 21:20:15  mpowers
 274  
  * Updated comments.
 275  
  *
 276  
  * Revision 1.12  2001/05/05 23:05:42  mpowers
 277  
  * Implemented Array Faults.
 278  
  *
 279  
  * Revision 1.11  2001/02/21 21:17:32  mpowers
 280  
  * Now retaining a reference to the recent changes observer.
 281  
  * Better documented need to retain reference.
 282  
  * Started implementing notifications.
 283  
  *
 284  
  * Revision 1.10  2001/02/16 22:51:29  mpowers
 285  
  * Now deep-cloning objects passed between editing contexts.
 286  
  *
 287  
  * Revision 1.9  2001/02/16 18:34:19  mpowers
 288  
  * Implementing nested contexts.
 289  
  *
 290  
  * Revision 1.8  2001/02/15 21:13:30  mpowers
 291  
  * First draft implementation is complete.  Now on to debugging.
 292  
  *
 293  
  * Revision 1.7  2001/02/14 23:03:02  mpowers
 294  
  * A near-complete first draft of EOEditingContext.
 295  
  *
 296  
  * Revision 1.6  2001/02/13 23:24:29  mpowers
 297  
  * Implementing more of editing context.
 298  
  *
 299  
  * Revision 1.5  2001/02/12 20:36:36  mpowers
 300  
  * Documented methods.
 301  
  *
 302  
  * Revision 1.4  2001/02/09 22:09:34  mpowers
 303  
  * Completed implementation of EOObjectStore.
 304  
  *
 305  
  * Revision 1.3  2001/02/06 15:24:11  mpowers
 306  
  * Widened parameters on abstract method to fix build.
 307  
  *
 308  
  * Revision 1.2  2001/02/06 14:57:42  mpowers
 309  
  * Defined abstract methods.
 310  
  *
 311  
  * Revision 1.1.1.1  2000/12/21 15:46:42  mpowers
 312  
  * Contributing wotonomy.
 313  
  *
 314  
  * Revision 1.2  2000/12/20 16:25:35  michael
 315  
  * Added log to all files.
 316  
  *
 317  
  *
 318  
  */
 319  
     
 320