blob: 96b0f6cf1a15f4adb83fed05b6e15b09d3dd7818 [file] [log] [blame]
<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&rsquo;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>