home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / EODEV.Z / EOAdaptorContext.h < prev    next >
Encoding:
Text File  |  1996-09-09  |  7.7 KB  |  198 lines
  1. // EOAdaptorContext.h 
  2. // Copyright (c) 1994, NeXT Software, Inc. All rights reserved.
  3.  
  4. #import <EOControl/EOControl.h>
  5. #import <EOAccess/EODefines.h>
  6.  
  7. @class EOAdaptor;
  8. @class EOAdaptorChannel;
  9.  
  10.  
  11. // An EOAdaptorContext represents a single transaction scope on the database
  12. // server. It's managed by an EOAdaptor object, which represents the main
  13. // connection to the server. If the server supports multiple concurrent
  14. // transaction sessions, the EOAdaptor may have several EOAdaptorContexts.
  15. // An EOAdaptorContext may in turn have several EOAdaptorChannels, which
  16. // handle actual access to the data on the server. An EOAdaptorContext by
  17. // default has no EOAdaptorChannels; to create a new EOAdaptorChannel, send
  18. // your EOAdaptorContext a -createAdaptorChannel message. See EOAdaptor.h and
  19. // EOAdaptorChannel.h for more information.
  20. //
  21. // An EOAdaptorContext retains its adaptor when created and an
  22. // EOAdaptorChannel retains its context, so when you create an adaptor,
  23. // adaptor context, and adaptor channel, you need only retain the channel for
  24. // all objects to remain valid.
  25. //
  26. // CONCCURRENT ACCESS
  27. //
  28. // When you use multiple EOAdaptorContexts, you can have several transactions
  29. // occurring simultaneously on the database server.  You should be aware of
  30. // the issues involved in concurrent access if you do this.
  31.  
  32.  
  33. @interface EOAdaptorContext:NSObject
  34. {
  35.     EOAdaptor *_adaptor;
  36.     NSMutableArray *_channels;
  37.     id _delegate;
  38.     unsigned short _transactionNestingLevel;
  39.     BOOL _debug;
  40.     struct {
  41.         unsigned shouldConnect:1;
  42.         unsigned shouldBegin:1;
  43.     unsigned didBegin:1;
  44.         unsigned shouldCommit:1;
  45.     unsigned didCommit:1;
  46.         unsigned shouldRollback:1;
  47.     unsigned didRollback:1;
  48.     unsigned int _RESERVED:25;
  49.     } _delegateRespondsTo;
  50. }
  51.  
  52. - initWithAdaptor:(EOAdaptor *)adaptor;
  53.     // designated initializer
  54.  
  55. - (BOOL)hasBusyChannels;
  56.     // Returns YES if the receiver has channels that have outstanding
  57.     // operations (that is, have a fetch in progress), NO otherwise.
  58.  
  59. - (BOOL)hasOpenChannels;
  60.     // Returns YES if the context has any open channels, NO otherwise. See
  61.     // -openChannel in EOAdaptorChannel.h.
  62.  
  63. - (NSArray *)channels;
  64.     // Returns an array of channels used by this context. Different adaptors
  65.     // may have different limits on the maximum number of channels per context.
  66.  
  67. - (EOAdaptor *)adaptor;
  68.     // Returns the EOAdaptor that handles the connection within which the
  69.     // adaptor context works.
  70.  
  71. - (EOAdaptorChannel *)createAdaptorChannel;
  72.     // Returns a new EOAdaptorChannel.  Returns nil if a new channel cannot
  73.     // be created.  EOAdaptorContexts by default have no channels at all.  The
  74.     // newly created channel retains its context.
  75.  
  76. - delegate;
  77. - (void)setDelegate:delegate;
  78.     // Caches methods that delegate responds to. Does not retain delegate. Propagates
  79.     // the delegate to all of its channels.
  80. @end
  81.  
  82.  
  83. // This category defines an interface for a basic transaction model
  84. // that incorporates begin, commit and rollback operations.
  85.  
  86. @interface EOAdaptorContext (EOTransactions)
  87.  
  88. - (void)beginTransaction;
  89.     // Attempts to begin a new transaction, nested within the current one if
  90.     // nested transaction are supported. Raises an exception if an error is
  91.     // encountered.
  92.  
  93. - (void)commitTransaction;
  94.     // Attempts to commit the last transaction begun. Raises an exception
  95.     // if an error is encountered. This method will raise an exception if
  96.     // any of the context's channels have a fetch in progress.
  97.  
  98. - (void)rollbackTransaction;
  99.     // Attempts to roll back the last transaction begun. Raises an exception
  100.     // if an error is encountered. This method will raise an exception if any
  101.     // of the context's channels have a fetch in progress.
  102.  
  103. - (BOOL)canNestTransactions;
  104.     // Returns YES if the database server can nest transactions, NO
  105.     // otherwise.
  106.  
  107. - (unsigned)transactionNestingLevel; 
  108.     // Returns the number of transactions in progress. If transactions
  109.     // can nest, this number may be greater than one. Superclass implements
  110.     // this method.
  111.  
  112. // Since databases vary widely in their ability to report transactions
  113. // generated automatically--for example through stored procedures--the
  114. // following notification methods help the caller keep the transaction objects
  115. // synchronized with the database.  These methods are also invoked by the
  116. // -beginTransaction, -commitTransaction, and -rollbackTransaction methods.
  117.  
  118. - (void)transactionDidBegin;
  119.     // Informs the receiver that the server has begun a transaction. Also sends
  120.     // an EOAdaptorContextBeginTransactionNotification. Superclass implements this
  121.     // method.
  122.  
  123. - (void)transactionDidCommit;
  124.     // Informs the receiver that the server has committed a transaction. Also sends
  125.     // an EOAdaptorContextCommitTransactionNotification. Superclass implements this
  126.     // method.
  127.  
  128. - (void)transactionDidRollback;
  129.     // Informs the receiver that the server has rolled back a transaction. Also sends
  130.     // an EOAdaptorContextRollbackTransactionNotification. Superclass implements this
  131.     // method.
  132.  
  133. + (void)setDebugEnabledDefault:(BOOL)yn;
  134. + (BOOL)debugEnabledDefault;
  135.     // setting inherited by new instances.  By default this comes from the user
  136.     // default "EOAdaptorDebugEnabled"
  137.  
  138. - (void)setDebugEnabled:(BOOL)debugEnabled;
  139.     // sets debug enabled flag on self and all outstanding channels. Any new
  140.     // channels that get created also have the debug flag set.
  141. - (BOOL)isDebugEnabled;
  142. @end
  143.  
  144. // EOAdaptorContext sends messages to its delegate for any transaction
  145. // begin, commit, or rollback. The delegate can use these methods to
  146. // preempt these operations, modify their results, or simply track activity.
  147. //
  148. // IMPORTANT: read the comments for the EODelegateResponse at the top of this
  149. // header file for information on how the adaptor context interprets delegate
  150. // responses.
  151.  
  152. @interface NSObject(EOAdaptorContextDelegation)
  153.  
  154. - (BOOL)adaptorContextShouldConnect:context;
  155.     // Invoked before the adaptor attempts to connect. The delegate can return
  156.     // NO if it wants to override the connect, YES if it wants the adaptor
  157.     // to attempt to connect in the usual way. The delegate should raise an
  158.     // exception if it fails to connect.
  159.  
  160. - (BOOL)adaptorContextShouldBegin:context;
  161.     // Invoked from -beginTransaction to ask the delegate whether or not to
  162.     // begin a transaction.
  163.  
  164. - (void)adaptorContextDidBegin:context;
  165.     // Invoked from -beginTransaction or -transactionDidBegin to tell the
  166.     // delegate that a transaction has begun. The delegate may take whatever
  167.     // action it needs based on this information.
  168.  
  169. - (BOOL)adaptorContextShouldCommit:context;
  170.     // Invoked from -beginTransaction to ask the delegate whether or not to
  171.     // commit a transaction.
  172.  
  173. - (void)adaptorContextDidCommit:context;
  174.     // Invoked from -commitTransaction or -transactionDidCommit to tell the
  175.     // delegate that a transaction has been committed.  The delegate may take
  176.     // whatever action it needs based on this information.
  177.  
  178. - (BOOL)adaptorContextShouldRollback:context;
  179.     // Invoked from -rollbackTransaction to ask the delegate whether or not to
  180.     // rollback a transaction transaction.
  181.  
  182. - (void)adaptorContextDidRollback:context;
  183.     // Invoked from -rollbackTransaction or -transactionDidRollback to tell
  184.     // the delegate that a transaction has been rolled back.  The delegate may
  185.     // take whatever action it needs based on this information.
  186.  
  187. @end
  188.  
  189. //
  190. // Notifications
  191. //
  192. EOACCESS_EXTERN NSString *EOAdaptorContextBeginTransactionNotification;
  193.     // Sent from -[EOAdaptorContext transactionDidBegin];
  194. EOACCESS_EXTERN NSString *EOAdaptorContextCommitTransactionNotification;
  195.     // Sent from -[EOAdaptorContext transactionDidCommit];
  196. EOACCESS_EXTERN NSString *EOAdaptorContextRollbackTransactionNotification;
  197.     // Sent from -[EOAdaptorContext transactionDidRollback];
  198.