doc/org.eclipse.ocl.doc/doc/0000-introduction.textile

h1. Overview and Getting Started

For a quick demonstration of OCL enrichment of an Ecore meta-model with computed constraints go to "Getting Started":#GettingStarted.

A PDF version of this documentation is available at "OCL 2021-03 (6.15.0) Documentation":http://download.eclipse.org/ocl/doc/6.15.0/ocl.pdf.

h2. What is OCL?

* _EMF is Modeled Structure_

The Eclipse Modeling Framework (EMF(Eclipse Modeling Framework)) supports the definition of structural meta-models and the subsequent use of models conforming to these meta-models. EMF also supports generating of Java code to represent the meta-models. Additional Java code can be provided to add behavior to the structural meta-models.

* _OCL is EMF and Modeled Behavior_

OCL(Object Constraint Language) provides a modeling language that allows the behavior to be embedded within the structural meta-models or provided as a complement to those meta-models. As a modeling language, OCL understands the models and so OCL code is much more compact than the equivalent Java. OCL code can be statically checked, whereas the corresponding Java code often uses reflection and so cannot be checked.  

Eclipse OCL is an implementation of the OMG OCL 2.4 specification for use with Ecore and UML meta-models.

h2. How Does It Work?

OCL is a programming language, so you will want to edit it, execute it and debug it.

h3. Editing

Eclipse OCL supports entry of semantically checked OCL expressions
* embedded within Ecore using the "OCLinEcore":#OCLinEcore editor
* as complementary documents using the "Complete OCL":#CompleteOCL editor
* interactive entry and evaluation using the "Interactive OCL":#InteractiveOCL console.
* programmatic entry and evaluation using the "Java API":#ProgrammersGuide

EMF supports entry of unchecked OCL
* embedded within Ecore using the Sample Ecore Editor properties view

Eclipse UML supports entry of unchecked OCL
* embedded within UML OpaqueExpressions using the UML Model Editor properties view

"Papyrus":#OCLinPapyrus supports entry of semantically checked OCL expressions
* embedded within UML OpaqueExpressions using the "Essential OCL":#EssentialOCL editor

h3. Execution

Eclipse OCL supports OCL execution
* interactive entry and evaluation using the "Interactive OCL":#InteractiveOCL console.
* programmatic entry and evaluation using the "Java API":#ProgrammersGuide

EMF support for generated models enables OCL execution of
* constraints, operation bodies and property initializers using the "Java API":#ProgrammersGuide

EMF support for dynamic models enables OCL execution of
* constraints using the "Validation Delegate":#ValidationDelegate API 
* operation bodies using the "Invocation Delegate":#InvocationDelegate API 
* property initializers using the "Setting Delegate":#SettingDelegate API 
* queries using the "Query Delegate":#QueryDelegate API 

All OCL execution is normally interpreted and starts from the OCL source text (Concrete Syntax). There is therefore a first time parsing overhead to create the compiled form (Abstract Syntax). The compiled form is cached to avoid repeated parsing costs. 

Altenatively the direct Java code generator may be used as described in the "Code Generator Tutorial":#CodeGenerationTutorial.

h3. Debugging

Since OCL is used embedded in a larger environment, debugging is not easy to provide for OCL in isolation. The "OCL debugger":#Debugger provides a variety of launch mechanisms that enable re-use of model element and/or constraint selections.

Alternatively the following approaches may be useful within other toosl

* use the hover-text in the semantic editor to understand the expression types
* use the quick-fixes in the semantic editor for possible corrections
** if the same fix is suggested more than once, try restarting the editor
* use the completion assist in the semantic editor for possible syntaxes
* use intermediate invariants to check partial results
* use the optional explanation messages for an invariant to provide a 'printf'
* use the "Interactive Xtext OCL":#InteractiveOCL console to practice a problematic expression on a model

h3. Testing

Once again, since OCL is used embedded in a larger environment, testing is not easy to provide for OCL in isolation. The following approaches may be useful.

