com.webobjects.eoaccess
Class EOAdaptorContext

java.lang.Object
  |
  +--com.webobjects.eoaccess.EOAdaptorContext

Direct Known Subclasses:

JDBCContext, JNDIContext

public abstract class EOAdaptorContext

extends Object

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

Concrete subclasses of EOAdaptorContext provide database-specific method implementations and represent 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 directly; rather, your 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.

Controlling Transactions

EOAdaptorContext defines a simple set of methods for explicitly controlling transactions: beginTransaction, commitTransaction, and rollbackTransaction. Each of these methods confirms the requested action with the adaptor context's delegate, then performs the action if possible.

There is also a set of methods for notifying an adaptor context that a transaction has been started, committed, or rolled back without using the beginTransaction, commitTransaction, 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
• 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 methods on behalf of the context. An EOAdaptorContext invokes these methods on 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, simply inform the delegate 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 registering as an observer with the default notification center (an instance of the NSNotificationCenter class).

Creating an EOAdaptorContext Subclass

EOAdaptorContext provides many default method implementations that are sufficient for concrete subclasses. The following methods establish structure and conventions that other Enterprise Objects Framework classes depend on and should be overridden with caution:

• transactionDidBegin
• transactionDidCommit
• transactionDidRollback
• hasOpenTransaction

If you override any of the above methods, your implementations should incorporate the superclass's implementation through an invocation of super.

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

• beginTransaction
• commitTransaction
• createAdaptorChannel
• rollbackTransaction

See Also:

createAdaptorChannel(), beginTransaction(), commitTransaction(), rollbackTransaction(), EOAdaptor.createAdaptorContext(), EOAdaptor, NSNotificationCenter

Inner Class Summary

static interface

EOAdaptorContext.Delegate EOAdaptorContext invokes its delegate any time a transaction is begun, committed, or rolled back.

Field Summary

static String	AdaptorContextBeginTransactionNotification
static String	AdaptorContextCommitTransactionNotification
static String	AdaptorContextRollbackTransactionNotification

Constructor Summary

EOAdaptorContext(EOAdaptor adaptor)
Returns a new EOAdaptorContext.

Method Summary

EOAdaptor	adaptor() Returns the receiver's EOAdaptor.
abstract void	beginTransaction() An abstract method that should be implemented by subclasses to attempt to begin a new transaction.
boolean	canNestTransactions() Deprecated. Nested transactions are not supported.
NSArray	channels() Returns an array of channels created by the receiver.
abstract void	commitTransaction() An abstract method that should be implemented by subclasses to attempt to commit the last transaction begun.
abstract EOAdaptorChannel	createAdaptorChannel() An abstract method that should be implemented by subclasses to create and return a new EOAdaptorChannel, or null if a new channel cannot be created.
static Object	defaultDelegate() Returns the default delegate, which is the object assigned as delegate to all newly created EOAdaptorContext instances and their EOAdaptorChannels.
Object	delegate() Returns the receiver's delegate, or null if the receiver doesn't have a delegate.
abstract void	handleDroppedConnection() An abstract method that should be implemented by subclasses to clean up after the receiver's adaptor has lost its connection to its database server.
boolean	hasBusyChannels() Returns true if any of the receiver's channels have outstanding operations (that is, have a fetch in progress), false otherwise.
boolean	hasOpenChannels() Returns true if any of the receiver's channels are open, false otherwise.
boolean	hasOpenTransaction() Returns true if a transaction is currently open (has begun but not yet committed or rolled back), false otherwise.
abstract void	rollbackTransaction() An abstract method that should be implemented by subclasses to attempt to roll back the last transaction begun.
static void	setDefaultDelegate(Object delegate) Sets the default delegate, which is the object assigned as delegate to all newly created EOAdaptorContext instances and their EOAdaptorChannels, to delegate.
void	setDelegate(Object delegate) Sets the receiver's delegate and the delegate of all the receiver's channels to delegate, or removes their delegates if delegate is null.
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 posts an AdaptorContextBeginTransactionNotification.
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 posts an AdaptorContextCommitTransactionNotification.
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 posts an AdaptorContextRollbackTransactionNotification.
int	transactionNestingLevel() Deprecated. Use hasOpenTransaction instead.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AdaptorContextBeginTransactionNotification

public static final String AdaptorContextBeginTransactionNotification

AdaptorContextCommitTransactionNotification

public static final String AdaptorContextCommitTransactionNotification

AdaptorContextRollbackTransactionNotification

public static final String AdaptorContextRollbackTransactionNotification

Constructor Detail

EOAdaptorContext

public EOAdaptorContext(EOAdaptor adaptor)

Returns a new EOAdaptorContext. Never invoke this constructor directly. You must use the adaptor method createAdaptorContext to create a new adaptor context.

Parameters:

adaptor - The adaptor for the new adaptor context.

See Also:

adaptor(), EOAdaptor.createAdaptorContext()

Method Detail

adaptor

public EOAdaptor adaptor()

Returns the receiver's EOAdaptor.

Returns:

The receiver's EOAdaptor.

See Also:

EOAdaptorContext(EOAdaptor adaptor), EOAdaptor

beginTransaction

public abstract void beginTransaction()

An abstract method that should be 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 implement beginTransaction only to execute more than one database operation in the same transaction scope.

This method should invoke the delegate method adaptorContextShouldBegin before beginning the transaction. If the transaction is begun successfully, the method should invoke transactionDidBegin on the receiver and invoke the delegate method adaptorContextDidBegin. Should throw a runtime 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.

