| h2(#EvaluatingConstraints). Evaluating Constraints and Queries |
| |
| In "Parsing Constraints":#ParsingConstraints, 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/modeling/mdt/ocl/javadoc/3.1.0/org/eclipse/ocl/Query.html |
| objects for evaluating constraints and query expressions. |
| |
| !images/5115-query.png(OCL Query API)! |
| |
| The @Query@ encapsulates an |
| "@EvaluationEnvironment@":http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/org/eclipse/ocl/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/modeling/mdt/ocl/javadoc/3.1.0/org/eclipse/ocl/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 @Resource@ |
| containing the context element of the evaluation. An alternative extent map can be |
| found in "@org.eclipse.ocl.ecore.opposites.ExtentMap@":http://download.eclipse.org/modeling/mdt/ocl/javadoc/3.1.0/org/eclipse/ocl/ecore/opposites/ExtentMap.html. |
| |
| 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: |
| |
| !images/5115-check-all.png(Evaluating all Constraints)! |
| "[Text for cut and paste]":../references/5115-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: |
| |
| !images/5115-check-one.png(Evaluating one Constraint)! |
| "[Text for cut and paste]":../references/5115-check-one.txt |
| |
| The @Query@ API also provides methods that work on |
| multiple elements. The first example, above, could be written more succinctly as: |
| |
| !images/5115-check-quick.png(Evaluating Constraints Quicker)! |
| "[Text for cut and paste]":../references/5115-check-quick.txt |