* use the "Interactive Xtext OCL":#InteractiveOCL console to practice sub-expressions of a problematic expression on a model

The Eclipse OCL development uses an extended JUnit framework that allows the Eclipse OCL code to be tested by assertions such as:

bc. 
assertQueryInvalid(null, "let b : Boolean = null in true and b");
assertQueryResults(null, "Set{'b'}", "Set{'a', 'b', 'c'} - Set{'c', 'a'}");

(The null first argument may be a context object.)

See the org.eclipse.ocl.xtext.tests plugin for further details.

h2. Eclipse OCL is Extensible

The Classic Eclipse OCL is used as a component in a variety of other Eclipse projects such as Acceleo, BIRT, GMF, Modisco, QVTo. Ecore models are used directly, which leads to some internal difficulties.

The new Unified Eclipse OCL exploits Xtext and uses Ecore models indirectly via a UML-aligned Pivot models. This provides a choice between the classic APIs that offer limited forward functionality, and the new APIs that some of which are promoted to non-experimental form in the Mars release. Many remain experimental and internal.

The new code already offers a fully modeled Standard Library that can be extended or replaced. The new OCL grammars are extended internally from Essential OCL to OCLinEcore or Complete OCL, and externally to QVT Core and QVT Relational. The associated Concrete Syntax to Abstract Syntax mapping is not yet model-driven and so harder to extend.

Full model-driven extensibility is planned for a future release.

h2. Who Uses OCL and Eclipse OCL?

The OCL specification is defined by the OMG(Object Management Group). It originally evolved as part of UML(Unified Modeling Language) where it is used for the detailed mathematical aspects that are not appropriate for graphical exposition. OCL 2.0 was split off from UML 2.0 in recognition of its greater utility.

Within the OMG context, OCL has been re-used as the foundation for the MOFM2T(Model to Text) Model-to-Text transformation language and the QVT(Query View Transformation) Model-to-Model transformation language. Eclipse implementations of these are available as the Acceleo and QVT Operational projects.

Eclipse OCL is an implementation of the OCL specification for use in conjunction with EMF and in particular Ecore and UML2 meta-models. As the behavioral extension for EMF, Eclipse OCL can be used wherever EMF can.

As a specification language, OCL is frequently used when the behavior of models is formally specified.

The use of OCL as an execution language has been hindered by the quality of tool support. Beyond the research domain, many usages have been proprietary. One advanced proprietary usage at SAP has been contributed to Eclipse OCL and is available as the "Impact Analyzer":#ImpactAnalyzer. This supports strategic planning of run-time notifications so that derived model properties can be updated efficiently in response to a change to a model. Thousand-fold speed improvements are achievable on large models using OCL rather than Java because OCL has a formal model-based semantics that is amenable to analysis.

The use of OCL in general is eased by the provision of good editors exploiting Xtext to provide comprehensive semantic feedback in a familiar editing style.

The use of OCL for execution is enhanced by providing direct Java code generation for OCL embedded in models. This should alleviate many of the performance concerns for interpreted execution of embedded OCL.

Debugging of OCL execution is now possible using the OCL debugger and the OCL Console can be used for OCL experimentation.

h2. Who is Behind Eclipse OCL?

Eclipse OCL is an Open Source project. The original code for OCL 1.x was contributed by IBM. It has evolved to support OCL 2.x under the auspices of Eclipse.

There is now a significant personnel and corporate overlap between the Eclipse OCL committers and the OMG OCL RTF(Revision Task Force) and so Eclipse OCL is pioneering solutions to many of the under-specification problems in the OCL specification.

You can expect future changes in OMG OCL to have an implementation in Eclipse OCL to demonstrate their viability. It is likely that the next version of the OCL specification will use Eclipse OCL and M2T(Model to Text) tooling to eliminate inconsistencies. Eclipse OCL is currently in use to check that the OCL used in the UML 2.5 specification is syntactically and semantically correct.

