PATH Documentation > WebObjects 4.5 > EOAccess Reference

EOAdaptorContext

Inherits from: NSObject

Declared in: EOAccess/EOAdaptorContext.h

Class Description

EOAdaptorContext is an abstract class that provides its concrete subclasses with a structure for handling database transactions. It's associated with EOAdaptor and EOAdaptorChannel, which, together with EOAdaptorContext, form the adaptor level of Enterprise Objects Framework's access layer. See the EOAdaptor class specification for more information about accessing, creating, and using adaptor level objects.

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.

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.

The EOAdaptorContext class has the following principal attributes:

Array of adaptor channels
Delegate
Adaptor

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.

You typically don't interact with EOAdaptorContext API directly; rather, a concrete adaptor context subclass inherits from EOAdaptorContext and overrides many of its methods, which are invoked automatically by the Enterprise Objects Framework. If you're not creating a concrete adaptor context subclass, there aren't very many methods you need to use, and you'll rarely invoke them directly. The following table lists the most commonly-used EOAdaptorContext methods:

EOAdaptorContext isn't declared to be abstract, but conceptually it is abstract. Never create instances of the EOAdaptorContext class.

Method	Description
- 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.

Method Types

Creating an EOAdaptorContext

- initWithAdaptor:

Accessing the adaptor

- adaptor

Creating adaptor channels

- createAdaptorChannel

- channels

Accessing and managing connection status

- hasOpenChannels

- hasBusyChannels

- handleDroppedConnection

Controlling transactions

- beginTransaction

- commitTransaction

- rollbackTransaction

- transactionDidBegin

- transactionDidCommit

- transactionDidRollback

- hasOpenTransaction

Debugging

+ setDebugEnabledDefault:

+ debugEnabledDefault

- setDebugEnabled:

- isDebugEnabled

Accessing the delegate

- delegate

- setDelegate:

+ defaultDelegate

+ setDefaultDelegate:

Class Methods

debugEnabledDefault

+ (BOOL)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:.

defaultDelegate

+ (id)defaultDelegate

Returns the default delegate-the object that is assigned as delegate to new adaptor context instances (and their channels).

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: - isDebugEnabled

setDefaultDelegate:

+ (void)setDefaultDelegate:(id)defaultDelegate

Sets the default delegate-the object assigned as delegate to all newly created EOAdaptorContext instances (and their EOAdaptorChannels). By default there is no default delegate.

Instance Methods

adaptor

- (EOAdaptor *)adaptor

Returns the receiver's EOAdaptor.

See Also: - initWithAdaptor:

beginTransaction

- (void)beginTransaction

Implemented by subclasses to attempt to begin a new transaction. A 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, the method sends self a transactionDidBegin message and invokes the delegate method adaptorContextDidBegin:. Raises an exception if the attempt is unsuccessful. Some possible reasons for failure are:

A connection to the database hasn't been established.
A transaction is already in progress.
A fetch is in progress.
The delegate refuses.
The database server fails to begin a transaction.

An adaptor context subclass should override this method without invoking EOAdaptorContext's implementation.

See Also: - hasOpenTransaction

channels

- (NSArray *)channels

Returns an array of channels created by the receiver.

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, the method sends self a transactionDidCommit message and invokes the delegate method adaptorContextDidCommit:. Raises an exception 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.

An adaptor context subclass should override this method without invoking EOAdaptorContext's implementation.

createAdaptorChannel

- (EOAdaptorChannel *)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

- delegate

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

handleDroppedConnection

- (void)handleDroppedConnection

Implemented by subclasses to clean up after the receiver's adaptor lost its connection to its database server. Invoked from EOAdaptor's handleDroppedConnection, this method cleans up the state of its adaptor channels and of itself so the receiver and its channels can be safely disposed of without any errors.

You should never invoke this method; it is invoked automatically by the Framework. Subclasses must implement this method, without invoking super, if the adaptor supports automatic database reconnection.

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)

hasOpenTransaction

- (BOOL)hasOpenTransaction

Returns YES if a transaction is open (begun but not yet committed or rolled back), NO otherwise.

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.

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, the method sends self a transactionDidRollback message and invokes the delegate method adaptorContextDidRollback:. Raises an exception 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.

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 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: - 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.

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.

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.

transactionDidRollback

- (void)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.

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.

Notifications

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