The Complete OCL provides a language for a document in which OCL complements an existing meta-model with invariants, and additional features.
The Complete OCL syntax is defined by the OMG OCL 2.4 specification.
The syntax comprises keywords such as
context followed by appropriate names and punctuation and OCL expressions.
With the exception of
endpackage there is no terminating punctuation and so the consequences of a syntax error can be quite far-reaching while editing a document. Concentrate on the first error.
A substantial example of Complete OCL may be found by installing the RoyalAndLoyal Example Project.
The grammar used by the Xtext editors may be found at:
/src/org/eclipse/ocl/examples/xtext/completeocl/CompleteOCL.xtext
in the org.eclipse.ocl.xtext.completeocl plugin. The Complete OCL grammar extends the Essential OCL grammar.
The Document syntax defines a Complete OCL document, for which *.ocl is the default extension.
A Complete OCL document may
-
import meta-models to be complemented
-
include additional Complute OCL documents
-
specify one or more Standard Library documents
and then provide complements for one of more Packages, Classifiers or Features.
The import, include and library declarations are Eclipse OCL extensions. The OCL 2.4 specification provides no mechanism for a Complete OCL document to reference external material.
The primary definitions of each meta-model may be imported by specifying the URI of a Package and optionally an alias for that Package.
The import may be from a *.ecore, *.uml or *.oclinecore file.
Additional documents complementing meta-model may be included by specifying the URI of the Complete OCL document.
Zero or more external libraries may be imported so that their definitions are merged to form a composite library of basic and extended evaluation capability.
The implicit import of the default OCL Standard Library is suppressed, if any library is imported. The default library may be extended by specifying it as the first library import.
library ocl : 'http://www.eclipse.org/ocl/3.1.0/OCL.oclstdlib'
The namespace URI of the first library package defines the namespace URI of the composite library. The namespace URI of subsequent library imports may not conflict, but may be null.
The PackageDeclaration syntax identifies a Package to be complemented.
The package keyword is followed by the optionally qualified name of the package to be complemented.
The name is followed by the declaration contexts to be complemented and finally an endpackage keyword.
The ContextDecl syntax identifies a model element to be complemented.
A complemented context may be a
The ClassifierContextDecl syntax identifies a Classifier to be complemented.
The context keyword is followed by an optional declaration of the name of the context variable. If omitted the context variable is named
self.
Then the optionally qualified name of the classifier to be complemented is defined. Qualification is required if the classifier context is specified directly as part of the document. Qualification may be omitted when the classifier context is specified as part of a package declaration.
Finally the content of the classifier context may comprise
The Def syntax defines an additional Feature for a Classifier.
The definition may define a static feature with a feature name.
A further name may be specified for no very obvious purpose other than symmetry with an invariant. The optional name is not used.
A parenthesized parameter list must be specified to define an operation and omitted for a property definition.
Then the property or optional operation return type is specified followed by the specification of the property initializer or operation body.
An additional definition is usable within an OCL expression as if it was defined in the complemented meta-model. For the purposes of reflection the additional appear as part of the complemented meta-model, however they remain complements and are not persisted with that meta-model.
The Inv syntax defines an invariant for a Classifier.
The inv keyword is followed by an optional invariant name an optional violation message and the specification of the invariant.
The optional name may be used by validation environments to identify the invariant in a control panel and in diagnostic messages.
The optional violation message provides an OCL expression that may be used by a validation environment to provide a custom message to explain a broken invariant. The severity of the invariant violationm may be controlled by the value of the invariant expression.
-
true indicates that the invariant was satisfied
-
false indicates that the invariant was violated with warning severity
-
null indicates that the invariant was violated with error severity
-
invalid indicates that the invariant failed to evaluate
In the Indigo release, the local variables of the invariant are not accessible to the violation message expression. This will be changed in a future release.
In the Indigo release, custom messages are available when a CompleteOCLEObjectValidator is used as the EValidator. This is not the case for validation in the Sample Ecore Editor and so a default message using the invariant name and the failing object is provided.
The OperationContextDecl syntax identifies an Operation to be complemented.
The context keyword is followed by the optionally qualified name of the operation to be complemented. Qualification is always required since the operation context may be specified as part of the document or a package declaration but not a classifier.
The name is followed by a parenthesized parameter list.
Finally an optional return type and the operation constraints are specified. The operation constraints may comprise
Any number of preconditions and postconditions can be specified. Only one body is permitted.
The Parameter syntax identifies a Parameter of an Operation to be complemented.
A parameter comprises an optional name and Essential OCL type declaration.
The parameter name may be omitted for Operation Contexts if the parameter name is not used by any of the constraints.
The parameter name is required for Operation Definitions.
Note that the type declarations are Essential OCL types such as
Sequence<String> rather than UML’s and OCLinEcore’s
String[*] {ordered !unique}. There are plans to unify these syntaxes.
The Body syntax defines the body for a complemented Operation.
The body keyword is followed by an optional name and the body specification.
The optional name is not used.
The Post syntax defines a postcondition for a complemented Operation.
The post keyword is followed by an optional name and the postcondition specification.
The optional name may be used by a validation environment to identify a failing postcondition.
The Indigo release parses and persists postconditions but does not evaluate them.
The Pre syntax defines a precondition for a complemented Operation.
The pre keyword is followed by an optional name and the precondition specification.
The optional name may be used by a validation environment to identify a failing precondition.
The Indigo release parses and persists preconditions but does not evaluate them.
The PropertyContextDecl syntax identifies a Property to be complemented.
The context keyword is followed by the optionally qualified name of the property to be complemented. Qualification is always required since the property context may be specified as part of the document or a package declaration but not a classifier.
Finally the property type and the property constraints are specified. The property constraints may comprise
An initialization is specified to define the property value when the property is created.
A derivation is specified to define the property value at all times.
It does not therefore make sense to specify both an an initial and an all-time value. If both are specified the derivation is used.
The Init syntax defines an initial value for a complemented Property.
The init keyword and colon are followed by the initial value specification.
The Der syntax defines a derived value for a complemented Property.
The der keyword and colon are followed by the derived value specification.
The Specification syntax provides an OCL expression to specify some aspect of a complemented model.
The specification comprises and Essential OCL Expression.
The NavigatingExp syntax defines enhancements to the Essential OCL NavigatingExp syntax.
The name of a model element may have a further @pre qualification for use within an operation postcondition. It allows the postcondition to access the value on entry to an operation.
? may be specified as the argument in a navigating expression to indicate unknown values when testing sent messages.
The Essential OCL NavigationOperators are extended to support
-
^to test whether a message has been sent message -
^^to reference the content of a message
The Complete OCL reserved words are unchanged from Essential OCL, consequently a Complete OCL Unreserved name is the same as an Essential OCL UnreservedName.
The Complete OCL has two additional built-in types:
OclMessage and
OclState. These names and the
Essential OCL RestrictedNames are not available without qualification or escaping.