# The OCLinEcore Language

Ecore Abstract Syntax supports the use of OCL embedded within EAnnotations.

The OCLinEcore language provides a textual Concrete Syntax that makes both Ecore and OCL accessible to users. Examples may be found in OCLinEcore Library Metamodel and OCLinEcore Helpers.

The OCLinEcore tooling provides a rich editing environment based on Xtext with strong semantic checking.

OCLinEcore is more than just an editor for OCL in Ecore, it is useful for

- providing a coherent textual view of an Ecore meta-model

- providing syntax sugar for some Ecore conventions

- editing and validating OCL

- integrating OCL into Ecore

It is planned to take the syntactic sugar further and provide full support for all class-related UML concepts. The language therefore uses UML as its point of reference wherever possible.

The OCLinEcore tooling may be used directly on *.ecore files, or on their *.oclinecore textual counterparts.

Please follow the OCLinEcore tutorial for an introduction to the language and its tooling.

### Syntax

The OCLinEcore syntax has a consistent structure influenced by the informal definitions in OMG specifications and by the Ecore hierarchy. Most Ecore concepts are represented by a syntax of the form:

- optional primary adjectives

- mandatory keyword

- mandatory name facet

- further facets

- an optional braced clause of secondary adjectives

- an optional braced clause of elements

  - composed elements

  - annotations

  - constraints

Thus in:

`abstract class Example extends Base { interface } { ... }
`

- `abstract` is a primary adjective

- `class` is a keyword

- `Example` is the name facet

- `extends Base` is a further facet

- `{ interface }` supports the secondary interface adjective.

- `{ ... }` provides a nested context for class content.

#### Grammar Implementation

The grammar used by the Xtext editors may be found at:

/src/org/eclipse/ocl/examples/xtext/oclinecore/OCLinEcore.xtext

in the org.eclipse.ocl.xtext.oclinecore plugin. The OCLinEcore grammar extends the Essential OCL grammar.

#### Module

The Module syntax supports the overall structure of an Ecore file

The definition of the module comprises

- optional module declaration

- optional specification of the OCL Standard libraries

- optional import of referenced Ecore or UML or OCLinEcore resources

- a hierarchy of Packages

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.

Zero or more external metamodels may be imported.

#### Package

The Package syntax supports a nested hierarchy of packages and classifiers

A Package has a name and optionally a namespace prefix and namespace URI.

The content of a Package may comprise Packages, Classifiers and Annotations.

#### Classifier

The Classifier syntax supports the definition of types within a Package.

A Classifier may be

- a Class

- a DataType

- an Enumeration with associated EnumerationLiterals

#### DataType

The DataType syntax supports the definition of an EDataType.

A DataType has a name and optionally template parameters and an instance class name.

A DataType may be serializable; by default it is not.

The content of a DataType may comprise invariants and Annotations.

#### Enumeration

The Enumeration syntax supports the definition of an EEnum.

An Enumeration has a name and optionally template parameters and an instance class name.

An Enumeration may be serializable; by default it is not.

The content of an Enumeration may comprise enumeration literals, invariants and Annotations.

#### EnumerationLiteral

The EnumerationLiteral syntax supports the definition of an EEnumLiteral.

An EnumerationLiteral has a name and optionally a value.

The content of an EnumerationLiteral may comprise Annotations.

#### Class

The Class syntax supports the definition of an EClass.

- optional abstract prefix

- optional extension of other classifiers

- optional invariants, annotations, features and operations

A Class may be abstract has a name and optionally template parameters.

(NB, the ‘abstract’ prefix is optional, even though the figure indicates that it is mandatory.)

A Class may extend one or more other Classes that may be specialized using the template parameters.

A Class may have an instance class name, and may also be declared to be an interface.

The content of a Class may comprise Annotations, Operations, StructuralFeatures and invariants.

#### StructuralFeature

The StructuralFeature syntax supports the definition of the StructuralFeatures.

A StructuralFeature may be

- an Attribute

- a Reference

#### Attribute

The Attribute syntax supports the definition of an EAttribute; a Property with a DataType value.

