Documentation

ETModelElementDescription class documentation

ETModelElementDescription : NSObject

Abstract base class used by Model Description core classes.

AuthorsEric Wasylishen
Declared inETModelElementDescription.h

Overview

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:] .

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.

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.

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.

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.

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).

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:

  • composite is derived from opposite.container
  • derived and not multivalued implies container
  • derived implies not persistent
  • if set, opposite.opposite must be self (i.e. opposite properties must refer to each other)
  • if set, opposite.owner must be type
  • owner must not be nil
  • type must not be nil

At the model level, the semantics are:

  • container property chains may not include cycles (could be turned into a model constraint)
  • any multivalued property defaults to empty
  • boolean properties default to false
  • non primitive properties default to nil
  • string and number properties do not have a default value (could be changed later)

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:

  • parent is not nil
  • parent must not be a primitive, unless self is a primitive
  • parent chain may not include cycles (could be removed, this comes from 'container property chains may not include cycles' in the model semantics of ETPropertyDescription)
  • package must not be nil
  • allPropertyDescriptions is derived as union of propertyDescription and parent.allPropertyDescriptions
  • propertyDescriptions replaces parent.propertyDescriptions in allPropertyDescriptions
  • allPropertyDescriptions must have unique names


Metamodel Description

+ (ETEntityDescription *) newEntityDescription

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

    Initialization

    + (id) descriptionWithName: (NSString *)name

    Returns an autoreleased entity, property or package description.

    See also -initWithName: .

      - (id) initWithName: (NSString *)name

      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.

        - (id) init

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

          Runtime Consistency Check

          - (void) checkConstraints: (NSMutableArray *)warnings

          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: .

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

            Returns an autoreleased warning built with the given explanation.

            See -checkConstraints: .

              Internal

              - (void) checkNotFrozen

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

                - (void) makeFrozen

                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.