com.webobjects.eoaccess
Class EODatabaseOperation

java.lang.Object
  com.webobjects.eoaccess.EODatabaseOperation

public class EODatabaseOperation
extends Object

An EODatabaseOperation object represents an operation (insert, update, or delete) to perform on an Enterprise Object and all the necessary information required to perform that operation. You don't ordinarily create instances of EODatabaseOperation. Rather, the Framework automatically creates an EODatabaseOperation object for each new, updated, or deleted object in an EOEditingContext. An EODatabaseContext object analyzes a set of database operations and maps each operation to one or more adaptor operations. The adaptor operations are then performed by an EOAdaptorChannel object. You generally interact with EODatabaseOperation objects only if you need to specify the order in which a set of operations are carried out.

An EODatabaseOperation specifies the Enterprise Object (called "object") on which the operation is performed, the EOGlobalID for the object, and the object's entity. In addition, the database operation has a snapshot containing the last known database values for the object and a newRow dictionary of new or updated values to save in the database.

See Also:

EODatabaseContext.Delegate.databaseContextWillOrderAdaptorOperations( EODatabaseContext dbCtxt, NSArray databaseOps)

Field Summary

static int	AdaptorDeleteOperator An EOAdaptorOperation object that deletes a row in a database server.
static int	AdaptorInsertOperator An EOAdaptorOperation object that inserts a row in a database server.
static int	AdaptorLockOperator An EOAdaptorOperation object that locks a row in a database server.
static int	AdaptorStoredProcedureOperator An EOAdaptorOperation object that executes a stored procedure in a database server.
static int	AdaptorUpdateOperator An EOAdaptorOperation object that updates a row in a database server.
static int	DatabaseDeleteOperator An EODatabaseOperation object that deletes an Enterprise Object.
static int	DatabaseInsertOperator An EODatabaseOperation object that inserts an Enterprise Object.
static int	DatabaseNothingOperator An EODatabaseOperation object that does nothing on an Enterprise Object.
static int	DatabaseUpdateOperator An EODatabaseOperation object that updates an Enterprise Object.

Constructor Summary

EODatabaseOperation(EOGlobalID globalID, Object object, EOEntity entity)
Creates and returns a new EODatabaseOperation object, setting the Enterprise Object to which the operation will be applied to object, its globalID to globalID, and its entity to entity.

Method Summary

NSArray	adaptorOperations() Returns the EOAdaptorOperation objects that need to be performed to carry out the database operation represented by the receiver.
void	addAdaptorOperation(EOAdaptorOperation adaptorOp) Adds adaptorOp to the receiver's list of adaptor operations.
int	databaseOperator() Returns the receiver's database operator.
NSDictionary	dbSnapshot() Returns the database snapshot for the receiver's Enterprise Object.
EOEntity	entity() Returns the EOEntity that owns to the receiver's enterprise object.
EOGlobalID	globalID() Returns the EOGlobalID object that corresponds to the receiver's Enterprise Object.
NSMutableDictionary	newRow() Returns a dictionary representation of the receiver's enterprise object.
Object	object() Returns the receiver's Enterprise Object.
NSDictionary	primaryKeyDiffs() Returns a dictionary that contains any primary key values in newRow that are different from those in the object's database snapshot.
void	recordToManySnapshot(NSArray gids, String name) Records the to-many snapshot gids for the relationship identified by name, belonging to the receiver's Enterprise Object.
void	removeAdaptorOperation(EOAdaptorOperation adaptorOp) Removes adaptorOp from the receiver's list of adaptor operations.
NSDictionary	rowDiffs() Returns the values in the receiver's newRow dictionary that are different than the corresponding values in its dbSnapshot, in other words, the new values for its Enterprise Object.
NSDictionary	rowDiffsForAttributes(NSArray atts) Returns the values for the EOAttributes of the receiver's Enterprise Object specified in atts that are new or updated relative to the object's database snapshot.
void	setDatabaseOperator(int databaseOperator) Sets the receiver's database operator to databaseOperator, which must be one of the list below.
void	setDBSnapshot(NSDictionary dbSnapshot) Sets the snapshot for the receiver's Enterprise Object.
void	setNewRow(NSMutableDictionary newRow) Sets the dictionary representation of the receiver's enterprise object.
NSDictionary	toManySnapshots() Returns the NSDictionary containing the snapshots for the to-many relationships of the receiver's Enterprise Object.
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

Field Detail

DatabaseNothingOperator

public static final int DatabaseNothingOperator

An EODatabaseOperation object that does nothing on an Enterprise Object.

See Also:

Constant Field Values

