org.gradle.model - api

api / org.gradle.model

Package org.gradle.model

Types

ModelElement	`interface ModelElement : Named` Represents an element in a model. Elements are arranged in a hierarchy.
ModelMap	`interface ModelMap<T : Any> : MutableIterable<T>, ModelElement` Model backed map like structure allowing adding of items where instantiation is managed. org.gradle.model.Managed types may declare model map properties. Model maps can only contain managed types.
ModelSet	`interface ModelSet<T : Any> : MutableSet<T>, ModelElement` A set of managed model objects. org.gradle.model.Managed types may declare managed set properties. Managed sets can only contain managed types. Managed set objects cannot be mutated via the mutative methods of the java.util.Set interface (e.g. `java.util.Set#add(Object)`, `java.util.Set#clear()`). To add elements to the set, the `#create(Action)` method can be used.
RuleSource	`open class RuleSource` A marker type for a class that is a collection of rules. A rule source is not used like a regular Java object. It is a stateless container of methods and possibly constants. Please consult the “Rule based model configuration” chapter of the Gradle User Guide for general information about “rules”. Rule methods Each method that is annotated with one of the following is considered a rule: Model Defaults Mutate Finalize Validate Rules org.gradle.platform.base.ComponentType org.gradle.platform.base.ComponentBinaries org.gradle.platform.base.BinaryTasks Each annotation specifies the type of the rule, which affects when it will be executed. The following constraints apply to all rule methods: A method may only be annotated by at most one of the above annotations. A rule method may be `static` or not; it makes no difference. A rule method cannot be generic (i.e. cannot have type parameters). With the exception of Model methods, all methods must have at least one parameter. With the exception of Model methods, all methods must have a `void` return type. See Model for information on the significance of the return type of a Model method. Subjects and inputs Method rules declare the subject and any inputs as parameters to the method. With the exception of Model methods, the subject of the rule is the, required, first parameter and all subsequent parameters are inputs. For a non-void Model method, the subject (i.e. model element being created) is the return object. For a void Model method, the subject is the first method parameter. The Path annotation can be placed on any parameter (except the subject of Model rules) to indicate the model element to bind to. If there is no Path annotation, a “by-type” binding will be attempted. The binding scope is determined by how the rule source is applied. General class constraints Along with the constraints on individual rule methods by their associated annotation, the following are general constraints of rule source implementations: Constructors are not allowed. Inheritance hierarchies are not allowed (i.e. all rules sources must directly extend RuleSource). Instance variables are not allowed. Non-final static variables are not allowed (i.e. constants are allowed). Methods cannot be overloaded. Implementations cannot be generic (i.e. cannot use type parameters).

Annotations

