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

- id - Identifier for the category. The ID is a hierarchical name, delimited by slashes, relative to the ID of the containing "category" element (if any). There is no problem with defining a category that is already defined by some other plug-in; the new name and description override the old, but if the IDs were the same, then the expectation is that so is the meaning.
- name - The localized name of the category.
- mandatory - Indicates whether the category is mandatory or not. The user cannot disable constraints that are in mandatory categories, so care must be taken in designating a category as mandatory. It must really be essential to the correct functioning of the application! If not specified, the implied value is false.

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

- mode - Describes whether a constraint operates in batch mode or live mode. If not specified, then the assumption is that the provider provides constraints in mixed modes.
- cache - For internal use only.
- class - An optional constraint provider class that will provide batch and live constraints.

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

- namespaceUri - The namespace URI of an EMF package supported by the constraint provider.

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

- class - Optionally identifies the model element type to which constraints apply. If omitted, then the constraint applies to all types in the EPackage on which the constraint provider is defined. In the case of two model element types with the same name in two different packages, use the optional qualified namespace URI in the following format to ensure that the target is resolved correctly: myClass:http:///someNameSpaceURI/1.0.0/

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

- name - Corresponds to the name of an EMF notification type.

  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.

- name - The feature name.

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

- id - A unique identifier for the constraint.
- name - A localizable name for the constraint (appears in the GUI).
- lang - Identifies the language in which the constraint is expressed. The language is not case-sensitive.

  The currently supported languages are "Java" and "OCL".

- severity - The severity of the problem if the constraint is violated. This correlates to the severity of tasks in the Tasks view of the Eclipse environment.

  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.

- statusCode - The plug-in unique status code, useful for logging.
- class - For "Java" language constraints only, identifies a class implementing the constraint.

  The class must extend the AbstractModelConstraint class, providing an implementation of the abstract validate() method.

- mode - Describes whether a constraint operates in batch mode, live mode, or feature mode.

  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.

- name - The name of the parameter.
- value - The value of the parameter. If the value attribute is not present, then the value is assumed to be in the body of the "param" element.

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

- categories - A comma-delimited list of fully-qualified category IDs to which the constraints grouped in this element belong. If none are specified, then the constraints are members of the default category. It is not recommended, however, to use the default category.

  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.

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

- name - Corresponds to the name of an EMF notification type.

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

###### 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