An Attribute may be static and has a name.

The `static` qualifier supports declaration of static properties which are supported by UML and OCL. Note that Ecore does not support static properties.

The `definition` qualifier is an obsolete experimental syntax for Complete OCL definitions.

An Attribute may may have a Type and multiplicity.

An Attribute may a simple initializer and a variety of qualifiers:

- `derived` specifies a derived attribute (default `!derived`)

- `id` specifies that the attribute provides the identifier if its class (default `!id`)

- `ordered` specifies that the attribute elements are ordered (default `!ordered`)

- `readonly` specifies that the attribute elements are readonly (not changeable) (default `!readonly`)

- `transient` specifies that the attribute elements are computed on the fly (default `!transient`)

- `unique` specifies that there are no duplicate attribute elements (default `unique`)

- `unsettable` specifies that attribute element may have no value (default `!unsettable`)

- `volatile` specifies that the attribute elements are not persisted (default `!volatile`)

The content of an Attribute may comprise Annotations, initial and derived constraints.

A simple constant value may be defined using the initializer. A computed value requires the use of a constraint. If both initial and derived constraints are present, the initial constraint is ignored.

The defaults for multiplicity lower and upper bound and for `ordered` and `unique` follow the UML specification and so corresponds to a single element Set that is `[1] {unique,!ordered}`. Note that UML defaults differ from the Ecore defaults which correspond to an optional element OrderedSet, that is `[?] {ordered,unique}`.

#### Reference

The Reference syntax supports the definition of an EReference; a Property with a Class value.

An Reference may be static and has a name and optionally an opposite name.

The `static` qualifier supports declaration of static properties which are supported by UML and OCL. Note that Ecore does not support static properties.

The `definition` qualifier is an obsolete experimental syntax for Complete OCL definitions.

A Reference may may have a Type and multiplicity.

A Reference may a simple initializer and a variety of qualifiers:

- `composes` specifies a composed (containing) reference (default `!composes`)

- `derived` specifies a derived reference (default `!derived`)

- `ordered` specifies that the reference elements are ordered (default `!ordered`)

- `readonly` specifies that the reference elements are readonly (not changeable) (default `!readonly`)

- `resolve` specifies that the reference elements proxies may need resolution (default `!resolve`)

- `transient` specifies that the reference elements are computed on the fly (default `!transient`)

- `unique` specifies that there are no duplicate reference elements (default `unique`)

- `unsettable` specifies that reference element may have no value (default `!unsettable`)

- `volatile` specifies that the reference elements are not persisted (default `!volatile`)

The content of a Reference may comprise keys, Annotations, initial and derived constraints.

A simple constant value may be defined using the initializer. A computed value requires the use of a constraint. If both initial and derived constraints are present, the initial constraint is ignored.

The defaults for multiplicity lower and upper bound and for `ordered` and `unique` follow the UML specification and so corresponds to a single element Set that is `[1] {unique,!ordered}`. Note that UML defaults differ from the Ecore defaults which correspond to an optional element OrderedSet, that is `[?] {ordered,unique}`.

#### Operation

The Operation syntax supports the definition of an EOperation.

An Operation may be static and has a name and optionally template parameters.

The `static` qualifier supports declaration of static operations which are supported by UML and OCL. Note that Ecore does not support static operations.

The `definition` qualifier is an obsolete experimental syntax for Complete OCL definitions.

An Operation has zero of more Parameters.

An Operation may have a return Type and multiplicity.

An Operation may declare zero or more throw Exceptions.

An Operation may have a variety of qualifiers:

- `derived` specifies a derived operation (default `!derived`)

- `ordered` specifies that the returned elements are ordered (default `!ordered`)

- `unique` specifies that there are no duplicate returned elements (default `unique`)

The content of an Operation may comprise Annotations, precondition, postcondition and body constraints.

The `static` qualifier supports declaration of static operations which are supported by UML and OCL. Note that Ecore does not support static operations.

The `definition` qualifier is an obsolete experimental syntax for Complete OCL definitions.

