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 {@link org.eclipse.papyrus.gmf.validate.GMFValidator}.
This class follows the standard EMF validator contract and its
{@link org.eclipse.papyrus.gmf.validate.GMFValidator#validate validate} operation
can be either called directly on a model element or it can be registered as a standard
{@link org.eclipse.emf.ecore.EValidator} in {@link org.eclipse.emf.ecore.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 {@link org.eclipse.emf.ecore.util.Diagnostician} class.
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.
The constraint on@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; }
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
.
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.
Boolean
type, otherwise is considered invalid.
java.text.MessageFormat
pattern and use {0} argument, which in runtime corresponds to the validated model element.
error, warn, info
.
If not specified, the default error
is applied.
The contextual instance that violates some constraints during validation is allways the source object encoded in the data of {@link org.eclipse.emf.common.util.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.
@constraints
("import"="http://www.eclipse.org/gmf/runtime/1.0.0/notation")