Documentation Archive Developer
Search
PATH  Documentation > WebObjects 4.5 > EOAccess Reference

Table of Contents

EOAdaptorChannel


Inherits from: NSObject
Conforms to: NSObject
(NSObject)
Declared in: EOAccess/EOAdaptorChannel.h



Class Description

EOAdaptorChannel is an abstract class that provides its concrete subclasses with a structure for performing database operations. It's associated with EOAdaptor and EOAdaptorContext, which, together with EOAdaptorChannel, 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 EOAdaptorChannel provides database-specific method implementations and represents an independent communication channel to the database server to which its EOAdaptor object is connected. You never interact with instances of the EOAdaptorChannel class, rather your Enterprise Objects Framework applications use instances of concrete subclasses that are written to interact with a specific database or other persistent storage system.

You use an adaptor channel to manipulate rows (records) by selecting, fetching, inserting, deleting, and updating them. An adaptor channel also gives you access to some of the metadata on the server, such as what stored procedures exist, what tables exist, and what their basic attributes and relationships are.

All of an adaptor channel's operations take place within the context of transactions controlled or tracked by its EOAdaptorContext. An adaptor context may manage several channels (though not all can), but a channel is associated with only one context.


Notifying the Adaptor Channel's Delegate

You can assign a delegate to an adaptor channel. The EOAdaptorChannel sends certain messages directly to the delegate, and the delegate responds to these messages on the channel's behalf. Many of the adaptor channel methods notify the channel's delegate before and after an operation is performed. Some delegate methods, such as adaptorChannel:shouldEvaluateExpression:, let the delegate determine whether the channel should perform an operation. Others, such as adaptorChannel:didEvaluateExpression:, are simply notifications 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 adaptorChannel:shouldEvaluateExpression:. If it simply wants notification when a transaction has begun, it implements adaptorChannel:didEvaluateExpression:.

The principal attributes of the EOAdaptorChannel class are:

To create an instance of a concrete EOAdaptorChannel subclass, you send a createAdaptorChannel message to an instance of the corresponding EOAdaptorContext subclass. You rarely create adaptor channels yourself. They are generally created automatically by other framework objects.

The following table lists EOAdaptorChannel's more commonly-used methods:


Method Description
openChannel Opens the channel so it can perform database operations.
closeChannel Close the channel.
selectAttributes:fetchSpecification:lock:entity: Selects rows matching the specified qualifier.
fetchRowWithZone: Fetches a row resulting from the last selectAttributes:fetchSpecification:lock:entity:, executeStoredProcedure:withValues:, or evaluateExpression:.
insertRow:forEntity: Inserts the specified row.
updateValues:inRowsDescribedByQualifier:entity: Updates the row described by the specified qualifier.
deleteRowDescribedByQualifier:entity: Deletes the row described by the specified qualifier.
executeStoredProcedure:withValues: Performs the specified stored procedure.
evaluateExpression: Sends the specified expression to the database.


Method Description
- openChannel Opens the channel so it can perform database operations.
- closeChannel Close the channel.
- selectAttributes:fetchSpecification:lock:entity: Selects rows matching the specified qualifier.
- fetchRowWithZone: Fetches a row resulting from the last selectAttributes:fetchSpecification:lock:entity:, executeStoredProcedure:withValues:, or evaluateExpression:.
- insertRow:forEntity: Inserts the specified row.
- updateValues:inRowDescribedByQualifier:entity: Updates the row described by the specified qualifier.
- deleteRowDescribedByQualifier:entity: Deletes the row described by the specified qualifier.
- executeStoredProcedure:withValues: Performs the specified stored procedure.
- evaluateExpression: Sends the specified expression to the database.
- performAdaptorOperation: Performs an adaptor operation by invoking the EOAdaptorChannel method appropriate for performing the specified operation.

For more information on subclassing EOAdaptorChannel, see "Creating an EOAdaptorChannel Subclass" .




