ETDeserializer class documentation

Authors

David Chisnall

Contents -

  1. Software documentation for the ETDeserializer class
  2. Software documentation for the ETDeserializerVendor protocol
  3. ETDeserializer types

Software documentation for the ETDeserializer class

ETDeserializer : NSObject

Declared in:
ETDeserializer.h
Deserializer. Performs construction of object graphs based on instructions received from back end. Each back end is expected to read data representing serialized objects and pass it to an instance of this class to perform the deserialization.

Instance Variables

Method summary

deserializerWithBackend: 

+ (ETDeserializer*) deserializerWithBackend: (id<ETDeserializerBackend>)aBackend;
Returns a new deserializer using the specified backend.

registerDeserializer: forStructNamed: 

+ (void) registerDeserializer: (custom_deserializer)aDeserializer forStructNamed: (char*)aName;
Register a custom deserializer for a specific type of structure. If a custom deserializer is registered for a specific type of structure then this will have responsibility for loading fields in the specified structure delegated to it.

backend 

- (id<ETDeserializerBackend>) backend;
Returns the backend in use by the deserializer.

beginArrayNamed: withLength: 

- (void) beginArrayNamed: (char*)aName withLength: (unsigned int)aLength;
Begin an array, with the specified length. All subsequent load commands from the deserializer until the corresponding -endArray call will be treated as elements of this array.

beginObjectWithID: withClass: 

- (void) beginObjectWithID: (CORef)aReference withClass: (Class)aClass;
Begin deserializing an object which is an instance of aClass and uniquely identified with aReference within the set of objects for which the current backend instance is responsible.

beginStruct: withName: 

- (void) beginStruct: (char*)aStructName withName: (char*)aName;
Begin deserializing a structure. All calls to the deserializer between this and the corresponding -endStruct call will be assumed to be fields within the structure.

endArray 

- (void) endArray;
End the current array and return to the previous deserialization mode.

endObject 

- (void) endObject;
Indicate that the object currently being loaded is now finished.

endStruct 

- (void) endStruct;
End deserializing a C structure.

loadCString: withName: 

- (void) loadCString: (char*)aCString withName: (char*)aName;
Set the instance variable aName to the value of aCString, copying the data.

loadChar: withName: 

- (void) loadChar: (char)aChar withName: (char*)aName;
Set the instance variable aName to the value of aChar.

loadClass: withName: 

- (void) loadClass: (Class)aClass withName: (char*)aName;
Set the instance variable aName to the value of aClass.

loadData: ofSize: withName: 

- (void) loadData: (void*)aBlob ofSize: (size_t)aSize withName: (char*)aName;
Set the instance variable aName to the value of aBlob, copying the data.

loadDouble: withName: 

- (void) loadDouble: (double)aDouble withName: (char*)aName;
Set the instance variable aName to the value of aDouble.

loadFloat: withName: 

- (void) loadFloat: (float)aFloat withName: (char*)aName;
Set the instance variable aName to the value of aFloat.

loadInt: withName: 

- (void) loadInt: (int)aInt withName: (char*)aName;
Set the instance variable aName to the value of aInt.

loadLong: withName: 

- (void) loadLong: (long)aLong withName: (char*)aName;
Set the instance variable aName to the value of aLong.

loadLongLong: withName: 

- (void) loadLongLong: (long long)aLongLong withName: (char*)aName;
Set the instance variable aName to the value of aLongLong.

loadObjectReference: withName: 

- (void) loadObjectReference: (CORef)aReference withName: (char*)aName;
Set the instance variable aName, which is a object reference, to the object referenced by aReference. This may be deferred until the object is loaded.

loadSelector: withName: 

- (void) loadSelector: (SEL)aSelector withName: (char*)aName;
Set the instance variable aName to the value of aSelector.

loadShort: withName: 

- (void) loadShort: (short)aShort withName: (char*)aName;
Set the instance variable aName to the value of aShort.

loadUUID: withName: 

- (void) loadUUID: (unsigned char*)aUUID withName: (char*)aName;
Set the instance variable aName to the value returned by -lookUpObjectForUUID: with aUUID.

loadUnsignedChar: withName: 

- (void) loadUnsignedChar: (unsigned char)aChar withName: (char*)aName;
Set the instance variable aName to the value of aChar.

loadUnsignedInt: withName: 

- (void) loadUnsignedInt: (unsigned int)aInt withName: (char*)aName;
Set the instance variable aName to the value of aInt.

