com.webobjects.eoaccess
Interface EOAdaptorChannel.Delegate

Enclosing class:

EOAdaptorChannel

public static interface EOAdaptorChannel.Delegate

EOAdaptorChannel invokes its delegate for nearly every operation that would affect data in the database server. The delegate can use these methods to preempt these operations, modify their results, or simply track activity.

Method Summary

void	adaptorChannelDidChangeResultSet(EOAdaptorChannel channel) Invoked from fetchRow when a select operation resulted in multiple result sets.
void	adaptorChannelDidEvaluateExpression(EOAdaptorChannel channel, EOSQLExpression expression) Invoked from evaluateExpression to tell the delegate that a query language expression has been evaluated by the database server.
void	adaptorChannelDidExecuteStoredProcedure(EOAdaptorChannel channel, EOStoredProcedure storedProcedure, NSDictionary values) Invoked from executeStoredProcedure after storedProcedure is executed successfully with the arguments in values.
void	adaptorChannelDidFetchRow(EOAdaptorChannel channel, NSMutableDictionary row) Invoked from fetchRow after a row is fetched successfully.
void	adaptorChannelDidFinishFetching(EOAdaptorChannel channel) Invoked from fetchRow to tell the delegate that fetching is finished for the current select operation.
Throwable	adaptorChannelDidPerformOperations(EOAdaptorChannel channel, NSArray operation, Throwable exception) Invoked from performAdaptorOperations.
void	adaptorChannelDidSelectAttributes(EOAdaptorChannel channel, NSArray attributes, EOFetchSpecification fetchSpec, boolean lock, EOEntity entity) Invoked from selectAttributes to tell the delegate that some rows have been selected in the database server.
NSDictionary	adaptorChannelShouldConstructStoredProcedureReturnValues(EOAdaptorChannel channel) Invoked from returnValuesForLastStoredProcedureInvocation to tell the delegate that object is constructing return values for the last stored procedure evaluated.
boolean	adaptorChannelShouldEvaluateExpression(EOAdaptorChannel channel, EOSQLExpression expression) Invoked from evaluateExpression to tell the delegate that the adaptor channel object is sending expression to the database server.
NSDictionary	adaptorChannelShouldExecuteStoredProcedure(EOAdaptorChannel channel, EOStoredProcedure storedProcedure, NSDictionary values) Invoked from executeStoredProcedure to tell the delegate that the adaptor channel object is executing storedProcedure with the arguments in values.
NSDictionary	adaptorChannelShouldReturnValuesForStoredProcedure(EOAdaptorChannel channel, NSDictionary values) Invoked from returnValuesForLastStoredProcedureInvocation to tell the delegate that object is returning values for a stored procedure.
boolean	adaptorChannelShouldSelectAttributes(EOAdaptorChannel channel, NSArray attributes, EOFetchSpecification fetchSpec, boolean lock, EOEntity entity) Invoked from selectAttributes to ask the delegate whether a select operation should be performed by the adaptor channel object for the attributes of entity using the fetch specification fetchSpec, locking the database rows or not according to the Boolean parameter lock.
void	adaptorChannelWillFetchRow(EOAdaptorChannel channel) Invoked from fetchRow to tell the delegate that a single row will be fetched.
NSArray	adaptorChannelWillPerformOperations(EOAdaptorChannel channel, NSArray operations) Invoked from performAdaptorOperations to tell the delegate that object is performing the EOAdaptorOperations in operations.

Method Detail

adaptorChannelDidChangeResultSet

public void adaptorChannelDidChangeResultSet(EOAdaptorChannel channel)

Invoked from fetchRow when a select operation resulted in multiple result sets. This method tells the delegate that the next invocation of fetchRow will fetch from the next result set. This method is invoked when fetchRow returns null and there are still result sets left to fetch. The delegate can invoke setAttributesToFetch to prepare for fetching the new rows.

Parameters:

channel - An adaptor channel object.

See Also:

EOAdaptorChannel.fetchRow(), EOAdaptorChannel.setAttributesToFetch(NSArray attributes)

adaptorChannelDidEvaluateExpression

public void adaptorChannelDidEvaluateExpression(EOAdaptorChannel channel,
                                                EOSQLExpression expression)

Invoked from evaluateExpression to tell the delegate that a query language expression has been evaluated by the database server.

Parameters:

channel - An adaptor channel object.

expression - A query language expression.

See Also:

