home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2J (Developer) / os42jdev.iso / NextDeveloper / OpenStepConversion / 3.3Headers / eoaccess / EOAdaptorChannel.h < prev    next >
Encoding:
Text File  |  1995-01-31  |  14.2 KB  |  321 lines
  1. // EOAdaptorChannel.h 
  2. // Copyright (c) 1994, NeXT Computer, Inc. All rights reserved.
  3.  
  4. #import "EOAdaptorContext.h"
  5.  
  6. #import <foundation/NSArray.h>
  7. #import <foundation/NSData.h>
  8. #import <foundation/NSDictionary.h>
  9. #import <foundation/NSObject.h>
  10. #import <foundation/NSString.h>
  11.  
  12. @class EOEntity;
  13. @class EOAttribute;
  14. @class EOQualifier;
  15. @class EOModel;
  16.  
  17.  
  18. // An EOAdaptorChannel represents an independent communication channel to the
  19. // database server. You use an EOAdaptorChannel to manipulate rows (records)
  20. // by selecting, fetching, inserting, updating, and deleting them.  An
  21. // EOAdaptorChannel also gives you access to some of the meta-data on the
  22. // server (what entities exist, and what their basic attributes or
  23. // relationships are).
  24. //
  25. // An EOAdaptorChannel works with an EOAdaptorContext object, which handles
  26. // transactions.  All of an EOAdaptorChannel's operations take place within
  27. // the context of transactions controlled or tracked by the EOAdaptorContext.
  28. // An EOAdaptorContext may manage several EOAdaptorChannels, but a channel is
  29. // associated with only one context.  See EOAdaptor.h and EOAdaptorContext.h
  30. // for more information.
  31. //
  32. // Not all adaptors support multiple channels per context.  For example, the
  33. // Sybase adaptor can have only one channel per context.
  34. //
  35. // An EOAdaptorContext retains its adaptor when created and an
  36. // EOAdaptorChannel retains its context, so when you create an adaptor,
  37. // adaptor context, and adaptor channel, you need only retain the channel for
  38. // all objects to remain valid.
  39. //
  40. // ATTRIBUTE NAMES
  41. //
  42. // Any EOAdaptorChannel method that uses attribute names uses the internal
  43. // names of the EOAttribute objects, NOT the external names of the database
  44. // server.  External names are only used internally by an adaptor channel and
  45. // in the -evaluateExpression: method (which sends an expression directly to
  46. // the server for processing).
  47.  
  48.  
  49. @interface EOAdaptorChannel:NSObject
  50. {
  51.     BOOL _debug;
  52.     id _delegate;
  53.     struct {
  54.     unsigned willInsertRow:1;
  55.     unsigned didInsertRow:1;
  56.     unsigned willUpdateRow:1;
  57.     unsigned didUpdateRow:1;
  58.     unsigned willDeleteRows:1;
  59.     unsigned didDeleteRows:1;
  60.     unsigned willSelectAttributes:1;
  61.     unsigned didSelectAttributes:1;
  62.     unsigned willFetchAttributes:1;
  63.     unsigned didFetchAttributes:1;
  64.     unsigned didChangeResultSet:1;
  65.     unsigned didFinishFetching:1;
  66.     unsigned willEvaluateExpression:1;
  67.     unsigned didEvaluateExpression:1;
  68.     unsigned int _RESERVED:18;
  69.     } _delegateRespondsTo;
  70. }
  71.  
  72. - (BOOL)isOpen;
  73.     // Returns YES if the channel has been opened with -openChannel,
  74.     // NO if not.
  75.  
  76. - (BOOL)openChannel;
  77.     // This method puts the channel and both its context and adaptor into a
  78.     // state where they are ready to perform database operations.  Returns YES
  79.     // on success, NO on failure for any reason.
  80.  
  81. - (void)closeChannel;
  82.     // This method disconnects the channel, disconnects the channel's context
  83.     // if the context has no other channels open, and then disconnects the
  84.     // adaptor if it has no additional contexts open.
  85.  
  86. - (EOAdaptorContext *)adaptorContext;
  87.     // Returns the EOAdaptorContext that controls transactions for the
  88.     // channel.
  89.  
  90. - (BOOL)insertRow:(NSDictionary *)row forEntity:(EOEntity *)entity;
  91.     // Inserts the attributes of row into the database.  row is an
  92.     // NSDictionary whose keys are attribute names and whose values are the
  93.     // values that will be inserted.  Returns YES on success, NO on failure
  94.     // for any reason.
  95.  
  96. - (BOOL)updateRow:(NSDictionary *)row
  97.     describedByQualifier:(EOQualifier *)qualifier; 
  98.     // Updates the row described by qualifier so that its values are equal to
  99.     // those in row.  row is an NSDictionary of attribute name/value pairs.
  100.     // Returns YES on success, NO on failure for any reason.
  101.  
  102. - (BOOL)deleteRowsDescribedByQualifier:(EOQualifier *)qualifier;
  103.     // Deletes the row described by the qualifier.  Returns YES on success,
  104.     // NO on failure for any reason.
  105.  
  106. - (BOOL)selectAttributes:(NSArray *)attributes
  107.     describedByQualifier:(EOQualifier *)qualifier
  108.     fetchOrder:(NSArray *)fetchOrder
  109.     lock:(BOOL)flag;
  110.     // Selects the given attributes in rows matching the qualifier.  The
  111.     // selected rows compose one or more result sets, each row of which will
  112.     // be returned by subsequent -fetchAttributes:withZone: messages according
  113.     // to the given fetchOrder (see EOAttributeOrdering.h).  If flag is YES,
  114.     // the rows are locked if possible so that no other user can modify them.
  115.     // Returns YES on success, NO on failure for any reason.
  116.  
  117. - (BOOL)evaluateExpression:(NSString *)expression;
  118.     // Sends expression to the database server for evaluation.  Returns YES
  119.     // if no error occurs, NO if any error occurs.
  120.  
  121. - (BOOL)isFetchInProgress;
  122.     // Returns YES if the adaptor channel is fetching, NO otherwise.  An
  123.     // adaptor channel is fetching if it's been sent a successful
  124.     // -selectAttributes:...  message, or if an expression sent through
  125.     // -evaluateExpression: resulted in a select.  An adaptor channel stops
  126.     // fetching when there are no more records to fetch or when it's sent
  127.     // a -cancelFetch message
  128.  
  129. - (NSArray *)describeResults;
  130.     // Returns an array of attributes describing the properties available in
  131.     // the current result set, as determined by -selectAttributes:...  or a
  132.     // select statement evaluated by -evaluateExpression:.
  133.  
  134. - (NSMutableDictionary *)fetchAttributes:(NSArray *)attributes 
  135.     withZone:(NSZone *)zone;
  136.     // Fetches the next row from the result set of the last
  137.     // -selectAttributes:...  message and returns values for the attribute
  138.     // names in attributes.  When there are no more rows in the current result
  139.     // set, this method returns nil, and invokes the delegate method
  140.     // -adaptorChannelDidChangeResultSet: if there are more results sets.
  141.     // When there are no more rows or result sets, this method returns NO,
  142.     // ends the fetch, and invokes -adaptorDidFinishFetching:.
  143.     // -isFetchInProgress returns YES until the fetch is cancelled or until
  144.     // this method exhausts all result sets and returns nil.
  145.  
  146. - (void)cancelFetch;
  147.     // Clears the result set created by the last selectAttributes:...
  148.     // message, and terminates the current fetch, so that
  149.     // -isFetchInProgress returns NO.
  150.  
  151. - (BOOL)readTypesForEntity:(EOEntity *)entity;
  152.     // Loads external type information from the database server into all
  153.     // root attributes of entity. Returns YES on sucess, NO on failure
  154.     // for any reason.
  155.  
  156. - (BOOL)readTypeForAttribute:(EOAttribute *)attribute;
  157.     // Loads external type information from the database server into
  158.     // attribute. Returns YES on sucess, NO on failure for any reason.
  159.  
  160. - (NSArray *)describeTableNames;
  161.     // Reads and returns an array of table names from the database.  This
  162.     // method in conjunction with describeModelWithTableNames: is used for
  163.     // building a default model in EOModeler.
  164.  
  165. - (EOModel *)describeModelWithTableNames:(NSArray *)tableNames;
  166.     // Constructs a default model out of the database's meta data.  It also
  167.     // put the adaptor name and connection dictionary in the new model.  This
  168.     // method obsoletes describeEntities, describeAttributes..., and
  169.     // describeRelationships...
  170.  
  171. - (NSArray *)describeEntities;
  172.     // Returns an array of default entities constructed from meta data
  173.     // returned by the database--for example, from the catalog or system
  174.     // tables.  This method is obsolete.
  175.  
  176. - (NSArray *)describeAttributesForEntity:(EOEntity *)entity;
  177. - (NSArray *)describeRelationshipsForEntity:(EOEntity *)entity;
  178.     // Returns an array of default attributes or relationships for entity,
  179.     // constructed from meta-data in the database server.  These methods don't
  180.     // actually assign the attributes or relationships to the entity--you have
  181.     // to do that yourself.  See EOEntity.h for descriptions of -addAttribute:
  182.     // and -addRelationship:.  These methods are obsolete.
  183.  
  184. - (void)setDebugEnabled:(BOOL)yn;
  185. - (BOOL)isDebugEnabled;
  186.     // These methods return/set the current debug setting. When debug is
  187.     // enabled, the adaptor channel will log any SQL that is evaluated and
  188.     // other useful information.
  189.  
  190. - delegate;
  191. - (void)setDelegate:delegate;
  192.     // These methods return/set the delegate of the adaptor channel.
  193.  
  194. - (NSMutableDictionary *)dictionaryWithObjects:(id *)objects forAttributes:(NSArray *)attributes zone:(NSZone *)zone;
  195.     // Used by AdaptorChannel subclasses to create dictionaries to return from
  196.     // fetchAttributes:withZone:
  197.  
  198. + (NSCalendarDate *)dateForAttribute:(EOAttribute *)attr year:(int)year month:(unsigned)month day:(unsigned)day hour:(unsigned)hour minute:(unsigned)minute second:(unsigned)second zone:(NSZone *)zone;
  199.     // Used by AdaptorChannel subclasses to create a calendar date object
  200.     // to return in an adaptor row.
  201. @end
  202.  
  203.  
  204. // EOAdaptorChannel sends messages to its delegate for nearly every
  205. // operation that would affect data in the database server. The delegate can
  206. // use these methods to preempt these operations, modify their results,
  207. // or simply track activity.
  208. //
  209. // IMPORTANT: read the comments for the EODelegateResponse type in
  210. // EOAdaptorContext.h for information on how the adaptor channel interprets
  211. // delegate responses.
  212.  
  213.  
  214. @interface NSObject(EOAdaptorChannelDelegation)
  215.  
  216. - (EODelegateResponse)adaptorChannel:channel
  217.     willInsertRow:(NSMutableDictionary *)row
  218.     forEntity:(EOEntity *)entity;
  219.     // Invoked from -insertRow:forEntity: to tell the delegate that a row is
  220.     // being inserted. The delegate may modify row, changing the values for
  221.     // particular keys (attributes), or even adding or deleting attributes.
  222.  
  223. - (void)adaptorChannel:channel
  224.     didInsertRow:(NSDictionary *)row
  225.     forEntity:(EOEntity *)entity;
  226.     // Invoked from -insertRow:forEntity: to tell the delegate that a row has
  227.     // been inserted. The delegate may use this information to update
  228.     // records, redisplay onscreen information, or take whatever other action
  229.     // it needs.
  230.  
  231. - (EODelegateResponse)adaptorChannel:channel
  232.     willUpdateRow:(NSMutableDictionary *)row
  233.     describedByQualifier:(EOQualifier *)qualifier;
  234.     // Invoked from -updateRow:describedByQualifier: to tell the delegate that
  235.     // a row is being updated.  The delegate can change the values for
  236.     // particular attribute names in row, add or delete attributes, or modify
  237.     // the qualifier.
  238.  
  239. - (void)adaptorChannel:channel
  240.     didUpdateRow:(NSDictionary *)row
  241.     describedByQualifier:(EOQualifier *)qualifier;
  242.     // Invoked from -updateRow:describedByQualifier: to tell the delegate that
  243.     // a row has been updated. The delegate may take whatever action it needs
  244.     // based on this information.
  245.  
  246. - (EODelegateResponse)adaptorChannel:channel
  247.     willDeleteRowsDescribedByQualifier:(EOQualifier *)qualifier;
  248.     // Invoked from -deleteRowsDescribedByQualifier: to tell the delegate that
  249.     // a row is being deleted.  The delegate can modify the qualifier to
  250.     // affect the result of the delete operation.
  251.  
  252. - (void)adaptorChannel:channel
  253.     didDeleteRowsDescribedByQualifier:(EOQualifier *)qualifier;
  254.     // Invoked from -deleteRowsDescribedByQualifier: to tell the delegate that
  255.     // some rows have been deleted. The delegate may take whatever action it
  256.     // needs based on this information.
  257.  
  258. - (EODelegateResponse)adaptorChannel:channel
  259.     willSelectAttributes:(NSMutableArray *)attributes
  260.     describedByQualifier:(EOQualifier *)qualifier
  261.     fetchOrder:(NSMutableArray *)fetchOrder
  262.     lock:(BOOL)flag;
  263.     // Invoked from -selectAttributes:describedByQualifier:fetchOrder:lock:
  264.     // to tell the delegate that a select operation is being performed.  The
  265.     // delegate can modify attributes or the qualifier to affect the select
  266.     // operation.
  267.  
  268. - (void)adaptorChannel:channel
  269.     didSelectAttributes:(NSArray *)attributes
  270.     describedByQualifier:(EOQualifier *)qualifier
  271.     fetchOrder:(NSArray *)fetchOrder
  272.     lock:(BOOL)flag;
  273.     // Invoked from -selectAttributes:describedByQualifier:fetchOrder:lock:
  274.     // to tell the delegate that some rows have been selected. The delegate
  275.     // may take whatever action it needs based on this information.
  276.  
  277. - (NSMutableDictionary *)adaptorChannel:channel
  278.     willFetchAttributes:(NSArray *)attributes
  279.     withZone:(NSZone *)zone;
  280.     // Invoked from -fetchAttributes:withZone: to tell the delegate that a
  281.     // single row will be fetched. If the delegate returns a non-nil
  282.     // value, that value will be treated as a dictionary resulting from a
  283.     // fetch operation; the adaptor channel doesn't perform a fetch, and
  284.     // -fetchAttributes:withZone: returns YES. If the delegate returns nil
  285.     // the adaptor channel perfoms the fetch itself.
  286.  
  287. - (NSMutableDictionary *)adaptorChannel:channel
  288.     didFetchAttributes:(NSMutableDictionary *)attributes
  289.     withZone:(NSZone *)zone;
  290.     // Invoked from -fetchAttributes:withZone: to tell the delegate that a
  291.     // single row has been fetched.  The delegate may modify and return the
  292.     // given dictionary of values, return a substitute dictionary, or nil
  293.     // to cause -fetchAttributes:withZone: to fail and return nil.
  294.  
  295. - (void)adaptorChannelDidChangeResultSet:channel;
  296.     // Invoked from -fetchAttributes:withZone: to tell the delegate that
  297.     // fetching will start for the next result set, when a select operation
  298.     // resulted in multiple result sets.  This method is invoked just after a
  299.     // -fetchAttributes:withZone: returns nil when there are still result sets
  300.     // left to fetch.
  301.  
  302. - (void)adaptorChannelDidFinishFetching:channel;
  303.     // Invoked from -fetchAttributes:withZone: to tell the delegate that
  304.     // fetching is finished for the current select operation.  This method is
  305.     // invoked when a fetch ends in -fetchAttributes:withZone: because there
  306.     // are no more result sets.
  307.  
  308. - (EODelegateResponse)adaptorChannel:channel 
  309.     willEvaluateExpression:(NSMutableString *)expression;
  310.     // Invoked from -evaluateExpression: to tell the delegate that an
  311.     // expression is about to be sent to the database server. The delegate
  312.     // may modify expression to affect the result.
  313.  
  314. - (void)adaptorChannel:channel
  315.     didEvaluateExpression:(NSString *)expression;
  316.     // Invoked from -evaluateExpression: to tell the delegate that a query
  317.     // language expression has been evaluated by the database server. The
  318.     // delegate may take whatever action it needs based on this information.
  319.  
  320. @end
  321.