home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2J (Developer) / os42jdev.iso / NextDeveloper / OpenStepConversion / 3.3Headers / eoaccess / EOAdaptorContext.h < prev    next >
Encoding:
Text File  |  1994-09-08  |  6.7 KB  |  172 lines
  1. // EOAdaptorContext.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 EOAdaptor;
  11. @class EOAdaptorChannel;
  12.  
  13. typedef enum { 
  14.     EODelegateRejects, EODelegateApproves, EODelegateOverrides
  15. } EODelegateResponse;
  16.     // EODelegateResponse is used to indicate the result a delegate demands
  17.     // on notification that a particular action will be taken.  If a delegate
  18.     // returns EODelegateRejects, the sender of the delegation message must
  19.     // abort the current operation and return a failure result.  If the
  20.     // delegate returns EODelegateApproves, the sender may continue the
  21.     // operation and return whatever result is appropriate.  If the delegate
  22.     // returns EODelegateOverrides, the sender must do nothing, but return a
  23.     // success result.  When a delegate overrides an operation it's
  24.     // responsible for seeing that the result of that operation is performed
  25.     // successfully.
  26.  
  27.  
  28. // An EOAdaptorContext represents a single transaction scope on the database
  29. // server. It's managed by an EOAdaptor object, which represents the main
  30. // connection to the server. If the server supports multiple concurrent
  31. // transaction sessions, the EOAdaptor may have several EOAdaptorContexts.
  32. // An EOAdaptorContext may in turn have several EOAdaptorChannels, which
  33. // handle actual access to the data on the server. An EOAdaptorContext by
  34. // default has no EOAdaptorChannels; to create a new EOAdaptorChannel, send
  35. // your EOAdaptorContext a -createAdaptorChannel message. See EOAdaptor.h and
  36. // EOAdaptorChannel.h for more information.
  37. //
  38. // An EOAdaptorContext retains its adaptor when created and an
  39. // EOAdaptorChannel retains its context, so when you create an adaptor,
  40. // adaptor context, and adaptor channel, you need only retain the channel for
  41. // all objects to remain valid.
  42. //
  43. // CONCCURRENT ACCESS
  44. //
  45. // When you use multiple EOAdaptorContexts, you can have several transactions
  46. // occurring simultaneously on the database server.  You should be aware of
  47. // the issues involved in concurrent access if you do this.
  48.  
  49.  
  50. @interface EOAdaptorContext:NSObject
  51. {
  52.     id _delegate;
  53.     struct {
  54.     unsigned willBegin:1;
  55.     unsigned didBegin:1;
  56.     unsigned willCommit:1;
  57.     unsigned didCommit:1;
  58.     unsigned willRollback:1;
  59.     unsigned didRollback:1;
  60.     unsigned int _RESERVED:26;
  61.     } _delegateRespondsTo;
  62. }
  63.  
  64. - (BOOL)hasBusyChannels;
  65.     // Returns YES if the receiver has channels that have outstanding
  66.     // operations (that is, have a fetch in progress), NO otherwise.
  67.  
  68. - (EOAdaptor *)adaptor;
  69.     // Returns the EOAdaptor that handles the connection within which the
  70.     // adaptor context works.
  71.  
  72. - (EOAdaptorChannel *)createAdaptorChannel;
  73.     // Returns a new EOAdaptorChannel.  Returns nil if a new channel cannot
  74.     // be created.  EOAdaptorContexts by default have no channels at all.  The
  75.     // newly created channel retains its context.
  76.  
  77. - delegate;
  78. - (void)setDelegate:delegate;
  79.     // These methods return/set the delegate of the adaptor context.
  80.  
  81. @end
  82.  
  83.  
  84. // This category defines an interface for a basic transaction model
  85. // that incorporates begin, commit and rollback operations.
  86.  
  87. @interface EOAdaptorContext (EOTransactions)
  88.  
  89. - (BOOL)beginTransaction;
  90.     // Attempts to begin a new transaction, nested within the current one if
  91.     // nested transaction are supported, returning YES if successful and NO
  92.     // if not.
  93.  
  94. - (BOOL)commitTransaction;
  95.     // Attempts to commit the last transaction begun, returning YES if
  96.     // successful and NO if not. This method will raise an exception if any
  97.     // of the context's channels have a fetch in progress or if the
  98.     // transactionNestingLevel of the databaseContext is out of sync with
  99.     // the adaptorContext.
  100.  
  101. - (BOOL)rollbackTransaction;
  102.     // Attempts to roll back the last transaction begun, returning YES if
  103.     // successful and NO if not. This method will raise an exception if any
  104.     // of the context's channels have a fetch in progress or if the
  105.     // transactionNestingLevel of the databaseContext is out of sync with
  106.     // the adaptorContext.
  107.  
  108. - (BOOL)canNestTransactions;
  109.     // Returns YES if the database server can nest transactions, NO
  110.     // otherwise.
  111.  
  112. - (unsigned)transactionNestingLevel; 
  113.     // Returns the number of transactions in progress. If transactions
  114.     // can nest, this number may be greater than one.
  115.  
  116. // Since databases vary widely in their ability to report transactions
  117. // generated automatically--for example through stored procedures--the
  118. // following notification methods help the caller keep the transaction objects
  119. // synchronized with the database.  These methods are also invoked by the
  120. // -beginTransaction, -commitTransaction, and -rollbackTransaction methods.
  121.  
  122. - (void)transactionDidBegin;
  123.     // Informs the receiver that the server has begun a transaction.
  124.  
  125. - (void)transactionDidCommit;
  126.     // Informs the receiver that the server has committed a transaction.
  127.  
  128. - (void)transactionDidRollback;
  129.     // Informs the receiver that the server has rolled back a transaction.
  130.  
  131. @end
  132.  
  133.  
  134. // EOAdaptorContext sends messages to its delegate for any transaction
  135. // begin, commit, or rollback. The delegate can use these methods to
  136. // preempt these operations, modify their results, or simply track activity.
  137. //
  138. // IMPORTANT: read the comments for the EODelegateResponse at the top of this
  139. // header file for information on how the adaptor context interprets delegate
  140. // responses.
  141.  
  142. @interface NSObject(EOAdaptorContextDelegation)
  143.  
  144. - (EODelegateResponse)adaptorContextWillBegin:context;
  145.     // Invoked from -beginTransaction to tell the delegate that a transaction
  146.     // is being started.
  147.  
  148. - (void)adaptorContextDidBegin:context;
  149.     // Invoked from -beginTransaction or -transactionDidBegin to tell the
  150.     // delegate that a transaction has begun. The delegate may take whatever
  151.     // action it needs based on this information.
  152.  
  153. - (EODelegateResponse)adaptorContextWillCommit:context;
  154.     // Invoked from -commitTransaction to tell the delegate that a transaction
  155.     // is being committed.
  156.  
  157. - (void)adaptorContextDidCommit:context;
  158.     // Invoked from -commitTransaction or -transactionDidCommit to tell the
  159.     // delegate that a transaction has been committed.  The delegate may take
  160.     // whatever action it needs based on this information.
  161.  
  162. - (EODelegateResponse)adaptorContextWillRollback:context;
  163.     // Invoked from -rollbackTransaction to tell the delegate that a
  164.     // transaction is being started.
  165.  
  166. - (void)adaptorContextDidRollback:context;
  167.     // Invoked from -rollbackTransaction or -transactionDidRollback to tell
  168.     // the delegate that a transaction has been rolled back.  The delegate may
  169.     // take whatever action it needs based on this information.
  170.  
  171. @end
  172.