# Relation

We consider in this chapter only the relations between classes. To add a relation to a class you have to use a class diagram (obviously the diagram or the relation drawing may be deleted just after !), it is not possible to add a relation through the browser. It is also not possible to move a relation into an other class or elsewhere.

The icon in the browser indicates if the relation is public (+), protected (#), private (-) or package (~). The protected and package visibilities are translated in private in Idl. The package visibility is translated in private in C++, and doesn't produce a visibility in Php (use this case to produce Php 4 code). A class relation is underlined.

A bi-directional relation is supported by two relation items in the browser.

A relation have a name, a stereotype, may have one or two roles and multiplicity (one by direction). Note that it is not possible to specify a stereotype for each direction of a bi directional relation, frankly I avow that the main reason is to simplify as it is possible the drawing of the relations in the diagrams with the associated labels.

In the browser are written the name of the relations (by default its kind) between parenthesis, the role(s) of the associations and aggregations, the end class of the generalization, realization and dependency. The stereotype may be may be showed/hidden through the Miscellaneous menu. The name of a relation is not used by the code generators.

Generally the relation's stereotype is used to specify how a relation with a multiplicitydifferent than 1 is translated in each language, for instance to produce a vector. The friend stereotype is a special case for a dependency and is used to produce a C++ friend declaration.

There are several kinds of relation :

- generalization : to produce an inheritance

- realization : produce also an inheritance, the code generators do not distinguish a realization and a generalization.

- dependency : only the dependency having the stereotype friend are considered by the C++ code generator.

- unidirectional association : to define a directional relation, the code generators will produce an attribute having the role name. In C++ the default generated code use pointer(s).

- directional aggregation : to define a directional relation, the code generators do not distinguish association and aggregation.

- directional composition (directional aggregation by value) : to define a directional composition, the code generators will produce an attribute having the role name. In C++ the default generated code does not use pointer(s).

- association : to define a bi-directional relation, the code generators will produce two attributes whose names are the roles's name.

- aggregation : to define a bi-directional aggregation, the code generators will produce two attributes whose names are the roles's name. This kind of relation may considered to be a shortcut to define two (directional) aggregations.

- composition (aggregation by value) : to define a bi-directional composition, the code generators will produce two attributes whose names are the roles's name. This kind of relation may considered to be a shortcut to define two (directional) aggregations by value.

By default, the example above produce the following codes (the visibility may be replaced by var to be compatible with Php 4) :

C++ | Java | Php | Idl
    class C : public C3 {
      protected:
        C * dir_a;
        C * dir_b;
        C2 * theC2;
    };

    class C2 {
      protected:
        C * theC;
        C2 a;
      friend class C3;
    };
    class C extends C3 {
      protected C dir_a;
      protected C dir_b;
      protected C2 theC2;
    }

    class C2 {
      protected C theC;
      protected C2 a;
    }
    class C extends C3 {
      protected $dir_a;
      protected $dir_b;
      protected $theC2;
    }

    class C2 {
      protected $theC;
      protected $a;
    }
    valuetype C : C3 {
      private C dir_a;
      private C dir_b;
      private C2 theC2;
    };

    valuetype C2 {
      private C theC;
      private C2 a;
    };

The multiplicity and stereotype may be used to produce the appropriate code with a natural and intuitive way. For instance the C's relation theC2 with the stereotype vector and multiplicity * will produce (depending on the generation settings) :

C++ | Java | Idl
    vector<C2 *> theC2;
    protected Vector theC2;
    private sequence<C2> theC2;

With the stereotype vector and the multiplicity 12, the C's relation theC2 will produce (depending on the generation settings) :

C++ | Java | Idl
    C2 * theC2[12];
    protected C2[] theC2;
    private sequence<C2,12> theC2;

Refer to the C++ Generator, Java generator, Php Generator, Python Generator and Idl generator for additional information.

## Menus

The relation menu appearing with a right mouse click on its representation in the browser is something like these, supposing it is not read-only nor deleted (see also menu in a diagram) :

### Menu : edit

edit allows to show/modify the relations properties. In case the relation is read-only, the fields of the dialog are also read-only.

#### Relation dialog, tab Uml

The tab Uml is a global tab, independent of the language :

Here the two roles are editable because the relation is bi-directional, and because it is an association or aggregation.

The default name of a relation is its kind between < and >, for instance <association>, the default name does not appears in a diagram.

It is possible to change the kind of the relation through the combo box type, but it is not possible to reverse a relation, the role A is always attached to the start class used to draw the relation, and the role B is only available when the relation is bi-directional.

The proposed stereotypes are the default ones specified through the Default stereotypes dialog more the current one (empty here). It is possible to choose into the list or to give a new one, or to empty it. The stereotype and the multiplicity are used both (may be with the stereotype of the class(es) in Idl) to compute the default declaration.

Association allows to define a class association, to produce it in the generated code use the keyword ${association}

By default, the names of the generated attributes are the role names.

The multiplicity is used to compute the default declaration and the generated code for each language, the proposed ones are not the alone know by the code generators, you may also use a number or a number between [] (they are not distinguished by BOUML) to specify a vector, or a sequence or numbers each between [] to specify a multi dimensioned array.

The initial value give the default value of the generated attribute(s), in C++ it is taken into account only when the relation is a class relation (static). By default the generated form is exactly the one you give, this means that you have to give the '=' when it must be generated, this allows to give the arguments of a constructor.

The visibility may be chosen with the radio buttons, the relations have a default visibility set through the class settings :

By default the description is used to produce comments by the code generators.

The editor button visible above and associated here to the description and initial value, allows to edit the description or initial value in an other window, or to call an external editor (for instance Xcoral) specified through the environment dialog. Note that this external editor have to create an own window, its parameter is the pathname of the file containing the description, its execution is done in parallel with BOUML which looks each second at the file contents to get the new definition until the dialog is closed (I do not like very much this polling but this works even QT isn't compiled with the thread support).

The default button visible above associated to the description allows to set the description with a default contain specified through the generation settings. Useful to generate comments compatible Java Doc or Doxygen for instance.

#### Relation dialog, tab C++

This tab allows to give the C++ definition of the relation, it is visible only when C++ is set through the Languages menu

For an association or an aggregation without multiplicity :

for a generalization, realization or a dependency :

In BOUML the generated code is obtained by the substitution of macros in a text, only the Declaration part is editable, the other one help you to see what will be generated for C++ (supposing you do not modify the C++ code generator !).

When you push the button default declaration, the form specified through the generation settings depending on the stereotype and multiplicity (and of course the language !) is proposed, this last may be modified as you want, even to produce illegal source code.

When you do not want to have this relation defined in C++, empties the declaration manually or using the button not generated in C++.

It is possible to follow the visibility as it is set in the UML Tab or to change it.

${static} produce an empty string when the relation is not an class relation (see the UML tab), else produce static

${const} produce an empty string when the relation is not read only (see the UML tab), else produce const

${type} is replaced by the class pointed by the relation (see the UML tab)

${name} is replaced by the relation's role name (see the UML tab)

${inverse_name} is replaced by the name of the inverse role (see the UML tab)

${stereotype} is replaced by the stereotype translated in C++ (first tab of the generation setting dialog)

${multiplicity} is replaced by the multiplicity (see the UML tab)

${value} is replaced in the source file by the initial value of the relation (see the UML tab)

${h_value} is replaced in the header file by the initial value of the relation (see the UML tab)

${mutable} produce an empty string when the check box mutable is not checked, else produce mutable

${volatile} produce an empty string when the check box volatile is not checked (see the UML tab), else produce volatile

${association} produce the association (may be the class forming a class-association with the relation)

The forms @{property} are replaced by the value of the corresponding user property if it is defined for the class or at an upper level, else it is not substituted.

When the check box virtual is checked the inheritance is virtual.

Refer to the generation settings and the C++ Generator for more details and explanation of the other keywords.

#### Relation dialog, tab Java

This tab allows to give the Java definition of the relation, it is visible only when Java is set through the Languages menu

For an association or an aggregation without multiplicity :

In BOUML the generated code is obtained by the substitution of macros in a text, only the Declaration part is editable, the other one help you to see what will be generated for Java (supposing you do not modify the Java code generator !).

When you push the button default declaration, the form specified through the generation settings depending on the stereotype and multiplicity (and of course the language !) is proposed, this last may be modified as you want, even to produce illegal source code.

When you do not want to have this relation defined in Java, empties the declaration manually or using the button not generated in Java.

It is possible to follow the visibility as it is set in the UML Tab or to change it replacing ${visibility} by the desired one.

${static} produce an empty string when the relation is not an class relation (see the UML tab), else produce static

${final} produce an empty string when the relation is not read only (see the UML tab), else produce final

${volatile} produce an empty string when the check box volatile is not checked (see the UML tab), else produce volatile

${transient} produce an empty string when check box transient is not checked, else produce transient

${type} is replaced by the class pointed by the relation (see the UML tab)

${stereotype} is replaced by the stereotype translated in Java (first tab of the generation setting dialog)

${multiplicity} is replaced by the multiplicity, a form [123] become [], (see the UML tab)

${name} is replaced by the relation's role name (see the UML tab)

${inverse_name} is replaced by the name of the inverse role (see the UML tab)

${value} is replaced by the initial value of the relation (see the UML tab)

${association} produce the association (may be the class forming a class-association with the relation)

${@} produces the annotations, when it is present in the definition the button Edit annotation is active, a specific dialog allows you to enter the annotations proposing the default annotations (Deprecated ...) and the ones defined through the classes stereotyped @interface :

The forms @{property} are replaced by the value of the corresponding user property if it is defined for the class or at an upper level, else it is not substituted.

Refer to the generation settings and Java generator for more details and explanation of the other keywords.

#### Relation dialog, tab Php

This tab allows to give the Php definition of the relation, it is visible only when Php is set through the Languages menu

In BOUML the generated code is obtained by the substitution of macros in a text, only the Declaration part is editable, the other one help you to see what will be generated for Php (supposing you do not modify the Php code generator !).

When you push the button default declaration, the form specified through the generation settings depending on the stereotype and multiplicity (and of course the language !) is proposed, this last may be modified as you want, even to produce illegal source code.

When you do not want to have this relation defined in Php, empties the declaration manually or using the button not generated in Php.

It is possible to follow the visibility as it is set in the UML Tab or to change it replacing ${visibility} by the desired one, to not generate the visibility set it to package

${static} produce an empty string when the relation is not an class relation (see the UML tab), else produce static

${const} produce an empty string when the relation is not read only (see the UML tab), else produce const

${var} produce var when the relation is not read only nor static(see the UML tab) and the visibility is not package, else produce an empty string

${name} is replaced by the relation's role name (see the UML tab)

${inverse_name} is replaced by the name of the inverse role (see the UML tab)

${value} is replaced by the initial value of the relation (see the UML tab)

The forms @{property} are replaced by the value of the corresponding user property if it is defined for the class or at an upper level, else it is not substituted.

Refer to the generation settings and Php generator for more details and explanation of the other keywords.

#### Relation dialog, tab Python

This tab allows to give the Python definition of the relation, it is visible only when Python is set through the Languages menu

For an association or an aggregation without multiplicity or having the multiplicity 1:

In BOUML the generated code is obtained by the substitution of macros in a text, only the Declaration part is editable, the other one help you to see what will be generated for Java (supposing you do not modify the Java code generator !).

When you push the button default declaration, the form specified through the generation settings depending on the stereotype and multiplicity (and of course the language !) is proposed, this last may be modified as you want, even to produce illegal source code.

When you do not want to have this relation defined in Java, empties the declaration manually or using the button not generated in Python.

The instance relations are automatically produced at the beginning of the body of the operation __init__ (this operation is produced for each class even when you don't define it). The static relation are produced inside the class definition.

${comment} produces a comment from the UML description, adding a # at the beginning or each line, following the current indent. A newline is produced if needed at the end to not have something else generated on the same line after the comment.

${description} is like for ${comment} but without adding #.

${self} inside the operation __init__ this produces the name of the first parameter followed by a dot, else nothing.

${type} produces the type of the relation, it is used by default when the relation is a composition to create an instance of this type, can also be used in a comment for a form @var

${multiplicity} produces the multiplicity of the relation, probably used inside a comment

${stereotype} is replaced by the translation in Python of the relation's stereotype (see the UML tab)

${name} is replaced by the role name (see the UML tab)

${inverse_name} is replaced by the name of the inverse role (see the UML tab)

${value} is replaced by the initial value of the relation (see UML tab) if it is not empty, else None

${association} produce the association (may be the class forming a class-association with the relation)

The forms @{property} are replaced by the value of the corresponding user property if it is defined for the class or at an upper level, else it is not substituted.

Refer to the generation settings and Python generator for more details and explanation of the other keywords.

#### Relation dialog, tab Idl

This tab allows to give the Idl definition of the relation, it is visible only when Idl is set through the Languages menu

For an association or an aggregation without multiplicity :

In BOUML the generated code is obtained by the substitution of macros in a text, only the Declaration part is editable, the other one help you to see what will be generated for Idl (supposing you do not modify the Idl code generator !).

When you push the button default declaration, the form specified through the generation settings depending on the stereotype of the class, the stereotype and multiplicity of the relation (and of course the language !) is proposed, this last may be modified as you want, even to produce illegal source code.

When you do not want to have this relation defined in Idl, empties the declaration manually or using the button not generated in Idl

It is possible to follow the visibility as it is set in the UML Tab or to change it replacing ${visibility} by the desired one.

${type} is replaced by the class pointed by the relation (see the UML tab)

${name} is replaced by the relation's role name (see the UML tab)

${inverse_name} is replaced by the name of the inverse role (see the UML tab)

The check box truncatable is available when the relation is an attribute or a generalization or a realization, and allows to produce the Idl keyword truncatable.

The forms @{property} are replaced by the value of the corresponding user property if it is defined for the class or at an upper level, else it is not substituted.

Refer to the generation settings and Idl generator for more details and explanation of the other keywords.

### Menu : duplicate

The menu entry duplicate clone the relation in the two directions when the relation is bi-directional. The name of the role(s) is empty in the new relation(s).

### Menu : add ...

These entries allow to produce get and set operations on the relation, contrarily to the similar operations made by hand, these two ones are linked to the associated relation to be updated, or deleted when the relations is deleted. The default name of the operations and their characteristics are set through the generation settings.

By default, the get and set operations generated for the C's relation theC2 are :

C++ | Java | Php
    inline const C2 * C::get_theC2() const {
      return theC2;
    }

    void C::set_theC2(C2 * value) {
      theC2 = value;
    }
    public final C2 get_theC2() {
      return theC2;
    }

    public void set_theC2(C2 value) {
      theC2 = value;
    }
    final public function getTheC2()
    {
      return $this->theC2;
    }

    public function setTheC2($value)
    {
      $this->theC2 = $value;
    }

Python | Idl
    def getTheC2(self):
        return self.theC2

    def setTheC2(self, value):
        self.theC2 = value
    C2 get_theC2();

    void set_theC2(C2 value);

### Menu : delete

The menu entry delete is only present when the relation is not read-only.

Delete the relation, associated get and set operations when they exist, and all the representation of them in the opened diagrams. After that it is possible to undelete them (from the browser) until you close the project : obviously the deleted items are not saved !

### Menu : mark

See mark

## Default stereotypes

The dialog allowing to set the default stereotypes has a tab reserved for the relations :

As you can see it is possible to specify a default stereotypes list for each kind of relation. Associated to a multiplicity the stereotype is used by the code generators to produce the desired forms, the translation in each language of the UML stereotype is specified through the generation settings.

## Generation settings

This very important dialog allows to specify many default definitions concerning the relations, more details will be given in C++ generator, Java generator, Python generator and Idl generator.

The tab Stereotypes allows to specify how the relation's stereotypes are translated in each language except Php :

As usual the last column do allows to copy/past/cut/insert line and applies on the line where you did the mouse click.

The third C++ tab allows to specify the default C++ generated code for the relations :

The fourth C++ tab allows to specify the get and set operations specificities in C++ :

The form in from of also in uml allows to specify the name of the operation in C++, the same rule is followed in UML if also in uml is set.

The second Java tab allows to specify the default Java generated code for the relations in Java :

The third Java tab allows to specify the get and set operations specificities in Java :

The form in from of also in uml allows to specify the name of the operation in Java, the same rule is followed in UML if also in uml is set.

The second Php tab allows to specify the default Php generated code for the relations and to specify the get and set operations specificities in Php :

The form in from of also in uml allows to specify the name of the operation in Php, the same rule is followed in UML if also in uml is set.

The second Python tab allows to specify the default Python generated code for the relations and to specify the get and set operations specificities in Python :

The form in from of also in uml allows to specify the name of the operation in Python, the same rule is followed in UML if also in uml is set.

The third Idl tab allows to specify the default Idl generated code for the relations :

At least the third Idl tab allows to specify the get and set operations specificities in Idl :

The form in from of also in uml allows to specify the name of the operation in Idl, the same rule is followed in UML if also in uml is set.

## Drawing

A relation is drawn in a diagram with a line may be with an arrow, and the associated labels : relation's name, stereotypes, role(s) and multiplicity(ies) :

When a class inherits a template class the actuals are indicated as a label of the realization :

To add a new relation between classes, select the appropriate relation through the buttons on the top of the diagram sub window, click on the start class with the left mouse button, move the mouse, each time the mouse button is raised a new line break is introduced, at least click on the end class. To abort a relation construction press the right mouse button or do a double click with the left mouse button.

A line may be broken, during its construction of after clicking on the line with the left mouse button and moving the mouse with the mouse button still pushed. To remove a line break, a double click on the point with the left mouse button is enough, or use the line break menu of the point using the right mouse button.

By default the lines go to the center of their extremities, to decenter a line click near the desired extremity and move the mouse click down. To come back to a center line, use the menu geometry

A right mouse click on a relation in a diagram or a double click with left mouse button calls the following menu (supposing the relation editable) :

### Menu : edit

To edit the relation

### Menu : select labels

To select the labels (relation's name, stereotypes, role(s) and multiplicity(ies)) associated to the relation. Useful when you are lost after many label movings.

### Menu : labels default position

To place the labels (relation's name, stereotypes, role(s) and multiplicity(ies)) associated to the relation in the default position. Useful when you are lost after many label movings.

By default when you move a class or a relation point break or edit the relation, the associated labels are moved to their default position, this may be irritating. To ask BOUML to not move the associated labels on the relations in a diagram, use the drawing settings of the diagrams.

### Menu : geometry

Allows to choose one of the line geometry or to recenter a decentered line :

Note : if you manually move the central line of the last two geometries this one stop to be automatically updated when you move one of the two extremities of the relation.

### Menu : tools

Appears only when at least one plug-out is associated to the relation. To apply a plug-out on the relation.

## Drawing settings

The drawing settings associated to the relations in a diagram may be set through the the diagram itself or one of its parent, for instance :

A settings valuing default indicates that the setting specified in the upper level (here the diagram) must be followed, obviously this one may also be default ... up to the project level.

#### draw all relations :

To automatically draw or not the new relations, obviously a relation will be added in a diagram only when the start and end classes (may be the same) are drawn.

#### show relation modifier :

To automatically write or not the modifiers (read-only, ordered, unique, union)

#### show relation visibility :

To automatically write or not the visibility

#### automatic labels position :

To ask BOUML to move or to not move the associated labels on the relations in a diagram when the relation is edited or the associated class pictures moved etc ...

#### show information note :

To ask Bouml to write the relation's constraint in the note attached to the class (except if this setting is set to false on the class, or when you ask for hide at least relation's constraint).

Previous : class

Next : attribute