| |
| h2(#OCLinEcore). 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":#OCLinEcoreMetamodel and |
| "OCLinEcore Helpers":#OCLinEcoreTutorialHelpers. |
| |
| 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":#OCLinEcoreTutorial for an introduction to the language and its tooling. |
| |
| h3. 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: |
| |
| bc.. |
| abstract class Example extends Base { interface } { ... } |
| p. |
| |
| * @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. |
| |
| h4. 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.examples.xtext.oclinecore plugin. The OCLinEcore grammar extends the Essential OCL grammar. |
| |
| h4. Module |
| |
| The Module syntax supports the overall structure of an Ecore file |
| |
| !{width:60%}images/1200-rootpackage.png(OCLinEcore Root Package Syntax)! |
| |
| 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":#OCLinEcore-Package |
| |
| |
| !{width:60%}images/1200-library.png(OCLinEcore Library Import 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. |
| |
| !{width:60%}images/1200-import.png(OCLinEcore Metamodel Import Syntax)! |
| |
| Zero or more external metamodels may be imported. |
| |
| h4(#OCLinEcore-Package). Package |
| |
| The Package syntax supports a nested hierarchy of packages and classifiers |
| |
| !{width:60%}images/1200-package1.png(OCLinEcore Package Syntax Part 1)! |
| |
| A Package has a name and optionally a namespace prefix and namespace URI. |
| |
| !{width:60%}images/1200-package2.png(OCLinEcore Package Syntax Part 2)! |
| |
| The content of a Package may comprise "Packages":#OCLinEcore-Package, "Classifiers":#OCLinEcore-Classifier and "Annotations":#OCLinEcore-Annotation. |
| |
| h4(#OCLinEcore-Classifier). Classifier |
| |
| The Classifier syntax supports the definition of types within a "Package":#OCLinEcore-Package. |
| |
| !{width:60%}images/1200-classifiers.png(OCLinEcore Classifier Syntax)! |
| |
| A Classifier may be |
| * a "Class":#OCLinEcore-Class |
| * a "DataType":#OCLinEcore-DataType |
| * an "Enumeration":#OCLinEcore-Enumeration with associated "EnumerationLiterals":#OCLinEcore-EnumerationLiteral |
| |
| h4(#OCLinEcore-DataType). DataType |
| |
| The DataType syntax supports the definition of an EDataType. |
| |
| !{width:60%}images/1200-datatype1.png(OCLinEcore DataType Syntax Part 1)! |
| |
| A DataType has a name and optionally template parameters and an instance class name. |
| |
| !{width:60%}images/1200-datatype2.png(OCLinEcore DataType Syntax Part 2)! |
| |
| A DataType may be serializable; by default it is not. |
| |
| The content of a DataType may comprise "invariants":#OCLinEcore-Constraint and "Annotations":#OCLinEcore-Annotation. |
| |
| h4(#OCLinEcore-Enumeration). Enumeration |
| |
| The Enumeration syntax supports the definition of an EEnum. |
| |
| !{width:60%}images/1200-enumeration1.png(OCLinEcore Enumeration Syntax Part 1)! |
| |
| An Enumeration has a name and optionally template parameters and an instance class name. |
| |
| !{width:60%}images/1200-enumeration2.png(OCLinEcore Enumeration Syntax Part 2)! |
| |
| An Enumeration may be serializable; by default it is not. |
| |
| The content of an Enumeration may comprise enumeration literals, "invariants":#OCLinEcore-Constraint and "Annotations":#OCLinEcore-Annotation. |
| |
| h4(#OCLinEcore-EnumerationLiteral). EnumerationLiteral |
| |
| The EnumerationLiteral syntax supports the definition of an EEnumLiteral. |
| |
| !{width:60%}images/1200-enumerationliteral.png(OCLinEcore EnumerationLiteral Syntax)! |
| |
| An EnumerationLiteral has a name and optionally a value. |
| |
| The content of an EnumerationLiteral may comprise "Annotations":#OCLinEcore-Annotation. |
| |
| h4(#OCLinEcore-Class). Class |
| |
| The Class syntax supports the definition of an EClass. |
| * optional abstract prefix |
| * optional extension of other classifiers |
| * optional invariants, annotations, features and operations |
| |
| !{width:60%}images/1200-class1.png(OCLinEcore Class Syntax Part 1)! |
| |
| 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.) |
| |
| !{width:60%}images/1200-class2.png(OCLinEcore Class Syntax Part 2)! |
| |
| A Class may extend one or more other "Classes":#OCLinEcore-TypeRef that may be specialized using the template parameters. |
| |
| !{width:60%}images/1200-class3.png(OCLinEcore Class Syntax Part 3)! |
| |
| A Class may have an instance class name, and may also be declared to be an interface. |
| |
| !{width:60%}images/1200-class4.png(OCLinEcore Class Syntax Part 4)! |
| |
| The content of a Class may comprise "Annotations":#OCLinEcore-Annotation, "Operations":#OCLinEcore-Operation, "StructuralFeatures":#OCLinEcore-StructuralFeature and "invariants":#OCLinEcore-Constraint. |
| |
| h4(#OCLinEcore-StructuralFeature). StructuralFeature |
| |
| The StructuralFeature syntax supports the definition of the StructuralFeatures. |
| |
| !{width:60%}images/1200-features.png(OCLinEcore Feature Syntax)! |
| |
| A StructuralFeature may be |
| * an "Attribute":#OCLinEcore-Attribute |
| * a "Reference":#OCLinEcore-Reference |
| |
| h4(#OCLinEcore-Attribute). Attribute |
| |
| The Attribute syntax supports the definition of an EAttribute; a Property with a DataType value. |
| |
| !{width:60%}images/1200-attribute1.png(OCLinEcore Attribute Syntax Part 1)! |
| |
| 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. |
| |
| !{width:60%}images/1200-attribute2.png(OCLinEcore Attribute Syntax Part 2)! |
| |
| An Attribute may may have a "Type":#OCLinEcore-TypeRef and multiplicity. |
| |
| !{width:60%}images/1200-attribute3.png(OCLinEcore Attribute Syntax Part 3)! |
| |
| 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@) |
| |
| !{width:60%}images/1200-attribute4.png(OCLinEcore Attribute Syntax Part 4)! |
| |
| The content of an Attribute may comprise "Annotations":#OCLinEcore-Annotation, initial and derived "constraints":#OCLinEcore-Constraint. |
| |
| 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}@. |
| |
| h4(#OCLinEcore-Reference). Reference |
| |
| The Reference syntax supports the definition of an EReference; a Property with a Class value. |
| |
| !{width:60%}images/1200-reference1.png(OCLinEcore Reference Syntax Part 1)! |
| |
| 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. |
| |
| !{width:60%}images/1200-reference2.png(OCLinEcore Reference Syntax Part 2)! |
| |
| A Reference may may have a "Type":#OCLinEcore-TypeRef and multiplicity. |
| |
| !{width:60%}images/1200-reference3.png(OCLinEcore Reference Syntax Part 3)! |
| |
| 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@) |
| |
| !{width:60%}images/1200-reference4.png(OCLinEcore Reference Syntax Part 4)! |
| |
| The content of a Reference may comprise keys, "Annotations":#OCLinEcore-Annotation, initial and derived "constraints":#OCLinEcore-Constraint. |
| |
| 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}@. |
| |
| h4(#OCLinEcore-Operation). Operation |
| |
| The Operation syntax supports the definition of an EOperation. |
| |
| !{width:60%}images/1200-operation1.png(OCLinEcore Operation Syntax Part 1)! |
| |
| 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. |
| |
| !{width:60%}images/1200-operation2.png(OCLinEcore Operation Syntax Part 2)! |
| |
| An Operation has zero of more "Parameters":#OCLinEcore-Parameter. |
| |
| !{width:60%}images/1200-operation3.png(OCLinEcore Operation Syntax Part 3)! |
| |
| An Operation may have a return "Type":#OCLinEcore-TypeRef and multiplicity. |
| |
| !{width:60%}images/1200-operation4.png(OCLinEcore Operation Syntax Part 4)! |
| |
| An Operation may declare zero or more throw "Exceptions":#OCLinEcore-TypeRef. |
| |
| !{width:60%}images/1200-operation5.png(OCLinEcore Operation Syntax Part 5)! |
| |
| 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@) |
| |
| !{width:60%}images/1200-operation6.png(OCLinEcore Operation Syntax Part 6)! |
| |
| The content of an Operation may comprise "Annotations":#OCLinEcore-Annotation, precondition, postcondition and body "constraints":#OCLinEcore-Constraint. |
| |
| 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}@. |
| |
| h4(#OCLinEcore-Parameter). Parameter |
| |
| The Parameter syntax supports the definition of an EParameter. |
| |
| !{width:60%}images/1200-parameter1.png(OCLinEcore Parameter Syntax Part 1)! |
| |
| A Parameter has a name, optional "Type:#OCLinEcore-TypeRef and multiplicity |
| |
| !{width:60%}images/1200-parameter2.png(OCLinEcore Parameter Syntax Part 2)! |
| |
| 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":#OCLinEcore-Annotation. |
| |
| 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}@. |
| |
| h4(#OCLinEcore-TypeRef). Types |
| |
| The Type syntax supports the definition of EType and EGenericType in conjunction with an ETypedElement. The syntax is very similar to Java. |
| |
| !{width:60%}images/1200-types.png(OCLinEcore Type Syntax)! |
| |
| _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. |
| |
| h4(#OCLinEcore-Annotations). AnnotationElement |
| |
| The AnnotationElement syntax supports the definition of an EAnnotation hierarchy with details, references and contents. |
| |
| !{width:60%}images/1200-annotations.png(OCLinEcore Annotations Syntax)! |
| |
| An AnnotationElement may be "Annotation":#OCLinEcore-Annotation or "Documentation":#OCLinEcore-Documentation. |
| |
| h4(#OCLinEcore-Annotation). Annotation |
| |
| The Annotation syntax supports the definition of an EAnnotation hierarchy with details, references and contents. |
| |
| !{width:60%}images/1200-annotation1.png(OCLinEcore Annotations Syntax Part 1)! |
| |
| An Annotation has a source URI, which may be specified without quotes if the URI is just a name. |
| |
| !{width:60%}images/1200-annotation2.png(OCLinEcore Annotations Syntax Part 2)! |
| |
| An Annotation may have "Details":#OCLinEcore-Detail. |
| |
| !{width:60%}images/1200-annotation3.png(OCLinEcore Annotations Syntax Part 3)! |
| |
| The content of an Annotation may comprise |
| * "Annotations":#OCLinEcore-Annotation |
| * content elements |
| * names that reference other elements |
| |
| h4(#OCLinEcore-Detail). Detail |
| |
| The Detail syntax supports the definition of a detail of an EAnnotation. |
| |
| !{width:60%}images/1200-detail.png(OCLinEcore Detail Syntax)! |
| |
| A detail comprises a detail key and optional value. |
| |
| h4(#OCLinEcore-Documentation). Documentation |
| |
| The Documentation syntax is an experimental syntactic sugar for a genmodel annotation. |
| |
| !{width:60%}images/1200-annotations.png(OCLinEcore Annotations Syntax)! |
| |
| It is likely to be replaced by a Javadoc-style comment that will be persisted in Ecore. |
| |
| h4(#OCLinEcore-Constraint). 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. |
| |
| !{width:60%}images/1200-constraints.png(OCLinEcore Constraints Syntax)! |
| |
| The integration occurs through the _SpecificationCS_ rule that invokes an "ExpCS":#EssentialOCL-Exp. (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: |
| |
| |
| |
| h4. Terminals |
| |
| The OCLinEcore grammar extens the Esstial OCL grammar which should be consulted for definition of INT, and ExpCS. |
| |
| !{width:60%}images/1200-terminals.png(OCLinEcore Terminal Syntax)! |
| |
| h4. Names |
| |
| An Unrestricted name is any name other than the OCL reserved keywords. See "UnrestrictedName":#EssentialOCL-UnrestrictedName. |
| |
| An Unreserved name is any name other than the OCL reserved keywords above or the OCL reserved types. See "UnreservedName":#EssentialOCL-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'@ |
| |
| h4. 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. |
| |
| h3. 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. |
| |