com.webobjects.eoaccess
Class EOAdaptorOperation

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

public class EOAdaptorOperation

extends Object

An EOAdaptorOperation object represents a single primitive operation in a database server (lock, insert, update, or delete a particular row, or execute a stored procedure) as well as all the necessary information required to perform the operation. An EOAdaptorOperation is processed by an EOAdaptorChannel object in the method performAdaptorOperation.

You don't ordinarily create instances of EOAdaptorOperation yourself. Rather, the Enterprise Objects Framework automatically creates an EOAdaptorOperation object and sends it to an adaptor channel when your application needs the database server to perform an operation. You generally directly interact with EOAdaptorOperation objects only if you need to specify the order in which a set of operations are carried out.

An EOAdaptorOperation has an entity and an operator (the type of operation it represents). EODatabaseOperation defines the following constants for adaptor operators:

• AdaptorLockOperator
• AdaptorInsertOperator
• AdaptorUpdateOperator
• AdaptorDeleteOperator
• AdaptorStoredProcedureOperator

An adaptor operation's operator determines the additional, operator- dependent information used by the EOAdaptorOperation object. For example, only a stored procedure operation has an EOStoredProcedure object. The operator-dependent information is accessible using the methods described below.

See Also:

EODatabaseOperation.AdaptorLockOperator, EODatabaseOperation.AdaptorInsertOperator, EODatabaseOperation.AdaptorUpdateOperator, EODatabaseOperation.AdaptorDeleteOperator, EODatabaseOperation.AdaptorStoredProcedureOperator, EOAdaptorChannel.performAdaptorOperation(EOAdaptorOperation adaptorOperation), adaptorOperator()

Constructor Summary

EOAdaptorOperation(EOEntity entity)
Creates and returns a new EOAdaptorOperation, with entity as the entity to which the operation will be applied.

Method Summary

int	adaptorOperator() Returns the receiver's adaptor operator.
NSArray	attributes() Returns the array of attributes to select when locking the row.
NSDictionary	changedValues() Returns the dictionary of values that need to be updated, inserted, or compared for locking purposes.
int	compareAdaptorOperation(EOAdaptorOperation other) Orders the adaptor operations represented by the receiver and other alphabetically by entity name, and by adaptor operator within the same entity.
EOEntity	entity() Returns the EOEntity to which the operation will be applied.
Throwable	exception() Returns the exception that was thrown when an adaptor channel attempted to process the receiver, or null if no exception was thrown or if the receiver hasn't been processed yet.
EOQualifier	qualifier() Returns the EOQualifier that identifies the specific row to which the adaptor operation applies.
void	setAdaptorOperator(int adaptorOperator) Sets the receiver's adaptor operator to adaptorOperator.
void	setAttributes(NSArray attributes) Sets the array of attributes to select when locking the row to attributes.
void	setChangedValues(NSDictionary changedValues) Sets the dictionary of values that need to be updated, inserted, or compared for locking purposes.
void	setException(Throwable exception) Sets the receiver's exception to exception.
void	setQualifier(EOQualifier qualifier) Sets the EOQualifier that identifies the row to which the adaptor operation will be applied.
void	setStoredProcedure(EOStoredProcedure storedProcedure) Sets the receiver's stored procedure.
EOStoredProcedure	storedProcedure() Returns the receiver's stored procedure.
String	toString() Returns a string representation of the receiver.

Methods inherited from class java.lang.Object

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

Constructor Detail

EOAdaptorOperation

public EOAdaptorOperation(EOEntity entity)

Creates and returns a new EOAdaptorOperation, with entity as the entity to which the operation will be applied.

Parameters:

entity - An entity.

See Also:

entity(), EOEntity

Method Detail

adaptorOperator

public int adaptorOperator()

Returns the receiver's adaptor operator. The operator determines which of the other adaptor operation attributes are valid. For example, an adaptor operation whose operator is AdaptorInsertOperator uses changedValues, but not attributes, qualifier, or storedProcedure.

Returns:

An integer constant representing an adaptor operation.

See Also:

EODatabaseOperation.AdaptorLockOperator, EODatabaseOperation.AdaptorInsertOperator, EODatabaseOperation.AdaptorUpdateOperator, EODatabaseOperation.AdaptorDeleteOperator, EODatabaseOperation.AdaptorStoredProcedureOperator, changedValues(), attributes(), qualifier(), storedProcedure()

attributes

public NSArray attributes()

Returns the array of attributes to select when locking the row. If attributes have not been assigned to the receiver, the primary key attributes are selected. Only valid for adaptor operations with the AdaptorLockOperator.

Returns:

The array of values to be used for the adaptor operation.

See Also:

EOAttribute

changedValues

public NSDictionary changedValues()

Returns the dictionary of values that need to be updated, inserted, or compared for locking purposes.

Returns:

The dictionary of values to be used for the adaptor operation.

compareAdaptorOperation

public int compareAdaptorOperation(EOAdaptorOperation other)

Orders the adaptor operations represented by the receiver and other alphabetically by entity name, and by adaptor operator within the same entity. Returns an NSComparator describing the relative order (NSOrderedAscending, NSOrderedSame, or NSOrderedDescending) of the receiver with respect to other.