Constants

EOAccess defines several NSString constants in EOAdaptorChannel.h for use as keys and values in an exception's userInfo dictionary (see performAdaptorOperations:).


Constant Description
EOAdaptorOperationsKey A userInfo dictionary key.
EOFailedAdaptorOperationKey A userInfo dictionary key.
EOAdaptorFailureKey A userInfo dictionary key.
EOAdaptorOptimisticLockingFailure A userInfo dictionary value.



Method Types

Accessing the adaptor context
- adaptorContext
Opening and closing a channel
- openChannel
- closeChannel
- isOpen
Creating an EOAdaptorChannel
- initWithAdaptorContext:
Modifying rows
- insertRow:forEntity:
- updateValues:inRowDescribedByQualifier:entity:
- updateValues:inRowsDescribedByQualifier:entity:
- deleteRowDescribedByQualifier:entity:
- deleteRowsDescribedByQualifier:entity:
- lockRowComparingAttributes:entity:qualifier:snapshot:
Fetching rows
- selectAttributes:fetchSpecification:lock:entity:
- describeResults
- setAttributesToFetch:
- attributesToFetch
- fetchRowWithZone:
- dictionaryWithObjects:forAttributes:zone:
- cancelFetch
- isFetchInProgress
Invoking stored procedures
- executeStoredProcedure:withValues:
- returnValuesForLastStoredProcedureInvocation
Assigning primary keys
- primaryKeyForNewRowWithEntity:
Sending SQL to the server
- evaluateExpression:
Batch processing operations
- performAdaptorOperation:
- performAdaptorOperations:
Accessing schema information
- describeTableNames
- describeStoredProcedureNames
- addStoredProceduresNamed:toModel:
- describeModelWithTableNames:
Debugging
- setDebugEnabled:
- isDebugEnabled
Accessing the delegate
- delegate
- setDelegate:


Instance Methods


adaptorContext

- (EOAdaptorContext *)adaptorContext

Returns the receiver's EOAdaptorContext. A subclass of EOAdaptorChannel doesn't need to override this method.

See Also: - initWithAdaptorContext:


addStoredProceduresNamed:toModel:

- (void)addStoredProceduresNamed:(NSArray *)storedProcedureNames toModel:(EOModel *)model

Overridden by subclasses to create EOStoredProcedure objects for the stored procedures named in storedProcedureNames and then to add them to model. This method is used in conjunction with describeStoredProcedureNames to build a default model in EOModeler. Raises an exception if an error occurs.

attributesToFetch

- (NSArray *)attributesToFetch

Implemented by subclasses to return the set of attributes to retrieve when fetchRowWithZone: is next invoked. An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

cancelFetch

- (void)cancelFetch

Implemented by subclasses to clear all result sets established by the last selectAttributes:fetchSpecification:lock:entity:, executeStoredProcedure:withValues:, or evaluateExpression: message and terminate the current fetch, so that isFetchInProgress returns NO.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.


closeChannel

- (void)closeChannel

Implemented by subclasses to close the EOAdaptorChannel so that it can't perform operations with the server. Any fetch in progress is canceled. If the receiver is the last open channel in an adaptor context and if the channel's adaptor context has outstanding transactions, closing the channel has server-dependent results: some database servers roll back all outstanding transactions but others do nothing. Regardless of whether outstanding transactions are rolled back, this method has the side effect of closing the receiver's adaptor context's connection with the database if the receiver is its adaptor context's last open channel.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - cancelFetch, - hasOpenTransaction (EOAdaptorContext)


delegate

- (id)delegate

Returns the receiver's delegate, or nil if the receiver doesn't have a delegate. A subclass of EOAdaptorChannel doesn't need to override this method.

deleteRowDescribedByQualifier:entity:

- (void)deleteRowDescribedByQualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity

