Gradle Rules Based Model Configuration Workshop

Transcript

1. Rules Based Model Configuration Workshop Gradle Summit – June 2015
 Mark Vieira & Rene Groeschke
2. © Gradle Inc. 2015 Workshop Format • 2 x 90 minute sessions • Hands-on labs • Pairing is encouraged • Ask questions anytime 2
3. © Gradle Inc. 2015 Overview • Motivation • Configuration rules • Creating RuleSource plugins • The managed model • Using the model DSL • Software Model 3
4. © Gradle Inc. 2015 Why do we need rules? • Ensuring proper configuration evaluation order in plugins is a pain and unreliable
 • Existing workarounds are: – Use Project.afterEvaluate() – Use ConventionMapping – Wrap configuration in a closure – Lazy GString 4
5. © Gradle Inc. 2015 Why do we need rules? • Existing plugins are a black box
 • Rules allow for Gradle to better understand what your plugin is doing – Proper configuration ordering – Lazy configuration evaluation 5
6. © Gradle Inc. 2015 Managed Model: Graph of objects that are managed by Gradle. Includes the elements themselves, their relationships and the rules that act on them. Configuration Rule: Discrete unit of code that adds to, updates, or reads from the model. 6
7. © Gradle Inc. 2015 Rule Subject: The object that the rule acts on. Typically this means modifying the object in some way. Rule Inputs: The object(s) that the rule reads from. These are immutable and fully configured by all other rules that declared them as a subject. 7
8. © Gradle Inc. 2015 Configuration Rules • Rules generally either create new model elements, or act on an existing element in the model. 
 • These rules are referred to as creation and mutation rules, respectively. 8
9. © Gradle Inc. 2015 Creation Rules • Adds a new top-level element to the model • Method annotated with @Model • Should return the model element • All method arguments are considered inputs 9
10. © Gradle Inc. 2015 Creating a model element 10 class Person {
 String firstName
 String lastName
 }
 
 @Model
 public Person person() {
 Person p = new Person();
 p.setFirstName("John");
 p.setLastName("Smith");
 
 return p;
 }
11. © Gradle Inc. 2015 Creating a model element By default, rule method name is used as model element name. Override this by supplying a value to @Model annotation. 11 @Model("person")
 public Person createPersonModel() {
 return new Person();
 }
12. © Gradle Inc. 2015 Mutation Rules • Methods annotated with @Mutate, @Defaults or @Finalize • Must return void • Must define at least one argument (subject) • May define 0 or more additional arguments (inputs) 12
13. © Gradle Inc. 2015 Reference Binding By Type: Default method of binding. Searches the root of the current scope for model element of given type. By Path: Use @Path annotation to explicitly bind to a particular node in the model. 13
14. © Gradle Inc. 2015 Binding by Type Simplest mutation rule accepts a single argument, which is the rule subject, bound by the subject type. 14 @Mutate
 public void updatePersonName(Person person) {
 person.setFirstName("Bob");
 }
15. © Gradle Inc. 2015 Binding by Path 15 @Model
 public Person first() {
 return new Person();
 }
 
 @Model
 public Person second() {
 return new Person();
 }
 
 @Mutate
 public void updateSecondPerson(@Path("second") Person person) {
 person.setFirstName("Alice");
 }
16. © Gradle Inc. 2015 Binding by Path Failing to specify path for input type where multiple binding candidates exist will result in ambiguity error. 16 A problem occurred evaluating root project 'gradle'. > Failed to apply plugin [class 'Rules'] > There is a problem with model rule Rules#updateSecondPerson(Person). > Type-only model reference of type Person (parameter 1) is ambiguous as multiple model elements are available for this type: - first (created by: Rules#first()) - second (created by: Rules#second())
17. © Gradle Inc. 2015 Binding Generic Types Type binding also works with generic types. 17 @Model
 public GenericType<String> first() {
 return new GenericType<String>();
 }
 
 @Model
 public GenericType<Boolean> second() {
 return new GenericType<Boolean>();
 }
 
 @Mutate
 public void updateStringTypeParam(GenericType<String> s) {
 // mutate subject
 }
