OpenStep (Enterprise)/OpenStepENTCD.toast/OEDEV/EODEV.Z/EOFault.h

Text File | 1996-09-11 | 6.6 KB | 198 lines

// EOFault.h
// Copyright (c) 1995, NeXT Software, Inc.  All rights reserved.
//
// An EOFault represents a Object (or a collection of objects) that haven't
// yet been fetched from their external ObjectStore.  When an object
// that has relationships is fetched, EOFaults are created for the
// destinations of those relationships (unless the corresponding objects have
// already been fetched and uniqued).
//
// You can create a fault for a single object--called an "object fault"--or
// for many objects described by a particular qualifier--called an "array
// fault." To-one relationships result in object faults, while to-many
// relationships result in array faults.  An object fault loads the real
// object whenever you message it (with some exceptions).  An array fault
// loads its objects as soon as you send it any message that requires accessing
// the contents of the array (-objectAtIndex:, -count, and so on).  Objects of
// either type are called "fault objects".
//
// You can use fault objects to defer a fetch--that is, set up for a fetch
// while your channel is in the middle of another operation.  For example,
// your Enterprise Object may need to fetch objects in its
// -takeValue:forKey: method, but since this can be invoked during a fetch,
// it has to defer its own fetch.
//

#import <Foundation/Foundation.h>

@class EOFaultHandler;

@interface EOFault
{
    Class isa;
    EOFaultHandler *_handler;
}

//
// Handled locally by the fault class
//
+ (void)initialize;
+ (Class)superclass;
+ (Class)class;
+ (id)self;

+ (id)retain;
+ (void)release;
+ (id)autorelease;
+ (unsigned)retainCount;

+ (BOOL)isKindOfClass:(Class)aClass;
+ (void)doesNotRecognizeSelector:(SEL)sel;
+ (BOOL)respondsToSelector:(SEL)sel;

//
// Fault management
//
+ (void)makeObjectIntoFault:(id)object withHandler:(EOFaultHandler *)handler;
    // Turn the object into a fault.
    // usually called by higher level constructors like
    // faultForGlobalID:editingContext: or
    // arrayFaultWithSourceGlobalID:relationshipName:editingContext:.

+ (BOOL)isFault:(id)object;
    // Returns YES if object is a fault object, NO otherwise.  You should use
    // this method if you need to know whether an object is in fact a fault
    // object.

+ (void)clearFault:(id)fault;
    // Turns fault into a freshly initialized instance of the target class.
    // Does NOT fetch data for the new instance. This will raise if
    // invoked with an object that isn't a fault object.  You'll rarely need
    // to use this method.

+ (EOFaultHandler *)handlerForFault:(id)fault;
    // the handler for this fault, or nil if not a fault

+ (Class)targetClassForFault:(id)fault;
    // Returns the class that will be instantiated when fault is fetched
    // or one of its superclasses.

//
// Forwarded to the faultHandler. Usually it could
// respond to the method without fetching the fault.
//
- (Class)superclass;
- (Class)class;

- (BOOL)isKindOfClass:(Class)class;
- (BOOL)isMemberOfClass:(Class)class;
- (BOOL)conformsToProtocol:(Protocol *)protocol;
- (BOOL)respondsToSelector:(SEL)sel;
- (NSMethodSignature *)methodSignatureForSelector:(SEL)aSelector;

- (id)retain;
- (void)release;
- (id)autorelease;
- (unsigned)retainCount;

- (NSString *)description;
- (NSString *)descriptionWithIndent:(unsigned)level;
- (NSString *)descriptionWithLocale:(NSDictionary *)locale;
- (NSString *)descriptionWithLocale:(NSDictionary *)locale indent:(unsigned)level;
- (NSString *)eoDescription;
- (NSString *)eoShallowDescription;
    // All these methods falls back to description

//
// dealloc clear the fault and call release on the resulting object.
//
- (void)dealloc;

//
// These methods are handled directly by the EOFault class
//
- (NSZone *)zone;
- (BOOL)isProxy; // Always NO.

//
// This message causes a fetch.  It is convenient to have a generic method
// which will cause a fault to trip.
//
- (id)self;

//
// Cause the fault to fire by calling handler to complete
// initialization (the handler is reponsible for sending a clearFault:)
// and forwarding on the message.
//
- (void)doesNotRecognizeSelector:(SEL)sel;
- (void)forwardInvocation:(NSInvocation *)invocation;

@end


// When an object is made into a fault, a handler must be assigned
// to finish initialization when the fault is fired.  Subclasses of
// EOFaultHandler can be created to implement this behavior.
// Subclasses add the additional instance variables to EOFaultHandler
// (such as the object primary key, or EOQualifier) that will be needed
// to finish object initialization.
//
@interface EOFaultHandler : NSObject
{
    Class _targetClass;  // the first 8 bytes of
    void *_extraData;    // the faulted object

    unsigned _extraRefCount;
}

- (void)setTargetClass:(Class)target extraData:(void *)data;
- (Class)targetClass;
- (void *)extraData;
    // FaultHandler accessor Methods

- (void)incrementExtraRefCount;
- (BOOL)decrementExtraRefCountWasZero;
- (unsigned)extraRefCount;
    // Called when the fault is initialised and on every retain/release

- (NSString *)descriptionForObject:object;
    // Return the description for the fault

//
// Forwarded messages from the fault
//
- (Class)classForFault:(id)fault;
    // classForFault: is returning the real fault class. It could be a
    // targetClass subclass. If faultClass is different than targetClass
    // the fault handler can fire the fault.
    // The default implementation is calling -targetClass.

- (BOOL)isKindOfClass:(Class)class forFault:(id)fault;
- (BOOL)isMemberOfClass:(Class)class forFault:(id)fault;
- (BOOL)conformsToProtocol:(Protocol *)protocol forFault:(id)fault;
- (BOOL)respondsToSelector:(SEL)sel forFault:(id)fault;
- (NSMethodSignature *)methodSignatureForSelector:(SEL)selector forFault:(id)fault;

- (void)completeInitializationOfObject:(id)object;
    // Overriden by subclasses to complete the initialization of
    // an object when its fault has been accessed.  For instance
    // a database object fault would use this method to fetch the
    // object contents from the server and hand the values to the
    // object. This method is responsible to handle the clearFault.
    // Note that the faultHandler will be released by the clearFault:
    // method.
    // The default implementation raise.

- (BOOL)shouldPerformInvocation:(NSInvocation *)invocation;
    // This method is called just before firing the fault.
    // If this method return NO the fault is not fired, and the value
    // returned to the caller is the return value stored in the invocation.
    // The invocation's target is set to the fault.
    // The default implementation return YES.

- (void)faultWillFire:(id)object;
    // This method is called at the begining of -clearFault.
    // The default implementation do nothing.
@end