Deletes the row described by qualifier from the database table corresponding to entity. Invokes deleteRowsDescribedByQualifier:entity: and raises an exception unless exactly one row is deleted. A subclass of EOAdaptorChannel doesn't need to override this method.

deleteRowsDescribedByQualifier:entity:

- (unsigned int)deleteRowsDescribedByQualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity

Implemented by subclasses to delete the rows described by qualifier from the database table corresponding to entity. Returns the number of rows deleted. Raises an exception on failure. Some possible reasons for failure are:

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - deleteRowDescribedByQualifier:entity:, - isOpen, - isFetchInProgress, - hasOpenTransaction (EOAdaptorContext)


describeModelWithTableNames:

- (EOModel *)describeModelWithTableNames:(NSArray *)tableNames

Overridden by subclasses to create and return a default model containing entities for the tables specified in tableNames. Assigns the adaptor name and connection dictionary to the new model. This method is typically used in conjunction with describeTableNames and describeStoredProcedureNames.

EOAdaptorChannel's implementation does nothing. An adaptor channel subclass should override this method to create a default model from the database's metadata.


describeResults

- (NSArray *)describeResults

Implemented by subclasses to return an array of EOAttributes describing the properties available in the current result set, as determined by selectAttributes:fetchSpecification:lock:entity:, executeStoredProcedure:withValues:, or a statement evaluated by evaluateExpression:. Only invoke this method if a fetch is in progress as determined by isFetchInProgress.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.


describeStoredProcedureNames

- (NSArray *)describeStoredProcedureNames

Overridden by subclasses to read and return an array of stored procedure names from the database. This method is used in conjunction with addStoredProceduresNamed:toModel: to build a default model in EOModeler. Raises an exception if an error occurs.

describeTableNames

- (NSArray *)describeTableNames

Overridden by subclasses to read and return an array of table names from the database. This method in conjunction with describeModelWithTableNames: is used to build a default model.

EOAdaptorChannel's implementation simply returns nil. An adaptor channel subclass should override this method to construct an array of table names from database metadata.


dictionaryWithObjects:forAttributes:zone:

- (NSMutableDictionary *)dictionaryWithObjects:(id *)objects forAttributes:(NSArray *)attributes zone:(NSZone *)zone

Used by EOAdaptorChannel subclasses to create dictionaries that can be returned from fetchRowWithZone:. You don't ordinarily invoke this method unless you are writing your own concrete adaptor. If you are writing a concrete adaptor, use of this method is optional but strongly recommended because it enables performance optimizations. The objects in objects are the values for the row that correspond to the EOAttribute objects in attributes. The dictionary representation of the row is created from zone.

A subclass of EOAdaptorChannel shouldn't override this method.


evaluateExpression:

- (void)evaluateExpression:(EOSQLExpression *)expression

Implemented by subclasses to send expression to the database server for evaluation, beginning a transaction first and committing it after evaluation if a transaction isn't already in progress. Raises an exception if an error occurs. An EOAdaptorChannel uses this method to send SQL expressions to the database.

If expression results in a select operation being performed, you can fetch the results as you would if you had sent a selectAttributes:fetchSpecification:lock:entity:. You must use the method setAttributesToFetch: before you begin fetching. Also, if expression evaluates to multiple result sets, you must invoke setAttributesToFetch: before you begin fetching each subsequent set.

evaluateExpression: invokes the delegate methods adaptorChannel:shouldEvaluateExpression: and adaptorChannel:didEvaluateExpression:.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation. Note, however, that the upper layers of the Framework never invoke evaluateExpression: directly. Thus, adaptors for data stores that don't naturally support an expression language (for example, flat file adaptors) don't need to implement this method to work with the Framework.

See Also: - fetchRowWithZone:


executeStoredProcedure:withValues:

- (void)executeStoredProcedure:(EOStoredProcedure *)storedProcedure withValues:(NSDictionary *)values

