
h2(#CompleteOCL). The Complete OCL Language

The Complete OCL provides a language for a document in which OCL complements an existing meta-model with invariants, and additional features.

h3. Syntax

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":#RoyalAndLoyalExample.

h4. Grammar Implementation

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.

h4(#CompleteOCL-Document). Complete OCL Document

The Document syntax defines a Complete OCL document, for which *.ocl is the default extension.

!{width:60%}images/1300-document.png(Complete OCL Document Syntax)!

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.

!{width:60%}images/1300-import.png(Complete OCL Import Syntax)!

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.

!{width:60%}images/1300-include.png(Complete OCL Include Syntax)!

Additional documents complementing meta-model may be included by specifying the URI of the Complete OCL document.

!{width:60%}images/1300-library.png(Complete OCL Library Syntax)!

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.

bc.. 
library ocl : 'http://www.eclipse.org/ocl/3.1.0/OCL.oclstdlib'
p. 

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.

h4(#CompleteOCL-PackageDeclaration). PackageDeclaration

The PackageDeclaration syntax identifies a Package to be complemented.

!{width:60%}images/1300-packagedeclaration1.png(Complete OCL Package Declaration Syntax Part 1)!

The package keyword is followed by the optionally qualified name of the package to be complemented.

!{width:60%}images/1300-packagedeclaration2.png(Complete OCL Package Declaration Syntax Part 2)!

The name is followed by the "declaration contexts":#CompleteOCL-ContextDecl to be complemented and finally an endpackage keyword.

h4(#CompleteOCL-ContextDecl). ContextDecl

The ContextDecl syntax identifies a model element to be complemented.

!{width:60%}images/1300-contextdecl.png(Complete OCL ContextDecl Syntax)!

A complemented context may be a
* "Classifier Context":#CompleteOCL-ClassifierContextDecl
* "Operation Context":#CompleteOCL-OperationContextDecl
* "Property Context":#CompleteOCL-PropertyContextDecl

h4(#CompleteOCL-ClassifierContextDecl). ClassifierContextDecl

The ClassifierContextDecl syntax identifies a Classifier to be complemented.

!{width:60%}images/1300-classifiercontextdecl1.png(Complete OCL Classifier Context Decl Syntax Part 1)!

The context keyword is followed by an optional declaration of the name of the context variable. If omitted the context variable is named @self@.

!{width:60%}images/1300-classifiercontextdecl2.png(Complete OCL Classifier Context Decl Syntax Part 2)!

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.

!{width:60%}images/1300-classifiercontextdecl3.png(Complete OCL Classifier Context Decl Syntax Part 3)!

Finally the content of the classifier context may comprise
* "Def":#CompleteOCL-Def to define an additional feature
* "Inv":#CompleteOCL-Inv to define an invariant

h4(#CompleteOCL-Def). Def

The Def syntax defines an additional Feature for a Classifier.

!{width:60%}images/1300-def1.png(Complete OCL Def Syntax Part 1)!

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.

!{width:60%}images/1300-def2.png(Complete OCL Def Syntax Part 2)!

A parenthesized "parameter":#CompleteOCL-Parameter list must be specified to define an operation and omitted for a property definition.

!{width:60%}images/1300-def3.png(Complete OCL Def Syntax Part 3)!

Then the property or optional operation return "type":#EssentialOCL-TypeExp is specified followed by the "specification":#CompleteOCL-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.

h4(#CompleteOCL-Inv). Inv

The Inv syntax defines an invariant for a Classifier.

!{width:60%}images/1300-inv.png(Complete OCL Inv Syntax)!

The inv keyword is followed by an optional invariant name an optional violation message and the "specification":#CompleteOCL-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. 

h4(#CompleteOCL-OperationContextDecl). OperationContextDecl

The OperationContextDecl syntax identifies an Operation to be complemented.

!{width:60%}images/1300-operationcontextdecl1.png(Complete OCL Operation Context Decl Syntax Part 1)!

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.

!{width:60%}images/1300-operationcontextdecl2.png(Complete OCL Operation Context Decl Syntax Part 2)!

The name is followed by a parenthesized "parameter":#CompleteOCL-Parameter list.

!{width:60%}images/1300-operationcontextdecl3.png(Complete OCL Operation Context Decl Syntax Part 3)!

Finally an optional return "type":#EssentialOCL-TypeExp and the operation constraints are specified. The operation constraints may comprise 
* a "Body":#CompleteOCL-Body to define operation body
* "Pre":#CompleteOCL-Inv to define a precondition on the operation
* "Post":#CompleteOCL-Inv to define a postcondition on the operation

Any number of preconditions and postconditions can be specified. Only one body is permitted.

h4(#CompleteOCL-Parameter). Parameter

The Parameter syntax identifies a Parameter of an Operation to be complemented.

!{width:60%}images/1300-parameter.png(Complete OCL Parameter Syntax)!

A parameter comprises an optional name and Essential OCL "type":#EssentialOCL-TypeExp declaration.

The parameter name may be omitted for "Operation Contexts":#CompleteOCL-OperationContextDecl if the parameter name is not used by any of the constraints.

The parameter name is required for "Operation Definitions":#CompleteOCL-Def.

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.

h4(#CompleteOCL-Body). Body

The Body syntax defines the body for a complemented Operation.

!{width:60%}images/1300-body.png(Complete OCL Body Syntax)!

The body keyword is followed by an optional name and the body "specification":#CompleteOCL-Specification.

The optional name is not used.

h4(#CompleteOCL-Post). Post

The Post syntax defines a postcondition for a complemented Operation.

!{width:60%}images/1300-post.png(Complete OCL Post Syntax)!

The post keyword is followed by an optional name and the postcondition "specification":#CompleteOCL-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.

h4(#CompleteOCL-Pre). Pre

The Pre syntax defines a precondition for a complemented Operation.

!{width:60%}images/1300-pre.png(Complete OCL Pre Syntax)!

The pre keyword is followed by an optional name and the precondition "specification":#CompleteOCL-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.

h4(#CompleteOCL-PropertyContextDecl). PropertyContextDecl

The PropertyContextDecl syntax identifies a Property to be complemented.

!{width:60%}images/1300-propertycontextdecl1.png(Complete OCL Property Context Decl Syntax Part 1)!

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.

!{width:60%}images/1300-propertycontextdecl2.png(Complete OCL Property Context Decl Syntax Part 2)!

Finally the property "type":#EssentialOCL-TypeExp and the property constraints are specified. The property constraints may comprise 
* an "Init":#CompleteOCL-Init to specify an initialization
* a "Der":#CompleteOCL-Der to specify a derivation

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.

h4(#CompleteOCL-Init). Init

The Init syntax defines an initial value for a complemented Property.

!{width:60%}images/1300-init.png(Complete OCL Init Syntax)!

The init keyword and colon are followed by the initial value "specification":#CompleteOCL-Specification.

h4(#CompleteOCL-Der). Der

The Der syntax defines a derived value for a complemented Property.

!{width:60%}images/1300-der.png(Complete OCL Der Syntax)!

The der keyword and colon are followed by the derived value "specification":#CompleteOCL-Specification.

h4(#CompleteOCL-Specification). Specification

The Specification syntax provides an OCL expression to specify some aspect of a complemented model.

!{width:60%}images/1300-specification.png(Complete OCL Specification Syntax)!

The specification comprises and "Essential OCL Expression":#EssentialOCL-Exp.

h4(#CompleteOCL-NavigatingExp). NavigatingExp

The NavigatingExp syntax defines enhancements to the "Essential OCL NavigatingExp":#EssentialOCL-NavigatingExp syntax.

!{width:60%}images/1300-navigatingexp.png(Complete 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.

!{width:60%}images/1300-navigatingarg.png(Complete OCL NavigatingArg Syntax)!

@?@ may be specified as the argument in a navigating expression to indicate unknown values when testing sent messages.

h4(#CompleteOCL-NavigationOperators). NavigationOperators

The "Essential OCL NavigationOperators":#EssentialOCL-NavigationOperators are extended to support
* @^@ to test whether a message has been sent message
* @^^@ to reference the content of a message

h4(#CompleteOCL-UnreservedName). UnreservedName

The Complete OCL reserved words are unchanged from Essential OCL, consequently a Complete OCL Unreserved name is the same as an "Essential OCL UnreservedName":#EssentialOCL-UnreservedName.

h4(#CompleteOCL-UnrestrictedName). UnrestrictedName

The Complete OCL has two additional built-in types: @OclMessage@ and @OclState@. These names and the "Essential OCL RestrictedNames":#EssentialOCL-UnrestrictedName are not available without qualification or escaping.