EOFaultHandler
- Inherits from:
- NSObject
- Conforms to:
- NSObject
- (NSObject)
Declared in:
- EOControl/EOFault.h
Class Description
EOFaultHandler is an abstract class that defines the mechanisms that create faults (EOFault objects) and help them to fire. Faults are used as placeholders for an enterprise object's relationship destinations. For example, suppose an Employee object has a department relationship to the employee's department. When an employee is fetched, faults are created for its relationship destinations. In the case of the department relationship, an empty Department object is created. The Department object's data isn't fetched until the Department is accessed, at which time the fault is said to fire.
Subclasses of EOFaultHandler perform the specific steps necessary to get data for the fault and fire it. The Access Layer, for example, uses private subclasses to fetch data using an EODatabaseContext (defined in EOAccess). Most of EOFaultHandler's methods are properly defined; you need only override completeInitializationOfObject: to provide appropriate behavior. In Yellow Box applications, you can optionally implement faultWillFire: to prepare for conversion, and shouldPerformInvocation: to intercept particular messages sent to the fault without causing it to fire.
In a Yellow Box application you create an EOFaultHandler using the standard alloc and init methods, possibly using a more specific init method with your subclass. To create a fault you invoke EOFault's makeObjectIntoFault:withHandler: class method with the object to turn into a fault and the EOFaultHandler. An EOFaultHandler belongs exclusively to a single fault, and shouldn't be shared or used by any other object.
Firing a Fault
When a fault receives a message that requires it to fire, it sends a completeInitializationOfObject: method to its EOFaultHandler. This method is responsible for invoking EOFault's clearFault:class method to revert the fault to its original state, and then do whatever is necessary to complete initialization of the object. Doing so typically involves fetching data from an external repository and passing it to the object.
As a trivial example, consider a subclass called FileFaultHandler, that simply stores a filename whose contents it reads from disk. Its initialization and completeInitializationOfObject: methods might look like these:
- (id)initWithFile:(NSString *)path { self = [super init]; filename = [path copy]; return self; } - (void)completeInitializationOfObject:(id)anObject { NSString *fileContents; [self retain]; // retain self so we won't get released by clearing the // fault. Otherwise, accessing "filename" will cause a crash. [EOFault clearFault:anObject]; fileContents = [NSString stringWithContentsOfFile:filename]; [anObject takeValue:fileContents forKey:@"fileContents"]; [self release]; return; }
initWithFile: just stores the path of the file to read in the instance variable filename. completeInitializationOfObject: invokes EOFault's clearFault: method, which reverts the fault into its original state (and also releases the fault handler, so references to self after this are illegal). It then gets the contents of the file it was created with and passes them to the reverted object. Note that this implementation doesn't assume the class of the cleared EOFault, instead using the generic takeValue:forKey: method to assign the file contents to it.
Method Types
- Creating and examining faults
- - createFaultForDeferredFault:sourceObject:
- Setting the target class and extra data
- - setTargetClass:extraData:
- - targetClass
- - extraData
- Reference counting
- - incrementExtraRefCount
- - decrementExtraRefCountIsZero
- - extraRefCount
- Getting the original class
- - classForFault:
- Firing a fault
- - completeInitializationOfObject:
- - faultWillFire:
- - shouldPerformInvocation:
- Getting a description
- - descriptionForObject:
- Checking class information
- - isKindOfClass:forFault:
- - isMemberOfClass:forFault:
- - conformsToProtocol:forFault:
- - methodSignatureForSelector:forFault:
- - respondsToSelector:forFault:
Instance Methods
classForFault:
- (Class)classForFault:(id)fault
See Also: - targetClass
completeInitializationOfObject:
- (void)completeInitializationOfObject:(id)aFault
conformsToProtocol:forFault:
- (BOOL)conformsToProtocol:(Protocol
*)aProtocol
forFault:(id)aFault
See Also: - completeInitializationOfObject:
createFaultForDeferredFault:sourceObject:
- (id)createFaultForDeferredFault:(id)fault
sourceObject:(id)eo
decrementExtraRefCountIsZero
- (BOOL)decrementExtraRefCountIsZero
If, after decrementing the reference count, the fault's new reference count is zero, this method returns YES, If the reference count has not become zero, this method returns NO. Objects that have a zero reference count are released at the end of the current event loop.
This
method is used by EOFaultHandler's internal reference counting
mechanism-it functions as the Foundation function NSDecrementExtraRefCountWasZero()
for
the receiver's EOFault.
descriptionForObject:
- (NSString *)descriptionForObject:(id)aFault
extraData
- (void *)extraData
extraRefCount
- (unsigned int)extraRefCount
faultWillFire:
- (void)faultWillFire:(id)aFault
incrementExtraRefCount
- (void)incrementExtraRefCount
This method is used by EOFaultHandler's internal reference counting mechanism and functions as the Foundation function NSIncrementExtraRefCount() for the receiver's EOFault.
See Also: - extraRefCount
isKindOfClass:forFault:
- (BOOL)isKindOfClass:(Class)aClass
forFault:(id)aFault
See Also: - completeInitializationOfObject:
isMemberOfClass:forFault:
- (BOOL)isMemberOfClass:(Class)aClass
forFault:(id)aFault
See Also: - completeInitializationOfObject:
methodSignatureForSelector:forFault:
- (NSMethodSignature *)methodSignatureForSelector:(SEL)aSelector
forFault:(id)aFault
See Also: - completeInitializationOfObject:
respondsToSelector:forFault:
- (BOOL)respondsToSelector:(SEL)aSelector
forFault:(id)aFault
See Also: - completeInitializationOfObject:
setTargetClass:extraData:
- (void)setTargetClass:(Class)targetClass
extraData:(void *)extraData
id
.shouldPerformInvocation:
- (BOOL)shouldPerformInvocation:(NSInvocation
*)anInvocation
See Also: - setReturnValue: (NSInvocation class of the Foundation Framework)
targetClass
- (Class)targetClass