EOAdaptorChannel.evaluateExpression(EOSQLExpression expression), EOSQLExpression

adaptorChannelDidExecuteStoredProcedure

public void adaptorChannelDidExecuteStoredProcedure(EOAdaptorChannel channel,
                                                    EOStoredProcedure storedProcedure,
                                                    NSDictionary values)

Invoked from executeStoredProcedure after storedProcedure is executed successfully with the arguments in values.

Parameters:

channel - An adaptor channel object.

storedProcedure - The stored procedure that has been executed.

values - The arguments used to execute storedProcedure.

See Also:

EOAdaptorChannel.executeStoredProcedure( EOStoredProcedure storedProcedure, NSDictionary values), EOStoredProcedure

adaptorChannelDidFetchRow

public void adaptorChannelDidFetchRow(EOAdaptorChannel channel,
                                      NSMutableDictionary row)

Invoked from fetchRow after a row is fetched successfully. This method is not invoked if an exception occurs during the fetch or if fetchRow returns null because there are no more rows in the current result set. The delegate may modify row, which will be returned from fetchRow.

Parameters:

channel - An adaptor channel object.

row - The row fetched.

See Also:

EOAdaptorChannel.fetchRow()

adaptorChannelDidFinishFetching

public void adaptorChannelDidFinishFetching(EOAdaptorChannel channel)

Invoked from fetchRow to tell the delegate that fetching is finished for the current select operation. This method is invoked when a fetch ends in fetchRow because there are no more result sets.

Parameters:

channel - An adaptor channel object.

See Also:

EOAdaptorChannel.fetchRow()

adaptorChannelDidPerformOperations

public Throwable adaptorChannelDidPerformOperations(EOAdaptorChannel channel,
                                                    NSArray operation,
                                                    Throwable exception)

Invoked from performAdaptorOperations. The exception parameter is null if no exception was thrown while operations were performed, otherwise, exception is the thrown exception. The delegate can return the same or a different exception, which is re-thrown by performAdaptorOperation. Or it can return null to prevent the adaptor channel from throwing an exception.

Parameters:

channel - An adaptor channel object.

operations - An array containing the adaptor operations being executed when this method was invoked.

exception - The exception that was thrown during performAdaptorOperations, or null if no exception was thrown.

Returns:

May return exception, or a different exception, or null.

See Also:

EOAdaptorChannel.performAdaptorOperations(NSArray adaptorOps)

adaptorChannelDidSelectAttributes

public void adaptorChannelDidSelectAttributes(EOAdaptorChannel channel,
                                              NSArray attributes,
                                              EOFetchSpecification fetchSpec,
                                              boolean lock,
                                              EOEntity entity)

Invoked from selectAttributes to tell the delegate that some rows have been selected in the database server. The delegate may take whatever action it needs based on this information.

Parameters:

channel - An adaptor channel object.

attributes - An array of the attributes selected based on fetchSpec.

fetchSpec - Describes the row(s) to be selected.

lock - true if the rows are locked.

entity - The entity corresponding to the row(s) to be selected.

See Also:

EOAdaptorChannel.selectAttributes(NSArray attributes, EOFetchSpecification fetchSpecification, boolean flag, EOEntity entity), EOEntity, EOFetchSpecification

adaptorChannelShouldConstructStoredProcedureReturnValues

public NSDictionary adaptorChannelShouldConstructStoredProcedureReturnValues(EOAdaptorChannel channel)

Invoked from returnValuesForLastStoredProcedureInvocation to tell the delegate that object is constructing return values for the last stored procedure evaluated. If the delegate returns a value other than null, returnValuesForLastStoredProcedureInvocation will return that value immediately rather than constructing a return value from the execution of the stored procedure.

Parameters:

channel - An adaptor channel object.

Returns:

null if the adaptor channel should construct return values from the last executed stored procedure, or an alternative return value.

See Also:

EOAdaptorChannel.returnValuesForLastStoredProcedureInvocation()

adaptorChannelShouldEvaluateExpression

public boolean adaptorChannelShouldEvaluateExpression(EOAdaptorChannel channel,
                                                      EOSQLExpression expression)

Invoked from evaluateExpression to tell the delegate that the adaptor channel object is sending expression to the database server. The delegate should return true to permit the adaptor channel to send expression to the server. If the delegate returns false, the adaptor channel does not send the expression and returns immediately. When the delegate returns false, the adaptor channel expects that the implementor of the delegate has done the work that evaluateExpression would have done. The delegate can create a new EOSQLExpression and send the expression itself before returning false.

