Chapter 67. Rule based model configuration

The term “model space” is used to refer to the formal model, which can be read and modified by rules.

A counterpart to the model space is the “project space”, which should be familiar to readers. The “project space” is a graph of objects (e.g project.repositories, project.tasks etc.) having a Project as its root. A build script is effectively adding and configuring objects of this graph. For the most part, the “project space” is opaque to Gradle. It is an arbitrary graph of objects that Gradle only partially understands.

Each project also has its own model space, which is distinct from the project space. A key characteristic of the “model space” is that Gradle knows much more about it (which is knowledge that can be put to good use). The objects in the model space are “managed”, to a greater extent than objects in the project space. The origin, structure, state, collaborators and relationships of objects in the model space are first class constructs. This is effectively the characteristic that functionally distinguishes the model space from the project space: the objects of the model space are defined in ways that Gradle can understand them intimately, as opposed to an object that is the result of running relatively opaque code. A “rule” is effectively a building block of this definition.

The model space will eventually replace the project space, becoming the only “space”.

The model space is defined by “rules”. A rule is just a function (in the abstract sense) that either produces a model element, or acts upon a model element. Every rule has a single subject and zero or more inputs. Only the subject can be changed by a rule, while the inputs are effectively immutable.

Gradle guarantees that all inputs are fully “realized“ before the rule executes. The process of “realizing” a model element is effectively executing all the rules for which it is the subject, transitioning it to its final state. There is a strong analogy here to Gradle's task graph and task execution model. Just as tasks depend on each other and Gradle ensures that dependencies are satisfied before executing a task, rules effectively depend on each other (i.e. a rule depends on all rules whose subject is one of the inputs) and Gradle ensures that all dependencies are satisfied before executing the rule.

Model elements are very often defined in terms of other model elements. For example, a compile task's configuration can be defined in terms of the configuration of the source set that it is compiling. In this scenario, the compile task would be the subject of a rule and the source set an input. Such a rule could configure the task subject based on the source set input without concern for how it was configured, who it was configured by or when the configuration was specified.

There are several ways to declare rules, and in several forms.

A model path identifies the location of an element relative to the root of its model space. A common representation is a period-delimited set of names. For example, the model path "tasks" is the path to the element that is the task container. Assuming a task whose name is hello, the path "tasks.hello" is the path to this task.

Currently, any kind of Java object can be part of the model space. However, there is a difference between “managed” and “unmanaged” objects.

A “managed” object is transparent and enforces immutability once realized. Being transparent means that its structure is understood by the rule infrastructure and as such each of its properties are also individual elements in the model space.

An “unmanaged” object is opaque to the the model space and does not enforce immutability. Over time, more mechanisms will be available for defining managed model elements culminating in all model elements being managed in some way.

Managed models can be defined by attaching the @Managed annotation to an interface:

@Managed
interface Person {
  void setFirstName(String name)
  String getFirstName()

  void setLastName(String name)
  String getLastName()
}

By defining a getter/setter pair, you are effectively declaring a managed property. A managed property is a property for which Gradle will enforce semantics such as immutability when a node of the model is not the subject of a rule. Therefore, this example declares properties named firstName and lastName on the managed type Person. These properties will only be writable when the view is mutable, that is to say when the Person is the subject of a Rule (see below the explanation for rules).

Managed properties can be of any scalar type. In addition, properties can also be of any type which is itself managed:

void setFirstName(String name)
String getFirstName()

void setHomeDirectory(File homeDir)
File getHomeDirectory()

void setId(Long id)
Long getId()

void setEmployed(boolean isEmployed)
boolean isEmployed()

void setAge(int age)
int getAge()

void setMother(Person mother)
Person getMother()

void setMaritalStatus(MaritalStatus status)
MaritalStatus getMaritalStatus()

ModelSet<Person> getChildren()

void setUserGroups(List<String> groups)
List<String> getUserGroups()

If the type of a property is itself a managed type, it is possible to declare only a getter, in which case you are declaring a read-only property. A read-only property will be instantiated by Gradle, and cannot be replaced with another object of the same type (for example calling a setter). However, the properties of that property can potentially be changed, if, and only if, the property is the subject of a rule. If it's not the case, the property is immutable, like any classic read/write managed property, and properties of the property cannot be changed at all.

Managed types can be defined out of interfaces or abstract classes and are usually defined in plugins, which are written either in Java or Groovy. Please see the Managed annotation for more information on creating managed model objects.

There are particular types (language types) supported by the model space and can be generalised as follows:

There are various contexts in which these types can be used:

FunctionalSourceSets and subtypes of LanguageSourceSet (which have been registered via ComponentType) can be added to the model space via rules or via the model DSL.

