doc/org.eclipse.ocl.doc/doc/6315-pivot-evaluating-constraints.textile

h2(#PivotEvaluatingConstraints). Evaluating Constraints and Queries

In "Parsing Constraints":#PivotParsingConstraints, we saw how to use
the @OCLHelper@ API for parsing OCL constraints and
query expressions.  Parsing constraints is very interesting in itself, but
we can also make OCL come alive in our applications by evaluating these
constraints.  For this, OCL provides a @Query@ API.

h3. The OCL Query

Like the @OCLHelper@ for parsing constraints, the OCL
facade object provides
"@Query@":http://download.eclipse.org/ocl/javadoc/4.1.0/org/eclipse/ocl/examples/pivot/Query.html
objects for evaluating constraints and query expressions.

!{width:60%}images/6315-query.png(OCL Query API)!

The @Query@ encapsulates an
"@EvaluationEnvironment@":http://download.eclipse.org/ocl/javadoc/4.1.0/org/eclipse/ocl/examples/pivot/EvaluationEnvironment.html
providing the run-time values of context variables to the OCL interpreter.  These
context variables are set and retrieved using the following methods:

* @add(String, Object)@: adds a name-value binding for a variable
* @replace(String, Object)@:  replaces an existing variable binding
* @remove()@:  removes a variable binding
* @getValueOf(String)@: obtains a variable value

The context variables of primary interest are @self@
and, in operation constraints, the variables corresponding to its parameters.
The @EvaluationEnvironment@ API is also used to supply
values for "global" variables added to the parsing @Environment@
by the client.

Another important consideration in the evaluation environment is the
@allInstance()@ operation, which obtains the entire
extent of a classifier.  For data types, this is a simple problem:  the extent
of an @Enumeration@ is well defined and the extents of
other kinds of @DataType@ s are undefined.  For
@Class@ extents, the @EvaluationEnvironment@
provides support for an extent map, mapping classes to the sets of their
instances, as determined by the client.  A client sets the extent map using the
"@OCL.setExtentMap()@":http://download.eclipse.org/ocl/javadoc/4.1.0/org/eclipse/ocl/examples/pivot/OCL.html#setExtentMap(java.util.Map)
method.  The default extent map, if none is provided by the client, lazily
computes the extent of a class from the EMF @ResourceSet@
containing the context element of the evaluation.

So, after optionally setting values of context variables (other than
@self@; the @Query@ takes care
of this) and an extent map, simply construct a query and use it to evaluate
the expression or check the constraint:

!{width:70%}images/6315-check-all.png(Evaluating all Constraints)!
"[Text for cut and paste]":../references/6315-check-all.txt

One of the advantages of the @Query@ API is that a
query's evaluation environment can be reused for multiple evaluations, as
above.  The extent of any classifier is only computed once.  For convenience,
however, in situations where only a single evaluation is required, the
@OCL@ class provides shortcuts:

!{width:70%}images/6315-check-one.png(Evaluating one Constraint)!
"[Text for cut and paste]":../references/6315-check-one.txt

The @Query@ API also provides methods that work on
multiple elements.  The first example, above, could be written more succinctly as:

!{width:70%}images/6315-check-quick.png(Evaluating Constraints Quicker)!
"[Text for cut and paste]":../references/6315-check-quick.txt