doc/org.eclipse.ocl.doc/doc/5200-delegates.textile - ocl/org.eclipse.ocl - Git at Google

 h2(#Delegates). Delegates

 EMF provides three delegation mechanisms that enable functionality not directly supported by EMF to be delegated to a technology that can support it.

 * a "Validation Delegate":#ValidationDelegate supports checking additional invariants on an EClassifier
 * a "Setting Delegate":#SettingDelegate supports getting an initial or derived computed value for an EStructuralFeature
 * an "Invocation Delegate":#InvocationDelegate supports the execution of a function defined by an EOperation

 and also

 * a "Query Delegate":#QueryDelegate supports the execution of a function not defined by an EOperation

 When you use the "OCLinEcore":#OCLinEcore editor, the required EAnnotations to support delegation are provided automatically. This section provides sufficient detail to allow them to be maintained manually using the Sample Ecore Editor or Java code.

 These EAnnotations ensure that delegates can be used for both genmodeled and reflective models.  The use of genmodel to generate Java classes for your metamodel has significant performance benefits for modeling, but currently makes little difference for OCL execution. The use of genmodel has the disadvantage that you must install the Java classes and so the user of the Java classes must run in a different Eclipse or standalone session to the developer. Conversely, using reflective models allows both developer and user to share the same Eclipse session.

 h3. GenModel Settings

 There is one GenModel setting that needs to be correctly set to ensure that OCL within generated Java classes can successfully be invoked by itself. Make sure that support for reflective operation invocation is generated by setting the @Operation Reflection@ option to @true@.

 h3(#OCLDelegateURI). OCL Delegate URIs

 Each application implementing delegation has an associated Delegate URI, which is
 * @http://www.eclipse.org/emf/2002/Ecore/OCL@ for the mature evaluator
 * @http://www.eclipse.org/emf/2002/Ecore/OCL/Pivot@ for the pivot evaluator

 Only the @http://www.eclipse.org/emf/2002/Ecore/OCL@ was available in the Helios release and so the Helios release of the OCLinEcore editor used that URI.

 The OCLinEcore editor uses the pivot metamodel which is more accurate and OMG compliant and so in the Indigo release, the OCLinEcore editor uses the @http://www.eclipse.org/emf/2002/Ecore/OCL/Pivot@ URI and converts all incoming usage of @http://www.eclipse.org/emf/2002/Ecore/OCL@ URI to @http://www.eclipse.org/emf/2002/Ecore/OCL/Pivot@.

 As described in "The two Eclipse OCLs":#EclipseOCLs the pivot evaluator uses an intermiediate pivot model to hide Ecore and UML2 and so allow full OMG-compliance. The pivot evaluator is only available when the OCL Examples and Editors feature has been installed as described in "Installation":#Installation.

 The OCL Delegate URIs are registered using the
 * org.eclipse.emf.ecore.invocation_delegate
 * org.eclipse.emf.ecore.setting_delegate
 * org.eclipse.emf.ecore.query_delegate
 * org.eclipse.emf.ecore.validation_delegate
 extension points.

 h3. Standalone Initialization

 The initialization code for standalone usage of EMF delegates is given in the "Standalone":#Standalone section.

 h3(#InvocationDelegate). Invocation Delegates

 An invocation delegate is invoked to execute the body of an EOperation. An invocation delegate must be registered for the EPackage of the EClassifier of the EOperation.

 The EPackage registration is provided by an EAnnotation on the EPackage
 * @source@ = @http://www.eclipse.org/emf/2002/Ecore@
 ** @key@ = @invocationDelegates@
 ** @value@ = _@OCL-Delegate-URI@_

 The invocation delegate is provided by an EAnnotation on the EOperation
 * @source@ = _@OCL-Delegate-URI@_
 ** @key@ = @body@
 ** @value@ = _@OCL-expression@_

 The _@OCL-expression@_ is evaluated to provide the EOperation value with the containing EClassifier as the @self@ context object and the EParameters accessible as parameters from OCL. The return type of the _@OCL-expression@_ must conform to the return type of the EOperation.

 h3(#SettingDelegate). Setting Delegates

 A setting delegate is invoked to provide the initial or derived value of an EStructuralFeature.  A setting delegate must be been registered for the EPackage of the EClassifier of the EStructuralFeature.

 The EPackage registration is provided by an EAnnotation on the EPackage
 * @source@ = @http://www.eclipse.org/emf/2002/Ecore@
 ** @key@ = @settingDelegates@
 ** @value@ = _@OCL-Delegate-URI@_

 The setting delegate is provided by an EAnnotation on the EStructuralFeature
 * @source@ = _@OCL-Delegate-URI@_
 ** @key@ = @derivation@
 ** @value@ = _@OCL-expression@_

 The _@OCL-expression@_ is evaluated to provide the EStructuralFeature value with the containing EClassifier as the @self@ context object. The result type of the _@OCL-expression@_ must conform to the type of the EStructuralFeature.

 An @initial@ rather than @derivation@ value may be specified. The @initial@ is ignored if a @derivation@ is also specified.

 h3(#ValidationDelegate). Validation Delegates

 A validation delegate is invoked to provide additional validation of an EClassifier. A validation delegate must be registered for the EPackage of the EClassifier for which the EClassifier provides any Ecore invariants or Ecore constraints.  Both Ecore constraints and invariants constrain an EClassifier, the difference is that an Ecore invariant is realised by an EOperation and so an Ecore invariant may be re-used by modeling environments that may wish to selectively check or re-check constraints.

 The EPackage registration is provided by an EAnnotation on the EPackage
 * @source@ = @http://www.eclipse.org/emf/2002/Ecore@
 ** @key@ = @validationDelegates@
 ** @value@ = _@OCL-Delegate-URI@_

 All Ecore constraints must be listed in an EAnnotation on the EClassifier
 * @source@ = @http://www.eclipse.org/emf/2002/Ecore@
 ** @key@ = @constraints@
 ** @value@ = _@constraintName1 constraintName2 constraintName3@_

 The validation delegate for each Ecore constraint is provided by a further EAnnotation on the EClassifier
 * @source@ = _@OCL-Delegate-URI@_
 ** @key@ = _@constraintName@_
 ** @value@ = _@OCL-expression@_

 The validation delegate for each Ecore invariant is provided by an EAnnotation on the EOperation
 * @source@ = _@OCL-Delegate-URI@_
 ** @key@ = @body@
 ** @value@ = _@OCL-expression@_

 The _@OCL-expression@_ is evaluated to validate the EClassifier with the EClassifier as the @self@ context object. The result type of the _@OCL-expression@_ must be Boolean.

 h3(#ValidationMessages). Validation Messages

 When a validation fails EMF generates a default diagnostic of the form @The@ _@'constraintName'@_ @is violated on@ _@'constrainedObject'@_.

 If the "OCLinEcoreEObjectValidator":#OCLinEcoreEObjectValidator or "CompleteOCLEObjectValidator":#CompleteOCLEObjectValidator are used a custom message may be supplied using an additional EAnnotation on the EClassifier.

 * @source@ = _@OCL-Delegate-URI@_
 ** @key@ = _@constraintName@_@$message@
 ** @value@ = _@OCL-expression@_

 The _@OCL-expression@_ is evaluated to produce the custom message with the EClassifier as the @self@ context object. The result type of the _@OCL-expression@_ must be String.

 The severity of the diagnostic can also be customized by exploiting the four values of the Boolean value of the constraint evaluation.
 * @true@ indicates successful validation
 * @false@ indicates unsuccessful validation with warning severity
 * @null@ indicates unsuccessful validation with error severity
 * @invalid@ indicates a failure to perform validation (error severity)

 h3(#QueryDelegate). Query Delegates

 A query delegate is invoked to evaluate a parameterized query on a EObject for which there is no corresponding EOperation. A query delegate is registered to install this query and allow its compiled form to be cached. The delegate may then be invoked as many times as required for compatible context objects and parameters.

 This facility enables an EMF application to execute OCL without declaring or instantiating any OCL classes.

 The query delegate registration is analogous to direct use of @OCL.newInstance().createHelper().createQuery()@

 The query delegate execution is analogous to
 @OCL.evaluate()@
	h2(#Delegates). Delegates

	EMF provides three delegation mechanisms that enable functionality not directly supported by EMF to be delegated to a technology that can support it.

	* a "Validation Delegate":#ValidationDelegate supports checking additional invariants on an EClassifier
	* a "Setting Delegate":#SettingDelegate supports getting an initial or derived computed value for an EStructuralFeature
	* an "Invocation Delegate":#InvocationDelegate supports the execution of a function defined by an EOperation

	and also

	* a "Query Delegate":#QueryDelegate supports the execution of a function not defined by an EOperation

	When you use the "OCLinEcore":#OCLinEcore editor, the required EAnnotations to support delegation are provided automatically. This section provides sufficient detail to allow them to be maintained manually using the Sample Ecore Editor or Java code.

	These EAnnotations ensure that delegates can be used for both genmodeled and reflective models. The use of genmodel to generate Java classes for your metamodel has significant performance benefits for modeling, but currently makes little difference for OCL execution. The use of genmodel has the disadvantage that you must install the Java classes and so the user of the Java classes must run in a different Eclipse or standalone session to the developer. Conversely, using reflective models allows both developer and user to share the same Eclipse session.

	h3. GenModel Settings

	There is one GenModel setting that needs to be correctly set to ensure that OCL within generated Java classes can successfully be invoked by itself. Make sure that support for reflective operation invocation is generated by setting the @Operation Reflection@ option to @true@.

	h3(#OCLDelegateURI). OCL Delegate URIs

	Each application implementing delegation has an associated Delegate URI, which is
	* @http://www.eclipse.org/emf/2002/Ecore/OCL@ for the mature evaluator
	* @http://www.eclipse.org/emf/2002/Ecore/OCL/Pivot@ for the pivot evaluator

	Only the @http://www.eclipse.org/emf/2002/Ecore/OCL@ was available in the Helios release and so the Helios release of the OCLinEcore editor used that URI.

	The OCLinEcore editor uses the pivot metamodel which is more accurate and OMG compliant and so in the Indigo release, the OCLinEcore editor uses the @http://www.eclipse.org/emf/2002/Ecore/OCL/Pivot@ URI and converts all incoming usage of @http://www.eclipse.org/emf/2002/Ecore/OCL@ URI to @http://www.eclipse.org/emf/2002/Ecore/OCL/Pivot@.

	As described in "The two Eclipse OCLs":#EclipseOCLs the pivot evaluator uses an intermiediate pivot model to hide Ecore and UML2 and so allow full OMG-compliance. The pivot evaluator is only available when the OCL Examples and Editors feature has been installed as described in "Installation":#Installation.

	The OCL Delegate URIs are registered using the
	* org.eclipse.emf.ecore.invocation_delegate
	* org.eclipse.emf.ecore.setting_delegate
	* org.eclipse.emf.ecore.query_delegate
	* org.eclipse.emf.ecore.validation_delegate
	extension points.

	h3. Standalone Initialization

	The initialization code for standalone usage of EMF delegates is given in the "Standalone":#Standalone section.

	h3(#InvocationDelegate). Invocation Delegates

	An invocation delegate is invoked to execute the body of an EOperation. An invocation delegate must be registered for the EPackage of the EClassifier of the EOperation.

	The EPackage registration is provided by an EAnnotation on the EPackage
	* @source@ = @http://www.eclipse.org/emf/2002/Ecore@
	** @key@ = @invocationDelegates@
	** @value@ = _@OCL-Delegate-URI@_

	The invocation delegate is provided by an EAnnotation on the EOperation
	* @source@ = _@OCL-Delegate-URI@_
	** @key@ = @body@
	** @value@ = _@OCL-expression@_

	The _@OCL-expression@_ is evaluated to provide the EOperation value with the containing EClassifier as the @self@ context object and the EParameters accessible as parameters from OCL. The return type of the _@OCL-expression@_ must conform to the return type of the EOperation.

	h3(#SettingDelegate). Setting Delegates

	A setting delegate is invoked to provide the initial or derived value of an EStructuralFeature. A setting delegate must be been registered for the EPackage of the EClassifier of the EStructuralFeature.

	The EPackage registration is provided by an EAnnotation on the EPackage
	* @source@ = @http://www.eclipse.org/emf/2002/Ecore@
	** @key@ = @settingDelegates@
	** @value@ = _@OCL-Delegate-URI@_

	The setting delegate is provided by an EAnnotation on the EStructuralFeature
	* @source@ = _@OCL-Delegate-URI@_
	** @key@ = @derivation@
	** @value@ = _@OCL-expression@_

	The _@OCL-expression@_ is evaluated to provide the EStructuralFeature value with the containing EClassifier as the @self@ context object. The result type of the _@OCL-expression@_ must conform to the type of the EStructuralFeature.

	An @initial@ rather than @derivation@ value may be specified. The @initial@ is ignored if a @derivation@ is also specified.

	h3(#ValidationDelegate). Validation Delegates

	A validation delegate is invoked to provide additional validation of an EClassifier. A validation delegate must be registered for the EPackage of the EClassifier for which the EClassifier provides any Ecore invariants or Ecore constraints. Both Ecore constraints and invariants constrain an EClassifier, the difference is that an Ecore invariant is realised by an EOperation and so an Ecore invariant may be re-used by modeling environments that may wish to selectively check or re-check constraints.

	The EPackage registration is provided by an EAnnotation on the EPackage
	* @source@ = @http://www.eclipse.org/emf/2002/Ecore@
	** @key@ = @validationDelegates@
	** @value@ = _@OCL-Delegate-URI@_

	All Ecore constraints must be listed in an EAnnotation on the EClassifier
	* @source@ = @http://www.eclipse.org/emf/2002/Ecore@
	** @key@ = @constraints@
	** @value@ = _@constraintName1 constraintName2 constraintName3@_

	The validation delegate for each Ecore constraint is provided by a further EAnnotation on the EClassifier
	* @source@ = _@OCL-Delegate-URI@_
	** @key@ = _@constraintName@_
	** @value@ = _@OCL-expression@_

	The validation delegate for each Ecore invariant is provided by an EAnnotation on the EOperation
	* @source@ = _@OCL-Delegate-URI@_
	** @key@ = @body@
	** @value@ = _@OCL-expression@_

	The _@OCL-expression@_ is evaluated to validate the EClassifier with the EClassifier as the @self@ context object. The result type of the _@OCL-expression@_ must be Boolean.

	h3(#ValidationMessages). Validation Messages

	When a validation fails EMF generates a default diagnostic of the form @The@ _@'constraintName'@_ @is violated on@ _@'constrainedObject'@_.

	If the "OCLinEcoreEObjectValidator":#OCLinEcoreEObjectValidator or "CompleteOCLEObjectValidator":#CompleteOCLEObjectValidator are used a custom message may be supplied using an additional EAnnotation on the EClassifier.

	* @source@ = _@OCL-Delegate-URI@_
	** @key@ = _@constraintName@_@$message@
	** @value@ = _@OCL-expression@_

	The _@OCL-expression@_ is evaluated to produce the custom message with the EClassifier as the @self@ context object. The result type of the _@OCL-expression@_ must be String.

	The severity of the diagnostic can also be customized by exploiting the four values of the Boolean value of the constraint evaluation.
	* @true@ indicates successful validation
	* @false@ indicates unsuccessful validation with warning severity
	* @null@ indicates unsuccessful validation with error severity
	* @invalid@ indicates a failure to perform validation (error severity)

	h3(#QueryDelegate). Query Delegates

	A query delegate is invoked to evaluate a parameterized query on a EObject for which there is no corresponding EOperation. A query delegate is registered to install this query and allow its compiled form to be cached. The delegate may then be invoked as many times as required for compatible context objects and parameters.

	This facility enables an EMF application to execute OCL without declaring or instantiating any OCL classes.

	The query delegate registration is analogous to direct use of @OCL.newInstance().createHelper().createQuery()@

	The query delegate execution is analogous to
	@OCL.evaluate()@