Direct tooling of the UML 2.5 and OCL 2.5 specifications for a future Eclipse release may demonstrate that the OCL aspects of the specifications is also functionally consistent.
 
h2(#GettingStarted). Getting Started

For a very quick demonstration of OCL, you may follow this very abbreviated version of the "OCLinEcore tutorial":#OCLinEcoreTutorial, where you can find "Installation":#Installation instructions. Once you have the OCL Examples and Editors feature installed you may follow these instructions to get an insight into the capabilities of OCL and the Eclipse OCL tooling.

Invoke *File->New->Project...* then select *Examples* then *OCL (Object Constraint Language) Plugins* then *OCLinEcore Tutorial* and *Finish* to create a small example project called *org.eclipse.ocl.examples.project.oclinecoretutorial*. It contains
* *model/Tutorial.ecore* - a small Library meta-model
* *model/Tutorial.xmi* - an even smaller Library model
* *model/Tutorial.genmodel* - a gebnerator for Java code

Select *model/Tutorial.ecore* and use the right button to invoke *Open With->OCLinEcore Editor*. This gives you a textual view of the Ecore file with embedded OCL invariants such as the Book constraint

bc.. 
invariant SufficientCopies:
  library.loans->select((book = self))->size() <= copies;
p. 

This invariant is named SufficientCopies. It 
* navigates from the implicit self (a Book)
* via the library 
* to its loans which it searches
* to select those loans that satisfy the predicate
** loaned book is equal to the self Book
* the size (number) of loans is computed
* and compared to the number of copies of the self Book

The invariant is satisfied if it evaluates true; i.e. if the number of loans is less than or equal to the number of copies.

You can see this invariant at work, by selecting *model/Tutorial.xmi* and using the right button to invoke *Open With->Sample Reflective Ecore Model Editor*. This gives you a tree view of a small library model.

Expand the root element and then select the *Library lib* element and use the right button menu to invoke *Validate*. You should get a pop-up reporting problems during Validation. Click *Details* and you will see that one of the problems is with the *SufficientCopies* invariant we have just looked at. If you browse the Properties View for *model/Tutorial.xmi*, you can verify that there are three loans but only two copies for the offending Book.

You may evaluate custom OCL queries interactively. From the editor for *Tutorial.xmi*, invoke *OCL->Show Xtext OCL Console* from the context menu. Select *Book b2* in the editor, then in the bottom line of the console enter the OCL expression *loans.member* and then Enter. The results are shown in the panel and identify that all three loans are by *Member m3*.

The expression *loans.member* is an abbreviated form of *self.loans->collect(aLoan : Loan | aLoan.member)* and demonstrates OCL's ability to perform many useful navigations over multi-element properties. The expression
* navigates from self, the Book b2 selection
* to its loans, using Book::loans which is a derived property defined in OCL
* for each of the loans, the iterator variable, aLoan, is assigned to the loan and
** the body, aLoan.member is evaluated to return the member making the loan
* the resulting members are collected to return a collection result
* the result is displayed on three lines in the results panel

You can step through execution using the OCL debugger. In the Console View type PageUp to restore the earlier text entry, then with *Book b2* still selected in the editor, click the debug icon in the Console tool bar. The debugger should open automatically, but if it doesn't, use *Window->Show View->Debug* from the Eclipse menu bar. The Variables View shows model elemnt values. Click F5 or Step Into a few times to progress execution.

You have now seen
* an Xtext editor that embeds OCL directly in Ecore models to provide programmed enrichment
* execution of OCL while validating a model using conventional Ecore tooling
* an interactive Console for custom OCL evaluations
* execution of a derived property defined in OCL
* the ability of OCL to express operations on multi-elements compactly
* the ability to debug OCL execution and browse data

You have not
* written any Java code
* generated any plugins
* needed to start an additional Eclipse session

Please follow the tutorials, examples and reference material for further information.