DatabaseInsertOperator

public static final int DatabaseInsertOperator

An EODatabaseOperation object that inserts an Enterprise Object.

See Also:

Constant Field Values

DatabaseUpdateOperator

public static final int DatabaseUpdateOperator

An EODatabaseOperation object that updates an Enterprise Object.

See Also:

Constant Field Values

DatabaseDeleteOperator

public static final int DatabaseDeleteOperator

An EODatabaseOperation object that deletes an Enterprise Object.

See Also:

Constant Field Values

AdaptorLockOperator

public static final int AdaptorLockOperator

An EOAdaptorOperation object that locks a row in a database server.

See Also:

Constant Field Values

AdaptorInsertOperator

public static final int AdaptorInsertOperator

An EOAdaptorOperation object that inserts a row in a database server.

See Also:

Constant Field Values

AdaptorUpdateOperator

public static final int AdaptorUpdateOperator

An EOAdaptorOperation object that updates a row in a database server.

See Also:

Constant Field Values

AdaptorDeleteOperator

public static final int AdaptorDeleteOperator

An EOAdaptorOperation object that deletes a row in a database server.

See Also:

Constant Field Values

AdaptorStoredProcedureOperator

public static final int AdaptorStoredProcedureOperator

An EOAdaptorOperation object that executes a stored procedure in a database server.

See Also:

Constant Field Values

Constructor Detail

EODatabaseOperation

public EODatabaseOperation(EOGlobalID globalID,
                           Object object,
                           EOEntity entity)

Creates and returns a new EODatabaseOperation object, setting the Enterprise Object to which the operation will be applied to object, its globalID to globalID, and its entity to entity.

Parameters:

globalID - The unique identifier for object.

object - The Enterprise Object on which the receiver will operate.

entity - The EOEntity to which object belongs.

Method Detail

dbSnapshot

public NSDictionary dbSnapshot()

Returns the database snapshot for the receiver's Enterprise Object. The snapshot contains the last known database values for the enterprise object. Returns an empty dictionary if the receiver's object has just been inserted into an EOEditingContext and has not yet been saved to the database.

Returns:

The database snapshot for the receiver's Enterprise Object.

See Also:

EODatabaseOperation.setDatabaseOperator(int databaseOperator), EOEditingContext

setDBSnapshot

public void setDBSnapshot(NSDictionary dbSnapshot)

Sets the snapshot for the receiver's Enterprise Object. If the object has just been inserted into an an EOEditingContext (EOControl), it won't have a snapshot. In this case, dbSnapshot should be an empty dictionary.

Parameters:

dbSnapshot - The database snapshot for the receiver's Enterprise Object, or an empty dictionary.

newRow

public NSMutableDictionary newRow()

Returns a dictionary representation of the receiver's enterprise object. In addition to all the properties of the Enterprise Object that are stored in the database, the dictionary contains values for the non-derived attributes of the Enterprise Object's entity that aren't visible in the Enterprise Object. For example, primary and foreign keys aren't ordinarily properties of an enterprise object but are attributes of the object's entity.

The newRow dictionary is initialized with the values in the receiver's snapshot. New or updated values are added to newRow (replacing out-of-date values) as the Enterprise Objects Framework maps changes in the object to an operation.

Returns:

A dictionary representation of the receiver's Enterprise Object.

setNewRow

public void setNewRow(NSMutableDictionary newRow)

Sets the dictionary representation of the receiver's enterprise object. newRow should contain values for all the properties of the Enterprise Object that are stored in the database and for the non-derived attributes of the Enterprise Object's entity that aren't visible in the Enterprise Object.

Parameters:

newRow - A dictionary representation of the receiver's Enterprise Object containing values for all properties and non-derived attributes of the object.

See Also:

EODatabaseOperation.databaseOperator(), EOAttribute

globalID

public EOGlobalID globalID()

Returns the EOGlobalID object that corresponds to the receiver's Enterprise Object.

Returns:

The globalID of the receiver's enterprise object.

See Also:

EODatabaseOperation.EODatabaseOperation(EOGlobalID aGlobalID, Object anObject, EOEntity anEntity)

object

public Object object()

Returns the receiver's Enterprise Object.

Returns:

The receiver's Enterprise Object.

entity

public EOEntity entity()

Returns the EOEntity that owns to the receiver's enterprise object.

Returns:

The entity to which the receiver's Enterprise Object belongs.

See Also:

EODatabaseOperation.EODatabaseOperation(EOGlobalID aGlobalID, Object anObject, EOEntity anEntity)

databaseOperator

public int databaseOperator()

Returns the receiver's database operator.

