doc/org.eclipse.ocl.doc/doc/6200-pivot-evaluator.textile - ocl/org.eclipse.ocl - Git at Google


 h2(#PivotEvaluator). The Pivot Evaluator

 The Pivot evaluator is a complete reimplementation of the classic evaluator to exploit experience and the Pivot metamodel
 * numeric growth beyond 32/64 bits is accommodated
 * equal numbers are equal regardless of type
 * templated types are supported
 * library operations are modeled and extensible
 * oclType() returns a Metaclass(OclSelf) offering full reflection without loss of static typing
 * optimised virtual function dispatch tables
 * code generation to Java

 The APIs of the two evaluators are very similar since Ecore compatibility is very important. For basic OCL evaluation, users should not notice any functional difference between the two evaluators. The Pivot evaluator is generally between 2 and 5 times faster as well as being more accurate. The code generated evaluation may be a further 20 times faster.

 h3(#PivotValue-History). The Evolving Pivot Value System

 The classic evaluator uses Ecore and Java library representations such as EObject, Integer, String and Set directly for evaluation. This avoids conversion costs but incurs OCL accuracy challenges for numeric equality and growth.

 The Juno release of the Pivot evaluator use polymorphic @Value@ representations such as EObjectValue, IntegerValue, StringValue and SetValue. This avoids the OCL accuracy difficulties but requires wrapper objects and incurs conversion costs wherever a compatible Ecore API is in use.

 The IntegerValue and RealValue classes avoid the equivalence and accuracy problems of Integer and Double by implementing Object.equals(Object) with OCL semantics.

 The costs of the polymorphic Boolean, String and EObject wrappers became apparent when testing the code generator and so the Kepler release uses a hybrid representation. Unboxed values (the natural Ecore and Java representation) are used wherever OCL and Java have compatible semantics, that is for Boolean, String, null, invalid/exception and EObjects that are not Types. Boxed polymorphic value representations are used wherever OCL and Java semantics differ, that is for IntegerValue, RealValue, CollectionValue, TupleValue and TypeValue. This avoids unnecessary conversion costs, but requires many instanceof tests to compensate for the lack of Value polymorphism. When generating code, static analysis can often eliminate many of the instanceof cases and so the hybrid representation is faster.

 h3(#PivotValues). The Pivot Value System

 Every value has a unique type identity supervised by the @IdManager@ class. This unique identity can be shared by multiple OCL applications that may have distinct type systems as a result of Complete OCL complements.

 Every value has a type that is determined from its type identity by a type-system-specific @IdResolver@ instance, which also supports conversion between boxed and unboxed value representations.

 h4(#PivotValueConversions). Value Conversions

 The values are managed by a @ValueFactory@ which provides many utility methods such as @ValueFactory.valueOf(Object)@ for creating a @Value@ from a naked Java object. The reverse conversion from a value to a naked Java object may be be performed by @Value.asObject()@ with
 methods in derived value classes providing stronger type returns.

 h4(#PivotIntegers). Polymorphic Integers

 The @IntegerValue@ interface has a family of IntIntegerValueImpl, LongIntegerValueImpl and BigIntegerValueImpl realizations that use Java types internally but support numeric growth where necessary without imposing the overheads of BigInteger on the vast majority of mundane usages. The wrapping of @int@ in @IntegerIntValueImpl@ is very comparable to the wrapping of @int@ in @java.lang.Integer@ so there is little performance or representation cost.

 This enables the Pivot evaluator to handle unlimited integers as specified by the OMG OCL specification.

 bq..
 Prior to the Juno release the handling of greater than 32 bit integers in the classic evaluator was suspect. The Juno release enhances support to allow for 64 bit integers but makes no provision for greater than 64 bit evaluations.
 p.

 h4(#PivotCollections). Polymorphic Collections

 The @CollectionValue@ interface has multiple implementations for Bag, OrderedSet, Sequence and Set with implementations that observe OMG OCL semantics.

 bq..
 The classic implementation uses Java collections directly, which unfortunately means that the Java semantics for equality is used. Consequently the classic evaluator incorrectly evaluates @Set{1,1.0}->size()@ as @2@.
 p.

 Using a distinct hierarchy of collection classes opens up opportunities for smart operation, such as in-place update for collections that are rendered redundant by a calculation.

 bq..
 The classic implementation creates a new collection at every opportunity.
 p.

 h4(#PivotObjects). Polymorphic Objects

 The @ObjectValue@ interface has an implementation for EObject and further implementations for more specialized objects such as types.

 The Pivot evaluator can be used on alternate data models by providing an alternate @ObjectValue@ to wrap
 an alternative form of data object.

 bq..
 The classic implementation uses EObject directly, which makes use of non-EObject data models rather hard.
 p.

 h3. The Pivot Evaluator Type System

 The Pivot Evaluator uses a very lightweight type system so that alternate implementations can be used.

 For compiled evaluation, a dispatch-table based implementation is used.

 For OCL compilation, a UML-aligned representation of the combined UML, OCL, library and user type systems is used.

 bq..
 The classic implementation uses either UML or Ecore meta-models directly, with Ecore as the meta-meta-model. Consequently there was no support for oclType(). Reflection was available in the non-OMF Ecore domain, so
 the meta-meta-class is "EClass" rather than "Class".
 p.

 h3. The Pivot Evaluator Implementation System

 The Pivot evaluator may be used in an interpreted form similar to the classic evaluator. In this form the evaluator performs a tree-walk over the Abstract Syntax Tree of the OCL expression. Languages that extend OCL may extend this tree-walk by implementing the relevant visitor evaluations for additional AST nodes.

 A partially optimized code generator is available for the Pivot evaluator for which the code generator walks the AST at compile-time. The code generator may be extended to support code generation for languages that extend OCL. See the QVTi code generator in the QVTd project as an example.

 h3. Polymorphic Implementations

 The OCL Standard Library comprises packages of classes with one class per library feature, each class implementing the polymorphic implementation interface.

 Provision of additional library function therefore requires
 * provision of the Java class for the library feature
 * declaration of the library feature

 Library features (properties, operations and iterations) are declared in a Standard Library model that identifies the invocation signature and binds it to a Java implementation.

 !{width:70%}images/6200-library-declarations.png(Standard Library Declarations)!

 The extract from @/org.eclipse.ocl.examples.library/model/OCL-2.4.oclstdlib@ shows the declaration of the @Collection@ type as a templated type with a @T@ parameter. The @Collection@ type conformsTo (extends/inherits/generalizes) the @OclAny@ type and is an instance of the @CollectionType@ meta-type.

 The @asSet@ operation takes no arguments and returns a @Set(T)@, a set of the collection template type. The declaration is bound to @org.eclipse.ocl.examples.library.collection.CollectionAsSetOperation@ which is the Java class name of the implementation.

 The @exists@ iteration has two overloads, taking one or two iterators of the collection template type. The iteration body is a lambda expression operating on a collection template element with no additional arguments to return a Boolean value. The iteration also returns a Boolean value. The same Java implementation class is used for both one and two argument forms.

 bq..
 The corresponding implementations in the classic evaluator were mostly inlined within the @EvaluationVisitorImpl.visitOperationCallExp@ method and so were difficult to extend.

 The corresponding declarations in the classic evaluator were partially modeled in *oclstdlib.ecore* or *oclstdlib.uml*, although in practice an equivalent manually code model initialization is used. The type declarations used by the parser and analyzer are independently coded and do not support iterations as modeled concepts.
 p.

	h2(#PivotEvaluator). The Pivot Evaluator

	The Pivot evaluator is a complete reimplementation of the classic evaluator to exploit experience and the Pivot metamodel
	* numeric growth beyond 32/64 bits is accommodated
	* equal numbers are equal regardless of type
	* templated types are supported
	* library operations are modeled and extensible
	* oclType() returns a Metaclass(OclSelf) offering full reflection without loss of static typing
	* optimised virtual function dispatch tables
	* code generation to Java

	The APIs of the two evaluators are very similar since Ecore compatibility is very important. For basic OCL evaluation, users should not notice any functional difference between the two evaluators. The Pivot evaluator is generally between 2 and 5 times faster as well as being more accurate. The code generated evaluation may be a further 20 times faster.

	h3(#PivotValue-History). The Evolving Pivot Value System

	The classic evaluator uses Ecore and Java library representations such as EObject, Integer, String and Set directly for evaluation. This avoids conversion costs but incurs OCL accuracy challenges for numeric equality and growth.

	The Juno release of the Pivot evaluator use polymorphic @Value@ representations such as EObjectValue, IntegerValue, StringValue and SetValue. This avoids the OCL accuracy difficulties but requires wrapper objects and incurs conversion costs wherever a compatible Ecore API is in use.

	The IntegerValue and RealValue classes avoid the equivalence and accuracy problems of Integer and Double by implementing Object.equals(Object) with OCL semantics.

	The costs of the polymorphic Boolean, String and EObject wrappers became apparent when testing the code generator and so the Kepler release uses a hybrid representation. Unboxed values (the natural Ecore and Java representation) are used wherever OCL and Java have compatible semantics, that is for Boolean, String, null, invalid/exception and EObjects that are not Types. Boxed polymorphic value representations are used wherever OCL and Java semantics differ, that is for IntegerValue, RealValue, CollectionValue, TupleValue and TypeValue. This avoids unnecessary conversion costs, but requires many instanceof tests to compensate for the lack of Value polymorphism. When generating code, static analysis can often eliminate many of the instanceof cases and so the hybrid representation is faster.

	h3(#PivotValues). The Pivot Value System

	Every value has a unique type identity supervised by the @IdManager@ class. This unique identity can be shared by multiple OCL applications that may have distinct type systems as a result of Complete OCL complements.

	Every value has a type that is determined from its type identity by a type-system-specific @IdResolver@ instance, which also supports conversion between boxed and unboxed value representations.

	h4(#PivotValueConversions). Value Conversions

	The values are managed by a @ValueFactory@ which provides many utility methods such as @ValueFactory.valueOf(Object)@ for creating a @Value@ from a naked Java object. The reverse conversion from a value to a naked Java object may be be performed by @Value.asObject()@ with
	methods in derived value classes providing stronger type returns.

	h4(#PivotIntegers). Polymorphic Integers

	The @IntegerValue@ interface has a family of IntIntegerValueImpl, LongIntegerValueImpl and BigIntegerValueImpl realizations that use Java types internally but support numeric growth where necessary without imposing the overheads of BigInteger on the vast majority of mundane usages. The wrapping of @int@ in @IntegerIntValueImpl@ is very comparable to the wrapping of @int@ in @java.lang.Integer@ so there is little performance or representation cost.

	This enables the Pivot evaluator to handle unlimited integers as specified by the OMG OCL specification.

	bq..
	Prior to the Juno release the handling of greater than 32 bit integers in the classic evaluator was suspect. The Juno release enhances support to allow for 64 bit integers but makes no provision for greater than 64 bit evaluations.
	p.

	h4(#PivotCollections). Polymorphic Collections

	The @CollectionValue@ interface has multiple implementations for Bag, OrderedSet, Sequence and Set with implementations that observe OMG OCL semantics.

	bq..
	The classic implementation uses Java collections directly, which unfortunately means that the Java semantics for equality is used. Consequently the classic evaluator incorrectly evaluates @Set{1,1.0}->size()@ as @2@.
	p.

	Using a distinct hierarchy of collection classes opens up opportunities for smart operation, such as in-place update for collections that are rendered redundant by a calculation.

	bq..
	The classic implementation creates a new collection at every opportunity.
	p.

	h4(#PivotObjects). Polymorphic Objects

	The @ObjectValue@ interface has an implementation for EObject and further implementations for more specialized objects such as types.

	The Pivot evaluator can be used on alternate data models by providing an alternate @ObjectValue@ to wrap
	an alternative form of data object.

	bq..
	The classic implementation uses EObject directly, which makes use of non-EObject data models rather hard.
	p.

	h3. The Pivot Evaluator Type System

	The Pivot Evaluator uses a very lightweight type system so that alternate implementations can be used.

	For compiled evaluation, a dispatch-table based implementation is used.

	For OCL compilation, a UML-aligned representation of the combined UML, OCL, library and user type systems is used.

	bq..
	The classic implementation uses either UML or Ecore meta-models directly, with Ecore as the meta-meta-model. Consequently there was no support for oclType(). Reflection was available in the non-OMF Ecore domain, so
	the meta-meta-class is "EClass" rather than "Class".
	p.

	h3. The Pivot Evaluator Implementation System

	The Pivot evaluator may be used in an interpreted form similar to the classic evaluator. In this form the evaluator performs a tree-walk over the Abstract Syntax Tree of the OCL expression. Languages that extend OCL may extend this tree-walk by implementing the relevant visitor evaluations for additional AST nodes.

	A partially optimized code generator is available for the Pivot evaluator for which the code generator walks the AST at compile-time. The code generator may be extended to support code generation for languages that extend OCL. See the QVTi code generator in the QVTd project as an example.

	h3. Polymorphic Implementations

	The OCL Standard Library comprises packages of classes with one class per library feature, each class implementing the polymorphic implementation interface.

	Provision of additional library function therefore requires
	* provision of the Java class for the library feature
	* declaration of the library feature

	Library features (properties, operations and iterations) are declared in a Standard Library model that identifies the invocation signature and binds it to a Java implementation.

	!{width:70%}images/6200-library-declarations.png(Standard Library Declarations)!

	The extract from @/org.eclipse.ocl.examples.library/model/OCL-2.4.oclstdlib@ shows the declaration of the @Collection@ type as a templated type with a @T@ parameter. The @Collection@ type conformsTo (extends/inherits/generalizes) the @OclAny@ type and is an instance of the @CollectionType@ meta-type.

	The @asSet@ operation takes no arguments and returns a @Set(T)@, a set of the collection template type. The declaration is bound to @org.eclipse.ocl.examples.library.collection.CollectionAsSetOperation@ which is the Java class name of the implementation.

	The @exists@ iteration has two overloads, taking one or two iterators of the collection template type. The iteration body is a lambda expression operating on a collection template element with no additional arguments to return a Boolean value. The iteration also returns a Boolean value. The same Java implementation class is used for both one and two argument forms.

	bq..
	The corresponding implementations in the classic evaluator were mostly inlined within the @EvaluationVisitorImpl.visitOperationCallExp@ method and so were difficult to extend.

	The corresponding declarations in the classic evaluator were partially modeled in oclstdlib.ecore or oclstdlib.uml, although in practice an equivalent manually code model initialization is used. The type declarations used by the parser and analyzer are independently coded and do not support iterations as modeled concepts.
	p.