| PATH |
Inherits from: Object
Package: com.webobjects.eoaccess
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.
| Note: EOAdaptorContext is abstract. Never create instances of the EOAdaptorContext class. |
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:
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:
| Method | Description |
| beginTransaction | Begins a transaction in the database server. |
| commitTransaction | Commits the last transaction begun. |
| rollbackTransaction | Rolls back the last transaction begun. |
Constructors EOAdaptorContext 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 Accessing the delegate delegate setDelegate defaultDelegate setDefaultDelegate
public EOAdaptorContext(EOAdaptor anAdaptor)
See Also: adaptor
public static Object defaultDelegate()
public static void setDefaultDelegate(Object anObject)
public EOAdaptor adaptor()
See Also: EOAdaptorContext constructor
public abstract void beginTransaction()
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 this a transactionDidBegin message and invokes the delegate method adaptorContextDidBegin. Throws an exception 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: hasOpenTransaction
public boolean canNestTransactions()
public NSArray channels()
See Also: createAdaptorChannel
public abstract void commitTransaction()
this a transactionDidCommit message and invokes the delegate method adaptorContextDidCommit. Throws an exception 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, rollbackTransaction, hasBusyChannels
public abstract EOAdaptorChannel createAdaptorChannel()
null if a new channel cannot be created. Sets the new channel's adaptorContext to this. 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
public Object delegate()
null if the receiver doesn't have a delegate.
public abstract void handleDroppedConnection()
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.
public boolean hasBusyChannels()
true if any of the receiver's channels have outstanding operations (that is, have a fetch in progress), false otherwise.
See Also: isFetchInProgress (EOAdaptorChannel)
public boolean hasOpenChannels()
true if any of the receiver's channels are open, false otherwise.
See Also: openChannel (EOAdaptorChannel), isOpen (EOAdaptorChannel)
public boolean hasOpenTransaction()
true if a transaction is open (begun but not yet committed or rolled back), false otherwise.
public abstract void rollbackTransaction()
this a transactionDidRollback message and invokes the delegate method adaptorContextDidRollback. Throws an exception 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
public void setDelegate(Object delegate)
null.
See Also: channels
public void transactionDidBegin()
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.
public void transactionDidCommit()
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.
public void transactionDidRollback()
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..
public int transactionNestingLevel()
public static final String AdaptorContextBeginTransactionNotification
| Notification Object | The notifying EOAdaptorContext object |
| Userinfo | None |
public static final String AdaptorContextCommitTransactionNotification
| Notification Object | The notifying EOAdaptorContext object |
| Userinfo | None |
public static final String AdaptorContextRollbackTransactionNotification
| Notification Object | The notifying EOAdaptorContext object |
| Userinfo | None |
© 2001 Apple Computer, Inc. (Last Published April 13, 2001)