(This documentation applies to Papyrus 3.0.0 and Eclipse Oxygen.)
The OCL in UML (using Papyrus) section shows how Papyrus may be used to create and maintain OCL expressions that enrich a UML model or profile.
In this section we show how some simple and not so simple OCL examples can solve useful specification problems.
OCL Constraints may be specified at any meta-level. A class-level defines the types and properties that are used by the instance-level. The OCL constraints validate that the instances are compliant. The OCL therefore executes on instances of the instance-level using the types and properties of the class-level.
A Constraint may be used just to document the design intent, but given an appropriate environment a constraint may be tested and/or used to verify the consistency of models. This may be
-
a test model defined by using UML InstanceSpecification to instantiate the UML model.
-
a live model created by instantiating the Ecore equivalent of the UML model
-
a UML model that conforms to a UML profile
In all cases when a validation of the model is requested, the validator attempts to execute each possible constraint on each possible instance to which it applies. When executing the constraint, the validator binds the
self variable to the instance to be validated. The type of
self is determined by the context of the Constraint. In Papyrus this context is determined by the non-Constraint end of the
<<context>> link from Constraint. The result of evaluating a Constraint should
true or
false. If
true, the constraint is satisfied. If
false the constraint is violated and some diagnostic should be shown to the user.
In Model Constraints, we provide examples that apply to the elements of UML model. The Constraints are evaluated on the instances of the model. How violations are diagnosed depends on the synthesis of model instances and the corresponding run-time environment.
In Profile Constraints, we provide examples that apply to the elements of a UML profile. The Constraints are evaluated to verify consistent usage of the elements in the model. Violations are diagnosed within the UML editor.
The figure shows a metamodel specified in UML as a Papyrus Class Diagram. The upper half shows a simple metamodel comprising just a
Person class. A
Person has a
String-valued
name and may have a
partner,
parents and/or
children.
Some constraints such as the
parents[0..2] limitation on the the number of parents to 2 may be specified directly using UML capabilities without any use of OCL. But many more challenging restrictions require OCL constraints, for which five examples are provided in the lower half of the figure.
To help understand the way in which OCL evaluates, it is helpful to consider some instances that conform to the constrained model
The figure shows a model comprising three persons whose names are
father,
mother and
baby.
The notation in the figure is similar to a UML Object Diagram. This should be drawable in Papyrus, unfortunately a number of bugs prevent this in the Oxygen release of Papyrus. The notation deviates slightly from UML by only underlining type name, and by using rounded rectangles to distinguish DataType values from Class instances.
The three instances of
Person are shown as three rectangles, with an instance name such as
pa and underlined type
Person. The three names are shown as rounded rectangles with values such as
father and type
String. The association between a
Person instance and their
name is shown by a directed link from the
Person instance to the value. The link is labelled with the relationship role which is
name.
The
partner relationship role is similarly shown by a directed link from
pa to
ma and vice-versa.
The simplest example constraint uses a regular expression to specify that the
name must consist of just alphabetic characters.
self.name.matches('[a-zA-Z]*')
The
. is the OCL Object navigation operator. It separates a cascade of navigation steps each of which returns a result value.
Evaluation starts at
self, which rather like
this in Java, is bound to an object whose type is the context of the Constraint. The result is therefore a
Person object such as
pa.
The property navigation step
name, traverses the relationship whose role is
name. The navigation steps from
pa to the
father value. The result is a String comprising
father.
The operation call step
matches('[a-zA-Z]*'), executes the regular expression matching function using the provided regex. The final result is
true or
false.
Another very simple example constraint checks that the
partner relationship does not have the same
Person as both its source and target.
self.partner <> self
The OCL comprises two navigation expressions separated by the infix
<> operator.
The first,
self.partner, navigates from
self to compute a result comprising the
partner of the
self context instance.
The second,
self just returns the context instance.
The not-equals
<> infix operator compares its preceding and following arguments and provides a
true result when the arguments are not-equal,
false when equal.
The one-to-one relationships between objects and values have a simple implementation typically involving a pointer. One-to-many and many-to-many relationships are more complex since a collection of values is involved.
The figure above elaborates the earlier figure to show the to-many relationships. The figure also uses a simpler representation of the object to value relationships by embedding each
name value within its
Person instance. One-to-one object relationships such as
partner are unaffected. To-many relationships such as
parents are shown using a multi-object drawn as three overlaid rectangles. Each multi-object is typically a collection owned by the relationship source and shown by a solid arrow labelled with the relationship name. Each element of the collection is identified by a dashed arrow.
child therefore has two
parents;
pa and
ma. Many-to-many relationships are convently realized as independent one-to-many relationships in each direction. The
children opposite of
parents is therefore shown by a
children multi-object for each parent identifying the one child.
When Ecore is used to implement UML, the multi-object is realized in exactly this way by an
EList.
OCL provides an ability to use these multi-objects within expressions. The multi-object is a
Collection, or more specifically a
Bag,
OrderedSet,
Sequence or
Set depending on whether the to-many-relationship is specified to be
ordered and/or
unique.
In OCL,
-> is the collection navigation operator that enables an evaluation to exploit all the target objects.
Each child should have two parents, but in any finite model there must be some
Person instances for which the parents are omitted. Hence the model specifies a [0..2] multiplicity rather than precisely [2..2]. We may remedy this deficiency with an OCL constraint.
self.children->forAll(child | child.parents->size() = 2)
The
self and
children navigate from the context object to locate the collection of all children of the context instance as the navigation result.
The
-> collection operator and the subsequent
forAll(child | ...) iteration cause an iteration to be performed over the children, assigning each child in turn to the
child iterator variable. The
... iterator body is evaluated for each child and accumulated so that the result of the
forAll is only
true if the body evaluation for each
child is also
true.
The iteration body navigates from each
child to select the collection of all of its
parents. Then the
-> collection navigation operator invokes the collection operation
size() to compute the size of the collection. This size is compared using the
= (equals) operator to the constant
2. The iteration body therefore returns
false unless the number of parents is equal to 2.
This example can be written more compactly as
children->forAll(parents->size() = 2)
since an implicit iterator is the default source for navigation within an iteration body, and
self is the default outside.
The instances of a user model often form an acyclic graph. It is therefore desirable to specify this as an OCL constraint so that any cycles are detected by an OCL model validator. This is fairly easy to specify with the help of the OCL transitive closure iteration.
self.parents->closure(parent | parent.parents)->excludes(self)
Once again the
self.parents navigation returns the collection of all parents of the context instance. This collection is used as a seed from which the
closure(parent | ... ) collection iteration grows the final result by repeatedly aggregating the result of the
... body evaluation. Each element of the interim result is bound to the
parent iterator until there are no values left in the result for which the iteration body has not been evaluated.
The
parent.parents iteration body just returns all parents of a given parent so that the closure progressively aggregates the grandparents then great-grandparents, then ...
Once the
closure completes, it returns a
Set (or
OrderedSet) of all ancestors which is passed to the the
excludes Collection operator to confirm that the
self instance is not an ancestor of itself.
This example can be written more compactly as
parents->closure(parents)->excludes(self)
A user model may not always allow arbitrary relationships between its instances. An OCL constraint can impose discipline, and within a more complex OCL constraint one or more let-variables may provide structure that aids readability.
In our example we may wish to impose a requirement that the two parents of a child are partners.
let selfAndPartner = self.oclAsSet()->including(self.partner) in
self.children->forAll(child | selfAndPartner->includesAll(child.parents))
The
let selfAndPartner ... in ... assigns the value of a first
... expression to the
selfAndPartner let-variable so that
selfAndPartner can then be used in the evaluation of the second
... expression that provides the final result. The let-variable allows a sub-computation to be re-used many times, or just to be assigned to a readable name.
The let-variable is computed by first using
self.oclAsSet() to compute a single element Set containing
self It then uses the collection operation
including(self.partner) to compute another set containing all (one) elements of the original set and also including another element. The result is therefore a set of the two elements,
self and
self.partner.
As before
self.children->forAll(child | ...) binds each child to the
child iterator and requires that the
... body evaluates to
true for all values of
child. The body verifies that the pair of persons cached in the
selfAndPartner includes each person identified by
child.parents.
This example can be written more compactly as
let selfAndPartner = self->including(partner) in
children->forAll(selfAndPartner = parents)
The more compact form exploits an implicit invocation of
oclAsSet() that occurs when a
-> collection navigation operator has a non-collection as its source.
Eliminating the explicit
child iterator from the
forAll iteration is permissible but perhaps unwise since an occasional OCL user may struggle to understand whether the final
parents is
self.parents or
child.parents.
A UML Profile provides an ability to extend an existing metamodel by defining Stereotypes that may be added to elements of the metamodel. The
Ecore.profile.uml which annotates
UML.uml to define the Eclipse UML support is a good example of such usage. The contrived example here that extends a single class metamodel would be much better realized by a new metamodel.
Our contrived example provides two forms of extension,
Gender and
Role intended for a
Person element, but since we are defining a profile we must define the extension for
Person's metaclass which is
Class. We also define another extension,
Vehicle, that is sensible for a
Class but clearly stupid for a
Person.
A
Person may have a
Gender defined as an abstract stereotype from which the concrete
Male and
Female stereotypes derive.
A
Person may have one or more
Role's defined as an abstract stereotype from which the concrete
Astronaut and
Priest stereotypes derive. A
Priest provides an additional
priesthood enumeration property that identifies the religious affiliation of the priest.
These definitions are drawn as an extension link from a base stereotype such as
Gender, to a metaclass, such as
Class. The link is a UML
Extension that is a form of
Association and so has two automatically synthesized
Property elements for its ends. The property role names are derived by applying
base_ or
extension_ prefixes to the target class/metaclass names. The
base_Class property therefore identifies the
Class metaclass end of the
Extension, and the
extension_Gender identifies the
Gender end.
The
extension_ property has a multiplicity for which [0..1] specifies that at most one application of the
Gender stereotype is permissible. Alternatively a [0..*] multiplicity specifies that zero or more applications of the
Role stereotype are possible; a priest may also be an astronaut. Specification of non-zero lowerbounds is possible but not generally appropriate since the application is to the metaclass. Mandating that a
Gender is always applied leads to stupidities if a completely independent class such as an
Road are also modeled.
The extension multiplicity provides a very limited imposition of design rules on the use of the stereotypes. Generally much more complex rules requiring OCL constraints are required. Four examples are shown and explained later.
(The Oxygen release of Papyrus provides a misleading editing interface for stereotype multiplicities. Use only the advanced properties after selecting the extension in the Model Explorer View).
The application of stereotypes is relatively straightforward and not the topic of this section. A profile is applied to the model, so that its stereotypes can be applied to the elements.
Applied stereotypes are shown within guilemets. The example above shows definition of a derived
Person class named
Priestess to which the
Female and
Priest stereotypes have been applied. Not shown in the diagram, is the definition of the
Priest::priesthood metaproperty with the
RABBI value.
The UML representation is deceptively simple and consequently rather confusing when writing OCL constraints. We need to look at the equivalent object model that the OCL evaluation uses.
The figure shows just the
Priestess class. In the centre, an instance of the
Class metaclass is instantiated as a
Class named
Priestess with the inherited String-valued
Property named
name. Each
Stereotype metaclass is instantiated as an element without a type specification. The elements are named
Priest and
Female.
The type specification is missing because the UML specification has no primary need for the concept of a stereotype instance. This omission leads to a complexity in the XMI serialization for UML. The omitted type is indicated by the guilemets surrounding the names.
The relationships between
Priestess and
«Female» show the synthesized
base_Class and
extension_Gender relationships. Note that it is
extension_Gender rather than
extension_Female since the profile defined
Gender as an extension of the
Class metaclass.
Female is a derivation of the defined extension.
The relationships between
Priestess and
«Priest» are more complex since more than one
Role may be applied. The
extension_Role therefore identifies a collection of zero or more
Role's. The example shows that the collection contains just the one
«Priest» element.
We may now examine some example constraints to see how this model is used by constraint evaluation.
A simple example constraint on an abstract
«Gender» stereotype confirms that only one of the
«Female» or
«Male» stereotypes is applied.
let gender = self.base_Class.extension_Gender in
gender.oclIsKindOf(Male) <> gender.oclIsKindOf(Female)
The navigation starts with
self bound to a
«Gender» instance since that is the
«context» of the Constraint definition. Navigation to
base_Class locates the instance of
Class to which the stereotype is provided. The further navigation to
extension_Gender locates a
«Gender» instance for any corresponding application of the stereotype. This instance is saved in the
gender let-variable.
The subsequent operation navigation from
gender using
oclIsKindOf(Male) returns
true if
gender is a
Male stereotype instance,
false otherwise. The similar test for
oclIsKindOf(Female) is compared so that the constraint is only
true when the applied stereotypes differ.
This Constraint is somewhat redundant since the at-most-one multiplicity on a
«Gender» stereotype inhibits any double application. The let-variable
gender is therefore always the same as
self. This constraint can therefore be written more compactly as:
true
A more useful constraint mandates that every non-abstract class to which a
«Role» is applied also has an application of the
«Gender» stereotype.
not self.base_Class.isAbstract implies
self.base_Class.extension_Gender <> null
When this is evaluated for our single instance example model, evaluation starts with
self bound to the
«Priest» stereotype instance since the
«context» of the constraint definition is the
Role from which
Priest derives.
self.base_Class navigates from the
«Priest» stereotype instance to the
Priestess class instance, where the
isAbstract navigation is used to test the
UML::Class::isAbstract property to determine whether
Priestess is abstract or not.
The
x implies y infix operator is often more readable that
(not x) or y; it conveniently short-circuits evaluation of a garbage second expression when the first expression is
false. In this example the subsequent evaluation is bypassed for instances of abstract classes.
The
self.base_Class.extension_Gender navigates first to the
Priestess class instance and then on to a
«Gender» stereotype instance. This navigation returns a non-null object if there is such an instance, or
null if there is not. The
<> null comparison therefore returns
true when a
Gender stereotype has been applied; or
false when not-applied.
Note that the examples specify a relevant stereotype as the
«context». It is possible to write an identical constraint when the
Class metaclass is specified as the
«context».
not isAbstract implies
extension_Role->notEmpty() implies
extension_Gender <> null
However this is inefficient since it must be executed for all possible classes where it performs a double test ‘any Role’ then ‘check Gender’. By defining the constraint on the
Role, the first test is performed for free. Redundant evaluations for e.g.
Road elements are avoided. Of course a separate constraint that
Role should only be applied to
Person may be desirable.
base_Class.oclIsKindOf(Person)
Stronger constraints may mandate a business rule such as requiring that
CATHOLIC priests are male.
self.priesthood = Priesthood::CATHOLIC implies
self.base_Class.extension_Gender.oclIsKindOf(Male)
The left hand side of the
implies restricts the constraint to the case where the
priesthood meta-property has been assigned the
CATHOLIC enumeration value. In our single class example, a
Priestess is assigned the value
RABBI and so the test always fails. If a further
CatholicPriest class is defined, this constraint then becomes useful, since the right hand side of the
implies expression checks that the
«Gender» stereotype instance is present and is a
«Male» stereotype instance.
Since multiple
«Role» stereotype instances are permitted, we may require a business rule to prohibit the application of two
Priest stereotypes.
self.base_Class.extension_Role->selectByKind(Priest)->size() = 1
As before
self is a
«Role» stereotype instance so that navigation to
base_Class identifies the
Person class that has been stereotyped. The
extension_Role identifies the collection of all applied
Role stereotypes since multiple applications are permitted.
The
-> collection navigation operator and the collection operation
selectByKind(Priest) returns a filtered collection that selects only those stereotype instances that are, or derive from, the
Priest stereotype. The further
-> collection navigation operator and the
size() collection operation compute the size of this collection. The constraint result is
true if the size equals 1;
false otherwise.
The
->notEmpty() collection navigation and operation is convenient to test whether one or more applications of a stereotype are present.
self.base_Class.extension_Role->notEmpty()
It is not uncommon to see
->notEmpty() used when at most one application is possible.
self.base_Class.extension_Gender->notEmpty()
This is not wrong, but is slightly inefficient since it provokes the following automatic non-collection to set conversion.
self.base_Class.extension_Gender.oclAsSet()->notEmpty()
It is more efficient to write
self.base_Class.extension_Gender <> null