# Unified or Pivot Programmers Guide

The Unified or Pivot Programmers Guide describes the ways in which the Pivot binding Eclipse OCL can be used from Java programs.

The Pivot binding was first available as an examples quality prototype in 3.1.0 (Indigo). The Pivot binding became the preferred binding in 6.0.0 (Mars). The older Ecore and UML bindings are described in a separate Ecore/UML Programmers Guide.

The OCL Parser/Interpreter provides an implementation of the Object Constraint Language 2.4 specification for EMF-based metamodels and models. It offers OCL constraint and query parsing and evaluation, model-based validation, and provides an infrastructure for content assist in textual editors.

The following features are supported in the current version:

- Classifier invariant constraints

- Operation precondition and postcondition constraints and body conditions

- Property constraints (initial-value and derivation)

- Attribute and operation definitions (def: expressions)

- Package context declaration

- Basic values and types

- Collection types

- Navigation of attributes and association ends

- Operation invocation

- Iteration expressions (all standard iterators)

- Let expressions

- If expressions

- Tuples

- Message expressions, including unspecified values

- Operations predefined by OCL: allInstances(), oclIsKindOf(), oclIsTypeOf(), oclAsType(), oclIsNew()

- Escape syntax for illegal names: type, operation, attribute, etc. names that correspond to OCL reserved words can be escaped in the standard fashion using a leading underscore (‘_’). In addition, names that contain spaces or tabs can be escaped by enclosing them in double-quotes (‘"’; this is non-standard). e.g., `self.ownedRule->forAll(c : Constraint | c._context = self)`

The above constructs are supported by the parser for parsing and for evaluation, with the exception of the oclIsNew() operation and message expressions. All of the above are supported for both Ecore and UML models. The following are supported by default for UML (both in parsing and evaluation):

- Navigation of non-navigable association ends (including those that are owned by the association)

- Qualified association end navigation

- Navigation to association classes, including source qualifiers

- Operations predefined by OCL: oclIsInState()

The following features are provided in addition to the OCL specification:

- String case conversion operations: toUpper(), toLower()

- Support for comparison (<, <=, etc.) and sorting of any java `Comparable` s of conformant types

- Transitive closure of associations: closure(expr : OCLExpression) iterator

- Navigation of “hidden” opposites of references specified in Ecore models using a `Property.oppositeRoleName` annotation with source `http://schema.omg.org/spec/MOF/2.0/emof.xml` on the forward reference, producing an `OppositePropertyCallExp` expression

The OCL implementation is defined in plug-ins for convenient deployment in Eclipse, but as is the case for EMF, it can also be used stand-alone. The plug-ins are partitioned thus:

- `org.eclipse.ocl.pivot`: the neutral Pivot model, interfaces, Standard Library and evaluator.

- `org.eclipse.ocl.examples.codegen`: the OCL to Java code generator.

- `org.eclipse.ocl.examples.debug...`: the extensible debugger.

- `org.eclipse.ocl.examples.validity`: the Validation View.

- `org.eclipse.ocl.xtext...`: Xtext editors.

## Validators

When using the Pivot metamodel, there are two specialized validators available to support integration of OCL in to a larger Ecore environment.

### OCLinEcoreEObjectValidator

Unfortunately, in the Indigo release, EMF does not support this customization and so must be activated by explicitly using an EValidator that is aware of the ValidationDelegateExtension extended API. This is available by using the OCLinEcoreEObjectValidator, which you may install globally by:

`EValidator.Registry.INSTANCE.put(null, new OCLinEcoreEObjectValidator());
`

or more selectively by adjusting the inheritance of the Validator class generated by EMF from (for a model of a Company):

`import org.eclipse.emf.ecore.util.EObjectValidator;
/**
* <!-- begin-user-doc -->
* The <b>Validator</b> for the model.
* <!-- end-user-doc -->
* @see company.CompanyPackage
*/
public class CompanyValidator extends EObjectValidator {
`

to

`import org.eclipse.ocl.xtext.oclinecore.validation.OCLinEcoreEObjectValidator;
/**
* <!-- begin-user-doc -->
* The <b>Validator</b> for the model.
* <!-- end-user-doc -->
* @see company.CompanyPackage
* @generated not
*/
public class CompanyValidator extends OCLinEcoreEObjectValidator {
`

Note the @generated not that indicates that the class interface is manually defined. Do not use @generated NOT since that indicates that the whole class is manually defined.

### CompleteOCLEObjectValidator

The CompleteOCLEObjectValidator is used to enable Complete OCL documents to participate in the validation processing of an Xtext editor.

The APIs for merging Complete OCL and Ecore as intermediate Pivots and then migrating the Pivot back to Ecore are experimental.