<< §6.1 Reflection | ↑ Table of Contents ↑ | §6.3 Annotations >> |
§6.2 Other API Elements
(a) Interfaces for role encapsulation
A set of pre-defined types exist that do not extend java.lang.Object
and have no features except the operators ==
and !=
.
Note:
The JLS defines that each interface declares all methods defined injava.lang.Object
(JLS §9.2)
and also each object referenced by an interface type can be widened to java.lang.Object
.
Compilers commonly implement this by declaring java.lang.Object
the super-type of all interfaces.
Such implementation has no visible difference with respect to the more complex definition in the JLS.
These predefined types are
org.objectteams.IConfined
- regular interface
org.objectteams.ITeam.IConfined
- role interface
org.objectteams.Team.Confined
- role class
These types provide no new functionality but inheriting from these types influences the semantics with respect to encapsulation. The purpose and usage of these types is described in §7.
(b) Interface for explicit lowering
The following role interface exists for the purpose of allowing explicit lowering:
org.objectteams.ITeam.ILowerable
- role interface
This interface was introduced in detail in §2.2.(d).
(c) Team activation methods
Every team can be activated and deactivated by predefined methods of the interface org.objectteams.ITeam
.
activate()
andactivate(Thread th)
- Methods for activation of a team
deactivate()
anddeactivate(Thread th)
- Methods for deactivation of a team
The usage of these Methods is described in §5.2.(b).
(d) Exceptions
The following Exceptions
can be thrown during the execution of an ObjectTeam/Java program:
ResultNotProvidedException
- Thrown if a replace callin without a base call does not provide the necessary (primitive type) base result (see §4.3.(e)).
LiftingFailedException
- Thrown if an actual ambiguity occurs during lifting (see §2.3.4.(c)) or if lifting would need to instantiate an abstract role class (see §2.5.(b)). This is a checked exception. See §2.3.5 for more information.
WrongRoleException
- Thrown during lifting if the base object has, with respect to the same team instance, previously been lifted to a role type that is not conform to the currently requested type (see §2.3.4.(d) and §2.4.3).
DuplicateRoleException
- Thrown during explicit role creation, if a new role is created for a base object, which already has a role of the required type in the given team (see §2.4.1.(c)).
RoleCastException
- Thrown during cast of an externalized role, if the casted expression is anchored to a different team instance than the cast type (see §1.2.4.(b)).
LiftingVetoException
- This exception is used internally to abort the process of lifting when a relevant guard predicate (§5.4) evaluated to false.
Such exceptions thrown from generated code will never appear in client code, so there is usually no need to catch a
LiftingVetoException
. However, in some situations it is useful to explicitly throw aLiftingVetoException
from a lifting constructor (§2.3.1.(b)) of a role. This style allows to abort lifting even after the lifting constructor has started to work and also for method parameters requiring lifting. If lifting was triggered due to a callin method binding, this binding will simply not trigger if aLiftingVetoException
is thrown while preparing the call to the role method.
(e) Role migration
The following interfaces can be used to enable role migration:
IBaseMigratable
- This interface declares a method
and instructs the compiler to generate an implementation of this method for any bound role declaring
<B> void migrateToBase(B otherBase)
IBaseMigratable
as its super-interface.
The effect of callingmigrateToBase
on a role instance is to re-bind this role to a new base instance. The base instance must be compatible to the role's base class (in order to avoid problems during lifting the compiler may require the base to be of the exact type of the role's base class). Passingnull
to this method causes anNullPointerException
to be thrown. ITeamMigratable
- This interface declares a method
and instructs the compiler to generate an implementation of this method for any role declaring
<R> R<@otherTeam> migrateToTeam(final ITeam otherTeam)
ITeamMigratable
as its super-interface.
The effect of callingmigrateToTeam
on a role instance is to re-bind this role to become a contained part of a new team instance. The team instance must be of the exact type of the role's enclosing team. Passingnull
to this method causes aNullPointerException
to be thrown.Caveat:
This method intentionally breaks the rules of family polymorphism: any referenceR<@previousTeam> r
which was established before migration will incorrectly imply that the role's enclosing team still ispreviousTeam
, which is no longer true after migration. While this does not effect any method lookup (which is still safe), further assumptions based on a role's dependent type are invalidated by team migration. The same holds for references from the migrating role to any sibling role instances.
If the rules of family polymorphism should be maintained one should just refrain from declaringITeamMigratable
as a role's super-interface.
For both methods the signature declared in the interface is over-generalized, yet the compiler performs the necessary checks
to
ensure that role, base and team instances are indeed compatible and additionally the return type of migrateToTeam
is checked as a self-type, i.e., it reflects the exact type of the call target.
<< §6.1 Reflection | ↑ Table of Contents ↑ | §6.3 Annotations >> |