BNZAtomicChange



Abstract

An AtomicChange is a single change on some target object, such as seting a new value for a variable.

Discussion

An AtomicChange is a single change on some target object, such as seting a new value for a variable. Usually, one will create single objects for each event that encapsulate single changes of a certain kind. An implementation of a certain AtomicChange then roughly corresponds to event-strings used to identify one event in NSNotificationCenter.

For example, imagine a class Person with a method setName. When using the NSNotificationCenter mechanism, one would define a string constant like PersonNameHasChangedEvent = "personNameHasChangedEvent". In the BNZTransactionalNotificationCenter framework an implementation of this protocol would be used not only to identify the type of change (of the variable "name" in this case) but also to apply the change (with commit) and redo/abort the change (with rollback).

Note that the AtomicChange objects themselves are not controlled by the BNZTransactionalNotificationCenter framework. So when you call commit or rollback on a change object that is part of an transaction (that may be active, committed or rolled back) the result is undefined. Therefore, you should neither use these objects directly nor store them and rely on their correct functioning at a later point.



Methods

changeType

Abstract: a unique identifier for this kind of change
- (id)changeType; 

Each change is identified by a type. Similar to an event (name), a changeType is used to determine the changes that affect some data.

For example: most commonly, a change type will directly correspond to a property name. Imagine a Person with an "address" property. An address change might then be done by a change that has "PersonAddressChange" as its identifier. The Person implementation will then use this identifier to find the changes on the address property that have been done within the current transaction.

Result: any object that identifies this kind of change. Usually a NSString*.

commit

Abstract: Commits the change
- (void)commit; 

This method is called during the commit phase of a transaction. It's task is, to apply the change (such as a "change name to 'Bob'") to the target object. When this method is called directly (i.e., outside the transaction framework) the effect is undefined. Most probably the change will just be applied without being controlled anyhow.

if a change could not be applied, this method is required to throw an NSException (of any type). Then, the transaction will be rolled back.


rollback

Abstract: rollback the change
- (void)rollback; 

When this method is called, the change (if it has already been applied) must be undone (such as, setting the variable value to the old name)

you should really make sure that this method does never throw an exception and undoes changes! If an exception is thrown, the other changes will be rolled back, but the application may remain in an undefined state (because this change may not have been undone)

if it is important wheather the commit has been called before or not the atomic change implementation has to care for this itself. rollback will be called independently from commit;


target

Abstract: The target of this change
- (id)target; 

Returns the target object where this change will be applied on when commit is called

Result: The target object

(Last Updated 8/31/2006)