home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2J (Developer) / os42jdev.iso / NextDeveloper / OpenStepConversion / 3.3Headers / eoaccess / EODatabaseChannel.h < prev    next >
Encoding:
Text File  |  1994-11-14  |  9.6 KB  |  233 lines
  1. // EODatabaseChannel.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. @class EODatabaseContext;
  11. @class EOQualifier;
  12. @class EODatabaseChannel;
  13. @class EOAdaptorChannel;
  14. @class EORelationship;
  15. @class EOEntity;
  16.  
  17. @interface NSObject(EODatabaseChannelNotification)
  18. - (void)awakeForDatabaseChannel:(EODatabaseChannel *)channel;
  19.     // Invoked when an object has been fully instantiated from a database.
  20.     // Your Enterprise Object classes should implement this method as needed.
  21. @end
  22.  
  23.  
  24. // An EODatabaseChannel manipulates records as instances of classes specified
  25. // in the EOModel.
  26. //
  27. // An EODatabaseChannel works with an EODatabaseContext object, which handles
  28. // transactions.  All of an EODatabaseChannel operations take place within the
  29. // context of transactions controlled or tracked by the EODatabaseContext.
  30. // An EODatabaseContext may work with several EODatabaseChannels, but a
  31. // channel is associated with only one context.
  32. //
  33. // Not all adaptors support multiple channels per context.
  34. //
  35. // An EODatabaseChannel creates a EOAdaptorChannel when initialized, and uses
  36. // this object to actually communicate with the database server.
  37.  
  38.  
  39. @interface EODatabaseChannel:NSObject
  40. {
  41.     EODatabaseContext *_databaseContext;
  42.     id _delegate;
  43.     EOAdaptorChannel *_adaptorChannel;
  44.     EOEntity *_currentEntity;
  45.     NSMutableArray *_fetchProperties;
  46.     NSMutableArray *_faultProperties; // Not used, kept for 1.0 compatibility
  47.     NSMutableArray *_writeProperties; // Not used, kept for 1.0 compatibility
  48.     EORelationship *_currentRelationship;
  49. }
  50.  
  51. - initWithDatabaseContext:(EODatabaseContext *)databaseContext;
  52.     // Initializes a newly allocated EODatabaseChannel with databaseContext
  53.     // as the context it works in. Returns self, or nil if no more channels
  54.     // can be associated with databaseContext.
  55.  
  56. - (BOOL)isOpen;
  57.     // Returns YES if the channel has been opened with -openChannel,
  58.     // NO if not.
  59.  
  60. - (BOOL)openChannel;
  61.     // This method puts the channel and both its context and database into a
  62.     // state where they are ready to perform operations.  Returns YES
  63.     // on success, NO on failure for any reason.
  64.  
  65. - (void)closeChannel;
  66.     // This method disconnects the channel, disconnects the channel's context
  67.     // if the context has no other channels open, and then disconnects the
  68.     // database if it has no additional contexts open.
  69.  
  70. - (BOOL)insertObject:object;
  71.     // Inserts object's attribute values as a row into the database.  Returns
  72.     // YES if successful, NO if not.
  73.  
  74. - (BOOL)updateObject:object;
  75.     // Updates the row in the database corresponding to object.  Returns YES
  76.     // if successful, NO if not.
  77.  
  78. - (BOOL)deleteObject:object;
  79.     // Deletes the row in the database corresponding to object.  Returns YES
  80.     // if successful, NO if not.
  81.  
  82. - (void)setCurrentEntity:(EOEntity *)entity;
  83.     // Sets an internal entity variable that is used for fetching.
  84.     // -fetchWithZone: uses the currentEntity to determine the class of object
  85.     // to fetch.  EODatabaseChannel clients can invoke this method after
  86.     // issuing a select statement by sending -evaluateExpression: to the
  87.     // database channel's adaptor channel to set the class of object fetched.
  88.  
  89. - (BOOL)selectObjectsDescribedByQualifier:(EOQualifier *)qualifier
  90.     fetchOrder:(NSArray *)fetchOrder;
  91.     // Selects objects by evaluating the qualifier; when fetched, objects will
  92.     // be returned in the order prescribed by the fetch order. Returns YES on
  93.     // success, NO on failure of any kind.
  94.  
  95. - fetchWithZone:(NSZone *)zone;
  96.     // Fetches and returns the next selected object; returns nil when there
  97.     // are no more objects in the result set.
  98.  
  99. - (BOOL)isFetchInProgress;
  100.     // Returns YES if the database channel is fetching, NO otherwise. A
  101.     // database channel is fetching if it's been sent a successful
  102.     // -selectObjectsDescribedByQualifier:... message. A database channel
  103.     // stops fetching when there are no more objects to fetch or when it's
  104.     // sent a -cancelFetch message.
  105.  
  106. - (void)cancelFetch;
  107.     // Cancels any fetch currently in progress.
  108.  
  109. - (BOOL)refetchObject:object;
  110.     // Refetches the row associated with object from the database. object
  111.     // is modified by this method. Returns YES on success, NO on failure for
  112.     // any reason.
  113.  
  114. - (BOOL)lockObject:object;
  115.     // Fetches the properties comprising object's snapshot and compares the
  116.     // fetched values with the values stored in the snapshot, locking the
  117.     // constituent rows in the process.  Returns YES if all values are the
  118.     // same; returns NO and fails if any of the values differ.
  119.  
  120. - (EODatabaseContext *)databaseContext;
  121.     // Returns the EODatabaseContext that controls transactions for the
  122.     // channel.
  123.  
  124. - (EOAdaptorChannel *)adaptorChannel;
  125.     // Returns the EOAdaptorChannel used by the EODatabaseChannel for
  126.     // communication with the database server.
  127.  
  128. - (void)setDelegate:delegate;
  129. - delegate;
  130.     // These methods return/set the delegate of the database channel.
  131.  
  132. @end
  133.  
  134.  
  135. @interface NSObject (EODatabaseChannelDelegatation)
  136.  
  137. - databaseChannel:channel willInsertObject:object;
  138.     // Invoked from -insertObject: to tell the delegate that an object will
  139.     // be inserted.  The delegate may return the object, a substitute, or nil
  140.     // to prevent insertion.
  141.  
  142. - (void)databaseChannel:channel didInsertObject:object;
  143.     // Invoked from -insertObject: to tell the delegate that an object was
  144.     // inserted.
  145.  
  146. - databaseChannel:channel willDeleteObject:object;
  147.     // Invoked from -deleteObject: to tell the delegate that an object will
  148.     // be deleted.  The delegate may return the object, a substitute, or nil
  149.     // to prevent deletion.
  150.  
  151. - (void)databaseChannel:channel didDeleteObject:object;
  152.     // Invoked from -deleteObject: to tell the delegate that an object was
  153.     // deleted.
  154.  
  155. - databaseChannel:channel willUpdateObject:object;
  156.     // Invoked from -updateObject: to tell the delegate that an object will
  157.     // be updated.  The delegate may return the object, a substitute, or nil
  158.     // to prevent updating.
  159.  
  160. - (void)databaseChannel:channel didUpdateObject:object;
  161.     // Invoked from -updateObject: to tell the delegate that an object was
  162.     // updated.
  163.  
  164. - (NSDictionary *)databaseChannel:channel
  165.     willRefetchObject:object
  166.     fromSnapshot:(NSDictionary *)snapshot;
  167.     // Invoked whenever an object that was previously fetched is fetched again
  168.     // and the re-fetched data is different from that in the object.  The
  169.     // object will be refetched with the dictionary returned by this method,
  170.     // which may be the snapshot provided or a substitute.  The delegate may
  171.     // also return nil to prevent the object from being refetched.
  172.  
  173. - (NSDictionary *)databaseChannel:channel
  174.     willRefetchConflictingObject:object
  175.     withSnapshot:(NSMutableDictionary *)snapshot;
  176.     // Invoked whenever an object is refetched in one transaction while an
  177.     // update on the object is pending in another transaction. This situation
  178.     // is highly suspect because it probably represents a programming error.
  179.     // It involves one object that has two or more potential states and there
  180.     // is no way that EOF can determine the correct one. In this case, a
  181.     // delegate MUST exist and MUST respond to this method or EOF will raise
  182.     // an error. 
  183.  
  184. - (BOOL)databaseChannel:channel
  185.     willSelectObjectsDescribedByQualifier:(EOQualifier *)qualifier
  186.     fetchOrder:(NSArray *)fetchOrder;
  187.     // Invoked from -selectObjectsDescribedByQualifier:...  to tell the
  188.     // delegate that the channel will select objects as specified by
  189.     // qualifier.  The delegate should not modify the qualifier or fetch order.
  190.     // If the delegate returns YES the channel will go ahead and select the
  191.     // object; if the delegate returns NO the channel will abort the select
  192.     // and return NO.
  193.  
  194. - (void)databaseChannel:channel
  195.     didSelectObjectsDescribedByQualifier:(EOQualifier *)qualifier
  196.     fetchOrder:(NSArray *)fetchOrder;
  197.     // Invoked from -selectObjectsDescribedByQualifier:...  to tell the
  198.     // delegate that the channel selected objects as specified by qualifier.
  199.  
  200. - (void)databaseChannel:channel
  201.     willFetchObjectOfClass:(Class)class
  202.     withZone:(NSZone *)zone;
  203.     // Invoked from -fetchWithZone: to tell the delegate that the channel will
  204.     // fetch the next selected object.
  205.  
  206. - (void)databaseChannel:channel didFetchObject:object;
  207.     // Invoked from -fetchWithZone: to tell the delegate that the channel
  208.     // fetched the next selected object.
  209.  
  210. - (BOOL)databaseChannel:channel willLockObject:object;
  211.     // Invoked from -lockObject: to tell the delegate that object will be
  212.     // locked using snapshot data to determine whether the database has been
  213.     // modified.  The delegate may return YES to allow the channel to proceed,
  214.     // or NO to cause the operation to fail and -lockObject: to return NO.
  215.  
  216. - (void)databaseChannel:channel didLockObject:object;
  217.     // Invoked from -lockObject: to tell the delegate that object was locked.
  218.  
  219. - (Class)databaseChannel:channel failedToLookupClassNamed:(const char *)name;
  220.     // Invoked when an attempt to lookup class name fails.  The delegate can
  221.     // take action (such as loading a bundle) to provide the channel with a
  222.     // class for name.
  223.  
  224. - (EORelationship *)databaseChannel:channel
  225.     relationshipForRow:(NSDictionary *)row 
  226.     relationship:(EORelationship *)relationship;
  227.     // Invoked when relationships are instantiated on a newly
  228.     // fetched object. The delegate can use the information in the row to
  229.     // determine which entity the target eo should be associated and replace
  230.     // the relationship appropriately.
  231. @end
  232.  
  233.