EOAdaptorContext

Inherits From:
NSObject

Declared in: EOAccess/EOAdaptorContext.h

The EOAdaptorContext class has the following principal attributes:

• Array of adaptor channels
• Delegate
• Adaptor

The following table lists the most commonly-used EOAdaptorContext methods:

- beginTransaction	Begins a transaction in the database server.
- commitTransaction	Commits the last transaction begun.
- rollbackTransaction	Rolls back the last transaction begun.
- setDebugEnabled:	Enables debugging in all the adaptor context's channels.

For more information, see "More about EOAdaptorContext".

Creating an EOAdaptorContext

- initWithAdaptor:

Accessing the adaptor

- adaptor

Creating adaptor channels

- createAdaptorChannel

- channels

Checking connection status

- hasOpenChannels

- hasBusyChannels

Controlling transactions

- beginTransaction

- commitTransaction

- rollbackTransaction

- transactionDidBegin

- transactionDidCommit

- transactionDidRollback

- canNestTransactions

- transactionNestingLevel

Debugging

+ setDebugEnabledDefault:

+ debugEnabledDefault

- setDebugEnabled:

- isDebugEnabled

Accessing the delegate

- delegate

- setDelegate:

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:

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

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:

• A connection to the database hasn't been established.
• Nested transactions aren't supported, and a transaction is already in progress.
• A fetch is in progress.
• The delegate refuses.
• The database server fails to begin a transaction.

See also: - commitTransaction, - rollbackTransaction, - canNestTransactions, - transactionNestingLevel

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

Returns an array of channels created by this context.

See also: createAdaptorChannel

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:

• A transaction is not in progress.
• Fetches are in progress.
• The delegate refuses.
• The database server fails to commit.

See also: - beginTransaction, - createAdaptorChannel, - transactionDidCommit, - hasBusyChannels

createAdaptorChannel

Implemented by subclasses to create and return a new AdaptorChannel, 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 fails if a newly created channel would exceed the limits.

See also: - channels

delegate

Returns the receiver's delegate, or nil if the receiver doesn't have a delegate.

See also: - setDelegate:

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

Returns YES if any of the receiver's channels are open, NO otherwise.

See also: - openChannel (EOAdaptorChannel), - isOpen (EOAdaptorChannel)

initWithAdaptor:

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

Returns YES if debugging is enabled in the receiver, NO otherwise.

See also: - setDebugEnabled:, + debugEnabledDefault, + setDebugEnabledDefault:

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:

• A transaction is not in progress.
• Fetches are in progress.
• The delegate refuses.
• The database server fails to rollback.

See also: - beginTransaction, - commitTransaction

setDebugEnabled:

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:

Sets the receiver's delegate and the delegate of 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

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

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

Informs the receiver that a transaction has rolled back in the database server, so the adaptor context 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

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

Notifications

EOAdaptorContextBeginTransactionNotification

Notification Object	The notifying EOAdaptorContext object
Userinfo	None

EOAdaptorContextCommitTransactionNotification

Notification Object	The notifying EOAdaptorContext object
Userinfo	None

EOAdaptorContextRollbackTransactionNotification

Notification Object	The notifying EOAdaptorContext object
Userinfo	None