doc/org.eclipse.ocl.doc/doc/6320-pivot-parsing-documents.textile - ocl/org.eclipse.ocl - Git at Google


 h2(#PivotParsingDocuments). Parsing OCL Documents

 As we saw in the "Parsing Constraints and Queries":#PivotParsingConstraints topic, the  "@OCL@":http://download.eclipse.org/ocl/javadoc/6.4.0/org/eclipse/ocl/utilities/OCL.html
 Facade provides an API for parsing OCL expressions embedded in models as constraints.

 The OCL specification defines a Complete OCL text document with which a UML (or Ecore) metamodel
 may be completed by providing many complementary constraints and expressions. In this case,
 the concrete syntax for context declarations indicates the context of
 constraints, equivalent to their placement in models.

 As an example, consider the following Complete OCL document:

 !{width:70%}images/6320-extlibrary.png(External Library)!
 "[Text for cut and paste]":../references/6320-extlibrary.ocl

 h3. The OCL Input

 The Pivot binding provides a UML-aligned representation and so a Complete OCL document can be parsed to provide a similar Resource to that
 derived from a UML or Ecore metamodel. A @Root@ contains a @Model@ which contains @Package@==s==
 and @Class@==es==. The complementing Resource from the Complete OCL document is independent of the similarly structured
 complemented Resource of the completed metamodel.

 The Pivot binding uses an Xtext parser with a UML-aligned output. The input text is therefore specified by
 a URI and loaded by the Xtext parser to create a Concrete Syntax Resource. This may then be converted to the Pivot Abstract Syntax Resource. The Abstract Syntax Resource has a conventional Model, Package, Class, Operation hierarchy in order to provide a coherent composition context for the Constraints.

 The elements of the independent complementing and complemented Resources are merged within @CompleteClass@==es== and
 @CompletePackage@==s== of the @CompleteModel@ managed behind the OCL facade.

 There are therefore two @Class@ objects named *Library*, one for each Resource. The objects are distinct in so far as they belong to different resources, which can be separately serialized, and in so far as they may appear distinct to OCL expressions that use reflective access. However they are logically merged and the @CompleteEnvironment@ provides utility methods that allow the multiple objects to be accessed as a merged object.

 bq.
 The Ecore binding provided an @OCLInput@ class to supervise the OCL source text, and the result of parsing the document was a @List<Constraint>@.
 p.

 The Complete OCL document is a textual Resource with an associated text tooling. The @OCL@ facade provides
 an API to load a Resource from a given @URI@.

 !{width:70%}images/6320-parsing.png(Parsing the Constraints)!
 "[Text for cut and paste]":../references/6320-parsing.txt

 h3. Traversing the Constraints

 The parsed resurce can be traversed in the same way as other EMF resources.

 !{width:70%}images/6320-traversing.png(Traversing the Constraints)!
 "[Text for cut and paste]":../references/6320-traversing.txt

 h3. Accessing the Constraints

 The contents of the Complete OCL document contribute to a @CompleteModel@ that merges all the contributions.
 The contributions can therefore be used as if defined in a primary metamodel.

 !{width:70%}images/6320-accessing.png(Accessing the Constraints)!
 "[Text for cut and paste]":../references/6320-accessing.txt

 h3. Using the Constraints to Validate a Model

 The standard EMF validation makes use of an @EValidatorRegistry@ that maps the URI of an @EPackage@ to the
 derived @EValidator@ that provides the constraints appilcable to the @EPackage@. If we want to exploit
 additional constraints defined in a Complete OCL document, we must extend the underlying @EValidator@.
 The @ComposedValidator@ enables multiple @EValidator@ to be composed and to behave as a single
 @EValidator@. @ComposedEValidator.install()@ replaces the single @EValidator@ by a composite
 initially containing just the replaced @EValidator@. A @CompleteOCLEObjectValidator@ provides the additional validation of the given @uri@ and @EPackage@.

 !{width:70%}images/6320-validating.png(Validating the Constraints)!
 "[Text for cut and paste]":../references/6320-validating.txt

 The standard @Diagnostician@ does not directly support validation of a @Resource@.
 @MyDiagnostician@ remedies this deficiency and provides a @SubstitutionLabelProvider@
 that provides slightly better labels within OCL diagnostics.

 !{width:70%}images/6320-diagnostician.png(Extended Diagnostician)!
 "[Text for cut and paste]":../references/6320-diagnostician.txt

 The source for these examples may be found in the org.eclipse.ocl.examples.xtext.tests plugin in model/parsingDocumentsExample.ocl and in src/org/eclipse/ocl/examples/test/xtext/PivotDocumentationExamples.java.

	h2(#PivotParsingDocuments). Parsing OCL Documents

	As we saw in the "Parsing Constraints and Queries":#PivotParsingConstraints topic, the "@OCL@":http://download.eclipse.org/ocl/javadoc/6.4.0/org/eclipse/ocl/utilities/OCL.html
	Facade provides an API for parsing OCL expressions embedded in models as constraints.

	The OCL specification defines a Complete OCL text document with which a UML (or Ecore) metamodel
	may be completed by providing many complementary constraints and expressions. In this case,
	the concrete syntax for context declarations indicates the context of
	constraints, equivalent to their placement in models.

	As an example, consider the following Complete OCL document:

	!{width:70%}images/6320-extlibrary.png(External Library)!
	"[Text for cut and paste]":../references/6320-extlibrary.ocl

	h3. The OCL Input

	The Pivot binding provides a UML-aligned representation and so a Complete OCL document can be parsed to provide a similar Resource to that
	derived from a UML or Ecore metamodel. A @Root@ contains a @Model@ which contains @Package@==s==
	and @Class@==es==. The complementing Resource from the Complete OCL document is independent of the similarly structured
	complemented Resource of the completed metamodel.

	The Pivot binding uses an Xtext parser with a UML-aligned output. The input text is therefore specified by
	a URI and loaded by the Xtext parser to create a Concrete Syntax Resource. This may then be converted to the Pivot Abstract Syntax Resource. The Abstract Syntax Resource has a conventional Model, Package, Class, Operation hierarchy in order to provide a coherent composition context for the Constraints.

	The elements of the independent complementing and complemented Resources are merged within @CompleteClass@==es== and
	@CompletePackage@==s== of the @CompleteModel@ managed behind the OCL facade.

	There are therefore two @Class@ objects named Library, one for each Resource. The objects are distinct in so far as they belong to different resources, which can be separately serialized, and in so far as they may appear distinct to OCL expressions that use reflective access. However they are logically merged and the @CompleteEnvironment@ provides utility methods that allow the multiple objects to be accessed as a merged object.

	bq.
	The Ecore binding provided an @OCLInput@ class to supervise the OCL source text, and the result of parsing the document was a @List<Constraint>@.
	p.

	The Complete OCL document is a textual Resource with an associated text tooling. The @OCL@ facade provides
	an API to load a Resource from a given @URI@.

	!{width:70%}images/6320-parsing.png(Parsing the Constraints)!
	"[Text for cut and paste]":../references/6320-parsing.txt

	h3. Traversing the Constraints

	The parsed resurce can be traversed in the same way as other EMF resources.

	!{width:70%}images/6320-traversing.png(Traversing the Constraints)!
	"[Text for cut and paste]":../references/6320-traversing.txt

	h3. Accessing the Constraints

	The contents of the Complete OCL document contribute to a @CompleteModel@ that merges all the contributions.
	The contributions can therefore be used as if defined in a primary metamodel.

	!{width:70%}images/6320-accessing.png(Accessing the Constraints)!
	"[Text for cut and paste]":../references/6320-accessing.txt

	h3. Using the Constraints to Validate a Model

	The standard EMF validation makes use of an @EValidatorRegistry@ that maps the URI of an @EPackage@ to the
	derived @EValidator@ that provides the constraints appilcable to the @EPackage@. If we want to exploit
	additional constraints defined in a Complete OCL document, we must extend the underlying @EValidator@.
	The @ComposedValidator@ enables multiple @EValidator@ to be composed and to behave as a single
	@EValidator@. @ComposedEValidator.install()@ replaces the single @EValidator@ by a composite
	initially containing just the replaced @EValidator@. A @CompleteOCLEObjectValidator@ provides the additional validation of the given @uri@ and @EPackage@.

	!{width:70%}images/6320-validating.png(Validating the Constraints)!
	"[Text for cut and paste]":../references/6320-validating.txt

	The standard @Diagnostician@ does not directly support validation of a @Resource@.
	@MyDiagnostician@ remedies this deficiency and provides a @SubstitutionLabelProvider@
	that provides slightly better labels within OCL diagnostics.

	!{width:70%}images/6320-diagnostician.png(Extended Diagnostician)!
	"[Text for cut and paste]":../references/6320-diagnostician.txt

	The source for these examples may be found in the org.eclipse.ocl.examples.xtext.tests plugin in model/parsingDocumentsExample.ocl and in src/org/eclipse/ocl/examples/test/xtext/PivotDocumentationExamples.java.