18. © Gradle Inc. 2015 Binding Generic Types Generic type arguments are required for rule subjects and inputs. Omitting type arguments will result in binding error. 18 A problem occurred evaluating root project 'gradle'. > Failed to apply plugin [class 'Rules'] > Rules#updateStringTypeParam(GenericType) is not a valid model rule method: raw type GenericType used for parameter 1 (all type parameters must be specified of parameterized type)
19. © Gradle Inc. 2015 What can I bind to? • Essentially, anything in the model:
 – Model elements added by plugins – Elements added via the model DSL – Implicit elements, such as tasks – Anything that shows up in model report 19
20. © Gradle Inc. 2015 Rule Inputs Arguments [1..n] are rule inputs. These should be treated as effectively immutable. This rule creates a model dependency between the subject and inputs. 20 @Mutate
 public void createTask(ModelMap<Task> tasks, Person person) {
 tasks.create('printName') {
 doLast {
 println "$person.lastName, $person.firstName"
 }
 }
 }
21. © Gradle Inc. 2015 Rule Inputs The rule subject depends on its inputs. If a subject is itself an input to another rule, these dependencies are transitive. 21 Subject Input Input Input
22. © Gradle Inc. 2015 Rule Inputs What’s the problem here? 22 @Model
 public Person first() {
 return new Person();
 }
 
 @Model
 public Person second() {
 return new Person();
 }
 
 @Mutate
 public void firstRule(@Path("first") Person first, @Path("second") Person second) {}
 
 @Mutate
 public void secondRule(@Path("second") Person second, @Path("first") Person first) {}
23. © Gradle Inc. 2015 Cycle Detection Remember, the relationship between a subject and its inputs forms a dependency. Gradle will detect any cycles and report the error. 23 > A cycle has been detected in model rule dependencies. References forming the cycle: first \- Rules#firstRule(Person, Person) \- second \- Rules#secondRule(Person, Person) \- first
24. © Gradle Inc. 2015 RuleSource Plugins • Rules are typically applied to a project in the form of a plugin. • RuleSource plugins are applied exactly the same as other plugins. • RuleSource plugins should extend RuleSource rather than implement Plugin<T>. 24
25. © Gradle Inc. 2015 RuleSource Plugins • Stateless collection of rule methods • Cannot declare constructor • Must extend directly from RuleSource • Cannot define instance variables • Methods cannot be overloaded • Cannot define generic type arguments 25
26. © Gradle Inc. 2015 RuleSource Plugins 26 class Rules extends RuleSource {
 @Model
 public Person person() {
 return new Person();
 }
 
 @Mutate
 public void updatePerson(Person person) {
 person.setFirstName("John");
 person.setLastName("Smith");
 }
 }
 
 apply plugin: Rules
27. © Gradle Inc. 2015 “Hybrid” Plugins You can continue to use a combination of rules and imperative code. 27 class MyPlugin implements Plugin<Project> {
 void apply(Project project) {
 project.getPluginManager().apply(JavaPlugin)
 }
 
 static class Rules extends RuleSource {
 @Model("person")
 public Person createPersonModel() {
 return new Person();
 }
 }
 }
 
 apply plugin: MyPlugin
28. © Gradle Inc. 2015 Lab
 01-­‐rulesource-­‐plugins 28
29. © Gradle Inc. 2015 Rule Ordering 29 @Defaults @Mutate @Finalize @Validate Subject  Mutable yes yes yes no
30. © Gradle Inc. 2015 Rule Ordering • All rules are evaluated before a model element is used as an input • Ordering rules otherwise behave identically to @Mutate • Only a single annotation should be used • Model DSL rules are considered @Mutate 30
31. © Gradle Inc. 2015 Lab
 02-rule-ordering 31