apply plugin: 'java-lang'

//Creating LanguageSourceSets via rules
class LanguageSourceSetRules extends RuleSource {
    @Model
    void mySourceSet(JavaSourceSet javaSource) {
        javaSource.source.srcDir("src/main/my")
    }
}
apply plugin: LanguageSourceSetRules

//Creating LanguageSourceSets via the model DSL
model {
    another(JavaSourceSet) {
        source {
            srcDir "src/main/another"
        }
    }
}

//Using FunctionalSourceSets
@Managed
interface SourceBundle {
    FunctionalSourceSet getFreeSources()
    FunctionalSourceSet getPaidSources()
}
model {
    sourceBundle(SourceBundle) {
        freeSources.create("main", JavaSourceSet)
        freeSources.create("resources", JvmResourceSet)
        paidSources.create("main", JavaSourceSet)
        paidSources.create("resources", JvmResourceSet)
    }
}

> gradle help
:help

As previously mentioned, a rule has a subject and zero or more inputs. The rule's subject and inputs are declared as “references” and are “bound” to model elements before execution by Gradle. Each rule must effectively forward declare the subject and inputs as references. Precisely how this is done depends on the form of the rule. For example, the rules provided by a RuleSource declare references as method parameters.

A reference is either “by-path” or “by-type”.

A “by-type” reference identifies a particular model element by its type. For example, a reference to the TaskContainer effectively identifies the "tasks" element in the project model space. The model space is not exhaustively searched for candidates for by-type binding; rather, a rule is given a scope (discussed later) that determines the search space for a by-type binding.

A “by-path” reference identifies a particular model element by its path in model space. By-path references are always relative to the rule scope; there is currently no way to path “out” of the scope. All by-path references also have an associated type, but this does not influence what the reference binds to. The element identified by the path must however by type compatible with the reference, or a fatal “binding failure” will occur.

@Managed interface Item extends Named {}
@Managed interface FileItem extends Item {
    void setSize(int size)
    int getSize()
}
@Managed interface DirectoryItem extends Item {
    ModelMap<Item> getChildren()
}

class PluginRules extends RuleSource {
    @Defaults void setDefaultFileSize(@Each FileItem file) {
        file.size = 1024
    }

    @Rules void applyValidateRules(ValidateRules rules, @Each DirectoryItem directory)  {}
}
apply plugin: PluginRules

abstract class ValidateRules extends RuleSource {
    @Validate
    void validateSizeIsPositive(ModelMap<FileItem> files) {
        files.each { file ->
            assert file.size > 0
        }
    }

    @Validate
    void validateSizeDivisibleBySixteen(ModelMap<FileItem> files) {
        files.each { file ->
            assert file.size % 16 == 0
        }
    }
}

model {
    root(DirectoryItem) {
        children {
            dir(DirectoryItem) {
                children {
                    file1(FileItem)
                    file2(FileItem) { size = 2048 }
                }
            }
            file3(FileItem)
        }
    }
}

You can define a rule that configures a particular model element. A configuration rule has the following form:

model {
    «model-path-to-subject» {
        «configuration code»
    }
}

Continuing with the example so far of the model element "person" of type Person being present, the following DSL snippet adds a configuration rule for the person that sets its lastName property.

model {
    person {
        lastName = "Smith"
    }
}

A configuration rule specifies a path to the subject that should be configured and a closure containing the code to run when the subject is configured. The closure is executed with the subject passed as the closure delegate. Exactly what code you can provide in the closure depends on the type of the subject. This is discussed below.

You should note that the configuration code is not executed immediately but is instead executed only when the subject is required. This is an important behaviour of model rules and allows Gradle to configure only those elements that are required for the build, which helps reduce build time. For example, let's run a task that uses the "person" object:

model {
    person {
        println "configuring person"
        lastName = "Smith"
    }
}

> gradle showPerson
configuring person
:showPerson
Hello John Smith!

BUILD SUCCESSFUL

Total time: 1 secs

You can see that before the task is run, the "person" element is configured by running the rule closure. Now let's run a task that does not require the "person" element:

> gradle somethingElse
:somethingElse
Not using person

BUILD SUCCESSFUL

Total time: 1 secs

In this instance, you can see that the "person" element is not configured at all.

It is also possible to create model elements at the root level. The general form of a creation rule is:

model {
    «element-name»(«element-type») {
        «initialization code»
    }
}

The following model rule creates the "person" element:

model {
    person(Person) {
        firstName = "John"
    }
}

A creation rule definition specifies the path of the element to create, plus its public type, represented as a Java interface or class. Only certain types of model elements can be created.

