ETSerializer class documentation

Authors

David Chisnall

Contents -

  1. Software documentation for the ETSerializer class
  2. Software documentation for the NSObject(ETSerializable) informal protocol
  3. ETSerializer types

Software documentation for the ETSerializer class

ETSerializer : NSObject

Declared in:
ETSerializer.h
The ETSerializer class performs object serialization. It extracts the instance variables and translates them into a stream of messages sent to a class implementing the ETSerializerBackend protocol, which handles the storage of the serialized data.

Instance Variables

Method summary

registerSerializer: forStruct: 

+ (void) registerSerializer: (custom_serializer)aFunction forStruct: (char*)aName;
Register a custom structure serializer for the named struct type.

serializerWithBackend: forURL: 

+ (ETSerializer*) serializerWithBackend: (Class)aBackendClass forURL: (NSURL*)anURL;
Return a new serializer using a backend of the specified class, writing to the specified URL.

backend 

- (id<ETSerializerBackend>) backend;
Retrieves the back end used by this serializer.

deserializer 

- (ETDeserializer*) deserializer;
Returns a deserializer which is the inverse of this serializer.

enqueueObject: 

- (void) enqueueObject: (id)anObject;
Add an object to the queue of unstored objects if we haven't loaded it yet, or increment its reference count if we have.

newVersion 

- (int) newVersion;
Create a new version of the object graph stored at -URL . CORef references are only guaranteed to be unique within a single version. By default this class stores a serialized object graph in a directory with the following layout: How other object stores handle the storage layout and multiple versions is up to subclasses. They can treat the URL as a base, and append a version number to each one, store the data separately within a single record or file, or any other option.

serializeObject: withName: 

- (unsigned long long) serializeObject: (id)anObject withName: (NSString*)aName;
Serialize the specified object.

setVersion: 

- (int) setVersion: (int)aVersion;
Creates a new version of the object graph with the specified version number.

storeObjectFromAddress: withName: 

- (size_t) storeObjectFromAddress: (void*)anAddress withName: (char*)aName;
Returns the size of the value to be stored for the object at the given address and known by instance variable aName.



Instance Variables for ETSerializer Class

backend

@protected id backend;
Description forthcoming.

branch

@protected NSString* branch;
Name of the current branch

currentClass

@protected Class currentClass;
Description forthcoming.

objectVersion

@protected int objectVersion;
Version of the object currently being written

store

@protected id store;
Description forthcoming.

storedObjects

@protected NSHashTable* storedObjects;
Description forthcoming.

unstoredObjects

@protected NSHashTable* unstoredObjects;
Description forthcoming.




Software documentation for the NSObject(ETSerializable) informal protocol

NSObject(ETSerializable)

Declared in:
ETSerializer.h
Informal protocol for serializable objects. Implement this to manually handle unsupported types.
Method summary

deserialize: fromPointer: version: 

- (void*) deserialize: (char*)aVariable fromPointer: (void*)aBlob version: (int)aVersion;
Load the contents of the named instance variable from the contents of aBlob. The aVersion parameter indicates the version of the class that serialized this instance variable as returned by +version . This method should return MANUAL_DESERIALIZE for cases if it completely deserializes the variable or AUTO_DESERIALIZE to cause the deserializer to automatically deserialize it. If the deserializer should load the variable to a different location, it should return a pointer to the location. An example use of this would be when loading a structure-pointer or dynamic array, where the memory should be allocated prior to deserialization.

serialize: using: 

- (BOOL) serialize: (char*)aVariable using: (ETSerializer*)aSerializer;
Serialize the named variable with the given serializer back end. This method should return YES if manual serialization has occurred. Returning NO will cause the serializer to attempt automatic serialization.

ETSerializer types

custom_serializer

typedef parsed_type_size_t(* custom_serializer;
Function type for custom structure serializers. The first argument contains the name of the instance variable containing the structure. The second contains a pointer to the structure, and the third the back end to use for serialization. Functions of this form, if registered with the ETSerializer class, will be used to serialize named structures in objects.