home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2J (Developer) / os42jdev.iso / NextDeveloper / OpenStepConversion / 3.3Headers / eoaccess / EODataSources.h < prev    next >
Encoding:
Text File  |  1994-10-24  |  3.6 KB  |  100 lines
  1. // EODataSources.h
  2. // Copyright (c) 1994, NeXT Computer, Inc. All rights reserved.
  3.  
  4. #import <foundation/NSArray.h>
  5. #import <foundation/NSData.h>
  6. #import <foundation/NSDictionary.h>
  7. #import <foundation/NSObject.h>
  8. #import <foundation/NSString.h>
  9.  
  10. // The EODataSources protocol defines the interface for a source of
  11. // data-bearing objects retrieved from some external store, such as an RDBMS.
  12. // EODataSources uses a simple insert/delete/update/fetch model.
  13. //
  14. // Changes to the objects provided by a data source are made in two phases.
  15. // First, you can modify an object independently of the data source.  These
  16. // changes don't affect the external store until you send an -insertObject:,
  17. // -deleteObject:, or -updateObject: message.  For example, if you release an
  18. // object you received from the data source, it isn't deleted from the
  19. // external store.  Invoking one of the messages listed sends the changes
  20. // associated with the object to the external store.  You must invoke
  21. // -saveObjects to make your changes permanent.  If an external store supports
  22. // rolling back of changes you can invoke -rollback (declared in the
  23. // EORollbackDataSources protocol) to undo the changes made since the last
  24. // -saveObjects message.
  25.  
  26.  
  27. @protocol EODataSources <NSObject>
  28.  
  29. - (NSArray *)keys;
  30.     // Returns the names of the keys that describe the data-bearing objects.
  31.  
  32. - createObject;
  33.     // Returns a new data bearing object with no values set, or nil if the
  34.     // data source won't allow object insertion.  You're responsible for
  35.     // assigning a proper primary key.
  36.  
  37. - (BOOL)insertObject:object;
  38.     // Inserts object into the data source.  Returns YES on success, NO on
  39.     // failure for any reason.
  40.  
  41. - (BOOL)deleteObject:object;
  42.     // Deletes object from the data source.  Returns YES on success, NO on
  43.     // failure for any reason.
  44.  
  45. - (BOOL)updateObject:object;
  46.     // Saves changes to object to the data source.  Returns YES on success,
  47.     // NO on failure for any reason.
  48.  
  49. - (NSArray *)fetchObjects;
  50.     // Returns an array of the data-bearing objects in the data source.
  51.  
  52. - (BOOL)saveObjects;
  53.     // Saves objects to persistent storage, if needed.  Returns YES on
  54.     // success, NO on failure for any reason.
  55.  
  56. - (BOOL)canDelete;
  57.     // Returns YES if the data source allows objects to be deleted, NO if it
  58.     // doesn't.
  59.  
  60. - coerceValue: value forKey: (NSString *)key;
  61.     // Coerce a value to the appropriate type.
  62.     // This method should convert to either an NSNumber, NSString, NSData,
  63.     // a custom type, or nil.  The value return by this method may be safely
  64.     // passed to an EO via takeValuesFromDictionary:.  This method is used
  65.     // by controllers to coerce values supplied from associations before
  66.     // those values are passed on to the EOs.
  67.  
  68. @end
  69.  
  70.  
  71. @protocol EOQualifiableDataSources <EODataSources>
  72.  
  73. - (void)qualifyWithRelationshipKey:(NSString *)key ofObject:sourceObject;
  74.     // qualify ourselves according to the relationship from
  75.     // the given source object
  76.     // A nil object will set up a qualifier that returns no records.
  77.  
  78. @end
  79.  
  80.  
  81. @protocol EOMasterDataSources <EODataSources>
  82.  
  83. - (id <EOQualifiableDataSources>)dataSourceQualifiedByKey:(NSString *)key;
  84.     // Returns a data source that can be set with 
  85.     // qualifyWithRelationshipKey:ofObject to supply objects associated 
  86.     // with a another objects key.  This is a useful way to get an appropriate
  87.     // detail data source for a given master data source.
  88.  
  89. @end
  90.  
  91.  
  92. @protocol EORollbackDataSources <EODataSources>
  93.  
  94. - (void)rollback;
  95.     // Reverses any changes made by -insertObject:, -deleteObject:, or
  96.     // -updateObject: since the data source was last sent a -saveObjects
  97.     // message.
  98.  
  99. @end
  100.