11.31 Relation Object
| Used on |
|
| Description | Describes a relation between two 'entities'.
A relationship allows you traverse from one entity instance to one or more related entity instances.
In design tools, relations are modelled by drawing an association between the entities.
In CloudTranBuilder, relations are modelled as a nested element underneath the entity.
The related entity instance(s) of an entity instance are calculated by matching corresponding attributes in the two objects.
The relation is based on the primary key at one end with a corresponding foreign key at the other end.
For example, a customer object could find its related accounts by matching the customer number on all account records with its own customer number.
The foreign key must contain the same number of fields as the primary key at the other end.
If the primary key contains multiple attributes, this means the foreign key must also have multiple elements,
one for each element of the primary key: each pair of the corresponding attributes are matched individually.
The pairs of corresponding attributes are specified in <key-map> sub-elements of the relation.
Relationships can be one-way (unidirectional) or two-way (bidirectional).
In a one-way relationship, it is possible to 'traverse' only from the first entity instance to the second.
One-way relationships have <key-map> sub-elements on one end only.
In a two-way relationship, it is also possible to traverse from the second entity instance to the first.
At least one end of a relationship must have key-maps: it doesn't make sense to have a zero-way relationship!
However, it is not necessary to specify <key-map>s if you are building a new application:
The foreign-key's <key-map>s, using default names, will be automatically generated.
Of course, if you are working with a predefined database structure,
it probably won't be defined with foreign-keys that match the generated defaults;
if so, you will need to define the <key-map>s.
|
Contained
Lists |
| 1 |
| Name | keyMap |
| Type | keyMap
|
| Description | A list of foreign-key/related-key fields to map from this end's entity to related entities.
|
| GenerateAllList | false |
|
|
Inherited
properties |
|
11.31.1 Property 'cascadeDelete'
|
| Description | 'cascade-delete' specifies whether to cascade the delete of this entity to the entity or entities identified by this relation.
It normally makes sense to set this on the 'one' end of the relation -
possibly on both ends of a one-to-one relation - but probably not on a 'many' end.
|
| Type | boolean |
| Default | false |
11.31.2 Property 'collectionType'
|
| Description | By specifying the collectionType property, you are effectively defining the relation to be 'to-many';
if you do not specify collectionType, the relation is 'to-one'.
If you specify a linkTable on a relation, the relation must be bidirectional
(i.e. one end must specify the 'inverse ' property) and both ends must specify the collection type.
Currently you cannot specify 'List' or 'Map' for collectionType;
these features will be added in a future version.
- If you specify List, you can define the 'listKey' property.
- If you specify Map, you also need to define the 'collectionKey' property.
|
| Type | String |
| Choices |
|
11.31.3 Property 'description'
|
| Description | Optional description.
Use this to
- document the meaning of a particular item
- specify functionality at the design stage for implementation later.
|
| Type | String |
11.31.4 Property 'externalName'
|
| Description | This is the external name for the relation.
as it will appear on pages if the relationship is used on a page.
By default it is the same as the relation name, capitalised and spaces separating 'word'.
|
| Type | String |
11.31.5 Property 'generateTableSchema'
|
| Description | Set this flag to 'true' to generate the table schema for the link table. To prevent the automatic generation, set it to false.
This also affects descriptor generation for app servers such as WebSphere. A similar field appears on entity.
By default it is set to 'true'.
|
| Type | boolean |
| Default | true |
11.31.6 Property 'inverse'
|
| Description | This field points to the relation at the other end of a bidirectional relation.
It is optional; if it is not specified (on either end of a relationship) it implies the relationship is unidirectional.
If a relationship is bidirectional, one and only one of the relations must specify this field.
Because the inverse property implicitly identifies the type at the other end of the relation (it is the entity that owns the relation),
the 'type' property of a relation is optional if it is part of a bidirectional relation - the type can be deduced from the relation and its inverse.
The placement of the 'inverse' property - which end of the relationship it is on - determines the default location of the foreign key
for one-to-one relations: it is on the entity whose relation is not marked with "inverse".
For example, if Customer.homeAddress and Address.customer are a one-to-one bidirectional relation
and the Address.customer is the one with the inverse set,
then the Customer entity will have the foreign key, which by default is the relation name + "FK".
This naming scheme is the default; the location of the foreign key or the column names can be overridden by
specifying the KeyMap child on a relation.
The use of the 'inverse' here is a hint:
- the non-inverse has the foreign key (the relational equivalent of the direct pointer) - so it is not deduced;
- the inverse side in the one-to-one relation does not have this.
Because in distributed systems, inter-entity group relations will have to do a global search across all partitions
to traverse from the inverse to the non-inverse relation,
it is better to have the most frequently-navigated direction from the non-inverse entity to the inverse.
If a bidirectional relation is to-many, then the entity with the to-many multiplicity has a foreign key:
- for one-to-many, then the entity at the many end has the foreign key, and the related entity does not have a foreign key
- for many-to-many, then both entities hold foreign keys for the relation.
A given relation can be in at most one bidirectional relationship. This means that:
- a relation can't be the target of the 'inverse' for two or more relations
- a relation which has 'inverse' set cannot itself be the target of another relation's 'inverse'.
|
| Type | String |
11.31.7 Property 'linkTable'
|
| Description | 'link-table' is the name of the database table that links two entities in a many-to-many relationship.
For each association between two entities, a row will be created in the link-table to represent the association.
A link table cannot have any additional modelled properties on it: it is defined and populated specifically to hold a many-to-many relation.
If you need additional modelled properties, model the link table as an entity with one-to-many relations from the two entities you first thought of.
For example, Footballer and FootballClub naturally have a many-to-many associations - players move around between clubs.
If you modelled a link table as FootballerAtClub entity, you could also have "startDate" and "endDate" on the FootballerAtClub entity
to hold more information about a footballer's association with a club.
|
| Type | String |
11.31.8 Property 'name'
|
| Description | The identifier of the relation.
This must be unique.
If not specified, numeric names are given according to the position of the relation.
|
| Type | String |
| Required | true |
| Default | |
11.31.9 Property 'required'
|
| Description | This determines whether at least a value needs to be input into this relation.
The name 'required' is used to be consistent with the 'required' property on attributes.
It is equivalent to 'NOT NULL' at the database level, and the difference between '0..' and '1..' on UML models.
The standard patterns use this property to
- propagate 'null' to persistent storage (if unset)
- enforce values are present before storage (if set)
- enforce entry of values into screens (if set).
A 'required' String value means that the string must be non-null - i.e. there must be a string object available -
but in this case the empty string is allowed.
To specify that a String value must be non-empty, us a constraint with min-length=1.
|
| Type | boolean |
11.31.10 Property 'routeToMaster'
|
| Description | The "routeToMaster" tells us that, in an entity group,
this relation is the one to use to find the master.
This field is optional.
It can only be set if all of the following conditions are met:
- the entity is a subsidiary in an entity group (i.e. has a parent entity in the modelling hierarchy)
- the related entity is the parent entity
- the relation is to-one towards the parent - you cannot use it on one-to-many and many-to-many.
This means that the parent end of the relationship must not have a "Collection Type" specified.
- the relation is bidirectional - this relation must be navigated in both directions to construct the space.
You do not need to set routeToMaster if there is only one "to-one" relationship to the parent in the subsidiary entity;
the code generator can deduce that the single suitable relationship must be the routeToMaster.
If there are multiple such relations, then one and only one must have the 'routeToMaster' property set true.
|
| Type | boolean |
11.31.11 Property 'type'
|
| Description | This is the type of the related entity. It must be an entity.
This is required in a unidirectional relationship.
This is optional on a bidirectional relationship - - and it is probably easier to leave it out,
because CloudTran can deduce the type of the relation from the 'inverse' property.
If the type is specified on either end of a bidirectional relationship,
it must be consistent with the 'inverse' specification.
|
| Type | String |
|
