This extension point allows plug-ins to contribute constraints into the model validation framework.
<!ELEMENT extension (category* , constraintProvider*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT category (category*)>
<!ATTLIST category
id CDATA #REQUIRED
name CDATA #REQUIRED
mandatory (true | false) >
Defines a constraint category. Constraints that are members of this category can be enabled or disabled by the user in the preference page, unless the "mandatory" attribute is set.
The body of the "category" element should contain the localized description of the category.
<!ELEMENT constraintProvider (package+ , description? , target* , constraints*)>
<!ATTLIST constraintProvider
mode (Batch|Live)
cache (true | false) "true"
class CDATA #IMPLIED>
Defines a set of constraints that apply to instances of EClasses in one or more EPackages identified by their namespace URIs. Any number of constraintProviders can be defined for the same packages, and a single constraintProvider can specify any number of packages.
<!ELEMENT package EMPTY>
<!ATTLIST package
namespaceUri CDATA #REQUIRED>
The "package" element declares an EMF EPackage to whose EClasses the constraint provider provides constraints. One or more packages may be declared. The targets of any constraints are resolved in the namespaces of the specified packages.
Note that only EClasses that are members of those exact packages indicated will have constraints applied to them from this provider. In particular, any sub-packages of an EPackage that are to have constraints provided must be explicitly declared.
<!ELEMENT description (#CDATA)>
Optional localizable description for an element in the extension point implementation. May appear in the GUI, depending on the element being described.
<!ATTLIST target
class CDATA #IMPLIED>
Specification of which model elements, events, and structural features constraints can be applied to.
When attached to a constraintProvider, this tag indicates generally the scope of the constraints that a provider provides. This can be used by the validation framework to reduce the number of providers that it consults when performing a validation, and is just an optimization.
When attached to a specific constraint element, the target specifies which particular EClass (for batch and live constraints) and events and/or features (for live constraints) the constraint applies to.
<!ATTLIST event
name (Add|Add Many|Create|Move|Remove|Remove Many|Removing Adapter|Resolve|Set|Unset) >
The EMF notification event that causes the validation of an instance of the associated model element type (live constraints only). This element may optionally specify any number of specific features to which the constraint applies. Any notifications for features not listed (if any are specified) will not trigger evaluation of the constraint.
Note that the "Create" event is not the deprecated EMF CREATE Notification type; it is a custom notification type that clients of the validation framework may choose to implement if they can simulate create notifications. Its Notification type code is 0.
<!ELEMENT feature EMPTY>
<!ATTLIST feature
name CDATA #REQUIRED>
Indicates for which structural feature the constraint should be triggered. If no features are specified, then the constraint is triggered for any feature change in the associated model element type.
Applies only to live-mode constraints.
<!ELEMENT constraint (description? , message , target* , param*)>
<!ATTLIST constraint
id CDATA #REQUIRED
name CDATA #REQUIRED
lang CDATA #REQUIRED
severity (INFO|WARNING|ERROR|CANCEL) "ERROR"
statusCode CDATA #REQUIRED
class CDATA #IMPLIED
mode (Batch|Live) "Batch">
Defines a single constraint. The lang attribute identifies the language in which the constraint is implemented. For the "Java" language, this element identifies a class that extends the AbstractModelConstraint class. Other languages, such as "OCL", may make use of the body of the constraint element and/or one or more parameters.
The currently supported languages are "Java" and "OCL".
The default severity (if none specified) is ERROR. The CANCEL severity should be used with caution, as it causes the validation operation to be interrupted, possibly resulting in the loss of valuable diagnostic information from other constraints.
The class must extend the AbstractModelConstraint class, providing an implementation of the abstract validate() method.
The default is batch if not specified.
<!ELEMENT param EMPTY>
<!ATTLIST param
name CDATA #REQUIRED
value CDATA #IMPLIED>
Defines a constraint-language-specific parameter, which provides additional meta-data not implemented by the basic XML schema.
Currently, neither of the supported "Java" or "OCL" languages uses additional parameters.
<!ELEMENT message (#CDATA)>
The error message pattern to display to the user. The pattern may contain {0}, {1}, etc. placeholders for replacement at run-time by model elements or other objects provided by the constraint implementation. The pattern is specified in the body of the tag, possibly as a CDATA section.
<!ELEMENT constraints (include* , constraint*)>
<!ATTLIST constraints
categories CDATA #IMPLIED>
Container for constraint declarations. The constraints grouped in one of these elements belong to the same set of categories.
Note that it is not a good idea to include constraints simultaneously in a category and some ancestor or descendent category. This would be quite confusing to the user.
<!ELEMENT include EMPTY>
<!ATTLIST include
path CDATA #REQUIRED>
For internal use only.
This example shows an extension that declares a small hierarchy of constraint categories, with example constraints showing the difference between Java and OCL languages.
<extension point=
"com.ibm.xtools.emf.validation.constraintProviders"
>
<category name=
"Example Constraints"
id=
"com.example.validation"
>
Description of the example constraints category.<category name=
"Foo"
id=
"foo"
>
Constraints for the EMF implementation of the Foo metamodel.</category>
</category>
<constraintProvider>
<package namespaceUri=
"http:///com/example/foo.ecore"
/>
<constraints categories=
"com.example.validation/foo"
>
<constraint class=
"com.example.validation.constraints.ThingReferences"
statusCode=
"11"
severity=
"WARNING"
lang=
"Java"
name=
"Things References"
id=
"thingReferences"
>
<description>
Things must not reference things that do not exist.</description>
<message>
{0} references non-existing things {1}.</message>
<target class=
"Thing"
/>
</constraint>
<constraint statusCode=
"12"
severity=
"ERROR"
lang=
"OCL"
mode=
"Live"
name=
"Things Must be Named"
id=
"thingName"
>
<description>
Things must have names.</description>
<message>
Thing has no name.</message>
<target class=
"Thing"
>
<event name=
"Set"
>
<feature name=
"name"
/>
</event>
</target>
<!-- The OCL constraint expression. -->
<![CDATA[ name->
notEmpty() ]]></constraint>
</constraints>
</constraintProvider>
</extension>
The "Java" language constraints are implemented using the facilities provided by the com.ibm.xtools.emf.validation package in the plug-in of the same name.
To apply the constraints defined on this extension point to the element(s) of a model, use the utilities offered by the com.ibm.xtools.emf.msl.EditingDomain class. These utilities validate the model against all batch and live constraints, returning the result in a composite status object. Live validation is also performed internally in the system as the model is changed.
(C) Copyright 2003, 2004 IBM Corporation. All Rights Reserved.