
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.3.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.

