WebObjects 5.4.2

com.webobjects.eoaccess
Class EOAdaptorOperation

java.lang.Object
  extended by 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:

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), EOAdaptorOperation.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:
EOAdaptorOperation.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, EOAdaptorOperation.changedValues(), EOAdaptorOperation.attributes(), EOAdaptorOperation.qualifier(), EOAdaptorOperation.storedProcedure()

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:

Parameters:
adaptorOperator - An integer constant specifying an adaptor operator.
See Also:
EODatabaseOperation.AdaptorLockOperator, EODatabaseOperation.AdaptorInsertOperator, EODatabaseOperation.AdaptorUpdateOperator, EODatabaseOperation.AdaptorDeleteOperator, EODatabaseOperation.AdaptorStoredProcedureOperator

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

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

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

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.

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.

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

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

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

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

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.

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)

toString

public String toString()
Returns a string representation of the receiver.

Overrides:
toString in class Object
Returns:
A string representation of the receiver.

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

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

Last updated June 2008

Copyright © 2000-2008 Apple Inc.