Permalink
Browse files

Fixes #1163 better documents association classes and error 19

  • Loading branch information...
TimLethbridge committed Jan 12, 2018
1 parent d139ed8 commit 257d0db521e863738a5eca1c5bad97ac560012b3
@@ -7,11 +7,31 @@ noreferences
An association class defines an object-oriented pattern to manage * -- * (many to many) associations when data needs to be stored about each link of that association.
</p>
<p>An association class is a class and can have most of the items found in an ordinary class. However it
always has two or more 1..many associations to other classes. These are syntactically shown as just a multiplicity (usually *, but 1..* and similar cases are allowed) and the role name of association class followed by the name of participating class and participating class role name. Another syntactical format of showing these associations is multiplicity followed by the name of the participating class (and an optional role name). </p>
<p>An association class is a class and can have the items found in an ordinary class (attributes, state machines, etc.).</p>
<p>However it
always has two or more 1..many associations to other classes. Each of these is written as:
<ul>
<li>A multiplicity (usually *, but 1..* and similar cases are allowed)
<li>(optional) A role name, i.e. another name for association class in the context of this association.
<li>The name of the participating class
<li>(optional) Participating class role name.
</ul>
</p>
<p>The first role name is generally omitted. It is only required if both participating class names are the same (i.e. a reflexive association class). There is an example of this below.</p>
<p>The first example below shows classic use of association classes. A Ticket can be sold to Person in order to attend a Seminar. A Seminar can have many Persons, and a Person can attend many Seminars, so one might imagine simply creating a * -- * association between these classes. However, we want to record the ticket number and price for each Person attending each Seminar. We encode these attributes in the Ticket association class.</p>
<p>For most purposes, an association class behaves in the same manner as though it was an ordinary class with two * -- 1 associations to the participating classes (Person and Seminar in this first example). This is shown in the second example below. However, we want to restrict the possibility of having <i>more than one</i> Ticket sold to the same Person for the same Seminar. Association classes add this constraint.</p>
<p>The third example below shows that it is possible to have more than two classes participate in an association class.</p>
<p>The fourth and fifth examples show the use of the role name for the association class itself. The use of such role names is mandatory when the association class on a reflexive many-many association, i.e. the associated classes are the same. In this example there are Members (e.g. people in a club) and some are assigned to be mentors of others. We want to record the date of each assignment, and we do that using an association class. But since both associated classes are the same (Member), we need to use role names on both ends to ensure all links can be navigated unambiguously. At the Assignment end we have menteeAssignments and mentorAssignments (note the plural) and at the Member end we have roles mentor and mentee.</p>
<p>If we do not use the role names in the 5th example, then <a href="E019DuplicateAssociation.html">error 19</a> will occur because it will not be possible to refer unambiguously to either side of the association.</p>
@@syntax
[[associationClassDefinition]] [[associationClassContent]] [[singleAssociationEnd]]
@@ -31,3 +51,7 @@ always has two or more 1..many associations to other classes. These are syntacti
@@source manualexamples/AssociationClassDefinition4.ump
@@endexample
@@example
@@source manualexamples/AssociationClassDefinition5.ump
@@endexample
@@ -6,7 +6,11 @@ noreferences
<h2>Umple semantic error reported when a class is given two associations with the same name.</h2>
<p>Associations between the same classes must be given different names. This error can occur when two associations have the same role name; the solution is to change one of the role names. The error can also occur when two associations are created without any role name at all. In that case the default name is generated from the associated class. The solution is to add a role name to one of the associations.
<p>Associations between the same classes must be given different names. This error can occur when two associations have the same role name; the solution is to change one of the role names. The error can also occur when two associations are created without any role name at all. In that case the default name is generated from the associated class. The solution is to add a role name to one of the associations.</p>
<p>The first example below is a simple case where there are identical associations with no role name. The second example shows how to solve this.</p>
<p>The third example shows that error 19 can also occur with association classes. The solution to this can be found in <a href="AssociationClassDefinition.html">the manual page for association classes.</a></p>
</p>
@@ -15,4 +19,10 @@ noreferences
@@source manualexamples/E019DuplicateAssociation1.ump
@@endexample
@@example
@@source manualexamples/E019DuplicateAssociation2.ump
@@endexample
@@example
@@source manualexamples/E019DuplicateAssociation3.ump
@@endexample
@@ -1,12 +1,15 @@
// The following shows the same example as using a regular class
// Instead of an association class
// The following shows how we might model sales of Ticket for
// Seminars to Persons without using an association class.
// Note, however, that in this model, it would be possible to sell
// more than one ticket to a Person for the same Seminar.
// Using an association class would hence be better than this.
class Ticket
{
Integer ticketNumber;
Double price = 0.0;
1 -- * Person attendee;
1 -- * Seminar;
* -- 1 Person attendee;
* -- 1 Seminar;
}
class Person
@@ -0,0 +1,12 @@
// This shows a reflexive association class, where the associated classes are
// the same (Member). In this case we must use role names at both ends to ensure
// navigation to the correct sets (mentors, mentees)
class Member {
name;
}
associationClass Assignment {
Date dateEstablished;
* menteeAssignments Member mentor;
* mentorAssignments Member mentee;
}
@@ -1,4 +1,6 @@
// The following example shows how to generate this error.
// The following example shows how to generate error 19.
// The solution is to at least one role name one or both of the Y ends
// and at least one role name on one of both of the X ends.
class X {
}
@@ -0,0 +1,9 @@
// Using role names rn1 and rn2 to avoid error 19
class X {
}
class Y {
1 -- * X;
1 rn2 -- * X rn1;
}
@@ -0,0 +1,12 @@
// Example of an association class definition that generates error 19
// The solution is to add a role name such as menteeAssignments between the first * and Member
class Member {
name;
}
associationClass Assignment {
Date dateEstablished;
* Member mentor;
* Member mentee;
}

0 comments on commit 257d0db

Please sign in to comment.