See Also:

hasOpenTransaction(), transactionDidBegin(), EOAdaptorContext.Delegate.adaptorContextShouldBegin(EOAdaptorContext adaptorContext), EOAdaptorContext.Delegate.adaptorContextDidBegin(EOAdaptorContext adaptorContext)

canNestTransactions

public boolean canNestTransactions()

Deprecated. Nested transactions are not supported.

channels

public NSArray channels()

Returns an array of channels created by the receiver.

Returns:

An array of channels used by this context.

See Also:

createAdaptorChannel()

commitTransaction

public abstract void commitTransaction()

An abstract method that should be implemented by subclasses to attempt to commit the last transaction begun. Should invoke the delegate method adaptorContextShouldCommit before committing the transaction. If the transaction is committed successfully, the method should invoke transactionDidCommit and invoke the delegate method adaptorContextDidCommit. Should throw a runtime 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.

See Also:

beginTransaction(), rollbackTransaction(), hasBusyChannels(), transactionDidCommit(), EOAdaptorContext.Delegate.adaptorContextShouldCommit(EOAdaptorContext adaptorContext), EOAdaptorContext.Delegate.adaptorContextDidCommit(EOAdaptorContext adaptorContext)

createAdaptorChannel

public abstract EOAdaptorChannel createAdaptorChannel()

An abstract method that should be implemented by subclasses to create and return a new EOAdaptorChannel, or null if a new channel cannot be created. Should set 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 should fail if a creating a new channel would exceed the limits.

Returns:

A new EOAdaptorChannel.

See Also:

EOAdaptorChannel.adaptorContext(), channels()

defaultDelegate

public static Object defaultDelegate()

Returns the default delegate, which is the object assigned as delegate to all newly created EOAdaptorContext instances and their EOAdaptorChannels. This method returns null until a valid delegate has been set using setDefaultDelegate.

Returns:

The default delegate.

See Also:

setDefaultDelegate(Object delegate)

delegate

public Object delegate()

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

Returns:

The receiver's delegate or null.

See Also:

setDelegate(Object delegate)

handleDroppedConnection

public abstract void handleDroppedConnection()

An abstract method that should be implemented by subclasses to clean up after the receiver's adaptor has lost its connection to its database server. Invoked from EOAdaptor's handleDroppedConnection, this method should clean up the state of the receiver and its adaptor channels so they can be safely disposed of without any errors. Subclasses must implement this method if the adaptor supports automatic database reconnection.

Never invoke this method yourself; it is invoked automatically by the Enterprise Objects Framework.

See Also:

EOAdaptor.handleDroppedConnection()

hasBusyChannels

public boolean hasBusyChannels()

Returns true if any of the receiver's channels have outstanding operations (that is, have a fetch in progress), false otherwise.

Returns:

true if any of the receiver's channels have outstanding operations.

See Also:

EOAdaptorChannel.isFetchInProgress()

hasOpenChannels

public boolean hasOpenChannels()

Returns true if any of the receiver's channels are open, false otherwise.

Returns:

true if any of the receiver's channels are open.

See Also:

EOAdaptorChannel.openChannel(), EOAdaptorChannel.isOpen()

hasOpenTransaction

public boolean hasOpenTransaction()

Returns true if a transaction is currently open (has begun but not yet committed or rolled back), false otherwise.

Returns:

true if a transaction is currently open.

rollbackTransaction

public abstract void rollbackTransaction()

An abstract method that should be implemented by subclasses to attempt to roll back the last transaction begun. Should invoke the delegate method adaptorContextShouldRollback before rolling back the transaction. If the transaction is begun successfully, the method should invoke transactionDidRollback and invoke the delegate method adaptorContextDidRollback. Should throw a runtime 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.

See Also:

beginTransaction(), commitTransaction(), transactionDidRollback(), EOAdaptorContext.Delegate.adaptorContextShouldRollback(EOAdaptorContext adaptorContext), EOAdaptorContext.Delegate.adaptorContextDidRollback(EOAdaptorContext adaptorContext)

setDefaultDelegate

public static void setDefaultDelegate(Object delegate)

Sets the default delegate, which is the object assigned as delegate to all newly created EOAdaptorContext instances and their EOAdaptorChannels, to delegate. The default delegate is null until this method has been used to set a valid delegate.

Parameters:

delegate - The object to assign as delegate to all newly created EOAdaptorContext instances.

See Also:

defaultDelegate()

setDelegate

public void setDelegate(Object delegate)

Sets the receiver's delegate and the delegate of all the receiver's channels to delegate, or removes their delegates if delegate is null.

Parameters:

delegate - The receiver's new delegate.

See Also:

channels(), delegate()

transactionDidBegin

public 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 posts an AdaptorContextBeginTransactionNotification. 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 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 an invocation of super.

See Also:

AdaptorContextBeginTransactionNotification, beginTransaction(), transactionDidBegin(), EOAdaptorChannel.evaluateExpression(EOSQLExpression expression)

transactionDidCommit

public 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 posts an AdaptorContextCommitTransactionNotification. 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 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 an invocation of super.

See Also:

AdaptorContextCommitTransactionNotification, commitTransaction()

transactionDidRollback

public 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 posts an AdaptorContextRollbackTransactionNotification. 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 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 an invocation of super.

See Also:

AdaptorContextRollbackTransactionNotification, rollbackTransaction()

transactionNestingLevel

public int transactionNestingLevel()

Deprecated. Use hasOpenTransaction instead.