ETModelElementDescription class documentation

Authors

Eric Wasylishen (ewasylishen@gmail.com)

Copyright: (C) 2009 Eric Wasylishen

Software documentation for the ETModelElementDescription class

ETModelElementDescription : NSObject

Declared in:
ETModelElementDescription.h

@group Model and Metamodel @abstract Abstract base class used by Model Description core classes.

The Model Description classes implement a Metamodel framework inspired by FAME (http://scg.unibe.ch/wiki/projects/fame).

Within this Metamodel, ETModelElementDescription provide basic abilities:

ETEntityDescription, ETPropertyDescription and ETPackageDescription all inherit from ETModelElementDescription, can be registered inside a model description repository using -[ETModelDescriptionRepository addDescription:].

@section Conceptual Model

This metamodel is based on the [FM3 specification](http://scg.unibe.ch/wiki/projects/fame/fm3).

For a good introduction, read the paper [FAME — A Polyglot Library for Metamodeling at Runtime](http://www.iam.unibe.ch/~akuhn/d/Kuhn-2008-MRT-Fame.pdf)

We support the entire FM3 specification with some minor adjustements, however the tower (model, metamodel, meta-metamodel) is not explicitly modeled in the API unlike in FAME.

The MSE serialization format is also unsupported. In the future, we will provide our own exchange format based on JSON.

@section FAME Terminology Change Summary

Those changes were made to further simplify the FAME terminology which can get obscure since it overlaps with the host language object model, prevent any conflict with existing GNUstep/Cocoa API and reuse GNUstep/Cocoa naming habits.

We list the FAME term first, then its equivalent name in EtoileFoundation:

FM3.Element
ETModelElementDescription
FM3.Class
ETEntityDescription
FM3.Property
ETPropertyDescription
FM3.RuntimeElement
ETAdaptiveModelObject
attributes (in Class)
propertyDescriptions (in ETEntityDescription)
allAttributes (in Class)
allPropertyDescriptions (in ETEntityDescription)
superclass (in Class)
parent (in ETEntityDescription)
package (in Class)
owner (in ETEntityDescription)
class (in Property)
owner (in ETPropertyDescription)

For the last two points, we can consider FM3.Property.class and FM3.Class.package have been merged into a single FM3.Element.owner property in EtoileFoundation since they were redundant.

@section Changes to FAME

In EtoileFoundation, there is a -owner property that represents either:

While in FAME, owner is a derived property and these various owner kinds are each modeled using a distinct property (class in FM3.Property and package in FM3.Class).

In FAME, container implies not multivalued. In EtoileFoundation, multivalued now controls whether a property is a container or not, and -isContainer is now derived.

Unlike FAME, EtoileFoundation does support overriding property descriptions. This is mainly useful, for read-only properties overriden as read-write in subclasses/subentities.

@section Additions to FAME

-isPersistent has been added to control the persistency, how the interpret the metamodel and its constraints for the framework providing the persistent support is up to this framework. For now, some CoreObject constraints are harcoded in the metamodel.

-isReadOnly has been added to support set-once properties.

-itemIdentifier has been added as a mean to get precise control over the UI generation with EtoileUI.

@section Removals to FAME/EMOF

NamedElement and NestedElement protocols don't exist explicitly.

Property description names can be in upper case (FAME was imposing lower case as a constraint).

@section Metamodel Constraint Summary

Metamodel constraints are checked in -checkConstraints: , while model constraints are validated in -[ETPropertyDescription validateValue:forKey:].

Note: In the future, -checkConstraints: should probably be delegated to -[ETPropertyDescription validateValue:forKey:] in the meta-metamodel.

If we sum up the changes to the FAME conceptual model, for the new ETPropertyDescription, the metamodel constraints are:

At the model level, the semantics are:

Since the metamodel is the model of the meta-metamodel, the model semantics apply to the metamodel too. For model constraints that apply to the metamodel, the validation would be done at the meta-metamodel level with -[ETPropertyDescription validateValue:forKey:], rather than at the metamodel level with -checkConstraints: .

For the new Entity Description, the metamodel constraints are:


Instance Variables

Method summary

descriptionWithName: 

+ (id) descriptionWithName: (NSString*)name;

@taskunit Initialization

Returns an autoreleased entity, property or package description.

See also -initWithName: .


newEntityDescription 

+ (ETEntityDescription*) newEntityDescription;
Subclasses must override this method.

@taskunit Metamodel Description

Returns a new self-description (aka meta-metamodel).


checkConstraints: 

- (void) checkConstraints: (NSMutableArray*)warnings;
An empty method provided for subclasses to override.

@taskunit Runtime Consistency Check

Checks the receiver conforms to the FM3 constraint spec and adds a short warning to the given array for each failure.

A warning must be a NSString instance that describes the issue. Every warning should be created with -warningWithMessage: .


checkNotFrozen 

- (void) checkNotFrozen;
Subclasses must NOT override this method.

@taskunit Internal

Throws an exception if the frozen flag is YES. This should be called in ETModelElementDescription and subclasses before every mutation.


init 

- (id) init;

Initializes and returns entity, property or package description whose name is Untitled.


initWithName: 

- (id) initWithName: (NSString*)name;
This is a designated initialiser for the class.

Initializes and returns an entity, property or package description.

You must only invoke this method on subclasses, otherwise nil is returned.

You should pass the property name in argument for a property description. And the class name for an entity description, the only exception is when the entity description applies to a prototype rather than a class.

Raises an NSInvalidArgumentException when the name is nil or already in use.


makeFrozen 

- (void) makeFrozen;
Subclasses must override this method.

Marks the receiver as frozen. From this point, the receiver is immutable and any attempt to mutate it will cause an exception to be thrown.


warningWithMessage: 

- (NSString*) warningWithMessage: (NSString*)msg;

Returns an autoreleased warning built with the given explanation.

See -checkConstraints: .




Instance Variables for ETModelElementDescription Class

_isFrozen

@protected BOOL _isFrozen;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.