loadUnsignedLong: withName: 

- (void) loadUnsignedLong: (unsigned long)aLong withName: (char*)aName;
Set the instance variable aName to the value of aLong.

loadUnsignedLongLong: withName: 

- (void) loadUnsignedLongLong: (unsigned long long)aLongLong withName: (char*)aName;
Set the instance variable aName to the value of aLongLong.

loadUnsignedShort: withName: 

- (void) loadUnsignedShort: (unsigned short)aShort withName: (char*)aName;
Set the instance variable aName to the value of aShort.

lookUpObjectForUUID: 

- (id) lookUpObjectForUUID: (unsigned char*)aUUID;
Look up the object with aUUID. By default, returns a retained UUID instance. If you don't use CoreObject, you may patch this method with a category to implement a custom strategy that resolve objects associated with UUIDs.

restoreObjectGraph 

- (id) restoreObjectGraph;
Restore the principle object from the back end, and any objects referenced by this object, recursively.

setBackend: 

- (void) setBackend: (id<ETDeserializerBackend>)aBackend;
Sets the back end which sends events to this deserializer.

setBranch: 

- (BOOL) setBranch: (NSString*)aBranch;
Set the branch from which to deserialize.

setClassVersion: 

- (void) setClassVersion: (int)aVersion;
Set the version of the class responsible for the next set of instance variables to be loaded. This will be called multiple times for an object which is of a class which inherits from another class with instance variables. This value will be passed to the object's manual deserialization method, and can be used to implement deserialization of older versions (or even newer ones).

setReferenceCountForObject: to: 

- (void) setReferenceCountForObject: (CORef)anObjectID to: (int)aRefCount;
Set the reference count of the object referenced by anObjectID to aRefCount.

setVersion: 

- (int) setVersion: (int)aVersion;
Set the version to deserialize next.



Instance Variables for ETDeserializer Class

backend

@protected id backend;
The backend sending messages to this deserializer.

classVersion

@protected int classVersion;
The version of the class being loaded. Used by custom deserializers to provide backwards compatibility.

invocations

@protected NSMutableArray* invocations;
List of ETInvocationDeserializers used to deserialize invocations in the object graph. These should not be destroyed until after the invocations have been fired.

isInvocation

@protected BOOL isInvocation;
Flag indicating whether the current object is an invocation. Used to to special case (read: ugly hack) deserialization for invocations.

loadedIVar

@protected int loadedIVar;
Index of last loaded instance variable. Used to accelerate lookup of the next one.

loadedObjectList

@protected NSMutableArray* loadedObjectList;
List of loaded object. Iterated over to perform post-deserialization tidy-up of loaded objects.

loadedObjects

@protected NSMapTable* loadedObjects;
A mapping between CORef references and loaded objects, used to set object pointers to the correct value.

object

@protected id object;
Object currently being deserialized

objectPointers

@protected NSMapTable* objectPointers;
A mapping between pointers and the CORef references of the objects to which they should point. Used to allow allow object a to be loaded before object b if a contains a pointer to b as an ivar.

stackTop

@protected int stackTop;
Offset within the state machine stack of the top

states

@protected ETDeserializerState states;
State machine stack.




Software documentation for the ETDeserializerVendor protocol

ETDeserializerVendor

Declared in:
ETDeserializer.h
Processes that want to vend out ETDeserializer instances via Distributed Objects shall implement the ETDeserializerVendor protocol.
Method summary

deserializerWithBackend: forObjectWithUUID: from: 

- (ETDeserializer*) deserializerWithBackend: (NSString*)backendClassString forObjectWithUUID: (ETUUID*)uuid from: (NSString*)sender;
Creates a deserializer for the named backend. The vending application may use the uuid and sender variables to determine additional details. If the application requesting the object is using an XMPPObjectStore, sender will refer to the JID of the user that is trying to sent an object graph.

obtainedObject: withUUID: from: 

- (void) obtainedObject: (id)object withUUID: (ETUUID*)uuid from: (NSString*)senderJID;
This method can be called by the requesting application to inform the vending process about successful deserialization.

ETDeserializer types

custom_deserializer

typedef void*(* custom_deserializer;

Custom deserializer for a specific structure.

void * custom_deserializer(char* varName,
		void * aBlob,
		void * aLocation);

The varName argument contains the name of the variable to be deserialized, as set by the corresponding custom serializer function.

The aBlob argument points