Implemented by subclasses to execute storedProcedure. Any arguments to the stored procedure are in values, a dictionary whose keys are the argument names. Use fetchRowWithZone: to get result rows and returnValuesForLastStoredProcedureInvocation to get return arguments and result status, if any. Raises an exception if an error occurs.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation. Note, however, that the upper layers of the Framework never invoke executeStoredProcedure:withValues: directly. Thus, adaptors for data stores that don't support stored procedures (for example, flat file adaptors) don't need to implement this method to work with the Framework


fetchRowWithZone:

- (NSMutableDictionary *)fetchRowWithZone:(NSZone *)zone

Implemented by subclasses to fetch the next row from the result set of the last selectAttributes:fetchSpecification:lock:entity:, executeStoredProcedure:withValues:, or evaluateExpression: message sent to the receiver. Returns values for the receiver's attributesToFetch in a dictionary whose keys are the attribute names. When there are no more rows in the current result set, this method returns nil, and invokes the delegate method adaptorChannelDidChangeResultSet: if there are more results sets. When there are no more rows or result sets, this method returns nil, ends the fetch, and invokes adaptorChannelDidFinishFetching:. isFetchInProgress returns YES until the fetch is canceled or until this method exhausts all result sets and returns nil. This method also invoke the delegate methods adaptorChannelWillFetchRow: and adaptorChannel:didFetchRow:.Raises an exception if an error occurs.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - setAttributesToFetch:


initWithAdaptorContext:

- initWithAdaptorContext:(EOAdaptorContext *)adaptorContext

The designated initializer for the EOAdaptorChannel class, this method is overridden by subclasses to initialize a newly allocated EOAdaptorChannel subclass and retain adaptorContext. Returns self.

You never invoke this method directly unless you are implementing a concrete adaptor context. It is invoked automatically from createAdaptorChannel-the EOAdaptorContext method you use to create a new adaptor channel.

A subclass of EOAdaptorChannel doesn't need to override this method, but may override it to perform additional initialization. A subclass that does override this method must incorporate the superclass's version through a message to super.

See Also: - adaptorContext


insertRow:forEntity:

- (void)insertRow:(NSDictionary *)row forEntity:(EOEntity *)entity

Implemented by subclasses to insert the values of row into the table in the database that corresponds to entity. row is a dictionary whose keys are attribute names and whose values are the values to insert. Raises an exception on failure. Some possible reasons for failure are:

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.


isDebugEnabled

- (BOOL)isDebugEnabled

Returns YES if the adaptor channel logs evaluated SQL and other useful information to the console (or to the standard error stream), NO if not. A subclass of EOAdaptorChannel doesn't need to override this method.

See Also: - setDebugEnabled: (EOAdaptorContext)


isFetchInProgress

- (BOOL)isFetchInProgress

Implemented by subclasses to return YES if the receiver is fetching, NO otherwise. An adaptor channel is fetching if:

An adaptor channel stops fetching when there are no more records to fetch or when it's sent a cancelFetch message.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - fetchRowWithZone:


isOpen

- (BOOL)isOpen

Implemented by subclasses to return YES if the channel has been opened with openChannel, NO if not. An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - closeChannel


lockRowComparingAttributes:entity:qualifier:snapshot:

- (void)lockRowComparingAttributes:(NSArray *)attributes entity:(EOEntity *)entity qualifier:(EOQualifier *)qualifier snapshot:(NSDictionary *)snapshot

Attempts to lock a row in the database by selecting it with locking on. The lock operation succeeds if a select statement generated with qualifier retrieves exactly one row and the values in the row match the values in snapshot, a dictionary whose keys are attribute names and whose values are the values that were last fetched from the database.

lockRowComparingAttributes:entity:qualifier:snapshot: invokes selectAttributes:fetchSpecification:lock:entity: with attributes as the attributes to select, a fetch specification built from qualifier, locking on, and entity as the entity. If the select returns no rows or more than one row, the method raises an EOGeneralAdaptorException. It also raises an EOGeneralAdaptorException if the values in the returned row don't match the corresponding values in snapshot.

