Appendix C: Notation Guide

This appendix describes the graphical notation used in the diagrams of this dissertation. The notation uses diagrammatic UML syntax where possible, and adds to it where necessary.

C.1 Classes and role types

A class is depicted as a rectangle, with the class name set in bold font at the top of the rectangle. If the class name is set in Italics, the class is abstract. Class and class type is used synonymously.

A role type is depicted as an oval. The name of the role type is prominently centered in the oval. Set below it, in parentheses and a smaller font, is the name of the role model the role type is defined by.

Figure C-1 depicts an example class and several example role types. Here, a class ResourceService provides the three role types Service, Provider, and Singleton of the role models ResourceService and RSSingleton, respectively. Thus, the qualified name of the role types is ResourceService.Service, RSSingleton.Provider, and RSSingleton.Singleton.

Figure C-1: Example class with role types.

Figure C-1 lets us distinguish between instance-level role types and class-level role types. An instance-level role type (a "regular" role type) is depicted as the aforementioned oval. An instance-level role type defines behavior that instances of a class conform to. A class-level role type is depicted as a rectangle (RSSingleton.Provider in Figure C-1). A class-level role type defines behavior that the class object representing the class conforms to.

Finally, Figure C-1 lets us distinguish between role types that have operations and role types that have no operations (still, expected behavior may be defined for these no-operation role types). A no-op role type is depicted with a gray mark in the upper right corner. Examples are the ResourceService.Client, the RSSingleton.Client, and the RSSingleton.Singleton role types. This property applies to instance-level and class-level role types alike.

Classes may relate to each other using class inheritance. Figure C-2 shows how the ResourceService class inherits from an abstract Service class (is a subclass of it).

Figure C-2: Class inheritance.

The arrow inheritance symbol in Figure C-2 is taken from UML. See Chapter 3 for a discussion of the semantics of class inheritance in the context of role modeling.

C.2 Object relationships

Object relationship descriptions are relationships between types that constrain how objects conforming to these types may reference each other at runtime. Object relationship descriptions only relate the same kind of types with each other: class types with class types and role types with role types. Also, when connecting role types, object relationship descriptions are constrained to connect only role types of the same the role model.

Object relationship descriptions are depicted as connections between types. All relationship descriptions can be annotated with further information like direction and cardinality. Their meaning is taken from UML.

Figure C-3 shows three object relationship descriptions between role types as they may occur in a role model.

Figure C-3: Object relationships in role models

These three cases have the following meaning:

1. The arrow between the Client role type and the Service role type depicts a unidirectional use-relationship between an object playing the Client role and an object playing the Service role.
2. The line between the Client role type and the Service role type depicts a bi-directional use-relationship between objects, each of which plays one of the roles.
3. The diamond at the start of the arrow indicates ownership of the object pointed at, and the star at the end of the arrow indicates a cardinality of many (following UML rules).

The scoping of the object relationship descriptions by a role model or class model is important. No role type may relate to a role type from another role model by an object relationship description. See Chapter 3 for a discussion of how classes and role types relate to each other with respect to object relationship descriptions.

C.3 Class and role models

A class model is a set of interrelated classes, tied together by class inheritance and object relationship descriptions. A role model is a set of role types, tied together by role constraints (see below) and object relationship descriptions.

Figure C-4 shows three example role models, one binary, two ternary. The role model name is set below the role type name. The role model name qualifies the role type name so that role types with the same name, for example the three Client role types, can be distinguished.

Figure C-4: Three example role models.

Figure C-5 shows one class model, consisting of three classes, and three example role models (from above).

Figure C-5: Example class model.

The example class model does not show its free role types. Free role types are color-coded with a gray background (see the section on frameworks below).

C.4 Role constraints

Role constraints are values that define how roles played according to two role types from the same role model may come together in one object. For any given pair of role types, there is one role constraint value. The default value is role-dontcare (see below).

Role constraints are depicted as connections between role types. Figure C-6 shows the four different role constraints that may occur in a role model.

Figure C-6: Role constraints in a role model.

These four cases have the following meaning:

1. Role-implied. The white-headed unidirectional arrow depicts a role-implied role constraint. The role constraint value of (Parent, Node) is role-implied, the role relationship value of (Node, Parent) is role-dontcare.
2. Role-equivalent. The white-headed bi-directional arrow depicts a role-equivalent role constraint. The role constraint value of both (Subject, Root) and (Root, Subject) is role-equivalent.
3. Role-prohibited. The bar-headed bi-directional arrow depicts a role-prohibited role constraint. The role constraint value of both (Child, Root) and (Root, Child) is role-prohibited.
4. Role-dontcare. The missing of a symbol depicts a role-dontcare role constraint. The role constraint value of both (Client, RootClient) and (RootClient, Client) is role-dontcare.

Role constraints connect role types within one role model. A role-prohibited constraint is scoped by the runtime object collaboration task. It is possible for an object to play roles according to two different role types (even if there is a role-prohibited constraint between them) given that these roles are played in different role model instances, that is different object collaboration tasks.

C.5 Role model shorthands

Some role model compositions keep recurring throughout the examples. The primary examples are Object Creation and Singleton Access. Therefore, the dissertation uses shorthands to conveniently represent these recurring compositions as one single role model. Such a shorthand is much like a template in that it needs to be applied and adapted to a specific situation.

Figure C-7 shows an example of the applied Object Creation shorthand, here for the creation of a ResourceService instance.

Figure C-7: Object Creation shorthand, applied to the ResourceService example.

Figure C-8 shows the expanded form of the Object Creation shorthand.

Figure C-8: Expanded form of the applied Object Creation shorthand.

Figure C-9 shows an example of the Singleton Access shorthand, here for the access to a single ResourceService instance.

Figure C-9: Singleton Access shorthand, applied to the ResourceService example.

Figure C-10 shows the expanded form of the Singleton Access shorthand.

Figure C-10: Expanded form of the Singleton Access shorthand.

Another candidate for a shorthand is the composition of a Manager role model, in which a Manager object maintains a dictionary of Elements, with the lookup functionality of a dictionary and its key objects.

Composite (compound) pattern applications [Rie97c] are not a suitable subjects for shorthands, because it is important to see the constituting role models. Shorthands should be used only for trivial role model compositions.

If non-trivial role model compositions are needed frequently and lead to cluttering up the figures, an explicit semantic construct for composing role models can be introduced and given a diagrammatic representation.

C.6 Frameworks

Frameworks are class models with well-defined boundaries. A visual border with the framework's name attached to it surrounds the framework classes. Also, free role types of the framework are color-coded in gray.

Figure C-11 shows a simple framework based on the Service and Starter class model from above.

Figure C-11: Example framework.

The framework comprises the Service, Starter, and ChainedStarter classes. It offers three free role types for client classes to pick up: Service.Client, Starter.Client, and ChainedStarter.Client. The color-coding of these free role types is maintained, even if they are assigned to classes in a client context, because they are still free for other clients to pick them up.