32. © Gradle Inc. 2015 Managed Types • Types whose implementations are provided by Gradle. • Allows for greater safety, control and diagnostics. • Improved performance. • Defined using the @Managed annotation 32
33. © Gradle Inc. 2015 Managed Types • Must be an interface or abstract class • May implement Named • May inherit from other @Managed types • Can provide implementations for read-only derived properties • Define properties via JavaBean conventions (getters/setters) 33
34. © Gradle Inc. 2015 Managed Types • Allowed property types are: 34 ▪ String ▪ Boolean ▪ Character ▪ Integer ▪ Long ▪ Double ▪ BigInteger ▪ BigDecimal ▪ File
35. © Gradle Inc. 2015 Managed Types • Instances of managed types are created using @Model rules • Rules for managed types return void • Managed type must be first argument • Other arguments are inputs 35
36. © Gradle Inc. 2015 Managed Types 36 @Managed
 interface Person {
 String getName();
 void setName(String name);
 }
 
 @Model
 public void person(Person person) {
 person.setName("John")
 }
37. © Gradle Inc. 2015 Managed Types Properties can be declared as unmanaged by adding @Unmanaged annotation to getter method. 37 @Managed
 interface Person {
 String getName();
 void setName(String name);
 @Unmanaged
 Date getBirthday();
 void setBirthday(Date birthday);
 }
38. © Gradle Inc. 2015 Lab
 03-­‐managed-­‐types 38
39. © Gradle Inc. 2015 Model Collections • Two new collection types ▪  ModelSet ▪  ModelMap
 • Behave  like  Set  and  Map
 • Collections  are  “model-­‐aware”  meaning   configuration  is  done  lazily  via  rules 39
40. © Gradle Inc. 2015 Model Collections 40 PolymorphicDomainObjectContainer DomainObjectCollection ModelMap ModelSet
41. © Gradle Inc. 2015 Model Collections You can create model elements of type ModelMap or ModelSet. Collection type must be a managed type. 41 @Model
 public void persons(ModelMap<Person> persons) {
 persons.create(“John”);
 }
42. © Gradle Inc. 2015 Model Collections Managed types can have collection properties. Only a getter may be declared. 42 @Managed
 interface Person {
 
 }
 
 @Managed
 interface Organization {
 ModelMap<Person> getMembers();
 }
43. © Gradle Inc. 2015 Model Collections Use @Path to bind to individual managed type properties or collection elements. 43 @Model
 public void orgs(ModelMap<Organization> orgs) {
 orgs.create('gradle')
 }
 
 @Mutate
 public void updateGradle(@Path("orgs.gradle.members") ModelMap<Person> members) {
 members.create('alice')
 members.create('bob')
 }
44. © Gradle Inc. 2015 Lab
 04-­‐model-­‐collections 44
45. © Gradle Inc. 2015 Model DSL • Configuration rules can be defined via DSL inside a top-level model{} block.
 • Both  creation  and  mutation  rules  supported
 • Reference rule inputs via $() syntax
 • Highly  likely  to  change 45
46. © Gradle Inc. 2015 Model DSL 46 @Managed
 interface Greeting {
 String getMessage()
 void setMessage(String message)
 }
 
 @Model
 public void greeting(Greeting greeting) {}
 
 @Mutate
 public void createTask(ModelMap<Task> tasks, Greeting greeting) {
 tasks.create('printGreeting') {
 doLast { println greeting.message }
 }
 }
47. © Gradle Inc. 2015 Model DSL (Mutation Rules) 47 model {
 greeting {
 message = 'Hello World!'
 }
 } $ gradle pG :printGreeting Hello World! BUILD SUCCESSFUL
48. © Gradle Inc. 2015 Model DSL • DSL rules are treated identically to method rules.
 • All  mutation  rules,  to  include  those  defined   via  the  DSL,  are  evaluated  before  a  model   element  is  used  as  an  input  to  a  rule.
 • No more afterEvaluate! 48
49. © Gradle Inc. 2015 Model DSL (Creation Rules) Note: Usage of $() requires passing –Dorg.gradle.model.dsl=true 49 model {
 greeting(Greeting) {
 message = 'Hello World!'
 }
 
 tasks {
 printGreeting(Task) {
 doLast {
 println $('greeting.message')
 }
 }
 }
 }
50. © Gradle Inc. 2015 Lab
 05-­‐model-­‐dsl 50
