Inherits From:
NSObject
Declared in: EOAccess/EOAdaptorContext.h
A concrete subclass of EOAdaptorContext provides database-specific method implementations and represents a single transaction scope (logical user) on the database server to which its EOAdaptor object is connected. You never interact with instances of the EOAdaptorContext class, rather your Enterprise Objects Framework applications use instances of concrete subclasses that are written to work with a specific database or other persistent storage system. To create an instance of a concrete EOAdaptorContext subclass, you send a createAdaptorContext message to an instance of the corresponding EOAdaptor subclass. You rarely create adaptor contexts yourself. They are generally created automatically by other framework objects.
If a database server supports multiple concurrent transaction sessions, an adaptor context's EOAdaptor can have several contexts. When you use multiple EOAdaptorContexts for a single EOAdaptor, you can have several database server transactions in progress simultaneously. You should be aware of the issues involved in concurrent access if you do this.
An EOAdaptorContext has an EOAdaptorChannel, which handles actual access to the data on the server. If the database server supports it, a context can have multiple channels. See your adaptor context's documentation to find out if your adaptor supports multiple channels. An EOAdaptorContext by default has no EOAdaptorChannels; to create a new channel send your EOAdaptorContext a createAdaptorChannel message.
Controlling Transactions
EOAdaptorContext defines a simple set of methods for explicitly controlling transactions: beginTransaction , commitTransaction , and rollbackTransaction . Each of these messages confirms the requested action with the adaptor context's delegate, then performs the action if possible.
There's also a set of methods for notifying an adaptor context that a transaction has been started, committed, or rolled back without using the begin -, commit -, or rollbackTransaction methods. For example, if you invoke a stored procedure in the server that begins a transaction, you need to notify the adaptor context that a transaction has been started. Use the following methods to keep an adaptor context synchronized with the state of the database server: transactionDidBegin , transactionDidCommit , and transactionDidRollback . These methods post notifications.
The Adaptor Context's Delegate and Notifications
You can assign a delegate to an adaptor context. The delegate responds to certain messages on behalf of the context. An EOAdaptorContext sends these messages directly to its delegate. The transaction-controlling methods-beginTransaction , commitTransaction , and rollbackTransaction -notify the adaptor context's delegate before and after a transaction operation is performed. Some delegate methods, such as adaptorContextShouldBegin: , let the delegate determine whether the context should perform an operation. Others, such as adaptorContextDidBegin: , are simply notifications that an operation has occurred. The delegate has an opportunity to respond by implementing the delegate methods. If the delegate wants to intervene, it implements adaptorContextShouldBegin: . If it simply wants notification when a transaction has begun, it implements adaptorContextDidBegin: .
EOAdaptorContext also posts notifications to the application's default notification center. Any object may register to receive one or more of the notifications posted by an adaptor context by sending the message addObserver:selector:name:object: to the default notification center (an instance of the NSNotificationCenter class). For more information on notifications, see the NSNotificationCenter class specification in the Foundation Framework Reference.
Creating an EOAdaptorContext Subclass
EOAdaptorContext provides many default method implementations that are sufficient for concrete subclasses. In fact, the following methods establish structure and conventions that other Enterprise Objects Framework classes depend on and should never be overridden:
Other methods require database-specific implementations that can be provided only by a concrete adaptor context subclass. A subclass must override the following methods in terms of the persistent storage system to which it interfaces:
debugEnabledDefault
Returns YES if new adaptor context instances have debugging enabled by default, NO otherwise. By default, adaptor contexts have debugging enabled if the user default EOAdaptorDebugEnabled is YES. (For more information on user defaults, see the NSUserDefaults class specification in the Foundation Framework Reference.) You can override the user default using the class method setDebugEnabledDefault: , or you can set debugging behavior for a specific instance with the instance method setDebugEnabled: .
setDebugEnabledDefault:
+ (void)setDebugEnabledDefault:
(BOOL)flag
Sets default debugging behavior for new instances of EOAdaptorContext. If flag is YES, debugging is enabled for new instances. If flag is NO, debugging is disabled. Use the instance method setDebugEnabled: to enable debugging for a specific adaptor context.
See also: + debugEnabledDefault , - isDebugEnabled
adaptor
Returns the receiver's EOAdaptor.
See also: - initWithAdaptor:
beginTransaction
- (void)beginTransaction
Implemented by subclasses to attempt to begin a new transaction, nested within the current one if nested transactions are supported. Each successful invocation of beginTransaction must be paired with an invocation of either commitTransaction or rollbackTransaction to end the transaction.
The Enterprise Objects Framework automatically wraps database operations in transactions, so you don't have to begin and end transactions explicitly. In fact, letting the framework manage transactions is sometimes more efficient. You typically use beginTransaction only to execute more than one database operation in the same transaction scope.
This method invokes the delegate method adaptorContextShouldBegin: before beginning the transaction. If the transaction is begun successfully, sends self a transactionDidBegin message and invokes the delegate method adaptorContextDidBegin: . Raises if the attempt is unsuccessful. Some possible reasons for failure are:
An adaptor context subclass should override this method without invoking EOAdaptorContext's implementation.
See also: - commitTransaction , - rollbackTransaction , - canNestTransactions , - transactionNestingLevel
canNestTransactions
- (BOOL)canNestTransactions
Implemented by subclasses to return YES if the database server and the adaptor context can nest transactions, NO otherwise. An adaptor context subclass should override this method without invoking EOAdaptorContext's implementation.
See also: - transactionNestingLevel
channels
- (NSArray *)channels
Returns an array of channels created by this context.
See also: - createAdaptorChannel
commitTransaction
- (void)commitTransaction
Implemented by subclasses to attempt to commit the last transaction begun. Invokes the delegate method adaptorContextShouldCommit: before committing the transaction. If the transaction is committed successfully, sends self a transactionDidCommit message and invokes the delegate method adaptorContextDidCommit: . Raises if the attempt is unsuccessful. Some possible reasons for failure are:
An adaptor context subclass should override this method without invoking EOAdaptorContext's implementation.
See also: - beginTransaction , - transactionDidCommit , - hasBusyChannels
createAdaptorChannel
- (EOAdaptorChannel *)createAdaptorChannel
Implemented by subclasses to create and return a new EOAdaptorChannel, or nil if a new channel cannot be created. Initializes the new channel by sending it initWithAdaptorContext:self . The newly created channel retains its context. A newly created adaptor context has no channels. Specific adaptors have different limits on the maximum number of channels a context can have, and createAdaptorChannel may fail if a newly created channel will exceed the limits.
An adaptor context subclass should override this method without invoking EOAdaptorContext's implementation.
See also: - channels
Returns the receiver's delegate, or nil if the receiver doesn't have a delegate.
See also: - setDelegate:
hasBusyChannels
- (BOOL)hasBusyChannels
Returns YES if any of the receiver's channels have outstanding operations (that is, have a fetch in progress), NO otherwise.
See also: - isFetchInProgress (EOAdaptorChannel)
hasOpenChannels
- (BOOL)hasOpenChannels
Returns YES if any of the receiver's channels are open, NO otherwise.
See also: - openChannel (EOAdaptorChannel), - isOpen (EOAdaptorChannel)
initWithAdaptor:
- initWithAdaptor:
(EOAdaptor *)adaptor
The designated initializer for the EOAdaptorContext class, this method is overridden by subclasses to initialize a newly allocated EOAdaptorContext subclass and retain adaptor. Returns self .
You never invoke this method directly. You must use the EOAdaptor method createAdaptorContext to create a new adaptor context.
See also: - adaptor
isDebugEnabled
- (BOOL)isDebugEnabled
Returns YES if debugging is enabled in the receiver, NO otherwise.
See also: - setDebugEnabled: , + debugEnabledDefault , + setDebugEnabledDefault:
rollbackTransaction
- (void)rollbackTransaction
Implemented by subclasses to attempt to roll back the last transaction begun. Invokes the delegate method adaptorContextShouldRollback: before rolling back the transaction. If the transaction is begun successfully, sends self a transactionDidRollback message and invokes the delegate method adaptorContextDidRollback: . Raises if the attempt is unsuccessful. Some possible reasons for failure are:
An adaptor context subclass should override this method without invoking EOAdaptorContext's implementation.
See also: - beginTransaction , - commitTransaction
setDebugEnabled:
- (void)setDebugEnabled:
(BOOL)flag
Enables debugging in the receiver and all its channels. If flag is YES, enables debugging; otherwise, disables debugging.
See also: - setDebugEnabled: (EOAdaptorChannel), - isDebugEnabled , + setDebugEnabledDefault: , - channels
setDelegate:
- (void)setDelegate:
delegate
Sets the receiver's delegate and all the receiver's channels to delegate, or removes their delegates if delegate is nil . The receiver does not retain delegate.
See also: - delegate , - channels
transactionDidBegin
- (void)transactionDidBegin
Informs the adaptor context that a transaction has begun in the database server, so the receiver can update its state to reflect this fact and send an EOAdaptorContextBeginTransactionNotification. This method is invoked from beginTransaction after a transaction has successfully been started. It is also invoked when the Enterprise Objects Framework implicitly begins a transaction.
You don't need to invoke this method unless you are implementing a concrete adaptor. Your concrete adaptor should invoke this method from within your adaptor context's implementation of beginTransaction method and anywhere else it begins a transaction-either implicitly or explicitly. For example, an adaptor channel's implementation of evaluateExpression: should check to see if a transaction is in progress. If no transaction is in progress, it can start one explicitly by invoking beginTransaction . Alternatively, it can start an implicit transaction by invoking transactionDidBegin .
A subclass of EOAdaptorContext doesn't need to override this method. A subclass that does override it must incorporate the superclass's version through a message to super .
See also: - transactionDidCommit , - transactionDidRollback
transactionDidCommit
- (void)transactionDidCommit
Informs the adaptor context that a transaction has committed in the database server, so the receiver can update its state to reflect this fact and send an EOAdaptorContextCommitTransactionNotification. This method is invoked from commitTransaction after a transaction has successfully committed.
You don't need to invoke this method unless you are implementing a concrete adaptor. Your concrete adaptor should invoke this method from within your adaptor context's implementation of commitTransaction method and anywhere else it commits a transaction-either implicitly or explicitly.
A subclass of EOAdaptorContext doesn't need to override this method. A subclass that does override it must incorporate the superclass's version through a message to super .
See also: - transactionDidBegin , - transactionDidRollback
transactionDidRollback
- (void)transactionDidRollback
Informs the adaptor context that a transaction has rolled back in the database server, so the receiver can update its state to reflect this fact and send an EOAdaptorContextRollbackTransactionNotification. This method is invoked from rollbackTransaction after a transaction has successfully been rolled back.
You don't need to invoke this method unless you are implementing a concrete adaptor. Your concrete adaptor should invoke this method from within your adaptor context's implementation of rollbackTransaction method and anywhere else it rolls back a transaction-either implicitly or explicitly.
A subclass of EOAdaptorContext doesn't need to override this method. A subclass that does override it must incorporate the superclass's version through a message to super .
See also: - transactionDidBegin , - transactionDidCommit
transactionNestingLevel
- (unsigned)transactionNestingLevel
Returns the number of transactions in progress. If the database server and the adaptor support nested transactions, this number may be greater than 1.
See also: - canNestTransactions
EOAdaptorContextBeginTransactionNotification
Sent from transactionDidBegin to tell observers that a transaction has begun. The notification contains:
Notification Object The notifying EOAdaptorContext object Userinfo None EOAdaptorContextCommitTransactionNotification
Sent from transactionDidCommit to tell observers that a transaction has been committed. The notification contains:
Notification Object The notifying EOAdaptorContext object Userinfo None EOAdaptorContextRollbackTransactionNotification
Sent from transactionDidRollback to tell observers that a transaction has been rolled back. The notification contains:
Notification Object The notifying EOAdaptorContext object
Userinfo None
Methods Implemented By the Delegate
adaptorContextDidBegin:
- (void)adaptorContextDidBegin: context
Invoked from beginTransaction to tell the delegate that a transaction has begun.
adaptorContextDidCommit:
- (void)adaptorContextDidCommit: context
Invoked from commitTransaction to tell the delegate that a transaction has been committed.
adaptorContextDidRollback:
- (void)adaptorContextDidRollback: context
Invoked from rollbackTransaction to tell the delegate that a transaction has been rolled back.
adaptorContextShouldBegin:
- (BOOL)adaptorContextShouldBegin: context
Invoked from beginTransaction to tell the delegate that context is beginning a transaction. If this method returns NO, the adaptor context does not begin a transaction. Return YES to allow the adaptor context to begin a transaction.
adaptorContextShouldCommit:
- (BOOL)adaptorContextShouldCommit: context
Invoked from commitTransaction to tell the delegate that context is committing a transaction. If this method returns NO, the adaptor context does not commit the transaction. Return YES to allow the adaptor context to commit.
adaptorContextShouldRollback:
- (BOOL)adaptorContextShouldRollback: context
Invoked from rollbackTransaction to tell the delegate that context is rolling back a transaction. If this method returns NO, the adaptor context does not roll back the transaction. Return YES to allow the adaptor context to roll back.
Copyright © 1997, Apple Computer, Inc. All rights reserved.