Adaptor operators are ordered as follows (ascending order):

• AdaptorLockOperator
• AdaptorInsertOperator
• AdaptorUpdateOperator
• AdaptorDeleteOperator
• AdaptorStoredProcedureOperator

An EODatabaseContext uses compareAdaptorOperation to order adaptor operations before invoking EOAdaptorChannel's performAdaptorOperations method.

Parameters:

other - The adaptor operation to be ordered against the receiver.

Returns:

An NSComparator indicating the ordering of the receiver with respect to other.

See Also:

EOAdaptorChannel.performAdaptorOperations(NSArray adaptorOps), EODatabaseContext, NSComparator

entity

public EOEntity entity()

Returns the EOEntity to which the operation will be applied.

Returns:

The entity to which the adaptor operation will be applied.

See Also:

EOEntity

exception

public Throwable exception()

Returns the exception that was thrown when an adaptor channel attempted to process the receiver, or null if no exception was thrown or if the receiver hasn't been processed yet.

Returns:

The exception thrown while the operation was being processed, or null.

qualifier

public EOQualifier qualifier()

Returns the EOQualifier that identifies the specific row to which the adaptor operation applies. Not valid for adaptor operations with the operators AdaptorInsertOperator or AdaptorStoredProcedureOperator.

Returns:

A qualifier identifying the specific row to which the adaptor operation applies.

See Also:

EOQualifier

setAdaptorOperator

public void setAdaptorOperator(int adaptorOperator)

Sets the receiver's adaptor operator to adaptorOperator. The value of adaptorOperator must be one of the following constants:

• AdaptorLockOperator
• AdaptorInsertOperator
• AdaptorUpdateOperator
• AdaptorDeleteOperator
• AdaptorStoredProcedureOperator

Parameters:

adaptorOperator - An integer constant specifying an adaptor operator.

See Also:

EODatabaseOperation.AdaptorLockOperator, EODatabaseOperation.AdaptorInsertOperator, EODatabaseOperation.AdaptorUpdateOperator, EODatabaseOperation.AdaptorDeleteOperator, EODatabaseOperation.AdaptorStoredProcedureOperator

setAttributes

public void setAttributes(NSArray attributes)

Sets the array of attributes to select when locking the row to attributes. The selected values are compared in memory to the corresponding snapshot values to determine if a row has changed since the application last fetched it. attributes is an array of EOAttribute objects that can't be compared in a qualifier (generally BLOB types); it should not be null or empty.

Generally, an adaptor operation's qualifier contains all the comparisons needed to verify that a row hasn't changed since the application last fetched, inserted, or updated it. If there aren't any attributes that can't be compared in a qualifier (generally BLOB types), attributes should contain primary key attributes. This method is only valid for adaptor operations with the AdaptorLockOperator.

Parameters:

attributes - An array attributes used for locking that can't be compared in a qualifier.

See Also:

EOAttribute, EODatabaseContext

setChangedValues

public void setChangedValues(NSDictionary changedValues)

Sets the dictionary of values that need to be updated, inserted, or compared for locking purposes. changedValues is a dictionary object whose keys are attribute names and whose values are the values for those attributes. As summarized in the following table, the contents of changedValues depends on the receiver's operator:

Operator	Contents of changedValues Dictionary
AdaptorLockOperator	Snapshot values used to verify that the database row hasn't changed since this application last fetched it.
AdaptorInsertOperator	The values to insert.
AdaptorUpdateOperator	The new values for the columns to update.
AdaptorDeleteOperator	Snapshot values (changedValues is only valid for AdaptorDeleteOperator if the receiver's entity uses a stored procedure to perform delete operations).
AdaptorStoredProcedureOperator	Snapshot values

Parameters:

changedValues - A dictionary of attributes and values, as described above.

setException

public void setException(Throwable exception)

Sets the receiver's exception to exception.

This method is typically invoked from EOAdaptorChannel's performAdaptorOperations method. If a database error occurs while processing an adaptor operation, the adaptor channel creates an exception and assigns it to the adaptor operation.

Parameters:

exception - The exception that has been thrown.

See Also:

EOAdaptorChannel.performAdaptorOperations(NSArray adaptorOps)

setQualifier

public void setQualifier(EOQualifier qualifier)

Sets the EOQualifier that identifies the row to which the adaptor operation will be applied.

Parameters:

qualifier - A qualifier identifying the row to which the adaptor operation is to be applied.

See Also:

EOQualifier

setStoredProcedure

public void setStoredProcedure(EOStoredProcedure storedProcedure)

Sets the receiver's stored procedure.

Parameters:

storedProcedure - The stored procedure to be used for the adaptor operation.

See Also:

EOStoredProcedure

storedProcedure

public EOStoredProcedure storedProcedure()

Returns the receiver's stored procedure. Only valid for adaptor operations with the AdaptorStoredProcedureOperator.

Returns:

The receiver's stored procedure.

See Also:

EOStoredProcedure

toString

public String toString()

Returns a string representation of the receiver.

Overrides:

toString in class Object

Returns:

A string representation of the receiver.