Inherits From:
Object (Java Client)
NSObject (Yellow Box)
Package:
com.apple.client.eocontrol (Java Client)
com.apple.yellow.eocontrol (Yellow Box)
EOFaultHandler is an abstract class that defines the mechanisms that create faults 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.
In a Yellow Box application you create an EOFaultHandler using the standard constructor . To create a fault in a Yellow Box application, you invoke the static method makeObjectIntoFault 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.
In a Java Client application you also create an EOFaultHandler using the standard constructor. To create a fault in a Java Client application, though, you send a newly-created object a turnIntoFault message and provide an EOFaultHandler that will help the fault to fire. In order for that newly-created object to be able to respond to turnIntoFault , the object must conform to the EOFaulting interface. An EOFaultHandler belongs exclusively to a single fault, and shouldn't be shared or used by any other object. In Java Client applications, the fault handler is the private property of the fault; you shouldn't send any messages to the fault hander, instead dealing exclusively with the fault.
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 the clearFault 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.
EOFaultHandler
public EOFaultHandler ()
Creates and returns an EOFaultHandler object.
clearFault
public static void clearFault (java.lang.Object aFault)
This method is only available in Yellow Box; there is no Java Client equivalent. Restores aFault to its status prior to the makeObjectIntoFault message that created it. Throws an exception if aFault isn't a fault.
You rarely use this method. Faults typically fire automatically when accessed, using the completeInitializationOfObject method.
handlerForFault
public static EOFaultHandler handlerForFault (java.lang.Object aFault)
This method is only available in Yellow Box; there is no Java Client equivalent. Returns the EOFaultHandler that will help aFault to fire. Returns null if aFault isn't a fault.
isFault
public static boolean isFault (java.lang.Object anObject)
Returns true if anObject is a fault, false otherwise.
makeObjectIntoFault
public static void makeObjectIntoFault (java.lang.Object anObject, EOFaultHandler aFaultHandler)
This method is only available in Yellow Box; there is no Java Client equivalent. Converts anObject into a fault, assigning aFaultHandler as the object that stores its original state and later converts the fault back into a normal object (typically by fetching data from an external repository). The new fault becomes the owner of aFaultHandler; you shouldn't assign it to another object.
targetClassForFault
public static java.lang.Class targetClassForFault (java.lang.Object anObject)
This method is only available in Yellow Box; there is no Java Client equivalent. Returns the class that will be instantiated when the fault fires. The returned class could be a superclass of the actual class instantiated.
classForFault
public java.lang.Class classForFault (java.lang.Object fault)
This method is only available in Yellow Box; there is no Java Client equivalent. Returns the target class of the receiver's fault object, which must be passed as aFault in case the receiver needs to fire it (EOFaultHandlers don't keep references 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: + targetClassForFault
completeInitializationOfObject
public void completeInitializationOfObject (java.lang.Object 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.
decrementExtraRefCountIsZero
public boolean decrementExtraRefCountIsZero ()
This method is only available in Yellow Box; there is no Java Client equivalent. 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 true , If the reference count has not become zero, this method returns false . Objects that have a zero reference count are marked for garbage collection.
This method is used by EOFaultHandler's internal reference counting mechanism.
descriptionForObject
public java.lang.String descriptionForObject (java.lang.Object aFault)
This method is only available in Yellow Box; there is no Java Client equivalent. Returns a string naming the original class of the receiver's fault and giving aFault's address, and also noting that it's a fault. (The fault must be passed as aFault because EOFaultHandlers don't keep references to their faults.)
extraRefCount
public int extraRefCount
This method is only available in Yellow Box; there is no Java Client equivalent. Returnsthe receiver's current reference count. This method is used by EOFaultHandler's internal reference counting mechanism.
faultWillFire
public void faultWillFire (java.lang.Object aFault)
This method is only available in Yellow Box; there is no Java Client equivalent. Informs the receiver that aFault is about to be reverted to its original state. EOFaultHandler's implementation does nothing.
incrementExtraRefCount
public void incrementExtraRefCount ()
This method is only available in Yellow Box; there is no Java Client equivalent. 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.
See also: - extraRefCount
isKindOfClass
public boolean isKindOfClass (java.lang.Class aClass, java.lang.Object aFault)
This method is only available in Yellow Box; there is no Java Client equivalent. Returns true 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 keep references 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
public boolean isMemberOfClass (java.lang.Class aClass, java.lang.Object aFault)
This method is only available in Yellow Box; there is no Java Client equivalent. Returns true 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 keep references 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
respondsToSelectorForFault
public boolean respondsToSelectorForFault (NSSelector aSelector, java.lang.Object aFault)
This method is only available in Yellow Box; there is no Java Client equivalent. Returns true 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 references 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
targetClass
public java.lang.Class targetClass ()
This method is only available in Yellow Box; there is no Java Client equivalent. 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.