Returns:

The receiver's database operator.

setDatabaseOperator

public void setDatabaseOperator(int databaseOperator)

Sets the receiver's database operator to databaseOperator, which must be one of the list below.

• DatabaseNothingOperator
• DatabaseInsertOperator
DatabaseUpdateOperator
• DatabaseDeleteOperator

Throws an exception if:

• databaseOperator is DatabaseInsertOperator and the database operator that is currently set for the receiver is DatabaseDeleteOperator
• databaseOperator is DatabaseDeleteOperator and the database operator that is currently set for the receiver is DatabaseInsertOperator

Parameters:

databaseOperator - The database operator to set for the receiver.

Throws:

IllegalStateException - if attempting to change the receiver's operation from insert to delete, or from delete to insert.

rowDiffs

public NSDictionary rowDiffs()

Returns the values in the receiver's newRow dictionary that are different than the corresponding values in its dbSnapshot, in other words, the new values for its Enterprise Object.

Returns:

The new or updated values for the receiver's Enterprise Object.

See Also:

EODatabaseOperation.primaryKeyDiffs()

rowDiffsForAttributes

public NSDictionary rowDiffsForAttributes(NSArray atts)

Returns the values for the EOAttributes of the receiver's Enterprise Object specified in atts that are new or updated relative to the object's database snapshot. In other words, the attribute values in the object's newRow dictionary that are different than the corresponding values in its dbSnapshot. Returns an empty dictionary if there are no differences in attribute values.

Throws an exception if atts contains an attribute that is not present in the the database snapshot for the receiver's object.

Parameters:

atts - The attributes of the receiver's Enterprise Object.

Returns:

The new or updated attribute values for the receiver's Enterprise Object, or an empty dictionary.

Throws:

IllegalStateException - if any of the attributes in atts is not found in the object's snapshot.

primaryKeyDiffs

public NSDictionary primaryKeyDiffs()

Returns a dictionary that contains any primary key values in newRow that are different from those in the object's database snapshot. Returns an empty dictionary if the database operation set for the receiver is not EODatabaseUpdateOperator.

Returns:

Any new or updated primary key values for the receiver's Enterprise Object.

See Also:

EODatabaseOperation.setDatabaseOperator(int databaseOperator), EODatabaseOperation.newRow()

adaptorOperations

public NSArray adaptorOperations()

Returns the EOAdaptorOperation objects that need to be performed to carry out the database operation represented by the receiver. Returns an empty array if no adaptor operations are set for the receiver.

Returns:

The receiver's EOAdaptorOperation objects.

See Also:

EODatabaseOperation.addAdaptorOperation(EOAdaptorOperation adaptorOperation), EODatabaseOperation.removeAdaptorOperation(EOAdaptorOperation adaptorOperation)

addAdaptorOperation

public void addAdaptorOperation(EOAdaptorOperation adaptorOp)

Adds adaptorOp to the receiver's list of adaptor operations.

Parameters:

adaptorOp - A adaptor operation to add to the receiver's list of adaptor operations.

See Also:

EODatabaseOperation.adaptorOperations(), EODatabaseOperation.removeAdaptorOperation(EOAdaptorOperation adaptorOperation)

removeAdaptorOperation

public void removeAdaptorOperation(EOAdaptorOperation adaptorOp)

Removes adaptorOp from the receiver's list of adaptor operations.

Parameters:

adaptorOp - A adaptor operation to remove from the receiver's list of adaptor operations.

See Also:

EODatabaseOperation.adaptorOperations(), EODatabaseOperation.addAdaptorOperation(EOAdaptorOperation adaptorOperation)

toString

public String toString()

Returns a string representation of the receiver.

Overrides:

toString in class Object

Returns:

A string representation of the receiver.

recordToManySnapshot

public void recordToManySnapshot(NSArray gids,
                                 String name)

Records the to-many snapshot gids for the relationship identified by name, belonging to the receiver's Enterprise Object. gids is an array of globalIDs that identify the objects at the destination of the specified to-many relationship.

Parameters:

gids - The globalIDs that comprise the to-many snapshot for the relationship specified by name.

name - The name of the to-many relationship for which to record a snapshot.

See Also:

EODatabaseOperation.toManySnapshots(), EODatabase, EORelationship

toManySnapshots

public NSDictionary toManySnapshots()

Returns the NSDictionary containing the snapshots for the to-many relationships of the receiver's Enterprise Object.

Returns:

The snapshots for the to-many relationships of the receiver's Enterprise Object

See Also:

EODatabaseOperation.recordToManySnapshot(NSArray globalIDs, String name)