ETModelDescriptionRepository class documentation
ETModelDescriptionRepository : NSObject <ETCollection, ETCollectionMutation>Overview
Each repository manages a closed model description graph. Model element descriptions present in a repository must only reference objects that belong to the same repository.
The repository contains three type of element descriptions:
- ETPackageDescription
- ETEntityDescription
- ETPropertyDescription
Main and Additional Repositories
A main repository is created in every tool or application at launch time. The +mainRepository is a special repository that automatically contains the entity descriptions provided through +[NSObject newEntityDescription] , that got collected in the NSObject class hierarchy when the repository is created.
Additional repositories can be created. For example, to store variations on the main repository data model.
You can collect entity descriptions provided through +[NSObject newEntityDescription] in additional repositories with -collectEntityDescriptionsFromClass:excludedClasses:resolvedNow:. Don't forget to call -checkConstraints: before using the repository.
Registering Model Description
To register an entity description, you must register the entity and its property descriptions, and do the same for the parent entity in case it is not registered yet.
[repo addDescription: entityDesc]; [repo addDescriptions: [entityDesc propertyDescriptions]]; [repo addDescription: [entityDesc parentEntity]]; [repo addDescriptions: [[entityDesc parentEntity] propertyDescriptions]]; // and so on
You must also register at the same time any entity description used as -[ETPropertyDescription type] or -[ETPropertyDescription persistentType] , and any property description referred to by -[ETPropertyDescription opposite] . If this last property description itself belongs to an unregisted entity, you must register this entity description as described previously and so on.
To register a package description, you must register the entities (and all the property and entity descriptions they refer to) and the property extensions in a way similar to the previous example.
If your model element descriptions contains named references (rather than explicit ones to the real objects) e.g. -[ETProprertyDescription oppositeName] , these descriptions must be added with -addUnresolvedDescription: , and -resolveNamedObjectReferences must be called once you don't need to call -addDescription: and -addUnresolvedDescription: anymore.
Note: If the entity describes a class, once registered, you usually bind it to its class as described in the next section.
Entity and Class Description Binding
By default, a repository can contain entity descriptions that apply to:
- a prototype or a similar object (a free-standing entity is usually used with ETAdaptiveModelObject)
- a class
For entity descriptions describing a class, the two-way binding is established with -setEntityDescription:forClass: .
If no bound entity description or class can be found, -entityDescriptionForClass: and -classForEntityDescription both attempt to return a parent entity or superclass.
Consistency Checking
Every time entity or package descriptions are added to the repository, you must check the model description graph consistency with -checkConstraints: .
It is up to you to do it, because the repository has no way to know when you are done adding descriptions and the repository content is in a coherent state that won't raise warnings.
Metamodel Description
- + (ETEntityDescription *) newEntityDescription
Self-description (aka meta-metamodel).
Initialization
- + (id) mainRepository
Returns the initial repository that exists in each process.
When this repository is created, existing entity descriptions are collected by invoking +newEntityDescription on every NSObject subclass and bound to the class that provided the description. See -setEntityDescription:forClass: .
After collecting the entity descriptions, -checkConstraints is called and must return no warnings, otherwise a NSInternalInconsistencyException is raised.
For an application, the UIApplication or NSApplication object must exist at the time this method is called.
- - (id) init
Returns a new repository that just contains the core metamodel (Object, Number, Boolean, String, Date, Value) and additional primitive entity descriptions (e.g. NSInteger, NSPoint etc.).
Collecting Entity Descriptions in Class Hierarchy
- - (void) collectEntityDescriptionsFromClass: (Class)aClass excludedClasses: (NSSet *)excludedClasses resolveNow: (BOOL)resolve
Traverses the class hierarchy downwards to collect the entity descriptions by invoking +newEntityDescription on each class (including the given class) and bind each entity description to the class that provided it. See -setEntityDescription:forClass: .
If resolve is YES, the named references that exists between the descriptions are resolved immediately with -resolveNamedObjectReferences . Otherwise they are not and the repository remain in an invalid state until -resolveNamedObjectReferences is called.
Registering and Enumerating Descriptions
- - (ETPackageDescription *) anonymousPackageDescription
Returns the default package to which entity descriptions are added when they have none and they get put in the repository.
e.g. NSObject is owned by the anonymous package when its entity description is automatically registered in the main repository.
See also -addDescription: .
- - (void) addUnresolvedDescription: (ETModelElementDescription *)aDescription
Adds the given package, entity or property description to the repository.
Full names can be set as late-bound references to other ETModelElementDescription objects, in all the following properties:
- ownerName (ETPropertyDescription and ETEntityDescription) -> owner
- packageName (ETPropertyDescription and ETEntityDescription) -> package
- parentName (ETEntityDescription) -> parent
- oppositeName (ETPropertyDescription) -> opposite
- typeName (ETPropertyDescription) -> type
- persistentTypeName (ETPropertyDescription) -> persistentType
Note: the name that follows the arrow is the property to be set.
For example, [anEntityDesc setParentName: @"MyPackage.MySuperEntity"] or [aPropertyDesc setOppositeName: @"MyPackage.MyEntity.whatever"] . For entity descriptions that belong to the anonymous package, the Anonymous prefix can be ommitted. For example, @"NSDate" is interpreted as @"Anonymous.NSDate" in -resolveNamedObjectReferences .
Once all the descriptions (unresolved or not) are registered to ensure a valid repository state, if any unresolved description was added, you must call -resolveNamedObjectReferences on the repository before using it or any registered description. If the added entity description is equal to a previously registered entity (based on a full name comparison), raises an exception.
- - (void) addDescription: (ETModelElementDescription *)aDescription
Adds the given package, entity or property description to the repository.
If the given description is an entity description whose owner is nil, -anonymousPackageDescription becomes its owner, and it gets registered under the full name 'Anonymous.MyEntityName'.
When you are done adding and removing descriptions, don't forget to call -checkConstraints: . If the added or removed descriptions include any entity descriptions, use also -setEntityDescription:forClass: to update the bindings between classes and entity descriptions.
- - (void) removeDescription: (ETModelElementDescription *)aDescription
Removes the given package, entity or property description from the repository.
When you are done adding and removing descriptions, don't forget to call -checkConstraints: . If the added or removed descriptions include any entity descriptions, use also -setEntityDescription:forClass: to update the bindings between classes and entity descriptions.
- - (NSArray *) packageDescriptions
Returns the packages registered in the repository.
The returned collection is an autoreleased copy.
- - (NSArray *) entityDescriptions
Returns the entity descriptions registered in the repository.
The returned collection is an autoreleased copy.
- - (NSArray *) propertyDescriptions
Returns the property description registered in the repository.
The returned collection is an autoreleased copy.
- - (NSArray *) allDescriptions
Returns all the package, entity and property descriptions registered in the repository.
The returned collection is an autoreleased copy.
- - (id) descriptionForName: (NSString *)aFullName
Returns a package, entity or property description registered for the given full name.
e.g. Anonymous.NSObject for NSObject entity. For model element descriptions that belong to the anonymous package, the Anonymous prefix can be ommitted. For example, @"ETModelElementDescription.name" is interpreted as @"Anonymous.ETModelDescription.name".
Binding Descriptions to Class Instances and Prototypes
- - (Class) classForEntityDescription: (ETEntityDescription *)anEntityDescription
Returns the class bound to the given entity description.
If no class is explicitly bound, returns the first bound class in the parent entity chain (by checking recursively until reaching the root entity whether the parent entity is bound to a class).
See -entityDescriptionForClass: and -setEntityDescription:forClass: .
- - (ETEntityDescription *) entityDescriptionForClass: (Class)aClass
Returns the entity description bound to the given class.
If no entity description is explicitly bound, returns the first bound entity in the superclass chain (by checking recursively until reaching the root class whether the superclass is bound to an entity).
See -classForEntityDescription: and -setEntityDescription:forClass: .
- - (void) setEntityDescription: (ETEntityDescription *)anEntityDescription forClass: (Class)aClass
Creates a two-way binding between the given entity description and class.
For entity descriptions not created in +[NSObject newEntityDescription] and not registered in the +mainRepository , this method must be invoked explicitly.
See -entityDescriptionForClass: and -classForEntityDescription: .
Resolving References Between Entity Descriptions
- - (void) resolveNamedObjectReferences
Resolves named references for all the description properties listed in -addUnresolvedDescription: .
For more details, you should also read Named References section in ETPropertyDescription class description.
When you are done resolving references, don't forget to call -checkConstraints: . If the added or removed descriptions include any entity descriptions, use also -setEntityDescription:forClass: to update the bindings between classes and entity descriptions.
