ToolingModelContract

Annotation used to mark TAPI model interfaces. On the client side such interfaces are instantiated via Java dynamic proxies, and we use this annotation when we want these proxies to have richer behaviour than just implementing the base interface.

For example. Let's say the TAPI model interface is Animal, but which also has child interfaces such as Dog, Cat, Bird. When we request a model typed as Animal on the TAPI client side, we will get a Java dynamic proxy, on which we can call any method from the Animal interface, but even if that model was originally let's say a Dog on the Gradle daemon side, the proxy will not support any methods specific to Dog, like let's say Dog.bark().

Basically polymorphism isn't supported by default in TAPI client-side model instances. This is what this annotation can be used to fix. We can use it to mark the base model interface (Animal in the above example) and specify which of its subtypes should be polymorpically handled on the TAPI client-side.

Let's say we define the Animal model interface like this:

     @ToolingModelContract(subTypes = [Dog.class, Cat.class])
     interface Animal {}

On the client-side we will be able to write code such as:

     if (model instanceof Dog) {
         ((Dog) model).bark();
     } else if (model instanceof Cat) {
         ((Cat) model).meow();
     } else if (model instance of Bird) {
         // will never be true, Bird is not specified as a model contract type
     }