The Framework uses this method whenever it needs to lock a row. When the Framework invokes it, qualifier specifies the primary key of the row to be locked and attributes used for locking to be compared in the database server. If any of the values specified in qualifier are different from the values in the database row, the select operation will not retrieve or lock the row. When this happens, the row to be locked has been updated in the database since it was last retrieved, and it isn't safe to update it.

Some attributes (such as BLOB types) can't be compared in the database. attributes should specify any such attributes. (If the row doesn't contain any such attributes, attributes can be nil.) If qualifier generates a select statement that returns and locks a single row, this method performs an in-memory comparison between the value in the retrieved row and the value in snapshot for each attribute in attributes. Therefore, snapshot must contain an entry for each attribute in attributes. In addition, it must contain an entry for the row's primary key.

A subclass of EOAdaptorChannel doesn't need to override this method.


openChannel

- (void)openChannel

Implemented by subclasses to put the channel and both its context and adaptor into a state where they are ready to perform database operations. Raises an exception if an error occurs. An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - isOpen, - closeChannel


performAdaptorOperation:

- (void)performAdaptorOperation:(EOAdaptorOperation *)adaptorOperation

Performs adaptorOperation by invoking the adaptor channel method appropriate for performing the specified operation. For example, if the adaptor operator for adaptorOperation is EOAdaptorInsertOperator, this method invokes insertRow:forEntity: using information in adaptorOperation to supply the arguments. Raises an exception if an error occurs.

A subclass of EOAdaptorChannel doesn't need to override this method.

See Also: - performAdaptorOperations:


performAdaptorOperations:

- (void)performAdaptorOperations:(NSArray *)adaptorOperations

Performs adaptor operations by invoking performAdaptorOperation: with each EOAdaptorOperation object in the array adaptorOperations. An adaptor channel subclass may be able to override this method to take advantage of database-specific batch processing capabilities. Invokes the delegate methods adaptorChannel:willPerformOperations: and adaptorChannel:didPerformOperations:exception:.

This method raises an exception if an error occurs. The exception's userInfo dictionary contains these keys:


Constant The corresponding value in the exception's userInfo dictionary
EOAdaptorOperationsKey An array of the EOAdaptorOperations being executed.
EOFailedAdaptorOperationKey The particular EOAdaptorOperation that failed.
EOAdaptorFailureKey If present, offers additional information on the type of error that occurred. Currently, the only possible value for this key is EOAdaptorOptimisticLockingFailure, which indicates that an update or lock operation failed because the row found in the database did not match the snapshot taken when the row was last fetched into the application.

A subclass of EOAdaptorChannel doesn't need to override the performAdaptorOperations: method.


primaryKeyForNewRowWithEntity:

- (NSDictionary *)primaryKeyForNewRowWithEntity:(EOEntity *)entity

Overridden by subclasses to return a primary key for a new row in the database table that corresponds to entity. The primary key returned from this method is a dictionary whose keys are the primary key attribute names. For example, suppose you've got a table MOVIE with primary key MOVIE_ID, and the corresponding Movie entity's primary key attribute is movieID. In this scenario, the dictionary returned from primaryKeyForNewRowWithEntity: has one entry whose key is movieID and whose value is the unique value to assign. If the primary key is compound (made up of more than one attribute), the dictionary should contain an entry for each primary key attribute. Note, however, that the Enterprise Objects Frameworks adaptors don't handle compound primary keys; they return nil from primaryKeyForNewRowWithEntity: if the primary key is compound.

If information in entity specifies an adaptor-specific means to assign a new primary key (for example, a sequence name or stored procedure), then this method returns a new primary key. Otherwise, if the key is a simple integer, the method tries to fetch a new primary key from the database using an adaptor-specific scheme. Otherwise, the method returns nil.

