home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / EODEV.Z / EOAdaptorChannel.h < prev    next >
Encoding:
Text File  |  1996-09-09  |  18.2 KB  |  375 lines
  1. // EOAdaptorChannel.h 
  2. // Copyright (c) 1994, NeXT Software, Inc. All rights reserved.
  3.  
  4. #import <EOAccess/EODefines.h>
  5. #import <EOAccess/EOAdaptorContext.h>
  6.  
  7. #import <EOControl/EOControl.h>
  8.  
  9. @class EOEntity;
  10. @class EOAttribute;
  11. @class EOQualifier;
  12. @class EOStoredProcedure;
  13. @class EOModel;
  14. @class EOAdaptorOperation;
  15. @class EOSQLExpression;
  16.  
  17. // An EOAdaptorChannel represents an independent communication channel to the
  18. // database server. You use an EOAdaptorChannel to manipulate rows (records)
  19. // by selecting, fetching, inserting, updating, and deleting them.  An
  20. // EOAdaptorChannel also gives you access to some of the meta-data on the
  21. // server (what entities exist, and what their basic attributes or
  22. // relationships are).
  23. //
  24. // An EOAdaptorChannel works with an EOAdaptorContext object, which handles
  25. // transactions.  All of an EOAdaptorChannel's operations take place within
  26. // the context of transactions controlled or tracked by the EOAdaptorContext.
  27. // An EOAdaptorContext may manage several EOAdaptorChannels, but a channel is
  28. // associated with only one context.  See EOAdaptor.h and EOAdaptorContext.h
  29. // for more information.
  30. //
  31. // Not all adaptors support multiple channels per context.  For example, the
  32. // Sybase adaptor can have only one channel per context.
  33. //
  34. // An EOAdaptorContext retains its adaptor when created and an
  35. // EOAdaptorChannel retains its context, so when you create an adaptor,
  36. // adaptor context, and adaptor channel, you need only retain the channel for
  37. // all objects to remain valid.
  38. //
  39. // ATTRIBUTE NAMES
  40. //
  41. // Any EOAdaptorChannel method that uses attribute names uses the internal
  42. // names of the EOAttribute objects, NOT the external names of the database
  43. // server.  External names are only used internally by an adaptor channel and
  44. // in the -evaluateExpression: method (which sends an expression directly to
  45. // the server for processing).
  46.  
  47.  
  48. @interface EOAdaptorChannel:NSObject
  49. {
  50.     BOOL _debug;
  51.     EOAdaptorContext *_context;
  52.     id _delegate;
  53.     struct {
  54.         unsigned willPerformOperations:1;
  55.         unsigned didPerformOperations:1;
  56.         unsigned shouldSelectAttributes:1;
  57.     unsigned didSelectAttributes:1;
  58.     unsigned willFetchRow:1;
  59.     unsigned didFetchRow:1;
  60.     unsigned didChangeResultSet:1;
  61.     unsigned didFinishFetching:1;
  62.     unsigned shouldEvaluateExpression:1;
  63.         unsigned didEvaluateExpression:1;
  64.         unsigned shouldExecuteStoredProcedure:1;
  65.         unsigned didExecuteStoredProcedure:1;
  66.         unsigned shouldConstructStoredProcedureReturnValues:1;
  67.         unsigned shouldReturnValuesForStoredProcedure:1;
  68.     unsigned int _RESERVED:18;
  69.     } _delegateRespondsTo;
  70. }
  71.  
  72. - initWithAdaptorContext:(EOAdaptorContext *)adaptorContext;
  73.     // designated initializer
  74.  
  75. - (BOOL)isOpen;
  76.     // Returns YES if the channel has been opened with -openChannel,
  77.     // NO if not.
  78.  
  79. - (void)openChannel;
  80.     // This method puts the channel and both its context and adaptor into a
  81.     // state where they are ready to perform database operations. Raises an
  82.     // exception if error occurs.
  83.  
  84. - (void)closeChannel;
  85.     // This method disconnects the channel and then disconnects the
  86.     // channel's context if the context has no other channels open.
  87.  
  88. - (EOAdaptorContext *)adaptorContext;
  89.     // Returns the EOAdaptorContext that controls transactions for the
  90.     // channel.
  91.  
  92. - (void)insertRow:(NSDictionary *)row forEntity:(EOEntity *)entity;
  93.     // Inserts the attributes of row into the database.  row is an
  94.     // NSDictionary whose keys are attribute names and whose values are the
  95.     // values that will be inserted. Row keys must refer to attributes that all
  96.     // belong to entity and that are either non-flattened or all flattened
  97.     // through the same relationshipPath. Raise an exception if error occurs.
  98.  
  99. - (void)updateValues:(NSDictionary *)values
  100.     inRowDescribedByQualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity; 
  101.     // Updates the row described by qualifier so that its values are equal to
  102.     // those in the values dictionary.  The values dictionary contains a set
  103.     // of attribute name/value pairs. All keys in the row and qualifer
  104.     // must refer to attributes that all belong to entity and that are either
  105.     // non-flattened or all flattened through the same relationshipPath.
  106.     // This method may raise an exception if an error occurs or if exactly
  107.     // one row is not updated.
  108.     // SubClassers: superclass provides default implementation.
  109.  
  110. - (unsigned)updateValues:(NSDictionary *)values
  111.     inRowsDescribedByQualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity;
  112.     // Similar to the preceding method, except this one may affect an arbitrary
  113.     // number of rows. Returns the number of rows affected by this method. Raises
  114.     // if an error occurs.
  115.  
  116. - (void)deleteRowDescribedByQualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity;
  117.     // Deletes the row described by the qualifier.  This methods may raise an
  118.     // exception if an error occurs or if exactly 1 row is not deleted.
  119.     // All keys in the qualifer must refer to attributes that all belong
  120.     // to entity and that are either non-flattened or all flattened
  121.     // through the same relationshipPath.
  122.     // SubClassers: superclass provides default implementation.
  123.  
  124. - (unsigned)deleteRowsDescribedByQualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity;
  125.     // Similar to the preceding method, except this one may delete an arbitrary
  126.     // number of rows. Returns the number of rows deleted by this method. Raises
  127.     // if an error occurs.
  128.  
  129. - (void)selectAttributes:(NSArray *)attributes fetchSpecification:(EOFetchSpecification *)fetchSpecification lock:(BOOL)flag entity:(EOEntity *)entity;
  130.     // Selects the given attributes in rows matching the qualifier.  The
  131.     // selected rows compose one or more result sets, each row of which will
  132.     // be returned by subsequent -fetchRowWithZone: messages according
  133.     // to the given fetchOrder (see EOSortOrdering.h).  If flag is YES,
  134.     // the rows are locked if possible so that no other user can modify them.
  135.     // This methods may raise an exception if an error occurs.
  136.  
  137. - (void)lockRowComparingAttributes:(NSArray *)atts entity:(EOEntity *)entity
  138.     qualifier:(EOQualifier *)qualifier snapshot:(NSDictionary *)snapshot;
  139.     // Attempts to lock a row in the database by selecting it with the locking
  140.     // on. The qualifier should contain the primary key of the row to be locked
  141.     // as well as any comparisons that can be done in the database server to
  142.     // ensure that the current snapshot is not out of date with respect to the
  143.     // row in the database. The atts array should contain any values that need
  144.     // to be fetched and compared in memory (such as blob columns in the database).
  145.     // The atts array can be nil if the row doesn't contain any blobs. The
  146.     // snapshot must contain any values needed to compare with the fetched atts and
  147.     // the primary key values for this row. This method raises if an error occurs.
  148.     // This method is implemented by the superclass, subclasses should not have to
  149.     // override.
  150.  
  151. - (void)evaluateExpression:(EOSQLExpression *)expression;
  152.     // Sends expression to the database server for evaluation. This methods
  153.     // may raise an exception if an error occurs.
  154.  
  155. - (BOOL)isFetchInProgress;
  156.     // Returns YES if the adaptor channel is fetching, NO otherwise.  An
  157.     // adaptor channel is fetching if an operation has been performed which
  158.     // can return row. An adaptor channel may be fetching after a
  159.     // -selectAttributes:...  message, an executeStoredProcdure: message,
  160.     // or if an expression sent through -evaluateExpression: resulted in
  161.     // a select.  An adaptor channel stops fetching when there are no more
  162.     // records to fetch or when it's sent a -cancelFetch message
  163.  
  164. - (NSArray *)describeResults;
  165.     // Returns an array of attributes describing the properties available in
  166.     // the current result set, as determined by -selectAttributes:...  or a
  167.     // select statement evaluated by -evaluateExpression:.
  168.     // This methods may raise an exception if an error occurs
  169.  
  170. - (NSMutableDictionary *)fetchRowWithZone:(NSZone *)zone;
  171.     // Fetches the next row from the result set of the last
  172.     // -selectAttributes:...  message and returns values for the attribute
  173.     // names in attributes. When no rows are left, this method invokes
  174.     // adaptorChannel:didFinishFetching:, and returns nil.
  175.     // For adaptors that can have multiple result sets (ODBC and Sybase),
  176.     // This method will return nil at the end of each result set, however
  177.     // isFetchInProgress will return NO. The channel will also send the
  178.     // delegate an an adaptorChannelDidChangeResultSet: message whenever
  179.     // the end of one result set has been reached and another one is
  180.     // pending.
  181.     // This methods may raise an exception if an error occurs.
  182.  
  183. - (void)setAttributesToFetch:(NSArray *)attributes;
  184.     // Allows the user to change the set of attributes used to describe the
  185.     // fetch data in the middle of a select. This is especially useful for
  186.     // DBMS's that have non-rectangular result sets (like Sybase) or when
  187.     // evaluating an expression using the evaluateExpression: method.
  188.     // This method raises if invoked when there is no fetch in progress.
  189.  
  190. - (NSArray *)attributesToFetch;
  191.     // Returns the set of attributes used by the adaptor for a particular fetch.
  192.  
  193. - (void)cancelFetch;
  194.     // Clears the result set created by the last selectAttributes:...
  195.     // message, and terminates the current fetch, so that
  196.     // -isFetchInProgress returns NO and new operations can be performed
  197.     // with the channel.
  198.  
  199. - (NSDictionary *)primaryKeyForNewRowWithEntity:(EOEntity *)entity;
  200.     // If information in the entity specifies an adaptor-specific
  201.     // means to assign a new primary key (e.g. a sequence name, or
  202.     // stored procedure) then returns a new primary key. Otherwise,
  203.     // if the key is a simple integer, the adaptor will attempt to
  204.     // fetch a new key from the database using an adaptor specific
  205.     // scheme. Otherwise, returns nil.
  206.  
  207. - (NSArray *)describeTableNames;
  208.     // Reads and returns an array of table names from the database.  This
  209.     // method is used in conjunction with describeModelWithTableNames: to
  210.     // build a default model in EOModeler. This methods may raise an
  211.     // exception if an error occurs
  212.  
  213. - (void)describeStoredProceduresForModel:(EOModel *)model;
  214.     // This method may raise an exception if an error occcurs.
  215.  
  216. - (EOModel *)describeModelWithTableNames:(NSArray *)tableNames;
  217.     // Constructs a default model out of the database's meta data.  It also
  218.     // put the adaptor name and connection dictionary in the new model.
  219.     // This methods may raise an exception if an error occurs.
  220.  
  221. - (void)setDebugEnabled:(BOOL)yn;
  222. - (BOOL)isDebugEnabled;
  223.     // These methods return/set the current debug setting. When debug is
  224.     // enabled, the adaptor channel will log any SQL that is evaluated and
  225.     // other useful information.
  226.  
  227. - (id)delegate;
  228. - (void)setDelegate:(id)delegate;
  229.     // These methods return/set the delegate of the adaptor channel. The channel's
  230.     // delegate is normally set by the adaptor context whenever it's delegate method
  231.     // is set or whenever the adaptor channel is created. This means that an adaptor
  232.     // context and all of it's channels will have the same delegate.
  233.  
  234. - (NSMutableDictionary *)dictionaryWithObjects:(id *)objects forAttributes:(NSArray *)attributes zone:(NSZone *)zone;
  235.     // Used by AdaptorChannel subclasses to create dictionaries to return from
  236.     // fetchRowWithZone:
  237. @end
  238.  
  239.  
  240. @interface EOAdaptorChannel(EOStoredProcedures)
  241. - (void)executeStoredProcedure:(EOStoredProcedure *)storedProcedure withValues:(NSDictionary *)values;
  242.     // Execute the given stored procedure. On successful completion you can
  243.     // call -returnValuesForStoredProcedure to get the return arguments, if any.
  244.     // This method may raise an exception if an error occcurs.
  245.  
  246. - (NSDictionary *)returnValuesForLastStoredProcedureInvocation;
  247.     // Returns a dictionary with all the OUT parameters and a special entry
  248.     // with the @"returnValue" key.  Stored procedures that have void return
  249.     // types will return an empty dictionary.
  250.     // If this method returns nil, then you need to fetchRowithZone:
  251.     // until all data has been processed before the return value will be
  252.     // available.
  253. @end
  254.  
  255. @interface EOAdaptorChannel(EOBatchProcessing)
  256. - (void)performAdaptorOperation:(EOAdaptorOperation *)adaptorOperation;
  257.     // Invokes the insertRow, updateRow, or deleteRow methods depending
  258.     // on the information in the adaptorOperation. This method may raise
  259.     // an exception if an error occurs.
  260.  
  261. - (void)performAdaptorOperations:(NSArray *)adaptorOperations;
  262.     // The superclass implementation of this method, calls
  263.     // [self performAdaptorOperation] with each adaptorOperation in the
  264.     // array. Specific adaptors may be able to implement this method in a more
  265.     // intelligent way to take advantage of a particular database specific
  266.     // API. By default, the database layer will sort the adaptorOperations in
  267.     // alphabetical order by entityName with the insert operations first in the
  268.     // list for the entity, followed by update operations, followed by deletes.
  269.     // This order can be affected, however, by delegate methods in the EODatabase
  270.     // layer. In addition, this method may be called by other clients than the
  271.     // EODatabase layer which may not conform to this convention.
  272. @end
  273.  
  274. // EOAdaptorChannel sends messages to its delegate for nearly every
  275. // operation that would affect data in the database server. The delegate can
  276. // use these methods to preempt these operations, modify their results,
  277. // or simply track activity.
  278.  
  279. @interface NSObject(EOAdaptorChannelDelegation)
  280.  
  281. - (NSArray *)adaptorChannel:channel
  282.     willPerformOperations:(NSArray *)operations;
  283.     // Invoked from -performAdaptorOperations. The delegate may return a the same
  284.     // or different NSArray to continue the method or nil to cause the method to
  285.     // return immediately.
  286.  
  287. - (NSException *)adaptorChannel:channel
  288.     didPerformOperations:(NSArray *)operations
  289.     exception:(NSException *)exception;
  290.     // Invoked from -performAdaptorOperations. The exception will be nil if no
  291.     // exception was raised during while performing the operations. Otherwise, the
  292.     // raised exception will be passed to the delegate. The delegate can return the
  293.     // the same or a different exception which will then be re-raised by the method
  294.     // or they can return nil to supress the raising of the exception.
  295.  
  296. - (BOOL)adaptorChannel:channel
  297.     shouldSelectAttributes:(NSArray *)attributes
  298.     fetchSpecification:(EOFetchSpecification *)fetchSpecification
  299.     lock:(BOOL)flag entity:(EOEntity *)entity;
  300.     // Invoked from -selectAttributes:fetchSpecification:lock:entity:
  301.     // to ask the delegate whether a select operation should be performed.
  302.     // The delegate can modify the fetchSpecification to alter the select.
  303.     // The delegate may return NO which causes the select not to happen.
  304.     // In this case the delegate may perform the select itself.
  305.  
  306. - (void)adaptorChannel:channel
  307.     didSelectAttributes:(NSArray *)attributes
  308.     fetchSpecification:(EOFetchSpecification *)fetchSpecification
  309.     lock:(BOOL)flag entity:(EOEntity *)entity;
  310.     // Invoked from -selectAttributes:fetchSpecification:lock:entity:
  311.     // to tell the delegate that some rows have been selected. The delegate
  312.     // may take whatever action it needs based on this information.
  313.  
  314. - (void)adaptorChannelWillFetchRow:channel;
  315.     // Invoked from -fetchRowWithZone: to tell the delegate that a
  316.     // single row will be fetched. Delegates can get and reset the attributes
  317.     // used in the fetch through the -attributesToFetch and the
  318.     // -setAttributesToFetch: methods.
  319.     // the adaptor channel perfoms the fetch itself.
  320.  
  321. - (void)adaptorChannel:channel didFetchRow:(NSMutableDictionary *)row;
  322.     // Invoked at the end of -fetchRowWithZone: whenever a row is successfully
  323.     // fetched. This method is not invoked if an exception occurs during the
  324.     // fetch or if the end of the fetch set is reached. Delegates can change
  325.     // the row dictionary.
  326.  
  327. - (void)adaptorChannelDidChangeResultSet:channel;
  328.     // Invoked from -fetchRowWithZone: to tell the delegate that
  329.     // fetching will start for the next result set, when a select operation
  330.     // resulted in multiple result sets.  This method is invoked just after a
  331.     // -fetchRowWithZone: returns nil when there are still result sets
  332.     // left to fetch.
  333.  
  334. - (void)adaptorChannelDidFinishFetching:channel;
  335.     // Invoked from -fetchRowWithZone: to tell the delegate that
  336.     // fetching is finished for the current select operation.  This method is
  337.     // invoked when a fetch ends in -fetchRowWithZone: because there
  338.     // are no more result sets.
  339.  
  340. - (BOOL)adaptorChannel:channel
  341.     shouldEvaluateExpression:(EOSQLExpression *)expression;
  342.     // Invoked from -evaluateExpression: to ask the delegate whether to
  343.     // send an expression to the database server.
  344.  
  345. - (void)adaptorChannel:channel
  346.     didEvaluateExpression:(EOSQLExpression *)expression;
  347.     // Invoked from -evaluateExpression: to tell the delegate that a query
  348.     // language expression has been evaluated by the database server. The
  349.     // delegate may take whatever action it needs based on this information.
  350.  
  351. - (NSDictionary *)adaptorChannel:channel
  352.     shouldExecuteStoredProcedure:(EOStoredProcedure *)procedure
  353.     withValues:(NSDictionary *)values;
  354.     // Invoked from -executeStoredProcedure:withArguments:
  355.     // If the delegate returns a value other than nil, that returned dictionary
  356.     // will will be used as the arguments to the stored procedure
  357.  
  358. - (void)adaptorChannel:channel
  359.     didExecuteStoredProcedure:(EOStoredProcedure *)procedure
  360.     withValues:(NSDictionary *)values;
  361.     // Invoked from -executeStoredProcedure:withValues: after the execution
  362.     // has succeeded.
  363.  
  364. - (NSDictionary *)adaptorChannelShouldConstructStoredProcedureReturnValues:channel;
  365.     // Invoked from -returnValuesForLastStoredProcedureInvocation.
  366.     // If the delegate returns a value other than nil, that value will be
  367.     // returned immediately to the calling method.
  368.  
  369. - (NSDictionary *)adaptorChannel:channel shouldReturnValuesForStoredProcedure:(NSDictionary *)returnValues;
  370.     // Invoked from -returnValuesForLastStoredProcedureInvocation
  371.     // If the delegate returns a dictionary, that dictionary will be returned to the
  372.     // calling method.
  373. @end
  374.  
  375.