The defaults for multiplicity lower and upper bound and for `ordered` and `unique` follow the UML specification and so corresponds to a single element Set that is `[1] {unique,!ordered}`. Note that UML defaults differ from the Ecore defaults which correspond to an optional element OrderedSet, that is `[?] {ordered,unique}`.

#### Parameter

The Parameter syntax supports the definition of an EParameter.

A Parameter has a name, optional "Type:#OCLinEcore-TypeRef and multiplicity

A Parameter may have a variety of qualifiers:

- `ordered` specifies that the returned elements are ordered (default `!ordered`)

- `unique` specifies that there are no duplicate returned elements (default `unique`)

The content of a Parameter may comprise Annotations.

The defaults for multiplicity lower and upper bound and for `ordered` and `unique` follow the UML specification and so corresponds to a single element Set that is `[1] {unique,!ordered}`. Note that UML defaults differ from the Ecore defaults which correspond to an optional element OrderedSet, that is `[?] {ordered,unique}`.

#### Types

The Type syntax supports the definition of EType and EGenericType in conjunction with an ETypedElement. The syntax is very similar to Java.

PrimitiveTypeRefCS provides access to the built-in OCL types and their corrersponding Ecore counterparts

OCL type | Ecore type
--- | ---
Boolean | EBoolean
Integer | EBigInteger
Real | EBigDecimal
String | EString
UnlimitedNatural | EBigInteger

TypedTypeRefCS provides for user defined types and their template parameterisation.

#### AnnotationElement

The AnnotationElement syntax supports the definition of an EAnnotation hierarchy with details, references and contents.

An AnnotationElement may be Annotation or Documentation.

#### Annotation

The Annotation syntax supports the definition of an EAnnotation hierarchy with details, references and contents.

An Annotation has a source URI, which may be specified without quotes if the URI is just a name.

An Annotation may have Details.

The content of an Annotation may comprise

- Annotations

- content elements

- names that reference other elements

#### Detail

The Detail syntax supports the definition of a detail of an EAnnotation.

A detail comprises a detail key and optional value.

#### Documentation

The Documentation syntax is an experimental syntactic sugar for a genmodel annotation.

It is likely to be replaced by a Javadoc-style comment that will be persisted in Ecore.

#### Constraints

The Constraints syntax supports the embedding of OCL expressions as invariants for classes, as preconditions, postconditions or bodies for operations and initial or derived values for properties.

The integration occurs through the SpecificationCS rule that invokes an ExpCS. (The alternative UnquotedString is an implementation detail that supports the import from Ecore where the OCL is in unparsed textual form rather than an analyzed syntax tree.)

A class invariant may be `callable` to specify that the Ecore representation is to use the EOperation rather than EAnnotation representation.

A class invariant optionally supports a second OCL expression as a parenthesis on the invariant name. This parenthesized expression is invoked when an invariant fails in order to provide a user-defined failure message. Whether this message is an error or a warning is determined by the evaluation of the invariant:

#### Terminals

The OCLinEcore grammar extens the Esstial OCL grammar which should be consulted for definition of INT, and ExpCS.

#### Names

An Unrestricted name is any name other than the OCL reserved keywords. See UnrestrictedName.

An Unreserved name is any name other than the OCL reserved keywords above or the OCL reserved types. See UnreservedName.

If you need to use any of these names or non-alphanumeric names, you must use the escaped string syntax for a name: e.g. `_'true'`. The usual Java backslash escapes, with the exception of octal are supported: `_'new-lines\n\x0a\u000a'`

#### Comments

Single line comments are supported by ignoring all text following `--`.

Multi line comments are supported by ignoring all text within `/* ... */`.

Documentation comments are supported for all text within `/** ... */`. Unfortunately no documentation EAnnotation is currently created.

### Limitations

OCLinEcore supports the full capabilities of Ecore, however the support for upper and lower bounds on generic types has not been adequately tested.

OCLinEcore provides primary syntaxes for some Ecore conventions such as genmodel annotations and constraints; much more support is needed for feature maps.