### §2.3.4 Binding ambiguities

While all examples so far have only shown 1-to-1 class bindings, several cases of multiple bindings are allowable. Ambiguities may be detected at compile time and/or at runtime.

#### (a) Potential ambiguity

A potential ambiguity is given, if two role classes `R1` and `R2` exist such that

- `R1` and `R2` are played by the same base class `B`, and
- `R1` and `R2` have a common super role `R0`, which is also bound to a base class `B0`, and
- neither role class `R1` nor `R2` is a (indirect) sub-class of the other.

##### Note:

According to §2.1.(c), if `B` is distinct from `B0` it has to be a sub-class of `B0`.

##### Effect:

In this case the compiler issues a warning, stating that the `B` may not be liftable, because both role classes `R1` and `R2` are candidates and there is no reason to prefer one over the other.
If no potential ambiguity is detected, lifting will always be unambiguous.

In the above situation, trying to lift an instance of type `B` to the role type `R0` is an illegal lifting request. If `R0` is bound to the same base class `B` as its sub-roles `R1` and `R2` are, role `R0` is unliftable, meaning that no instance of `R0` can ever by obtained by lifting.

##### Example code (Potential Ambiguity):

1

    team class MyTeam {

2

      public class SuperRole playedBy MyBase {...}

3

      public class SubRoleA extends SuperRole {...}

4

      public class SubRoleB extends SuperRole {...}

5

    }

#### (b) Definite ambiguity

A definite ambiguity is given if

- the situation of potential ambiguity according to (a) above is given and
- lifting is requested (either by method binding or explicitly (§2.3.2)) from the shared base class `B` to any role class `R0` that is a common super role for `R1` and `R2`.

Definite binding ambiguity also occurs in cases of generic declared lifting §2.3.2.(e) if the specified role `R` is unbound and if two independent sub-roles `R1` and `R2` exist that introduce a playedBy binding to the same base class `BX`. In this case no potential ambiguity is flagged because roles `R1` and `R2` have no shared bound super-role.

##### Effect:

Code causing definite ambiguity is required to handle `org.objectteams.LiftingFailedException`.

In cases of definite binding ambiguity lifting will indeed fail except for some corner cases. Such corner cases may arise if lifting already finds an appropriate role in the cache or if an (indirect) subrole of the ambiguously bound role is an unambiguous lift target for the concrete type of the base object at run-time. See also §2.3.5.

##### Example code (Definite Ambiguity):

1

    team class MyTeam {

2

      public class SuperRole playedBy MyBase {...}

3

      public class SubRoleA extends SuperRole playedBy SubBase {...}

4

      public class SubRoleB extends SuperRole playedBy SubBase {...}

5

6

      public void useSuperRole(SubBase as SuperRole r) {...} // must declare LiftingFailedException

7

    }

#### (c) Actual ambiguity

At runtime actual ambiguity may occur if for the dynamic type of a base to be lifted the conditions of (b) above hold accordingly. Actual ambiguity is only possible in cases reported by the compiler as potential or definite ambiguity.

##### Effect:

An actual ambiguity is reported at runtime by throwing a `org.objectteams.LiftingFailedException`.

##### Example code (Actual Ambiguity):

1

    import org.objectteams.LiftingFailedException;

2

    team class MyTeam {

3

      public class SuperRole playedBy MyBase {...}

4

      public class SubRoleA extends SuperRole playedBy SubBase {...}

5

      public class SubRoleB extends SuperRole playedBy SubBase {...}

6

7

      public void useSuperRole(MyBase as SuperRole r) throws LiftingFailedException {...}

8

    }

9

    // plus these calls:

10

    MyTeam mt = new MyTeam();

11

    mt.useSuperRole(new SubBase()); // will throw a LiftingFailedException

#### (d) Mismatching role

In cases of potential ambiguity another runtime error may occur: a mismatching role is encountered when a role is found in the cache, which is not conform to the required type. This happens, if the base object has previously been lifted to a type that is incompatible with the currently requested type.

##### Effect:

This is reported by throwing a `org.objectteams.WrongRoleException`.

##### Example code (Mismatching Role):

1

    import org.objectteams.LiftingFailedException;

2

    					team class MyTeam {

3

      public class SuperRole playedBy MyBase {...}

4

      public class SubRoleA extends SuperRole {...}

5

      public class SubRoleB extends SuperRole {...}

6

7

      public void useRoleA(MyBase as SubRoleA r) throws LiftingFailedException {...}

8

      public void useRoleB(MyBase as SubRoleB r) throws LiftingFailedException {...}

9

    }

10

    // plus these calls:

11

    MyTeam mt = new MyTeam();

12

    MyBase b = new MyBase();

13

    mt.useRoleA(b); // creates a SubRoleA for b

14

    mt.useRoleB(b); // finds the SubRoleA which is not compatible

15

                    // to the expected type SubRoleB.

From the second item of §2.3.4.(a) follows, that for binding ambiguities different role hierarchies are analyzed in isolation. For this analysis only those role classes are considered that are bound to a base class (directly using `playedBy` or by inheriting this relation from another role class). I.e., two role classes that have no common bound super role will never cause any ambiguity.