EMF Model Validation Constraint Providers

Identifier:
org.eclipse.emf.validation.constraintProviders

Since:
1.0

Description:

This extension point allows plug-ins to contribute constraints into the model validation framework.

Configuration Markup:

<!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 (#PCDATA)>

Optional localizable description for an element in the extension point implementation. May appear in the GUI, depending on the element being described.



<!ELEMENT target ((event | customEvent)*)>

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



<!ELEMENT event (feature*)>

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



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



<!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 (#PCDATA)>

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.



<!ELEMENT include EMPTY>

<!ATTLIST include

path CDATA #REQUIRED>

For internal use only.



<!ELEMENT customEvent (feature*)>

<!ATTLIST customEvent

name CDATA #REQUIRED>

A custom notification event that causes the validation of an instance of the associated model element type (live constraints only). The custom events available are determined by the installed providers of event generators on the org.eclipse.emf.validation.eventTypes extension point.

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.



Examples:

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="org.eclipse.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>


Copyright (c) 2003, 2004 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html