EOAdaptorChannel's implementation simply returns nil. See your adaptor channel's documentation for information on how it generates primary keys.

A subclass of EOAdaptorChannel must override this method. For example, to return a value generated by a sequence, you'd create the proper SQL statement (using EOSQLExpression's expressionForString: method) and evaluate it (using the evaluateExpression: method).


returnValuesForLastStoredProcedureInvocation

- (NSDictionary *)returnValuesForLastStoredProcedureInvocation

Implemented by subclasses to return stored procedure parameter and return values. Used in conjunction with executeStoredProcedure:withValues:. The dictionary returned by this method has entries whose keys are stored procedure parameter names and whose values are the parameter values. The dictionary also contains a special entry for the stored procedures return value with the key "returnValue". Returns an empty dictionary for stored procedures that have void return types. Returns nil if the stored procedure has results to fetch. In this case, you must use fetchRowWithZone: until there are no more results to fetch before the return value will be available.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.


selectAttributes:fetchSpecification:lock:entity:

- (void)selectAttributes:(NSArray *)attributes fetchSpecification:(EOFetchSpecification *)fetchSpecification lock:(BOOL)flag entity:(EOEntity *)entity

Implemented by subclasses to select attributes in rows matching the qualifier in fetchSpecification and set the receiver's attributes to fetch. The selected rows compose one or more result sets, each row of which will be returned by subsequent fetchRowWithZone: messages according to fetchSpecification's sort orderings. If flag is YES, the rows are locked if possible so that no other user can modify them (the lock specification in fetchSpecification is ignored). Raises an exception if an error occurs. Some possible reasons for failure are:

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - setAttributesToFetch:


setAttributesToFetch:

- (EOAdaptorContext *)adaptorContext

Implemented by subclasses to specify the set of attributes used to describe fetch data from a corresponding select. attributes is an array of the attributes to fetch. This method is invoked after evaluateExpression: but before the first call to fetchRowWithZone:. This method raises an exception if invoked when there is no fetch in progress.

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - selectAttributes:fetchSpecification:lock:entity:


setDebugEnabled:

- (void)setDebugEnabled:(BOOL)flag

Enables debugging in the receiver and all its channels. If flag is YES, enables debugging; otherwise, disables debugging. When debugging is enabled, the adaptor channel logs evaluated SQL and other useful debugging information to the console (or to the standard error stream). The information provided may vary from adaptor to adaptor and may change from release to release.

A subclass of EOAdaptorChannel 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: - setDebugEnabled: (EOAdaptorContext)


setDelegate:

- (void)setDelegate:(id)delegate

Sets the receiver's delegate to delegate, or removes its delegate if delegate is nil.The receiver does not retain its delegate. A subclass of EOAdaptorChannel doesn't need to override this method. A subclass that does override it must incorporate the superclass's version through a message to super.

updateValues:inRowDescribedByQualifier:entity:

- (void)updateValues:(NSDictionary *)values inRowDescribedByQualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity

Updates the row described by qualifier. Invokes updateValues:inRowsDescribedByQualifier:entity: and raises an exception unless exactly one row is updated.

A subclass of EOAdaptorChannel doesn't need to override this method.


updateValues:inRowsDescribedByQualifier:entity:

- (unsigned int)updateValues:(NSDictionary *)values inRowsDescribedByQualifier:(EOQualifier *)qualifier entity:(EOEntity *)entity

Implemented by subclasses to update the rows described by qualifier with the values in values. values is a dictionary whose keys are attribute names and whose values are the new values for those attributes (the dictionary need only contain entries for the attributes being changed). Returns the number of updated rows. Raises an exception if an error occurs. Some possible reasons for failure are:

An adaptor channel subclass should override this method without invoking EOAdaptorChannel's implementation.

See Also: - updateValues:inRowDescribedByQualifier:entity:



Table of Contents