com.webobjects.eocontrol
Class EOFaultHandler

java.lang.Object
  com.webobjects.eocontrol.EOFaultHandler

Direct Known Subclasses:

EOAccessGenericFaultHandler

public abstract class EOFaultHandler

extends Object

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 EOAccess layer, for example, uses private subclasses to fetch data using an EODatabaseContext. Most of EOFaultHandler's methods are properly defined. Only overriding of completeInitializationOfObject is needed to provide appropriate behavior.

An EOFaultHandler belongs exclusively to a single fault object, and shouldn't be shared or used by any other object. You also shouldn't send messages directly to a fault handler object, only the fault object should do that.

An EOFaultHandler can be created using the standard constructor. To turn an object into a fault, the static method EOFaulthandler.makeObjectIntoFault can be invoked with the object and a fault handler as an argument. Alternatively, you can send a newly created object a turnIntoFault message (defined in the EOFaulting interface which must be implemented by all objects which can be faults) and provide an EOFaultHandler as argument that will help the fault to fire.

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 data source and passing it to the object.

See Also:

completeInitializationOfObject(Object), makeObjectIntoFault(Object, EOFaultHandler), clearFault(Object), EOFaulting.turnIntoFault(EOFaultHandler)

Constructor Summary

EOFaultHandler()

Method Summary

static void	clearFault(Object object) Restores object to its status prior to the makeObjectIntoFault message that turned it into a fault.
abstract void	completeInitializationOfObject(Object object) Implemented by subclasses to revert object to its original state (to fire the fault) and complete its initialization in whatever means is appropriate to the subclass.
Object	createFaultForDeferredFault(Object fault, EOEnterpriseObject sourceEO) Invoked by willReadRelationship to ensure that fault isn't a deferred fault, or to replace it with a normal fault if it is.
String	descriptionForObject(Object object) Returns a String that describes object.
static String	eoShallowDescription(Object object) Returns a String that describes object in a short form.
abstract void	faultWillFire(Object object) Informs the receiver that object is about to be reverted to its original state.
static EOFaultHandler	handlerForFault(Object object) Returns the EOFaultHandler that will help object to fire.
static boolean	isFault(Object object) Returns true if object is a fault, false otherwise.
static void	makeObjectIntoFault(Object object, EOFaultHandler handler) Converts object into a fault, assigning handler as the object that stores how to retrieve its original state and later converts the fault back into a normal object (typically by fetching data from an external data source).
Class	targetClass() Returns the target class of the receiver's fault.
String	toString() Returns a String containing a string representation of the receiver.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

EOFaultHandler

public EOFaultHandler()

Method Detail

clearFault

public static void clearFault(Object object)

Restores object to its status prior to the makeObjectIntoFault message that turned it into a fault. Throws an IllegalArgumentException if object isn't a fault. Faults typically fire automatically when accessed, using the completeInitializationOfObject method.

Parameters:

object - the fault to be restored to its pre-fault-creation object

Throws:

IllegalArgumentException

See Also:

completeInitializationOfObject(Object), makeObjectIntoFault(Object, EOFaultHandler)

completeInitializationOfObject

public abstract void completeInitializationOfObject(Object object)

Implemented by subclasses to revert object to its original state (to fire the fault) and complete its initialization in whatever means is appropriate to the subclass. For example, the EOAccess layer's 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.

Parameters:

object - the fault object to be initialized (fired)

createFaultForDeferredFault

public Object createFaultForDeferredFault(Object fault,
                                          EOEnterpriseObject sourceEO)

Invoked by willReadRelationship to ensure that fault isn't a deferred fault, or 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. You should never need to override this method.

Parameters:

fault - the fault object to replace

sourceEO - the enterprise object instance, using deferred faulting

Returns:

a normal fault after replacing it from the deferred fault

See Also:

EODeferredFaulting.willReadRelationship(Object object)

descriptionForObject

public String descriptionForObject(Object object)

Returns a String that describes object.

Parameters:

object - the object whose description is to be generated

Returns:

a String that describes the receiver

See Also:

EOEnterpriseObject.eoShallowDescription(), EOEnterpriseObject.eoDescription()

eoShallowDescription

public static String eoShallowDescription(Object object)

Returns a String that describes object in a short form.

Parameters:

object - the object whose description is to be generated

Returns:

a String that describes the receiver in a short form

See Also:

EOEnterpriseObject.eoShallowDescription(), EOEnterpriseObject.eoDescription()

faultWillFire

public abstract void faultWillFire(Object object)

Informs the receiver that object is about to be reverted to its original state. EOFaultHandler's implementation does nothing.

Parameters:

object - the fault object which will fire

handlerForFault

public static EOFaultHandler handlerForFault(Object object)

Returns the EOFaultHandler that will help object to fire. Returns null if object isn't a fault.

Parameters:

object - the object to return the fault handler for

Returns:

the fault handler that will help the object to fire; null if the object isn't a fault

See Also:

makeObjectIntoFault(Object, EOFaultHandler), isFault(Object object)

isFault

public static boolean isFault(Object object)

Returns true if object is a fault, false otherwise.

Parameters:

object - the object to test for a fault

Returns:

true if the object is a fault; false otherwise

See Also:

EOFaulting.isFault()

makeObjectIntoFault

public static void makeObjectIntoFault(Object object,
                                       EOFaultHandler handler)

Converts object into a fault, assigning handler as the object that stores how to retrieve its original state and later converts the fault back into a normal object (typically by fetching data from an external data source). The new fault becomes the owner of handler.

Parameters:

object - the object to turn into a fault

handler - the fault handler

See Also:

completeInitializationOfObject(Object), handlerForFault(Object), isFault(Object), clearFault(Object)

targetClass

public 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 EOAccess layer fires faults for entities with subentities into the appropriate class on fetching their data.

Returns:

the target class of the receiver's fault

toString

public String toString()

Returns a String containing a string representation of the receiver.

Returns:

a String containing a string representation of the receiver