A creation rule may also provide a closure containing the initialization code to run when the element is created. The closure is executed with the element passed as the closure delegate. Exactly what code you can provide in the closure depends on the type of the subject. This is discussed below.

The initialization closure is optional and can be omitted, for example:

model {
    barry(Person)
}

You should note that the initialization code is not executed immediately but is instead executed only when the element is required. The initialization code is executed before any configuration rules are run. For example:

model {
    person {
        println "configuring person"
        println "last name is $lastName, should be Smythe"
        lastName = "Smythe"
    }
    person(Person) {
        println "creating person"
        firstName = "John"
        lastName = "Smith"
    }
}

> gradle showPerson
creating person
configuring person
last name is Smith, should be Smythe
:showPerson
Hello John Smythe!

BUILD SUCCESSFUL

Total time: 1 secs

Notice that the creation rule appears in the build script after the configuration rule, but its code runs before the code of the configuration rule. Gradle collects up all the rules for a particular subject before running any of them, then runs the rules in the appropriate order.

Most DSL rules take a closure containing some code to run to configure the subject. The code you can use in this closure depends on the type of the subject of the rule.

In general, a rule closure may contain arbitrary code, mixed with some type specific DSL syntax.

model {
    people {
        john(Person) {
            firstName = "John"
        }
    }
}

model {
    people {
        john {
            lastName = "Smith"
        }
    }
}

model {
    people {
        john(Person) {
            println "creating $it"
            firstName = "John"
            lastName = "Smith"
        }
        all {
            println "configuring $it"
        }
        barry(Person) {
            println "creating $it"
            firstName = "Barry"
            lastName = "Barry"
        }
    }
}

> gradle listPeople
creating Person 'people.barry'
configuring Person 'people.barry'
creating Person 'people.john'
configuring Person 'people.john'
:listPeople
Hello Barry Barry!
Hello John Smith!

BUILD SUCCESSFUL

Total time: 1 secs

model {
    person {
        address {
            city = "Melbourne"
        }
    }
}

Scalar properties in managed types can be assigned CharSequence values (e.g. String, GString, etc.) and they will be converted to the actual property type for you. This works for all scalar types including Files, which will be resolved relative to the current project.

enum Temperature {
   TOO_HOT,
   TOO_COLD,
   JUST_RIGHT
}

@Managed
interface Item {
   void setName(String n); String getName()

   void setQuantity(int q); int getQuantity()

   void setPrice(float p); float getPrice()

   void setTemperature(Temperature t)
   Temperature getTemperature()

   void setDataFile(File f); File getDataFile()
}

class ItemRules extends RuleSource {
   @Model
   void item(Item item) {
      def data = item.dataFile.text.trim()
      def (name, quantity, price, temp) = data.split(',')
      item.name = name
      item.quantity = quantity
      item.price = price
      item.temperature = temp
   }

   @Defaults
   void setDefaults(Item item) {
      item.dataFile = 'data.csv'
   }

   @Mutate
   void createDataTask(ModelMap<Task> tasks, Item item) {
      tasks.create('showData') {
         doLast {
            println """
Item '$item.name'
   quantity:    $item.quantity
   price:       $item.price
   temperature: $item.temperature"""
         }
      }
   }
}

apply plugin: ItemRules

model {
   item {
      price = "${price * (quantity < 10 ? 2 : 0.5)}"
   }
}

In the above example, an Item is created and is initialized in setDefaults() by providing the path to the data file. In the item() method the resolved File is parsed to extract and set the data. In the DSL block at the end, the price is adjusted based on the quantity; if there are fewer than 10 remaining the price is doubled, otherwise it is reduced by 50%. The GString expression is a valid value since it resolves to a float value in string form.

Finally, in createDataTask() we add the showData task to display all of the configured values.

Rules declared in the DSL may depend on other model elements through the use of a special syntax, which is of the form:

$.«path-to-model-element»

Paths are a period separated list of identifiers. To directly depend on the firstName of the person, the following could be used:

$.person.firstName

model {
    tasks {
        hello(Task) {
            def p = $.person
            doLast {
                println "Hello $p.firstName $p.lastName!"
            }
        }
    }
}

In the above snippet, the $.person construct is an input reference. The construct returns the value of the model element at the specified path, as its default type (i.e. the type advertised by the Model Report). It may appear anywhere in the rule that an expression may normally appear. It is not limited to the right hand side of variable assignments.

The input element is guaranteed to be fully configured before the rule executes. That is, all of the rules that mutate the element are guaranteed to have been previously executed, leaving the target element in its final, immutable, state.

Most model elements enforce immutability when being used as inputs. Any attempt to mutate such an element will result in a runtime error. However, some legacy type objects do not currently implement such checks. Regardless, it is always invalid to attempt to mutate an input to a rule.