<html> | |
<head> | |
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
<title>Parsing Constraints and Queries</title> | |
<link href="book.css" rel="stylesheet" type="text/css"> | |
<meta content="DocBook XSL Stylesheets V1.75.1" name="generator"> | |
<link rel="home" href="index.html" title="OCL Documentation"> | |
<link rel="up" href="PivotProgrammersGuide.html" title="Unified or Pivot Programmers Guide"> | |
<link rel="prev" href="PivotThreadSafety.html" title="Pivot Thread Safety"> | |
<link rel="next" href="PivotEvaluatingConstraints.html" title="Evaluating Constraints and Queries"> | |
</head> | |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> | |
<h1 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">Parsing Constraints and Queries</h1> | |
<div class="section" title="Parsing Constraints and Queries"> | |
<div class="titlepage"> | |
<div> | |
<div> | |
<h2 class="title" style="clear: both"> | |
<a name="PivotParsingConstraints"></a>Parsing Constraints and Queries</h2> | |
</div> | |
</div> | |
</div> | |
<p>This section may be contrasted with the corresponding | |
<a class="link" href="ProgrammersGuide.html#ParsingConstraints" title="Parsing Constraints and Queries">Parsing Constraints and Queries</a> for the Ecore binding to see examples of the changes needed to migrate from the Ecore binding to the Pivot binding. | |
</p> | |
<p>The OCL parser provides two APIs for parsing constraint and query expressions using the | |
<a class="ulink" href="http://download.eclipse.org/ocl/javadoc/6.3.0/org/eclipse/ocl/pivot/utilities/OCL.html" target="_new"> | |
<code class="code">OCL</code> | |
</a> Facade. | |
</p> | |
<div class="section" title="The OCL Facade"> | |
<div class="titlepage"> | |
<div> | |
<div> | |
<h3 class="title"> | |
<a name="TheOCLFacade2"></a>The OCL Facade</h3> | |
</div> | |
</div> | |
</div> | |
<p>The | |
<a class="ulink" href="http://download.eclipse.org/ocl/javadoc/6.3.0/org/eclipse/ocl/pivot/utilities/OCL.html" target="_new"> | |
<code class="code">OCL</code> | |
</a> class provides both a Facade and a Handle for the various objects that support different aspects of OCL parsing and evaluation. | |
</p> | |
<p> | |
</p> | |
<div class="mediaobject"> | |
<img src="images/6310-environment.png"></div> | |
<p> | |
</p> | |
<p>The | |
<code class="code">OCL</code> class is a simple type. | |
</p> | |
<div class="blockquote"> | |
<blockquote class="blockquote"> | |
<p> | |
There is no need for the many template parameters that parameterize the equivalent OCL class for the Ecore/UML bindings.</p> | |
</blockquote> | |
</div> | |
<p></p> | |
<p>Behind the scenes, | |
<code class="code">OCL</code> instances share an | |
<code class="code">EnvironmentFactory</code> that creates and owns the primary support objects and provides an API to create these and other important artefacts. | |
</p> | |
<p>The | |
<code class="code">ProjectManager</code> supports the discovery of metamodels to resolve URI references. | |
</p> | |
<div class="itemizedlist"> | |
<ul class="itemizedlist" type="disc"> | |
<li class="listitem"> | |
<p> | |
<code class="code">OCL.NO_PROJECTS</code> is a very lightweight | |
<code class="code">ProjectManager</code> supporting access only to those models known to the external | |
<code class="code">ResourceSet</code>. | |
</p> | |
</li> | |
<li class="listitem"> | |
<p> | |
<code class="code">OCL.CLASS_PATH</code> is a heavyweight | |
<code class="code">ProjectManager</code> supporting access to models registered with plugins on the Java classpath. | |
</p> | |
</li> | |
</ul> | |
</div> | |
<p>The external | |
<code class="code">ResourceSet</code> is a potentially user-supplied | |
<code class="code">ResourceSet</code> to manage the external metamodels such as Ecore or UML models or Xtext Concrete Syntax models. | |
</p> | |
<p>The external metamodels are converted to the normalized Pivot representation under control of the | |
<code class="code">MetamodelManager</code> which maintains the normalized representation in an Abstract Syntax as | |
<code class="code">ResourceSet</code>. | |
</p> | |
<p>A merged view of the normalized metamodels is provided by the | |
<code class="code">CompleteModel</code> under control of the | |
<code class="code">CompleteEnvironment</code> that also supervises a | |
<code class="code">StandardLibrary</code>, | |
<code class="code">TupleManager</code> and | |
<code class="code">LambdaManager</code> for more specialized aspects of the merge. The | |
<code class="code">CompleteEnvironment</code> API supports synthesis of Collection and Map types. | |
</p> | |
<p>Access to the normalized representations from diverse contexts, in particular from generated Java code, requires an ability to discover the merged representation of e.g. the | |
<span class="bold"><strong>Boolean</strong></span> type from the minimal concept of a | |
<span class="bold"><strong>Boolean</strong></span> type-id. The | |
<code class="code">IdResolver</code> performs the id-to-object conversion. | |
</p> | |
<p>When Pivot models are derived from Xtext source text, a Concrete Syntax representation is converted to the normalized Abstract Syntax. The | |
<code class="code">CS2ASMapping</code> tracks the equivalences in this conversion so that tooling can reverse the navigation to discover appropriate text to highlight in a source editor for an underlying model element. | |
</p> | |
<p>The | |
<code class="code">OCL</code> handle may also reference a | |
<code class="code">ModelManager</code>. This is used to identify objects during evaluation of operations such as | |
<code class="code">allInstnaces()</code>. | |
</p> | |
</div> | |
<div class="section" title="OCL Handles"> | |
<div class="titlepage"> | |
<div> | |
<div> | |
<h3 class="title"> | |
<a name="OCLHandles"></a>OCL Handles</h3> | |
</div> | |
</div> | |
</div> | |
<p>The static factory methods of the | |
<code class="code">OCL</code> class are used to create new instances. These are suitable for suitable for parsing OCL constraints | |
on any Ecore or UML model and evaluating them on instances of the model. | |
</p> | |
<p>If you already have models loaded in a | |
<code class="code">ResourceSet</code>, you may activate OCL functionality by creating a new | |
<code class="code">OCL</code> instance specifying that OCL should exploit that ResourceSet. | |
</p> | |
<p> | |
</p> | |
<div class="mediaobject"> | |
<img src="images/6310-creating-external.png"></div> | |
<p> | |
<a class="ulink" href="../references/6310-creating-external.txt" target="_new">[Text for cut and paste]</a> | |
</p> | |
<p>Alternatively you may leave the | |
<code class="code">OCL</code> instance to create the | |
<code class="code">ResourceSet</code>. | |
</p> | |
<p> | |
</p> | |
<div class="mediaobject"> | |
<img src="images/6310-creating-internal.png"></div> | |
<p> | |
<a class="ulink" href="../references/6310-creating-internal.txt" target="_new">[Text for cut and paste]</a> | |
</p> | |
<p>It is good practice to invoke | |
<code class="code">dispose()</code> explicitly to release all | |
OCL-related Resource references promptly rather than rely on garbage collection. | |
</p> | |
<p> | |
</p> | |
<div class="mediaobject"> | |
<img src="images/6310-dispose.png"></div> | |
<p> | |
<a class="ulink" href="../references/6310-dispose.txt" target="_new">[Text for cut and paste]</a> | |
</p> | |
<p>When repeated parsing and evaluation occurs on a model, it is very beneficial to re-use rather than | |
re-create the underyling OCL support objects. This is easily achieved in simple scenarios by re-using the | |
<code class="code">OCL</code> instance directly. In more complex scenarios the handle behavior of an | |
<code class="code">OCL</code> instance can be exploited | |
to create multiple handles for diverse usages each of which is disposed when complete. The dispose of the | |
underlying OCL support occurs when the final handle disposes. | |
</p> | |
</div> | |
<div class="section" title="Class Context"> | |
<div class="titlepage"> | |
<div> | |
<div> | |
<h3 class="title"> | |
<a name="ClassContext"></a>Class Context</h3> | |
</div> | |
</div> | |
</div> | |
<p>Parsing an OCL expression requires a classifier to define the type of | |
<code class="code">self</code>. This is passed to | |
<code class="code">createInvariant()</code>, which enforces a Boolean result type, or to | |
<code class="code">createQuery()</code>, which allows any result type. | |
</p> | |
<p>The result of parsing a query expression or a constraint is an | |
<a class="ulink" href="http://download.eclipse.org/ocl/javadoc/6.3.0/org/eclipse/ocl/pivot/ExpressionInOCL.html" target="_new"> | |
<code class="code">ExpressionInOCL</code> | |
</a>, | |
an instance of the | |
<a class="link" href="AbstractSyntax.html" title="OCL Abstract Syntax Model">Abstract Syntax Model</a>. | |
</p> | |
<p> | |
</p> | |
<div class="mediaobject"> | |
<img src="images/6310-context.png"></div> | |
<p> | |
<a class="ulink" href="../references/6310-context.txt" target="_new">[Text for cut and paste]</a> | |
</p> | |
</div> | |
<div class="section" title="Operation and Property Contexts"> | |
<div class="titlepage"> | |
<div> | |
<div> | |
<h3 class="title"> | |
<a name="OperationandPropertyContexts"></a>Operation and Property Contexts</h3> | |
</div> | |
</div> | |
</div> | |
<p>In the case of constraints on operations or properties, the context consists | |
of two elements: the constrained operation/property and a classifier that | |
defines the type of | |
<code class="code">self</code> while parsing the OCL. The classifier is deduced as the | |
container of the operation or property. These can be constrained as follows: | |
</p> | |
<p> | |
</p> | |
<div class="mediaobject"> | |
<img src="images/6310-define.png"></div> | |
<p> | |
<a class="ulink" href="../references/6310-define.txt" target="_new">[Text for cut and paste]</a> | |
</p> | |
</div> | |
<div class="section" title="Errors"> | |
<div class="titlepage"> | |
<div> | |
<div> | |
<h3 class="title"> | |
<a name="Errors"></a>Errors</h3> | |
</div> | |
</div> | |
</div> | |
<p>The preceding examples are simplified by the assumption that there will be no parsing errors. In practice | |
<code class="code">ParserException</code>s should be caught and handled in an appropriate way by the application. | |
</p> | |
<p> | |
</p> | |
<div class="mediaobject"> | |
<img src="images/6310-errors.png"></div> | |
<p> | |
<a class="ulink" href="../references/6310-errors.txt" target="_new">[Text for cut and paste]</a> | |
</p> | |
</div> | |
<div class="section" title="The OCL Helper"> | |
<div class="titlepage"> | |
<div> | |
<div> | |
<h3 class="title"> | |
<a name="TheOCLHelper2"></a>The OCL Helper</h3> | |
</div> | |
</div> | |
</div> | |
<div class="blockquote"> | |
<blockquote class="blockquote"> | |
<p> | |
The Ecore/UML bindings for OCL provide an OCLHelper class to assist in creating queries. A similar | |
class is available with the Pivot binding for compatibility although it is largely redundant since | |
the | |
<code class="code">OCL</code> class class be used directly. An | |
<code class="code">OCLHelper</code> will give a small performance benefit | |
for multiple parses but not as much as direct use of an underlying | |
<code class="code">ParserContext</code> or a structuring | |
multiple queries in a Complete OCL document. | |
</p> | |
<p>From an OCL instance, we can create a helper object with which to parse constraints | |
and additional operation/attribute definitions.</p> | |
<p> | |
</p> | |
<div class="mediaobject"> | |
<img src="images/6310-oclhelper.png"></div> | |
<p> | |
</p> | |
<p>The | |
<code class="code">OCLHelper</code> is primarily designed for parsing | |
constraints and query expressions embedded in models, providing the following | |
API for that purpose: | |
</p> | |
<p>* | |
<code class="code">createQuery()</code>: parses a query expression | |
</p> | |
<p>* | |
<code class="code">createConstraint()</code>: parses a constraint of a given | |
<code class="code">ConstraintKind</code> | |
</p> | |
<p>* | |
<code class="code">createInvariant()</code>: convenience for invariant constraints | |
</p> | |
<p>* | |
<code class="code">createPrecondition()</code>: convenience for pre-condition constraints | |
</p> | |
<p>* | |
<code class="code">createPostcondition()</code>: convenience for post-condition constraints | |
</p> | |
<p>* | |
<code class="code">createBodyCondition()</code>: convenience for body conditions | |
</p> | |
<p>* | |
<code class="code">createDerivedValueExpression()</code>: convenience for attribute derived values | |
</p> | |
<p>Different kinds of constraints require different context environments. The | |
<code class="code">setContext()</code>, | |
<code class="code">setOperationContext()</code>, | |
and | |
<code class="code">setAttributeContext()</code> methods create the appropriate | |
nested | |
<code class="code">Environment</code> s in the host | |
<code class="code">OCL</code> | |
instance’s root environment. | |
</p> | |
<p>The Ecore/UML bindings variously produce a Constraint or OCLExpression result. A Constraint has too much context and an OCLExpression too little. An ExpressionInOCL produced by the Pivot binding is just right.</p> | |
</blockquote> | |
</div> | |
<p></p> | |
</div> | |
</div> | |
</body> | |
</html> |