doc/org.eclipse.ocl.doc/doc/6310-pivot-parsing-constraints.textile - ocl/org.eclipse.ocl - Git at Google


 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.4.0/org/eclipse/ocl/pivot/utilities/OCL.html Facade.

 h3. The OCL Facade

 The "@OCL@":http://download.eclipse.org/ocl/javadoc/6.4.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.4.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.

	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.4.0/org/eclipse/ocl/pivot/utilities/OCL.html Facade.

	h3. The OCL Facade

	The "@OCL@":http://download.eclipse.org/ocl/javadoc/6.4.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.4.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.