
h2(#PivotParsingConstraints). Parsing Constraints and Queries

This section may be contrasted with the corresponding "Parsing Constraints and Queries":#ParsingConstraints for the Ecore binding to see examples of the changes needed to migrate from the Ecore binding to the Pivot binding.

The OCL parser provides two APIs for parsing constraint and query expressions using the "@OCL@":http://download.eclipse.org/ocl/javadoc/6.3.0/org/eclipse/ocl/pivot/utilities/OCL.html Facade.

h3. The OCL Facade

The "@OCL@":http://download.eclipse.org/ocl/javadoc/6.3.0/org/eclipse/ocl/pivot/utilities/OCL.html class provides both a Facade and a Handle for the various objects that support different aspects of OCL parsing and evaluation.

!{width:60%}images/6310-environment.png(Core OCL Environment API)!

The @OCL@ class is a simple type.

bq.. 
There is no need for the many template parameters that parameterize the equivalent OCL class for the Ecore/UML bindings.
p. 

Behind the scenes, @OCL@ instances share an @EnvironmentFactory@ that creates and owns the primary support objects and provides an API to create these and other important artefacts.

The @ProjectManager@ supports the discovery of metamodels to resolve URI references.
* @OCL.NO_PROJECTS@ is a very lightweight @ProjectManager@ supporting access only to those models known to the ==external==@ResourceSet@. 
* @OCL.CLASS_PATH@ is a heavyweight @ProjectManager@ supporting access to models registered with plugins on the Java classpath. 

The ==external==@ResourceSet@ is a potentially user-supplied @ResourceSet@ to manage the external metamodels such as Ecore or UML models or Xtext Concrete Syntax models.

The external metamodels are converted to the normalized Pivot representation under control of the @MetamodelManager@ which maintains the normalized representation in an Abstract Syntax ==as==@ResourceSet@.

A merged view of the normalized metamodels is provided by the @CompleteModel@  under control of the @CompleteEnvironment@ that also supervises a @StandardLibrary@, @TupleManager@ and @LambdaManager@ for more specialized aspects of the merge. The @CompleteEnvironment@ API supports synthesis of Collection and Map types.

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 *Boolean* type from the minimal concept of a *Boolean* type-id. The @IdResolver@ performs the id-to-object conversion.

When Pivot models are derived from Xtext source text, a Concrete Syntax representation is converted to the normalized Abstract Syntax. The @CS2ASMapping@ 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.

The @OCL@ handle may also reference a @ModelManager@. This is used to identify objects during evaluation of operations such as @allInstnaces()@.

h3. OCL Handles

The static factory methods of the @OCL@ 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.

If you already have models loaded in a @ResourceSet@, you may activate OCL functionality by creating a new @OCL@ instance specifying that OCL should exploit that ResourceSet.

!{width:70%}images/6310-creating-external.png(Creating the OCL with an External ResourceSet)!
"[Text for cut and paste]":../references/6310-creating-external.txt

Alternatively you may leave the @OCL@ instance to create the @ResourceSet@.

!{width:70%}images/6310-creating-internal.png(Creating the OCL with an Internal ResourceSet)!
"[Text for cut and paste]":../references/6310-creating-internal.txt

It is good practice to invoke @dispose()@ explicitly to release all
OCL-related Resource references promptly rather than rely on garbage collection.

!{width:70%}images/6310-dispose.png(Disposing the OCL)!
"[Text for cut and paste]":../references/6310-dispose.txt

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
@OCL@ instance directly. In more complex scenarios the handle behavior of an @OCL@ 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.

h3. Class Context

Parsing an OCL expression requires a classifier to define the type of @self@. This is passed to 
@createInvariant()@, which enforces a Boolean result type, or to @createQuery()@, which allows any result type.

The result of parsing a query expression or a constraint is an
"@ExpressionInOCL@":http://download.eclipse.org/ocl/javadoc/6.3.0/org/eclipse/ocl/pivot/ExpressionInOCL.html,
an instance of the "Abstract Syntax Model":#AbstractSyntax.

!{width:70%}images/6310-context.png(The OCL Context)!
"[Text for cut and paste]":../references/6310-context.txt

h3. Operation and Property Contexts

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 @self@ while parsing the OCL. The classifier is deduced as the
container of the operation or property. These can be constrained as follows:

!{width:70%}images/6310-define.png(Defining a constraint)!
"[Text for cut and paste]":../references/6310-define.txt

h3. Errors

The preceding examples are simplified by the assumption that there will be no parsing errors. In practice @ParserException@==s== should be caught and handled in an appropriate way by the application.

!{width:70%}images/6310-errors.png(Handling errors)!
"[Text for cut and paste]":../references/6310-errors.txt

h3. The OCL Helper

bq.. 
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 @OCL@ class class be used directly. An @OCLHelper@ will give a small performance benefit
for multiple parses but not as much as direct use of an underlying @ParserContext@ or a structuring
multiple queries in a Complete OCL document.

From an OCL instance, we can create a helper object with which to parse constraints
and additional operation/attribute definitions.

!{width:60%}images/6310-oclhelper.png(OCL Parsing Helper API)! 

The @OCLHelper@ is primarily designed for parsing
constraints and query expressions embedded in models, providing the following
API for that purpose:

* @createQuery()@: parses a query expression

* @createConstraint()@: parses a constraint of a given @ConstraintKind@

* @createInvariant()@: convenience for invariant constraints

* @createPrecondition()@: convenience for pre-condition constraints

* @createPostcondition()@: convenience for post-condition constraints

* @createBodyCondition()@: convenience for body conditions

* @createDerivedValueExpression()@: convenience for attribute derived values

Different kinds of constraints require different context environments.  The
@setContext()@, @setOperationContext()@,
and @setAttributeContext()@ methods create the appropriate
nested @Environment@ s in the host @OCL@
instance's root environment.

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. 