Parameters:

channel - An adaptor channel object.

expression - The expression to be sent to the database server.

Returns:

true to permits the adaptor channel to send expression to the database server.

See Also:

EOAdaptorChannel.evaluateExpression(EOSQLExpression expression), EOSQLExpression

adaptorChannelShouldExecuteStoredProcedure

public NSDictionary adaptorChannelShouldExecuteStoredProcedure(EOAdaptorChannel channel,
                                                               EOStoredProcedure storedProcedure,
                                                               NSDictionary values)

Invoked from executeStoredProcedure to tell the delegate that the adaptor channel object is executing storedProcedure with the arguments in values. The delegate can return a different dictionary of arguments to pass to the stored procedure, or null to permit the adaptor channel to use the original values.

Parameters:

channel - An adaptor channel object.

storedProcedure - A stored procedure.

values - The original arguments to be passed to storedProcedure.

Returns:

Should return a dictionary of new arguments to storedProcedure or null to use the original values.

See Also:

EOAdaptorChannel.executeStoredProcedure(EOStoredProcedure storedProcedure, NSDictionary values), EOStoredProcedure

adaptorChannelShouldReturnValuesForStoredProcedure

public NSDictionary adaptorChannelShouldReturnValuesForStoredProcedure(EOAdaptorChannel channel,
                                                                       NSDictionary values)

Invoked from returnValuesForLastStoredProcedureInvocation to tell the delegate that object is returning values for a stored procedure. If the delegate returns a value other than null, that value is returned from returnValuesForLastStoredProcedureInvocation instead of values.

Parameters:

channel - An adaptor channel object.

values - The values returned by the channel for a stored procedure.

Returns:

null if the adaptor channel should return the values from the last executed stored procedure, oa dictionary of alternate return values.

See Also:

EOAdaptorChannel.returnValuesForLastStoredProcedureInvocation()

adaptorChannelShouldSelectAttributes

public boolean adaptorChannelShouldSelectAttributes(EOAdaptorChannel channel,
                                                    NSArray attributes,
                                                    EOFetchSpecification fetchSpec,
                                                    boolean lock,
                                                    EOEntity entity)

Invoked from selectAttributes to ask the delegate whether a select operation should be performed by the adaptor channel object for the attributes of entity using the fetch specification fetchSpec, locking the database rows or not according to the Boolean parameter lock. If the delegate wants to perform a different select it should invoke selectAttributes itself with a new fetch specification, and return false (indicating that the adaptor channel should not perform the select itself). The delegate should not modify fetchSpec but rather should create a new fetch specification if needed.

Parameters:

channel - An adaptor channel object.

attributes - An array of the attributes to fetch.

fetchSpec - Describes the row(s) to be fetched.

lock - If true, the rows are locked during the fetch.

entity - The entity corresponding to the row(s) to be fetched.

Returns:

true to enable the adaptor channel to perform the specified fetch, false if the delegate will perform its own fetch. returns false.

See Also:

EOAdaptorChannel.selectAttributes(NSArray attributes, EOFetchSpecification fetchSpecification, boolean flag, EOEntity entity), EOEntity, EOFetchSpecification

adaptorChannelWillFetchRow

public void adaptorChannelWillFetchRow(EOAdaptorChannel channel)

Invoked from fetchRow to tell the delegate that a single row will be fetched. The delegate can determine the attributes used by the fetch by sending attributesToFetch to object, and can change the set of attributes to fetch by sending setAttributesToFetch to object. The adaptor channel performs the actual fetch.

Parameters:

channel - An adaptor channel object.

See Also:

EOAdaptorChannel.fetchRow(), EOAdaptorChannel.attributesToFetch(), EOAdaptorChannel.setAttributesToFetch(NSArray attributes)

adaptorChannelWillPerformOperations

public NSArray adaptorChannelWillPerformOperations(EOAdaptorChannel channel,
                                                   NSArray operations)

Invoked from performAdaptorOperations to tell the delegate that object is performing the EOAdaptorOperations in operations. The delegate may return operations or a different NSArray for the adaptor channel to perform. If the delegate returns null, the adaptor channel does not perform the operations and returns from the method immediately.

Parameters:

channel - An adaptor channel object.

operations - An array of adaptor operations.

Returns:

An array of adaptor operations to perform, or null.

See Also:

EOAdaptorChannel.performAdaptorOperations(NSArray adaptorOps)