Defaults	`class Defaults` Denotes that the RuleSource method rule carrying this annotation initializes the rule subject with default values. Default rules execute first for a given subject, just after the subject has been created but before Model rules and Mutate rules. The first parameter of the rule is the rule subject, which is mutable for the duration of the rule. Please see RuleSource for more information on method rules.
Each	`class Each` Signals that a RuleSource rule should be applied to all matching descendant elements of the scope instead of the scope itself.
Finalize	`class Finalize` Denotes that the RuleSource method rule carrying this annotation finalizes the rule subject. Finalize rules execute after Mutate rules, but before Validate rules. The first parameter of the rule is the rule subject, which is mutable for the duration of the rule. Please see RuleSource for more information on method rules.
Managed	`class Managed` A managed type is transparent to the model space, and enforces immutability at the appropriate times in the object's lifecycle. Gradle generates implementations for managed types. As such, managed types are declared either as interfaces or abstract classes. The generated implementation integrates with the model space mechanisms, and manages mutability. Managed types are mostly behaviour-less, as they are data. Instances of managed types should effectively be considered value objects. Properties Managed types declare their structure as properties, via getter and setter methods. Getter and setter methods are expected to conform to the well-known Java Bean naming conventions. A read/write “name” property would be expressed via the following methods: `void setName(String name); String getName();` A getter and setter must be declared for each property that is not of a managed type or of ModelSet. For properties of managed types or of ModelSet the getter is mandatory and the setter is optional. If no setter is provided the property is considered inherent and defaults to an "empty" instance of the type. In addition to the traditional getter method, properties of type `boolean` (but not `Boolean`) also support a getter method which name starts with `is`, for example: `void setEnabled(boolean enabled); boolean isEnabed();` Supported property types The following JDK types are allowed: String Boolean Character Byte Short Integer Long Float Double java.math.BigInteger java.math.BigDecimal java.io.File All primitive types and Enum types are also allowed. Properties that are themselves of a managed type are also supported. Currently, the only collection types that are supported are ModelSet and ModelMap, as well as java.util.Set or java.util.List of org.gradle.model.internal.manage.schema.extract.ScalarTypes, where scalar types is either one of the supported immutable JDK types above or an enumeration. Properties of any other type must have their getter annotated with Unmanaged. An unmanaged property is not transparent to the model infrastructure and is guaranteed to be immutable when realized. Named types Managed types may implement/extend the org.gradle.api.Named interface. Any managed type implementing this interface will have its `name` attribute populated automatically based on the name of the corresponding node in the model graph. The ModelMap type requires that its elements are org.gradle.api.Named. Inheritance Managed types can be arranged into an inheritance hierarchy. Every type in the hierarchy must conform to the constraints of managed types. Calculated read-only properties Managed types can contain getter methods that return calculated values, based on other properties. For example, a “name” property may return the concatenation of a “firstName” and “lastName” property. When using Java 8 or later, such properties can be implemented as interface default methods. Alternatively, the managed type can be implemented as an abstract class with the calculated property implemented as a non-abstract getter method. In both cases, the implementation of the calculated property getter may not call any setter method. Abstract classes A managed type can be implemented as an abstract class. All property getters and setters must be declared `abstract` (with the exception of calculated read-only properties). The class cannot contain instance variables, constructors, or any methods that are not a getter or setter. Creating managed model elements Please see Model for information on creating model elements of managed types.
Model	`class Model` Denotes that the RuleSource method rule carrying this annotation creates a new top level element in the model space. The method must advertise a name and type for the model element. The name is defined either by the name of the method, or the `#value` of this annotation. The type is defined differently depending on whether the new element is Managed or not. Creating managed model elements If the element is to be of a managed type, the method must return `void` and receive the newly created instance as the first parameter. All other parameters are considered inputs. It is an error for a `@Model` rule to return `void` and specify a non-managed type as the first parameter. It is an error for a `@Model` rule to return `void` and for the first parameter to be annotated with Path. It is an error for a `@Model` rule to specify a managed type as the return type. Creating non-managed model elements If the element is to be of a non-managed type, the method must return the newly created instance. All parameters are considered inputs. Please see RuleSource for more information on method rules.
Mutate	`class Mutate` Denotes that the RuleSource method rule carrying this annotation mutates the rule subject. Mutate rules execute after Defaults rules, but before Finalize rules. The first parameter of the rule is the rule subject, which is mutable for the duration of the rule. Please see RuleSource for more information on method rules.
Path	`class Path` Specifies a model path on a parameter
RuleInput	`class RuleInput` Attached to the getter for a property on a RuleSource to denote that the property defines an implicit input for all rules defined by the rule source.
RuleTarget	`class RuleTarget` Attached to the getter for a property on a RuleSource to denote that the property defines the target for the rule source.
Rules	`class Rules` Denotes that the RuleSource method rule carrying this annotation defines additional rules based on its inputs.
Unmanaged	`class Unmanaged` Indicates that a property of a managed model element is explicitly of an unmanaged type. This annotation must be present on the getter of the property for the unmanaged type. If the annotation is not present for a property that is not a managed type, a fatal error will occur.
Validate	`class Validate` Denotes that the RuleSource method rule carrying this annotation validates the rule subject. Validate rules execute after Finalize rules, but before rule subject is used as an input. The first parameter of the rule is the rule subject, which is immutable. Please see RuleSource for more information on method rules.

Exceptions

ConfigurationCycleException	`open class ConfigurationCycleException : GradleException` Thrown when a cycle is encountered while configuring a model element.
InvalidModelRuleDeclarationException	`open class InvalidModelRuleDeclarationException : GradleException` Thrown when a model rule, or source of model rules, is declared in an invalid way.
InvalidModelRuleException	`open class InvalidModelRuleException : GradleException` Thrown when there is a problem with the usage of a model rule. This exception is different to InvalidModelRuleDeclarationException in that it signifies a problem with using a model rule in a particular context, whereas `InvalidModelRuleDeclarationException` signifies a problem with the declaration of the model rule itself (which therefore means that the rule could not be used in any context). This exception should always have cause, that provides information about the actual problem.
ModelRuleBindingException	`open class ModelRuleBindingException : GradleException` Thrown when there is a problem binding the model element references of a model rule. Should always be thrown as the cause of a org.gradle.model.InvalidModelRuleException.
ModelViewClosedException	`open class ModelViewClosedException : ReadOnlyModelViewException` Thrown when at attempt is made to mutate a subject of a rule after the rule has completed. This can potentially happen when a reference to the subject is retained during a rule and then used afterwards, Such as when an anonymous inner class or closure “closes over” the subject.
ReadOnlyModelViewException	`open class ReadOnlyModelViewException : GradleException` Thrown when an attempt is made to change the value of a model element that is not writable at the time.
WriteOnlyModelViewException	`open class WriteOnlyModelViewException : GradleException` Thrown when an attempt is made to read the value of a model element that is not readable at the time.