Package org.eclipse.gmf.validate

Definition of constraint ecore annotations schema for model validation purposes.

See:
          Description

Class Summary
GMFValidator Validator of GMF constraint annotations.
ValidationOptions Holds GMF specific options to be used in validation
 

Package org.eclipse.gmf.validate Description

Definition of constraint ecore annotations schema for model validation purposes.

Package Specification

This package defines special ecore annotations for use in GMF models validation. These annotation forms the client API GMF Validation framework which can be involved in validation by using GMFValidator. This class follows the standard EMF validator contract and its validate operation can be either called directly on a model element or it can be registered as a standard EValidator in EValidator.Registry for a desired ecore package nsURI. Both approaches involve constraint annotations defined in validated element's ecore meta-model while only the latter one ensures that these constraints get involved in the standard EMF validation using Diagnostician class.

Constraint annotations

GMF Validation introduces special constraint annotations enabling the use of boolean type expressions further restricting the model contents, usually complementing or refining standard EMF constraints. The usage on exemplary use-case and semantics of GMF constraint annotations is demonstrated in the example bellow using an ecore model fragment in Emfatic notation.

@EmfaticAnnotationMap(constraints="http://www.eclipse.org/gmf/2005/constraints")

@constraints(
        ocl="birthDate <> null && hireDate <> null implies birthDate <= hireDate", 
        severity="warning",
        description="An unborn person ''{0}'' was hired!!!"
)
// additional "Person" constraints go here ...  
class Person {
        @constraints(
                ocl="nick <> null imlies nick.size() < 5", 
                description="The ''{0}'' nick name is too long"
        )
        // additional constraints related to "nick" go here ... 
        attr String[1] nick;
        attr String[1] name;
        attr Date[1] birthDate;
        attr Date hireDate;
}
The constraint on Person class complements the EMF cardinality constraint on birthDate which is guarded by the basic EMF validator but is also dependent on hireDate existence. Therefore the OCL expression parsed in the context of Person checks whether both are defined and only then it enforce the restriction based on their comparison. Another common example of EMF complementing constraints could a be mutual exclusion rules for related structural features.
The Person::nick feature's constraint refines the required constraint on nick by restricting the length of its string value. The corresponding OCL expression is defined again in the context of Person class.
Note: Both constraints mentioned above are parsed in the context of Person as it is the only valid OCL expression context [oclIsKindOf(EClassifier)] in the nearest outer-scope. The structuring used in the example is purely based on the logical scope of the restrictions. For instance, the rule for birthDate, hireDate involves both attributes, thus is rather consider class-wide. The is mainly because of the clarity aspect, but could be also helpful when removing ecore elements involved in GMF constraints. However, the broken annotations are detected and reported by GMFValidator.

Annotation Semantics

GMF constraints are defined as EAnnotation elements with source=http://www.eclipse.org/gmf/2005/constraints. and attached either to EClass or its EStructuralFeature, in which case the containing EClass is allways the context for OCL expressions evaluation.
Constraint annotations details (key : value) is listed bellow.

The contextual instance that violates some constraints during validation is allways the source object encoded in the data of Diagnostic object resulting from validation.

GMF constraints are inheritable. Once a constraint is defined in the context of EClass instance, all sub-classes of this class are restricted as well. So it's possible to add the most common constraints to super-class and spread the specializing constraints to particular sub-classes.

In some cases in OCL, the user might need to reference a classifier from a meta-model, which is not loaded automatically if the validated model has no references this meta-model's elements. By default, OCL implementation performs classifier lookup in the global EPackage.Registry. Only initialized packages are involved in the lookup, those whose instances are put to the registry instead of EPackage.Descriptor. For instance, there might be an OCL constraint like self.oclIsKindOf(model::Foo) while there is no reference to model::Foo in the validated model. If the model has not been initialized in the registrey yet, the OCL will report an error on uknown classifier. To solve this issue, an import annotation can be used, source=http://www.eclipse.org/gmf/2005/constraints
Import annotations details (key : value) is listed bellow.

The import annotation is to be located in the EPackage element of the annotated ecore model. This enables the imported classifiers in the OCL environments of all constraint annotation attached to the package contained ecore elements.
For instance, the annotation below ensures access to the runtime diagram notation meta-model.
@constraints("import"="http://www.eclipse.org/gmf/runtime/1.0.0/notation")



Copyright © 2012. All Rights Reserved.