Documentation Archive Developer
Search
PATH  Documentation > WebObjects 4.5 > EOControl Reference

Table of Contents

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

Returns the target class of the receiver's EOFault, which must be passed as aFault in case the receiver needs to fire it (EOFaultHandlers don't store back pointers to their faults). For example, to support entity inheritance, the Access layer fires faults for entities with subentities to confirm their precise class membership.

See Also: - targetClass



completeInitializationOfObject:

- (void)completeInitializationOfObject:(id)aFault

Implemented by subclasses to revert aFault to its original state and complete its initialization in whatever means is appropriate to the subclass. For example, the Access layer subclasses of EOFaultHandler fetch data from the database and pass it to the object. This method is invoked automatically by a fault when it's sent a message it can't handle without fetching its data. EOFaultHandler's implementation merely throws an exception.

conformsToProtocol:forFault:

- (BOOL)conformsToProtocol:(Protocol *)aProtocol forFault:(id)aFault

Returns YES if the target class of the receiver's EOFault conforms to aProtocol. This EOFault must be passed as aFault in case the receiver needs to fire it (EOFaultHandlers don't store back pointers to their faults). For example, to support entity inheritance, the Access layer fires faults for entities with subentities to confirm their precise class membership.

See Also: - completeInitializationOfObject:



createFaultForDeferredFault:sourceObject:

- (id)createFaultForDeferredFault:(id)fault sourceObject:(id)eo

Invoked by willReadRelationship to ensure that fault isn't a deferred fault, and to replace it with a normal fault if it is. EOFaultHandler's implementation simply returns its fault. A private subclass that handles deferred faulting implements this method to return a normal fault if fault is a deferred fault, so you should never need to override this method.

decrementExtraRefCountIsZero

- (BOOL)decrementExtraRefCountIsZero

Decrements the reference count for the receiver's fault. An object's reference count is the number of objects that are accessing it. Newly created objects have a reference count of one. If another object is referencing an object, the object is said to have an extra reference count.

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

Returns a string naming the original class of the receiver's fault and giving aFault's id, and also noting that it's a fault; for example: "<Employee (Fault 0x3a07)>". (The fault must be passed as aFault because EOFaultHandlers don't store back pointers to their faults.)

extraData

- (void *)extraData

Returns the bytes replaced by the receiver's id in the original object's state, as a pointer to void. When the receiver's EOFault is reverted to its original state, both its isa pointer and this data are replaced.

extraRefCount

- (unsigned int)extraRefCount

Returns the receiver's current reference count. This method is used by EOFaultHandler's internal reference counting mechanism and functions as the Foundation function NSExtraRefCount() for the receiver's EOFault.

faultWillFire:

- (void)faultWillFire:(id)aFault

Informs the receiver that aFault is about to be reverted to its original state. EOFaultHandler's implementation does nothing. This method is invoked by EOFault's clearFault: method.

incrementExtraRefCount

- (void)incrementExtraRefCount

Increments the reference count for the receiver's fault. An object's reference count is the number of objects that are accessing it. Newly created objects have a reference count of one. If another object is referencing an object, the object is said to have an extra reference count.

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

Returns YES if the target class of the receiver's fault is aClass or a subclass of aClass. The fault must be passed in as aFault in case the receiver needs to fire it (EOFaultHandlers don't store back pointers to their faults). For example, to support entity inheritance, the Access layer fires faults for entities with subentities to confirm their precise class membership.

See Also: - completeInitializationOfObject:



isMemberOfClass:forFault:

- (BOOL)isMemberOfClass:(Class)aClass forFault:(id)aFault

Returns YES if the target class of the receiver's fault is aClass. This fault must be passed as aFault in case the receiver needs to fire it (EOFaultHandlers don't store back pointers to their faults). For example, to support entity inheritance, the Access layer fires faults for entities with subentities to confirm their precise class membership.

See Also: - completeInitializationOfObject:



methodSignatureForSelector:forFault:

- (NSMethodSignature *)methodSignatureForSelector:(SEL)aSelector forFault:(id)aFault

Returns the NSMethodSignature for aSelector in the target class of the receiver's EOFault, which must be passed as aFault in case the receiver needs to fire it (EOFaultHandlers don't store back pointers to their faults). For example, to support entity inheritance, the Access layer fires faults for entities with subentities to confirm their precise class membership.

See Also: - completeInitializationOfObject:



respondsToSelector:forFault:

- (BOOL)respondsToSelector:(SEL)aSelector forFault:(id)aFault

Returns YES if the target class of the receiver's fault responds to aSelector. This fault must be passed as aFault in case the receiver needs to fire it (EOFaultHandlers don't store back pointers to their faults). For example, to support entity inheritance, the Access layer fires faults for entities with subentities to confirm their precise class membership.

See Also: - completeInitializationOfObject:



setTargetClass:extraData:

- (void)setTargetClass:(Class)targetClass extraData:(void *)extraData

Stores targetClass and extraData as state of the original object overwritten when an EOFault is created by EOFault's makeObjectIntoFault:withHandler: method, which replaces targetClass with the EOFault class, and extraData with the EOFaultHandler's id.

shouldPerformInvocation:

- (BOOL)shouldPerformInvocation:(NSInvocation *)anInvocation

Overridden by subclasses to circumvent reversion of an EOFault to its original state. Returns YES if the EOFault should revert and perform anInvocation, NO if it shouldn't. If this method returns NO, the receiver should set anInvocation's return value appropriately. EOFaultHandler's implementation returns YES.

See Also: - setReturnValue: (NSInvocation class of the Foundation Framework)



targetClass

- (Class)targetClass

Returns the target class of the receiver's fault. The fault may, however, be converted to a member of this class or of a subclass of this class. For example, to support entity inheritance, the Access layer fires faults for entities with subentities into the appropriate class on fetching their data.


Table of Contents