PATH Documentation > WebObjects 4.5 > EOControl Reference

EOFaultHandler

Inherits from:
(com.apple.client.eocontrol) Object
(com.apple.yellow.eocontrol) NSObject

Package:
com.apple.client.eocontrol

com.apple.yellow.eocontrol

Class Description

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 com.apple.yellow.eocontrol applications, you can optionally implement faultWillFire to prepare for conversion.

In a com.apple.yellow.eocontrol application you create an EOFaultHandler using the standard constructor. To create a fault in a com.apple.yellow.eocontrol 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 com.apple.client.eocontrol application you also create an EOFaultHandler using the standard constructor. To create a fault in a com.apple.client.eocontrol 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 com.apple.client.eocontrol applications, the fault handler is the private property of the fault; you shouldn't send any messages to the fault handler, 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.

Method Types

Creating and examining faults

createFaultForDeferredFault (com.apple.yellow.eocontrol only)

clearFault (com.apple.yellow.eocontrol only)

isFault

makeObjectIntoFault (com.apple.yellow.eocontrol only)

handlerForFault (com.apple.yellow.eocontrol only)

targetClassForFault (com.apple.yellow.eocontrol only)

Reference counting

incrementExtraRefCount (com.apple.yellow.eocontrol only)

decrementExtraRefCountIsZero (com.apple.yellow.eocontrol only)

extraRefCount (com.apple.yellow.eocontrol only)

Getting the original class

classForFault (com.apple.yellow.eocontrol only)

Firing a fault

completeInitializationOfObject

faultWillFire (com.apple.yellow.eocontrol only)

Getting a description

descriptionForObject

eoShallowDescription (com.apple.client.eocontrol only)

Checking class information

isKindOfClass (com.apple.yellow.eocontrol only)

isMemberOfClass (com.apple.yellow.eocontrol only)

respondsToSelectorForFault (com.apple.yellow.eocontrol only)

Static Methods

eoShallowDescription

public static String eoShallowDescription(Object anObject)

(com.apple.client.eocontrol only) See the method description for EOEnterpriseObject's eoShallowDescription.

clearFault

public static void clearFault(Object aFault)

(com.apple.yellow.eocontrol only) 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(Object aFault)

(com.apple.yellow.eocontrol only) Returns the EOFaultHandler that will help aFault to fire. Returns null if aFault isn't a fault.

isFault

public static boolean isFault(Object anObject)

Returns true if anObject is a fault, false otherwise.

makeObjectIntoFault

public static void makeObjectIntoFault( Object anObject, EOFaultHandler aFaultHandler)

(com.apple.yellow.eocontrol only) 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 Class targetClassForFault(Object anObject)

(com.apple.yellow.eocontrol only) Returns the class that will be instantiated when the fault fires. The returned class could be a superclass of the actual class instantiated.

Instance Methods

classForFault

public Class classForFault(Object fault)

(com.apple.yellow.eocontrol only) 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: targetClass

completeInitializationOfObject

public void completeInitializationOfObject(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.

createFaultForDeferredFault

public Object createFaultForDeferredFault(Object fault, Object eo)

(com.apple.yellow.eocontrol only) 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

public boolean decrementExtraRefCountIsZero()

(com.apple.yellow.eocontrol only) 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 candidates for garbage collection.

This method is used by EOFaultHandler's internal reference counting mechanism.

descriptionForObject

public String descriptionForObject(Object aFault)

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()

(com.apple.yellow.eocontrol only) Returns the receiver's current reference count. This method is used by EOFaultHandler's internal reference counting mechanism.

faultWillFire

public void faultWillFire(Object aFault)

(com.apple.yellow.eocontrol only) Informs the receiver that aFault is about to be reverted to its original state. EOFaultHandler's implementation does nothing.

incrementExtraRefCount

public void incrementExtraRefCount()

(com.apple.yellow.eocontrol only) 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( Class aClass, Object aFault)

(com.apple.yellow.eocontrol only) 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( Class aClass, Object aFault)

(com.apple.yellow.eocontrol only) 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, Object aFault)

(com.apple.yellow.eocontrol only) 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 Class targetClass()

(com.apple.yellow.eocontrol only) 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.