51. © Gradle Inc. 2015 Software Model • Managed  model  is  domain  agnostic.   • Need a more structured model targeting the software build domain. • Software is generally comprised of several components that produce binaries. • In  Gradle,  tasks  are  then  used  to  create  the   binaries 51
52. © Gradle Inc. 2015 Binary Software Model 52 BinarySpec BinarySpec ComponentSpec LanguageSourceSet LanguageSourceSet Task Task Task Task Binary LanguageSourceSet
53. © Gradle Inc. 2015 Software Model • Software  model  is  designed  to  be   extensible  and  adaptable  to  new  domains.
 • Underlying model behind Gradle native and Play support
 • API includes specialty rules for registering custom language, component and binary types. 53
54. © Gradle Inc. 2015 Registering a custom language type 54 interface CustomLanguageSourceSet extends LanguageSourceSet {} 
 class DefaultCustomLanguageSourceSet extends BaseLanguageSourceSet implements CustomLanguageSourceSet {}
 
 apply plugin: MySamplePlugin
 
 class MySamplePlugin extends RuleSource {
 @LanguageType
 void declareCustomLanguage( LanguageTypeBuilder<CustomLanguageSourceSet> builder) { 
 builder.setLanguageName("custom")
 builder.defaultImplementation(DefaultCustomLanguageSourceSet)
 }
 }
55. © Gradle Inc. 2015 Registering a custom component type 55 interface SampleComponent extends ComponentSpec {} 
 class DefaultSampleComponent extends BaseComponentSpec implements SampleComponent {}
 
 apply plugin: MySamplePlugin
 
 class MySamplePlugin extends RuleSource {
 @ComponentType
 void register(ComponentTypeBuilder<SampleComponent> builder) {
 builder.defaultImplementation(DefaultSampleComponent)
 }
 }
56. © Gradle Inc. 2015 Registering a custom binary type 56 interface SampleBinary extends BinarySpec {} 
 class DefaultSampleBinary extends BaseBinarySpec implements SampleBinary {}
 
 apply plugin: MySamplePlugin
 
 class MySamplePlugin extends RuleSource {
 @BinaryType
 void defineBinaryType(BinaryTypeBuilder<SampleBinary> builder) {
 builder.defaultImplementation(DefaultSampleBinary)
 }
 }
57. © Gradle Inc. 2015 Mapping components to binaries @ComponentBinaries rules  are  used  to   create  binaries  for  each  component. 57 @ComponentBinaries
 void createBinariesForSampleLibrary(ModelMap<SampleBinary> binaries, SampleComponent component) { 
 binaries.create("${component.name}Binary", SampleBinary)
 }
58. © Gradle Inc. 2015 Creating tasks for building binaries @BinaryTasks rules are used to create tasks for each binary. 58 @BinaryTasks
 void createBinaryTasks(ModelMap<Task> tasks, SampleBinary binary) {
 tasks.create("${binary.name}Task1")
 tasks.create("${binary.name}Task2") {
 dependsOn "${binary.name}Task1"
 }
 }
59. © Gradle Inc. 2015 Software Model Components can then be configured via the model DSL. 59 model {
 components {
 foo(SampleComponent)
 bar(SampleComponent)
 }
 }
60. © Gradle Inc. 2015 Software Model Tasks Lifecycle tasks are automatically created for each binary. 60 Build tasks ----------- assemble - Assembles the outputs of this project. [barBinary, fooBinary] barBinary - Assembles DefaultSampleBinary 'barBinary'. barBinaryTask1 barBinaryTask2 build - Assembles and tests this project. [assemble, check] fooBinary - Assembles DefaultSampleBinary 'fooBinary'. fooBinaryTask1 fooBinaryTask2
61. © Gradle Inc. 2015 Model Report • Display a textual report of managed model • Evaluates the entire model graph • Work in progress 61
62. © Gradle Inc. 2015 Demo 62
63. © Gradle Inc. 2015 Limitations and Future Work • Bridge the gap between managed and non-managed model types
 • Expose project model to rules
 • Model DSL improvements
 • Configuration rules and software model still currently under active development 63
64. © Gradle Inc. 2015 Questions? 64