EOFault
- Inherits from:
- none (EOFault is a root class)
Declared in:
- EOControl/EOFault.h
Class Description
EOFault and EOFaultHandler form a general mechanism for substituting placeholder objects that convert themselves into regular objects. An EOFault is most commonly used by the Access Layer to represent an object not yet fetched from the database, but that must nonetheless exist as an instance in the application-typically because it's the destination of a relationship. EOFault is a completely general class; there's no need to create subclasses to customize fault handling. Instead, you create subclasses of EOFaultHandler to accommodate different means of converting faults into regular objects.
The faulting mechanism provides for continuity of an object's id even when that object's state isn't yet available. An EOFault simply holds the place for an ultimate "real" object, handling all methods that it can without causing the state to be loaded. When an EOFault receives a message that it can't handle, it calls upon its EOFaultHandler to fire it, converting it into a "real" object. This often involves accessing the external, persistent state of the object.
Creating an EOFault
Rather than allocating and initializing an EOFault, you turn an existing object into one using EOFault's makeObjectIntoFault:withHandler: class method. When you do so, you must provide an EOFaultHandler that will later help the fault to fire. makeObjectIntoFault:withHandler: preserves the id of the original object, overlaying its isa pointer with that of the EOFault class and slipping the EOFaultHandler among its instance variables. Once this is done, the original object is an EOFault that will fire when accessed.
The EOFaultHandler should be considered completely private property of the EOFault once you've created it. You should neither retain the EOFaultHandler or send it any other messages, instead dealing exclusively with the newly created EOFault or the EOFault class itself.
EOFault Behavior
EOFault implements many basic object methods in a manner that doesn't cause the receiver to fire. The following methods all behave as though normal for the original object:
doesNotRecognizeSelector: is a special case here, in that it's only invoked if the selector in question isn't found for the original class. Normally, methods not implemented by EOFault, but implemented by the original class, cause the receiver to fire as described below.
These methods don't cause the receiver to fire, but also don't hide the presence of the EOFault class:
- description | - descriptionWithLocale: |
- descriptionWithIndent: | - descriptionWithLocale:indent: |
- eoDescription | - eoShallowDescription |
The following common methods, along with any others not explicitly mentioned in this section, do cause the receiving EOFault to fire.
When an EOFault receives one of these messages, it fires in one of a few different ways. dealloc invokes the - clearFault: class method to revert the receiver back to its original state, then reinvokes dealloc to clean up instance variables and deallocate the object. The other methods all send a special message, completeInitializationOfObject:, to the EOFaultHandler to transform the EOFault into a regular object, possibly different from its original state. In addition, forwardInvocation: sends a shouldPerformInvocation: to the EOFaultHandler first, which allows it to perform the method itself without causing the EOFault to be transformed. If the EOFaultHandler returns YES, though, the EOFault then sends it a completeInitializationOfObject: message.
Examining an EOFault
Three additional EOFault methods allow you to explicitly check whether an object is an EOFault without causing it to fire, and to get its original class and EOFaultHandler if it is an EOFault. These methods are:
You can use these methods to base some decisions on whether an object is an EOFault, though you should rarely need to do so.
Method Types
- Creating and examining faults
- + makeObjectIntoFault:withHandler:
- + isFault:
- + clearFault:
- + handlerForFault:
- + targetClassForFault:
- + respondsToSelector:
- Checking class information
- - class
- - isKindOfClass:
- - isMemberOfClass:
- - respondsToSelector:
- - conformsToProtocol:
- - methodSignatureForSelector:
- Run-time support
- - forwardInvocation:
- - doesNotRecognizeSelector:
- Getting a fault's description
- - description
- - descriptionWithIndent:
- - descriptionWithLocale:
- - descriptionWithLocale:indent:
- - eoDescription
- - eoShallowDescription
- Reference-counting
- - retain
- - release
- - retainCount
- - autorelease
- - dealloc
- Miscellaneous object methods
- - self
- - isProxy
- - superclass
- - zone
Class Methods
clearFault:
+ (void)clearFault:(id)aFault
You rarely use this method. Faults typically fire automatically when accessed, using EOFaultHandler's completeInitializationOfObject: method. See the EOFaultHandler class specification for more information.
handlerForFault:
+ (EOFaultHandler *)handlerForFault:(id)aFault
isFault:
+ (BOOL)isFault:(id)anObject
YES
if anObject is
an EOFault, NO
otherwise.makeObjectIntoFault:withHandler:
+ (void)makeObjectIntoFault:(id)anObject
withHandler:(EOFaultHandler *)aFaultHandler
respondsToSelector:
+ (BOOL)respondsToSelector:(SEL)aSelector
YES
if
the receiving class responds to aSelector, NO
otherwise.targetClassForFault:
+ (Class)targetClassForFault:(id)aFault
Instance Methods
autorelease
- (id)autorelease
class
- (Class)class
See Also: - classForFault: (EOFaultHandler), + targetClassForFault:
conformsToProtocol:
- (BOOL)conformsToProtocol:(Protocol
*)aProtocol
YES
if
the object that the receiving EOFault will become conforms to aProtocol, NO
if
it doesn't. This may cause the EOFault to fire in order to determine
its actual class membership.See Also: - conformsToProtocol:forFault: (EOFaultHandler)
dealloc
- (void)dealloc
description
- (NSString *)description
descriptionWithIndent:
- (NSString *)descriptionWithIndent:(unsigned
int)indentLevel
descriptionWithLocale:
- (NSString *)descriptionWithLocale:(NSDictionary
*)locale
descriptionWithLocale:indent:
- (NSString *)descriptionWithLocale:(NSDictionary
*)locale
indent:(unsigned int)indentLevel
doesNotRecognizeSelector:
- (void)doesNotRecognizeSelector:(SEL)aSelector
eoDescription
- (NSString *)eoDescription
See Also: - eoDescription ( EOEnterpriseObject)
eoShallowDescription
- (NSString *)eoShallowDescription
See Also: - eoShallowDescription ( EOEnterpriseObject)
forwardInvocation:
- (void)forwardInvocation:(NSInvocation
*)anInvocation
NO
,
returns immediately. If it returns YES
,
sends a completeInitializationOfObject: message
to the EOFaultHandler with self as the argument.
Once the receiver has fired it invokes anInvocation.isKindOfClass:
- (BOOL)isKindOfClass:(Class)aClass
YES
if aClass is
the class, or a superclass, of the object that the receiving EOFault
will become, NO
otherwise.
This may cause the EOFault to fire in order to determine its actual
class membership.See Also: - isMemberOfClass:, - isKindOfClass:forFault: (EOFaultHandler)
isMemberOfClass:
- (BOOL)isMemberOfClass:(Class)aClass
YES
if aClass is
the class of the object that the receiving EOFault will become, NO
otherwise.
This may cause the EOFault to fire in order to determine its actual
class membership.See Also: - isKindOfClass:, - isMemberOfClass:forFault: (EOFaultHandler)
isProxy
- (BOOL)isProxy
NO
.methodSignatureForSelector:
- (NSMethodSignature *)methodSignatureForSelector:(SEL)aSelector
See Also: - methodSignatureForSelector: (EOFaultHandler)
release
- (void)release
respondsToSelector:
- (BOOL)respondsToSelector:(SEL)aSelector
YES
if
the object that the receiving EOFault will become responds to aSelector, NO
otherwise. This
may cause the EOFault to fire in order to determine its actual class
membership.See Also: - respondsToSelector:forFault: (EOFaultHandler)
retain
- (id)retain
retainCount
- (unsigned int)retainCount
self
- (id)self
self
.
This is the recommended way to simply fire an EOFault.superclass
- (Class)superclass
See Also: - classForFault: ( EOFaultHandler)
zone
- (NSZone *)zone
zone
method.