Documentation

Overview

A COObject instance is a generic model object described by a metamodel (see -entityDescription), and its lifecycle is managed by a COObjectGraphContext.

For a persistent object, a -branch owns the -objectGraphContext .

For a transient object, the -objectGraphContext is standalone, -branch and -persistentRoot return nil.

From COEditingContext to COObject, there is a owner chain where each element owns the one just below in the list:

• COEditingContext
• COPersistentRoot
• COBranch
• COObjectGraphContext
• COObject

Object Equality

COObject inherits NSObject's -hash and -isEqual: methods, so equality is based on pointer comparison.

You must never override -hash or -isEqual:. This is a consequence of the fact that we promise it is safe to put a COObject instance in an NSSet and then mutate the COObject.

Use -isTemporallyEqual: to check both UUID and revision match. For example, when the same object is in use in multiple editing contexts simultaneously.

Common Use Cases

For an existing persistent root or transient object graph context, -initWithObjectGraphContext: is used to create additional inner objects.

To navigate the object graph, access or change the state of these objects, -valueForProperty: and -setValue:forProperty: are available. For instances of COObject subclasses that declare synthesized properties, you should use these accessors rather than those Property-Value Coding methods.

Creation

A persistent or transient object can be instantiated by using -initWithObjectGraphContext: or some other initializer (-init is not supported). The resulting object is a inner object that belongs to the object graph context.

For a transient object graph context, you can later use -[COEditingContext insertNewPersistentRootWithRootObject:] to turn an existing inner object into a root object (the object graph context becoming persistent).

You can instantiate also a new persistent root and retrieve its root object by using -[COEditingContext insertNewPersistentRootWithEntityName:] or similar COEditingContext methods.

When writing a COObject subclass, -initWithObjectGraphContext: can be overriden to initialize the the subclass properties.

The designated initializer rule remains valid in the COObject class hierarchy, but -initWithObjectGraphContext: must work correctly too (it must never return nil or a wrongly initialized instance), usually you have to override it to call the designated initializer. All secondary initializers (inherited or not) must return valid instances or nil. The easiest way to comply is described below:

• For additional initializers, call the designated initializer
• For each new designated initializer, override -initWithObjectGraphContext: to call it

Don't create singletons for COObject subclass in +initialize , because -[COObject entityDescription] would return nil.

For the property initialization rules, see Properties section.

Deletion

An inner object is deleted, when it becomes unreachable from the root object in the -objectGraphContext .

It is never explicitly deleted, instead this object must be removed in a collection or a relationship, and once this object doesn't belong to any collection or relationship that can be accessed from the root object, it is declared as unreachable, and will be deleted by the COObjectGraphContext garbage collection (usually on a future commit).

Properties

By default, COObject stores its properties in a variable storage, similar to a dictionary. In the rare cases, where the variable storage is too slow, properties can be stored in instance variables.

In a COObject subclass implementation, the variable storage can be accessed with -valueForVariableStorageKey: and -setValue:forVariableStorageKey: . You must not access the properties with these methods from other objects, this is the same than a direct instance variable access. For reading and writing properties, you must use accessors (synthesized or hand-written ones), or -valueForProperty: and -setValue:forProperty: (known as Property-Value Coding).

For multivalued properties stored in instance variables, you are responsible to allocate the collections in each COObject subclass designed initializer, and to release them in -dealloc (or use ARC). If a multivalued property is stored in the variable storage, COObject allocates the collections at initialization time and releases them at deallocation time (you can access these collections using -valueForVariableStorageKey: in your subclass initializers).

For explanations about accessors, see Writing Accessors section.

Writing Accessors

You can use Property-Value Coding to read and write properties. However implementing accessors can improve readability, type checking etc. For most attributes, we have a basic accessor pattern. For Multivalued properties (relationships or collection-based attributes), the basic accessor pattern won't work correctly.

For a COObject subclass, CoreObject will synthesize attribute accessors at run-time, if the property is declared @dynamic on the implementation side. For now, CoreObject doesn't synthesize collection-compliant accessors (such as Key-Value Coding collection accessors) beside set and get, all collection mutation methods must be hand-written based on the Multivalued Accessor Pattern.

