
h2(#DebuggerTutorial). Debugger tutorial

This tutorial has been updated for Eclipse Mars: Eclipse 4.5, EMF 2.11, OCL 6.0.
* Some screenshots may be slightly out of date.

In this tutorial we will continue the "OCLinEcore tutorial":#OCLinEcoreTutorial and show how to use the "OCL debugger":#Debugger to debug:
* constraints typed manually in the Console View
* embedded OCLinEcore validation failures from the Validity View
* Complete OCL validation failures from the Validity View

h3. Load OCLinEcore Tutorial Example Project

The material for the first two parts of this tutorial is available as part of the OCLinEcore Example project that you
may load by selecting *New* then *Example...* using the right button context menu of the Project Explorer. This
should give the *New Example* dialog in which you can select the *OCL (OCL Constraint Language) Plugins* and the *OCLinEcore Tutorial*.

The material for the third parts of this tutorial is available as part of the CompleteOCL Example project that you
may load in a similar way.

h3. The OCL Debugger

The OCL debugger is a customization of the Eclipse debugger framework, so most of its functionality should present few surprises to those familiar with the Java debugger.

There is:
* a Stack View that shows the current line number in nested Evaluation Environments
* a Variables View in which local and intermediate variables can be re-examined
* an Editor in which the source is highlighted to show the next AST node to be evaluated
* an Outline in which the source is shown in tree form
* a Breakpoints View in which breakpoints can be controlled

We will demonstrate some of these facilities by debugging a simple example.

h3. Very Simple Debug session

We will debug the execution of the OCL expression *self.name* on an EPackage.

h4. Starting the debugger

Double click on *model/Tutorial.ecore* to open the model and expand the top entry to show the EPackage.

!{width:70%}images/4500-simple-debugger-model.png(SimpleDebuggerModel)!

If the model opens with another editor, close it, and open with the Sample Ecore Editor by selecting *model/Tutorial.ecore* and then *Open With->Sample Ecore Model Editor* from the context menu.

Select the *tutorial* EPackage and invoke *OCL->Show Xtext OCL Console* from the context menu. (Wait a second or two.)

At the bottom of the Console window type *self.name*, then hit the Enter key. Then hit the Page Up key to redisplay your entry.

!{width:70%}images/4500-simple-debugger-input.png(SimpleDebuggerInput)!

The Console runs an evaluation automatically after hitting Enter and shows the evaluation result: *'tutorial'*.

The Console View provides the two pieces of information necessary to run the OCL debugger:
* an EObject to be used as OCL's *self*; the Console shows the current selection just below its tool bar
* an OCL expression to execute

Start the debugger by clicking the debug icon in the Console View tool bar. (Wait a second or two.)

The debugger perspective should appear automatically. If it doesn't, you can open the Debug perspective manually by invoking *Window->Perspective->Open Perspective->Debug* from the Eclipse menu bar.

!{width:50%}images/4500-simple-debugger-image.png(SimpleDebuggerImage)!

A Complete OCL document is created automatically to encapsulate the OCL expression inside as an additional operation for the type of the *self* object. This document is shown in the editor; it is readonly. 

The stack display shows the context as line 5 of *oclDebugExpression()* in the synthesized Complete OCL document.

Select the *oclDebugExpression()* line in the stack display; *self* is highlighted in the Complete OCL document, since the next evaluation to perform is to evaluate the VariableExp AST node that performs the self access.

The Variables View shows two variables.
* *self* is the OCL self object
* *$pc* is a synthetic variable representing the current Program Counter

The Outline View displays a slightly trimmed OCL Abstract Syntax tree; you may choose to close this view. In a future release it may change to support breakpoints. The view shows
* an *Import* for *ecore* 
* a *Class* named *EPackage* containing 
* an *Operation* named *oclDebugExpression* containing
* an *ExpressionInOCL* whose *OwnedBody* is a *PropertyCallExp* for *name* and whose source is
* a *VariableExp* for *self*.

The outline shows fuller type signatures to assist in debugging.

h4. Exploring Variables

The Variables View provides an ability to drill down arbitrarily to examine the data available to your program.

The left column of the display presents the name of a variable and may be expanded to navigate to parts of the data referenced by the variable. Part name displays are currently shown 0-based, rather than 1-based as in OCL. 

The right column variously displays the type of parts that can be expanded and the values of those that cannot. An OCL syntax is used so Strings appear in single quotes and Collections use names such as OrderedSet. 

The bottom line shows a textual rendering of the selected variable. For many types of data a helpful rendering is available. For others the fallback is to the default Java toString() functionality. The text can be customized by
* the *org.eclipse.ocl.pivot.utilities.getText()* method if the object implements *Labelable*
* the *LabelUtil.QUALIFIED_NAME_REGISTRY* if an *org.eclipse.ocl.pivot.label_generator* extension point has a registration for the objects' class

Click on the expand/collapse icon to the left of *$pc* to expand it and allow inspection of the OCL AST. A VariableExp is next to execute and its *$pc.referredProperty* or *$pc.type* may be examined to see more program detail.

Click on the expand/collapse icon to the left of *self*, which is an *ecore::EPackage*, to expand it and shows its fields such as *name* which is *'tutorial'*.

Click on the expand/collapse icon to the left of *self.eClassifiers* to show the four classifiers.

Select *self.eClassifiers[ 1 ]* so that the bottom line display shows that the second is named Book. 

!{width:50%}images/4500-simple-debugger-image.png(SimpleDebuggerVariables)!

The Variables View provides more insight that the Sample Ecore Properties View, so you may find it convenient to use a trivial OCL debugger session using *self* as the OCL expression to browse arbitrary model data.

h4. Stepping Execution

Click F5 or the *Step Into* icon to advance execution by one AST node evaluation.

!{width:50%}images/4500-simple-debugger-step1.png(SimpleDebuggerStep1)!

The editor now highlights *.name*; *$pc* shows a PropertCallExp as the next execution. *$pc.referredProperty* shows that it is *ecore::ENamedElement:name*.

An additional synthetic variable *$owwnedSource* shows the result of the *self* evaluation that forms the source term of the PropertyCallExp. As expected this is the same as *self*.

Click F5 or the *Step Into* icon again to advance execution by a further AST node evaluation.

!{width:50%}images/4500-simple-debugger-step2.png(SimpleDebuggerStep2)!

The whole of *self.name* is highlighted and *$pc* shows that the overall ExpressionInOCL is about to be evaluated. The synthetic *$ownedBody* for its input shows that *self.name* evaluated to *'tutorial'*.

h3. Debugging a Validation failure

OCL is useful for elaborating models with additional well-formedness rules, but when these fail it can be difficult to understand why a failure occurred, particularly if the bug is in the OCL rather than the model. We will now show how the OCL debugger can be used to debug a validation failure.

Double click on *model/Tutorial.xmi* to open the model, and expand the top two entries to show some detail.

!{width:70%}images/4500-validation-debugger-model.png(ValidationDebuggerModel)!

If the model opens with another editor, close it, and open with the Sample Reflective Ecore Model Editor by selecting *model/Tutorial.xmi* and then *Open With->Sample Reflective Ecore Model Editor* from the context menu.

Select the first line and invoke *Validate* from the context menu. (Wait a second.) Optionally click on Details.

!{width:70%}images/4500-validation-debugger-errors.png(ValidationDebuggerErrors)!

These error messages provide insufficient precision to really understand the problems, so click *OK* to dismiss the popup then select *Book b2*, which has an error, and invoke *OCL->Show Validity View* to provide more insight.

If the Validity View shows question marks rather than red/green/amber status decorations, Click the Run icon in the Validity View tool bar.

!{width:50%}images/4500-validation-debugger-vv1.png(ValidationDebuggerVV1)!

Click the *Pin* icon in the Validity View tool bar to avoid thrashing whenever you change mouse selection.

Uncheck the top *ecore* line in the Metamodel Constraints since we are not interested in the successful Ecore metamodel constraints just those in the *tutorial* metamodel.

Similarly uncheck the bottom *tutorial* line in the Model Elements since we are not interested in the successful metamodel, just those in the tutorial model.

Click on the + tool bar icon so that the detail is shown.

!{width:50%}images/4500-validation-debugger-vv2.png(ValidationDebuggerVV2)!

We will now debug the failure of the *tutorial::Book::SufficientCopies* on the *Library lib::Book b2* model element. Select either of the leaf warnings, that is either the *tutorial::Book::SufficientCopies* child of *Book b2* in the left hand pane, or the *Library lib::Book b2* child of *SufficientCopies* in the right hand pane, and invoke *Debug Single Enabled Selection*. Wait a second or two and the debugger starts. If it doesn't, open the Debugger perspective manually.

!{width:50%}images/4500-validation-debugger-image.png(ValidationDebuggerImage)!

Select the *oclDebuggerExpression()* stack line.
The debugger shows *library.loans->select((book = self))->size() <= copies* with *l* highlighted as the next execution. 
The outline shows that the *VariableExp* for *self* is next to execute. The *library* in the source code is a shorthand for *self.library*
so highlighting *l* is an approximation to highlighting the invisible *source.* in front of *library*.
*$pc* in the Variables View also shows a VariableExp for self as the next instruction.

Click F5 or *Step Into* and *$pc* advances and the editor highlight changes to *library*.

Click F5 or *Step Into* a few more times and the highlight will show the iteration within the *select* body, allowing each state of each element to be examined to determine why the exhibited behavior occurs.

Continue to Click F5 or *Step Into* until *->size()* is highlighted. 

!{width:40%}images/4500-validation-debugger-step1.png(ValidationDebuggerStep1)!

Expanding *$ownedSource* in the Variables View shows the Set of three selected Loans each of which has the same book as self.

 Click F5 or *Step Into* three more times until *<=* is highlighted. 

!{width:40%}images/4500-validation-debugger-step2.png(ValidationDebuggerStep2)!

We can now see that the *$ownedSource*, left hand side, of the comparison is 3 and the *$ownedArguments[==0==]* right hand side is 2.
A further step and we see the result as *$ownedBody* demonstrating why the validation failed.

h3. Debugging Complete OCL validation failure

The two preceding examples displayed their source text in a synthesized Complete OCL document.

In this example we debug a failure for which the OCL is already available in a Complete OCL document.

Open the *model/EcoreTestFile.ecore* from the "Complete OCL tutorial":#CompleteOCLTutorial project using the Sample Ecore Editor.

Within the Ecore editor use *OCL->Load Document* and then drag and drop *model/ExtraEcoreValidation.ocl* and click *OK* to dismiss the pop up.

Again within the Ecore editor use *OCL->Show Validity View* to see the constraint/element pairs. __If the Validity View was already visible, close it and re-show it since in Mars addition of a Complete OCL document fails to refresh correctly.__

In the Validity View, uncheck the *ecore* Metamodel Constraint contributions retaining just the *ExtraEcoreValidation.ocl* contribution. Click the plus icon in the *Metamodel Constraint* tool bar to expand all entries.

!{width:50%}images/4500-complete-ocl-debugger-model.png(CompleteOCLDebuggerModel)!

Select the bottom right *BadClass* model element below the *DerivationIsVolatile* constraint and invoke *Debug Single Enabled Selection*. from the context menu (wait a second or two). The debugger should start, if not open the Debugger perspective manually.

__In Mars, select the *DerivationIsVolatile* stack line to refresh the selection.__

!{width:40%}images/4500-complete-ocl-debugger-image.png(CompleteOCLDebuggerImage)!

Both *asError* and *hasDerivation* are OCL-defined so as you step you successively navigate into the defined property and operation.

h3. Console experiments

While debugging, the original OCL expression from the Console is presented in a Complete OCL editor. This editor is readonly so you cannot edit it to correct mistakes or to experiment.

You may however safely use the OCL Console to perform further experiments. Select a suitable self object in the Variable View and cut and paste to prepare your experimental OCL expression.

__In Mars, Console selections cannot be Collections so you are unfortunately restricted to single objects.__

h3. Longer range stepping

In the examples above we have only used F5 or *Step Into*.

In principle the tedious stepping through an iteration can be avoided by F7 or *Step Return* which should terminate on the popped evaluation environment at the end of the iteration. __This facility has not been adequately tested in Mars__.

If you arrange for some line breaks in your source text you can use F6 or *Step Next* to proceed until the line number advances. __This facility has not been adequately tested in Mars__. Line breaks can be added in the OCL Console using Shift and Enter together.

h3. Break points

When debugging OCL from Complete OCL documents, the original document is a suitable source for the debugger and so line breakpoints can be set. __This facility has not been adequately tested in Mars__
 

