|
|
| Line 1: |
Line 1: |
| − | = Validation Rules =
| + | This page has been moved to https://github.com/eclipse/capella/wiki/Validation-Rules |
| − | | + | |
| − | == Model Validation Rules ==
| + | |
| − | | + | |
| − | Capella offers a '''model validation''' functionality. This validation is available through a '''contextual menu command''' that executes a set of rules on the selected model element.
| + | |
| − | | + | |
| − | The set of executed rules can be customized through the preferences (non-mandatory rules can be activated or deactivated), and additional specific rules can be contributed through an '''extension point'''.
| + | |
| − | | + | |
| − | == Extension Point Description ==
| + | |
| − | | + | |
| − | An Eclipse extension point allows plug-ins to contribute constraints into the EMF model validation framework.
| + | |
| − | | + | |
| − | The extension point is provided by:
| + | |
| − | * the plug-in '''org.eclipse.emf.validation'''
| + | |
| − | * and its identifier '''constraintProviders'''.
| + | |
| − | | + | |
| − | Following figures details the contents of the extension point:
| + | |
| − | | + | |
| − | [[File:Capella ValidationRules ExtensionPoint.png|800px|center|Capella ValidationRules ExtensionPoint]]
| + | |
| − | | + | |
| − | The contribution to the extension point is done in the '''plugin.xml''' file of the plugin.
| + | |
| − | Open this file and focus on the '''plugin.xml''' tab:
| + | |
| − | <br>
| + | |
| − | <pre>
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <?eclipse version="3.2"?>
| + | |
| − | <plugin>
| + | |
| − | <extension point="org.eclipse.emf.validation.constraintProviders">
| + | |
| − | <constraintProvider>
| + | |
| − | <package namespaceUri=""/>
| + | |
| − | <constraints categories="">
| + | |
| − | <constraint
| + | |
| − | class=""
| + | |
| − | id=" "
| + | |
| − | isEnabledByDefault="true"
| + | |
| − | lang="Java"
| + | |
| − | mode="Batch"
| + | |
| − | name=" "
| + | |
| − | severity="ERROR"
| + | |
| − | statusCode="1">
| + | |
| − | <message>
| + | |
| − | </message>
| + | |
| − | <target class=""/>
| + | |
| − | <description>
| + | |
| − | </description>
| + | |
| − | </constraint>
| + | |
| − | </constraints>
| + | |
| − | </constraintProvider>
| + | |
| − | </extension>
| + | |
| − | </plugin>
| + | |
| − | </pre>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | {| class="wikitable"
| + | |
| − | |+Detail of the different fields
| + | |
| − | |-
| + | |
| − | |'''namespaceUri'''
| + | |
| − | |Namespace URI of an EMF package supported by the constraint provider. Following is the list of all URI currently available in Capella. Each one matches a subset of the Capella Metamodel:<br>
| + | |
| − | <pre>
| + | |
| − | Capella Modeller http://www.polarsys.org/capella/core/modeller/1.1.0
| + | |
| − | Capella Core http://www.polarsys.org/capella/core/core/1.1.0
| + | |
| − | Capella Common http://www.polarsys.org/capella/core/common/1.1.0
| + | |
| − | Composite Structure http://www.polarsys.org/capella/core/cs/1.1.0
| + | |
| − | Operational Analysis http://www.polarsys.org/capella/core/oa/1.1.0
| + | |
| − | System Analysis http://www.polarsys.org/capella/core/ctx/1.1.0
| + | |
| − | Logical Architecture http://www.polarsys.org/capella/core/la/1.1.0
| + | |
| − | Physical Architecture http://www.polarsys.org/capella/core/pa/1.1.0
| + | |
| − | Deployment http://www.polarsys.org/capella/core/pa/deployment/1.1.0
| + | |
| − | EPBS http://www.polarsys.org/capella/core/epbs/1.1.0
| + | |
| − | Functional Analysis http://www.polarsys.org/capella/core/fa/1.1.0
| + | |
| − | Shared Model http://www.polarsys.org/capella/core/sharedmodel/1.1.0
| + | |
| − | Requirement http://www.polarsys.org/capella/core/requirement/1.1.0
| + | |
| − | Interaction http://www.polarsys.org/capella/core/interaction/1.1.0
| + | |
| − | Information http://www.polarsys.org/capella/core/information/1.1.0
| + | |
| − | Communication http://www.polarsys.org/capella/core/information/communication/1.1.0
| + | |
| − | Data Type http://www.polarsys.org/capella/core/information/datatype/1.1.0
| + | |
| − | Data Value http://www.polarsys.org/capella/core/information/datavalue/1.1.0
| + | |
| − | | + | |
| − | Modelling Core http://www.polarsys.org/capella/common/core/1.1.0
| + | |
| − | Behavior http://www.polarsys.org/capella/common/behavior/1.1.0
| + | |
| − | Activity http://www.polarsys.org/capella/common/activity/1.1.0
| + | |
| − | </pre>
| + | |
| − | Note: The meta-models URI has changed: only the version number as it used to change between a version N and N+1:
| + | |
| − | <pre>
| + | |
| − | http://www.polarsys.org/capella/common/.../1.0.0
| + | |
| − | -> http://www.polarsys.org/capella/common/.../1.1.0
| + | |
| − | http://www.polarsys.org/capella/core/.../1.0.0
| + | |
| − | -> http://www.polarsys.org/capella/core/.../1.1.0
| + | |
| − | </pre>
| + | |
| − | |-
| + | |
| − | |<pre>
| + | |
| − | <constraints categories="">
| + | |
| − | <constraint
| + | |
| − | </pre>
| + | |
| − | |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.
| + | |
| − | | + | |
| − | Here is the list of all categories currently available in Capella. New ones can be created but the root prefix shall always be '''capella.category''':<br>
| + | |
| − | <pre>
| + | |
| − | capella.category/quality
| + | |
| − | capella.category/integrity
| + | |
| − | capella.category/design
| + | |
| − | capella.category/design/coverage
| + | |
| − | capella.category/design/well-formedness
| + | |
| − | capella.category/design/well-formedness/state_machines
| + | |
| − | capella.category/design/well-formedness/dataflows
| + | |
| − | capella.category/design/well-formedness/components
| + | |
| − | capella.category/design/well-formedness/data
| + | |
| − | capella.category/design/well-formedness/interfaces
| + | |
| − | capella.category/design/well-formedness/scenarios
| + | |
| − | capella.category/design/well-formedness/capabilities
| + | |
| − | capella.category/design/well-formedness/use_cases
| + | |
| − | capella.category/design/consistency
| + | |
| − | capella.category/design/completeness
| + | |
| − | capella.category/structural_conformance_to_m2
| + | |
| − | capella.category/transition
| + | |
| − | capella.category/transition/consistency
| + | |
| − | capella.category/transition/consistency/data
| + | |
| − | capella.category/transition/consistency/state_machines
| + | |
| − | capella.category/transition/consistency/interfaces
| + | |
| − | capella.category/transition/consistency/dataflows
| + | |
| − | capella.category/transition/consistency/scenarios
| + | |
| − | capella.category/transition/consistency/capabilities
| + | |
| − | capella.category/transition/justification
| + | |
| − | capella.category/transition/justification/physical_architecture
| + | |
| − | capella.category/transition/justification/logical_architecture
| + | |
| − | capella.category/transition/justification/epbs
| + | |
| − | capella.category/transition/justification/generic
| + | |
| − | capella.category/transition/justification/system_analysis
| + | |
| − | </pre>
| + | |
| − | Note: categories are <capella_source_code_tree>\core\plugins\org.polarsys.capella.core.validation\plugin.xml <br>
| + | |
| − | Modify this file to add new categories (they must be children of capella.category)
| + | |
| − | | + | |
| − | |-
| + | |
| − | |<pre>
| + | |
| − | <constraint
| + | |
| − | class=""
| + | |
| − | id=" "
| + | |
| − | isEnabledByDefault="true"
| + | |
| − | lang="Java"
| + | |
| − | mode="Batch"
| + | |
| − | name=" "
| + | |
| − | severity="ERROR"
| + | |
| − | statusCode="1">
| + | |
| − | <message>
| + | |
| − | </message>
| + | |
| − | <target class=""/>
| + | |
| − | <description>
| + | |
| − | </description>
| + | |
| − | </constraint>
| + | |
| − | </pre>
| + | |
| − | |Defines a single constraint:
| + | |
| − | * '''id''' - A unique identifier for the constraint.
| + | |
| − | * '''name''' - A localizable name for the constraint (appears in the GUI). '''Note that {0} identify the element type and {1} its name'''.
| + | |
| − | * '''lang''' - Identifies the language in which the constraint is expressed. The language is not case-sensitive. The currently supported languages are '''Java''' and '''OCL'''. For the '''Java''' language, this element identifies a class that extends the '''AbstractValidationRule''' class. Other languages, such as '''OCL''', may make use of the body of the constraint element and/or one or more parameters.
| + | |
| − | * '''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 '''AbstractValidationRule''' class, providing an implementation of the abstract method: <pre>validate()</pre>
| + | |
| − | * '''mode''' - Describes whether a constraint operates in batch mode, live mode, or feature mode. The default is batch if not specified.
| + | |
| − | * '''isEnabledByDefault''' - Indicates if this constraint should be enabled by default. User can change this setting in preferences. The default value is true.
| + | |
| − | |}
| + | |
| − | | + | |
| − | == Validation Rule Implementation ==
| + | |
| − | | + | |
| − | The '''AbstractValidationRule''' class that is extended by '''CapellaTutorialValidationRule''' class provides some facilities to manage messages.
| + | |
| − | | + | |
| − | '''Notes:'''
| + | |
| − | * To return a valid status, return the result of the call to the method: <pre>createSuccessStatus()</pre>
| + | |
| − | * To return an invalid status, return the result of the call to the method: <pre>createFailureStatus(...)</pre> The parameters are the validation context and a set of parameters that will be passed to your message (they will be used only if you defined '''{0}, {1}, etc. parameters''' in your message text: see the previous section).
| + | |
| − | | + | |
| − | == Sample Validation Rule ==
| + | |
| − | In this sample validation rule, we check that all '''Functions''' in Physical Architecture have a description and a summary.
| + | |
| − | | + | |
| − | First, we create a new '''plugin project''' using Capella Studio.
| + | |
| − | | + | |
| − | Then, we edit the '''MANIFEST/MANIFEST.MF''' file to add:
| + | |
| − | * the necessary dependencies in the '''Dependencies''' tab:
| + | |
| − | ** '''org.eclipse.emf.validation'''
| + | |
| − | ** '''org.polarsys.capella.core.validation'''
| + | |
| − | * and the contribution to the extension point:
| + | |
| − | | + | |
| − | Select the '''Extensions''' tab then click on the '''add...''' button. The '''plugin.xml''' file is generated. Open this file and select the '''plugin.xml''' tab:
| + | |
| − | <pre>
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <?eclipse version="3.2"?>
| + | |
| − | <plugin>
| + | |
| − | <extension point="org.eclipse.emf.validation.constraintProviders">
| + | |
| − | <constraintProvider>
| + | |
| − | <package namespaceUri="http://www.polarsys.org/capella/core/pa/1.1.0"/>
| + | |
| − | <constraints categories="capella.category/design/well-formedness/data">
| + | |
| − | <constraint
| + | |
| − | class="myfirstvalidationrule.CapellaTutorialValidationRule"
| + | |
| − | id="DWF_PA_99"
| + | |
| − | isEnabledByDefault="true"
| + | |
| − | lang="Java"
| + | |
| − | mode="Batch"
| + | |
| − | name="DWF_PA_99 - Physical Architecture Functions Description and Summary"
| + | |
| − | severity="ERROR"
| + | |
| − | statusCode="1">
| + | |
| − | <message>
| + | |
| − | The function {1} has either no description or no summary!
| + | |
| − | </message>
| + | |
| − | <target class="PhysicalFunction"/>
| + | |
| − | <description>
| + | |
| − | This validation rule checks that all Functions in Physical Architecture have a description and a summary.
| + | |
| − | </description>
| + | |
| − | </constraint>
| + | |
| − | </constraints>
| + | |
| − | </constraintProvider>
| + | |
| − | </extension>
| + | |
| − | </plugin>
| + | |
| − | </pre>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | Then we implement the code of the validation rule:
| + | |
| − | | + | |
| − | <br>
| + | |
| − | <pre>
| + | |
| − | package myfirstvalidationrule;
| + | |
| − | import org.eclipse.core.runtime.IStatus;
| + | |
| − | import org.eclipse.emf.ecore.EObject;
| + | |
| − | import org.eclipse.emf.validation.IValidationContext;
| + | |
| − | import org.polarsys.capella.common.data.modellingcore.AbstractNamedElement;
| + | |
| − | import org.polarsys.capella.core.data.pa.PhysicalFunction;
| + | |
| − | import org.polarsys.capella.core.validation.rule.AbstractValidationRule;
| + | |
| − | | + | |
| − | public class CapellaTutorialValidationRule extends AbstractValidationRule {
| + | |
| − | /**
| + | |
| − | * {@inheritDoc}
| + | |
| − | */
| + | |
| − | @Override
| + | |
| − | public IStatus validate(IValidationContext ctx) {
| + | |
| − | EObject eObj = ctx.getTarget();
| + | |
| − | if (eObj instanceof PhysicalFunction) {
| + | |
| − | PhysicalFunction capellaElt = (PhysicalFunction) eObj;
| + | |
| − | String desc = capellaElt.getDescription();
| + | |
| − | String summary = capellaElt.getSummary();
| + | |
| − | if (desc == null || desc.isEmpty() || summary == null || summary.isEmpty()) {
| + | |
| − | if (capellaElt instanceof AbstractNamedElement) {
| + | |
| − | AbstractNamedElement namedElt = (AbstractNamedElement) capellaElt;
| + | |
| − | return ctx.createFailureStatus(new Object[] {capellaElt.eClass().getName(), namedElt.getName()});
| + | |
| − | }
| + | |
| − | return ctx.createFailureStatus(new Object[] {capellaElt.eClass().getName(), "<unnamed>"});
| + | |
| − | }
| + | |
| − | }
| + | |
| − | return ctx.createSuccessStatus();
| + | |
| − | }
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | Note: A dependency to '''org.polarsys.capella.core.validation''' plugin shall be added.
| + | |
| − | | + | |
| − | <br>
| + | |
| − | | + | |
| − | | + | |
| − | Now we can export the plugin using right-click on the project directory > Export > Plug-in Development > Deployable plug-ins and fragments.
| + | |
| − | | + | |
| − | Select '''Archive file''' radio button and give the archive a name (e.g. <SOME_PATH>/MyValidationRule.zip) and click on finish.
| + | |
| − | | + | |
| − | Extract the contents of the generated archive into <CAPELLA_HOME_DIRECTORY>/eclipse/dropins directory and launch Capella.
| + | |
| − | | + | |
| − | Open Windows > Preferences in the menu bar, expand '''Model Validation''' and select '''Constraints'''.
| + | |
| − | | + | |
| − | Expand '''Capella''' > '''Design''' > '''Well-formedness''' and click on '''Data'''.
| + | |
| − | | + | |
| − | Scroll down and check the validation rule is present. Click on it to visualize its description.
| + | |
| − | <br>
| + | |
| − | [[File:Capella ValidationRules SamplePrefs.png|600px|center|Capella ValidationRules SamplePrefs]]
| + | |
| − | <br>
| + | |
| − | | + | |
| − | Click on cancel and create a Capella project, and a '''Physical Function''' at Physical Architecture level.
| + | |
| − | | + | |
| − | Right-click on this function and select '''Validate'''. Check that an error is raised, meaning the sample validation rule has been called:
| + | |
| − | <br>
| + | |
| − | [[File:Capella ValidationRules SampleError.png|400px|center|Capella ValidationRules SampleError]]
| + | |
| − | <br>
| + | |
| − | | + | |
| − | This tutorial will be enriched to address other topics like contributing to the quick fix, etc.
| + | |
| − | | + | |
| − | You can download the sample validation rule source code following [[File:Capella_sample_validation_rule.zip|this link]].
| + | |
| − | | + | |
| − | [[Category:Capella]]
| + | |