Note: For a COObject subclass such as COCollection that holds a single collection, the subclass can conform to ETCollection and ETCollectionMutation protocols, and adopt their related traits, in this way no dedicated accessors need to be implemented.

Basic Accessor Pattern

 - (void)name
 {
     // When no ivar is provided, you can use the variable storage as below
     // return [self valueForVariableStorageKey: @"name"];
     return name;
 }

 - (void)setName: (NSString *)aName
 {
     [self willChangeValueForProperty: @"name"];
     // When no ivar is provided, you can use the variable storage as below
     // [self setValue: aName: forVariableStorageKey: @"name"];
     name =  aName;
     [self didChangeValueForProperty: @"name"];
 }
 

Multivalued Accessor Pattern

The example below is based on a COObject subclass using a names instance variable. If the value is stored in the variable storage, the example must be adjusted to use -valueForVariableStorageKey: and -setValue:forVariableStorageKey: .

 - (void)names
 {
     // The synthesized accessor would just do the same.
     return [names copy];
 }

 - (void)addName: (NSString *)aName
 {
     NSArray *insertedObjects = A(aName);
     NSIndexSet *insertionIndexes = [NSIndexSet indexSet];

     [self willChangeValueForProperty: key
	                          atIndexes: insertionIndexes
                          withObjects: insertedObjects
                         mutationKind: ETCollectionMutationKindInsertion];

     // You can update the collection in whatever you want, the synthesized 
     // accessors would just use ETCollectionMutation methods.
     [names addObject: aName];

     [self didChangeValueForProperty: key
                           atIndexes: insertionIndexes
                         withObjects: insertedObjects
                        mutationKind: ETCollectionMutationKindInsertion];
 }

 - (void)removeName: (NSString *)aName
 {
     NSArray *removedObjects = A(aName);
     NSIndexSet *removalIndexes = [NSIndexSet indexSet];

     [self willChangeValueForProperty: key
	                          atIndexes: removalIndexes
                          withObjects: removedObjects
                         mutationKind: ETCollectionMutationKindRemoval];

     // You can update the collection in whatever you want, the synthesized 
     // accessors would just use ETCollectionMutation methods.
     [names removeObject: aName];

     [self didChangeValueForProperty: key
                           atIndexes: removalIndexes
                         withObjects: removedObjects
                        mutationKind: ETCollectionMutationKindRemoval];
 }

 // Direct setters are rare, but nonetheless it is possible to write one as below...
 - (void)setNames: (id <ETCollection>)newNames
 {
     NSArray *replacementObjects = A(aName);
     // If no indexes are provided, the entire collection is replaced or set.
     NSIndexSet *replacementIndexes = [NSIndexSet indexSet];

     [self willChangeValueForProperty: key
	                          atIndexes: replacementIndexes
                          withObjects: replacementObjects
                         mutationKind: ETCollectionMutationKindReplacement];

     // You can update the collection in whatever you want, the synthesized 
     // accessor would just do the same or allocate a custom CoreObject
     // primitive collections.
     names = [newNames mutableCopy];

     [self didChangeValueForProperty: key
                           atIndexes: replacementIndexes
                         withObjects: replacementObjects
                        mutationKind: ETCollectionMutationKindReplacement];
 }
 

To implement a getter that returns an incoming relationships e.g. parent(s), just use -valueForVariableStorageKey: (see the -name getter example above).

You must never implement incoming relationship setters.

To access incoming relationships when no accessors are available, just use -valueForProperty: as you would do it for other properties.

Serialization and Metamodel

At commit time, all the inner objects in a COObjectGraphContext are serialized into an intermediate COItem representation with COItemGraph protocol.

At serialization time, each object is turned into a COItem with -[COObject storeItem]. At deserialization, a COItem is passed to -[COObject setStoreItem:] to recreate the object state.

All properties declared as persistent (see -[ETPropertyDescription isPersistent]) in the metamodel are serialized, transient properties are skipped. For transient properties, COObject don't manage them in any way, but just ensure their values respect the metamodel constraints (in -didChangeValueForProperty:).

For persistent properties, COObject supports both relationships to other inner objects, and attributes that contain primitive objects such as NSString or NSDate.

Both attributes and relationships can be either univalued or multivalued (to-one or to-many), see -[ETPropertyDescription isMultivalued] in the metamodel.

