PATH  WebObjects 4.0 Documentation > EOAccess Reference



EOAdaptorContext

Inherits From:
NSObject

Inherits From:
com.apple.yellow.webobjects


Class Description

EOAdaptorContext is an abstract class that defines transaction handling in Enterprise Objects Framework applications. 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 EOAdaptorContext class has the following principal attributes:

Other framework classes create EOAdaptorContext objects automatically. This is typically done with EOAdaptor's createAdaptorContext method, which creates an adaptor context and assigns its 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 "EOAdaptorContext".


Method Types

Constructors
EOAdaptorContext
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

Constructors


EOAdaptorContext

public EOAdaptorContext()

public EOAdaptorContext(EOAdaptor anAdaptor)

Returns a new EOAdaptorContext. You never invoke either of the constructors directly. You must use the Adaptor method createAdaptorContext to create a new adaptor context.

See also: adaptor



debugEnabledDefault

public static boolean debugEnabledDefault()

Returns true if new adaptor context instances have debugging enabled by default, false otherwise. By default, adaptor contexts have debugging enabled if the user default EOAdaptorDebugEnabled is true. (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

public static void setDebugEnabledDefault(boolean flag)

Sets default debugging behavior for new instances of EOAdaptorContext. If flag is true, debugging is enabled for new instances. If flag is false, debugging is disabled. Use the instance method setDebugEnabled to enable debugging for a specific adaptor context.

See also: debugEnabledDefault, isDebugEnabled


Instance Methods


adaptor

public EOAdaptor adaptor()

Returns the receiver's EOAdaptor.


beginTransaction

public abstract 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, 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: canNestTransactions, transactionNestingLevel


canNestTransactions

public abstract boolean canNestTransactions()

Implemented by subclasses to return true if the database server and the adaptor context can nest transactions, false otherwise. An adaptor context subclass should override this method without invoking EOAdaptorContext's implementation.

See also: transactionNestingLevel


channels

public NSArray channels()

Returns an array of channels created by the receiver.

See also: createAdaptorChannel


commitTransaction

public abstract 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 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


createAdaptorChannel

public abstract EOAdaptorChannel createAdaptorChannel()

Implemented by subclasses to create and return a new AdaptorChannel, or 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


delegate

public java.lang.Object delegate()

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

See also: setDelegate


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.

See also: isFetchInProgress (EOAdaptorChannel)


hasOpenChannels

public boolean hasOpenChannels()

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

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


isDebugEnabled

public boolean isDebugEnabled()

Returns true if debugging is enabled in the receiver, false otherwise.

See also: setDebugEnabled, debugEnabledDefault, setDebugEnabledDefault


rollbackTransaction

public abstract 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 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


setDebugEnabled

public void setDebugEnabled(boolean flag)

Enables debugging in the receiver and all its channels. If flag is true, enables debugging; otherwise, disables debugging.

See also: setDebugEnabled (EOAdaptorChannel), isDebugEnabled, setDebugEnabledDefault, channels


setDelegate

public void setDelegate(java.lang.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.

See also: delegate, channels


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

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

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

public int 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


AdaptorContextBeginTransactionNotification

public static final java.lang.String AdaptorContextBeginTransactionNotification

Sent from transactionDidBegin to tell observers that a transaction has begun.


AdaptorContextCommitTransactionNotification

public static final java.lang.String AdaptorContextCommitTransactionNotification

Sent from transactionDidCommit to tell observers that a transaction has been committed.


AdaptorContextRollbackTransactionNotification

public static final java.lang.String AdaptorContextRollbackTransactionNotification

Sent from transactionDidRollback to tell observers that a transaction has been rolled back.





Copyright © 1998, Apple Computer, Inc. All rights reserved.