Relationships can be either undirectional or bidirectional (one-way or two-way). To create a bidirectional relationships, -[ETPropertyDescription opposite] must be set on one side. The other side or opposite is the inverse relationship. For a bidirectional relationship, a single side can be marked as persistent, the other side must be transient. The persistent side is known as an outgoing relationship, and the transient side as an incoming relationship. CoreObject doesn't load incoming relationships into each COObject, but load them in the relationship cache. This rule doesn't apply to transient relationships.

With metamodel constraints, CoreObject supports several multivalued relationship variations:

Keyed Relationship

hold in a NSDictionary – -[ETPropertyDescription isKeyed] == YES in the metamodel

Ordered Relationship

hold in a NSArray – -[ETPropertyDescription isOrdered] == YES in the metamodel

Unordered Relationship

hold in a NSSet – -[ETPropertyDescription isOrdered] == NO in the metamodel

Unidirectional Relationship

a one-way relationship – -[ETPropertyDescription opposite] == nil in the metamodel

Bidirectional Relationship

a two-way relationship – -[ETPropertyDescription opposite != nil in the metamodel

Composite Relationship

a parent/child relationship – -[[ETPropertyDescription multivalued] is not the same on both side

A persistent keyed relationship is undirectional, -[ETPropertyDescription opposite] must be nil.

A composite relationsip is just a bidirectional relationship subcase, it models a tree structure inside the object graph, and in this way, a composite determines how the object graph is copied. A composite object (or child object) is copied rather than aliased when the tree structure it belongs to is copied.

With metamodel constraints, CoreObject supports several variations over attribute collections:

Keyed Collection

hold in a NSDictionary – -[ETPropertyDescription isKeyed] == YES in the metamodel

Ordered Collection

hold in a NSArray – -[ETPropertyDescription isOrdered] == YES in the metamodel

Unordered Collection

hold in a NSSet – -[ETPropertyDescription isOrdered] == NO in the metamodel

For relationships or attribute collections, both ordered and unordered, duplicates are not allowed, and if the same object is inserted twice in a collection, CoreObject will remove the previous reference to this object in the collection.

A keyed relationship or attribute collection is unordered, -[ETPropertyDescription isOrdered] must be NO. This restriction applies to transient properties too currently.

Note: If a collection is a relationship or an attribute collection is controlled by -[ETPropertyDescription type], and whether this entity description return YES to -[ETEntityDescription isPrimitive]. You can override -[ETEntityDescription isPrimitive] in a ETEntityDescription subclass to declare new attribute objects in the metamodel. However CoreObject will treat all COObject instances as relationships internally, since CoreObject serialized format has a fixed set of attribute types (see COType).

Object Graph Loading

When a persistent root's root object is accessed, the entire object graph bound to it is loaded (if the root object is not present in memory).

When a persistent inner object is loaded, once the attribute values have been deserialized, -awakeFromDeserialization is sent to the object to let it update its state before being used. You can thus override -awakeFromDeserialization to recreate transient properties, recompute correct property values based on the deserialized values, etc. But you must not access or update persistent relationships in -awakeFromDeserialization directly.

You can override -didLoadObjectGraph to manipulate persistent relationships in a such way. Loading a persistent object usually result in the other inner objects being loaded, and -didLoadObjectGraph is sent to all the inner objects once all these objects have been loaded.

Although you should avoid to override -didLoadObjectGraph , in some cases it cannot be avoided. For example, an accessor can depend on or alter the state of a relationship (e.g. a parent object in a tree structure). To give a more concrete example, in EtoileUI -[ETLayoutItem setView:] uses -[ETLayoutItemGroup handleAttacheViewOfItem:] to adjust the parent view, so -[ETLayoutItem setView:] cannot be used until the parent item is loaded.

Model Validation

At commit time, all the changed objects are validated with -validate . You can override this method to implement some custom validation logic per COObject subclass. By default, the object will be validated with the model validation logic packaged with the metamodel, -validateAllValues will check each property value with the validation rules provided by -[ETPropertyDescription role] and -[ETRoleDescription validateValue:forKey:].

Note: -validateAllValues currently doesn't check that the property values respect the constraints set on their related property descriptions. For now, CoreObject enforces these metamodel constraints in -didChangeValueForProperty: .