/*
* Copyright 2015 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.gradle.model;
import org.gradle.api.Incubating;
/**
* A marker type for a class that is a collection of rules.
* <p>
* A rule source is not used like a regular Java object.
* It is a stateless container of methods and possibly constants.
* <p>
* Please consult the “Rule based model configuration” chapter of the Gradle User Guide for general information about “rules”.
*
* <h3>Rule methods</h3>
* <p>
* Each method that is annotated with one of the following is considered a rule:
* <ul>
* <li>{@link Model}</li>
* <li>{@link Defaults}</li>
* <li>{@link Mutate}</li>
* <li>{@link Finalize}</li>
* <li>{@link Validate}</li>
* <li>{@link Rules}</li>
* <li>{@link org.gradle.platform.base.ComponentType}</li>
* <li>{@link org.gradle.platform.base.ComponentBinaries}</li>
* <li>{@link org.gradle.platform.base.BinaryTasks}</li>
* </ul>
* <p>
* Each annotation specifies the type of the rule, which affects when it will be executed.
* <p>
* The following constraints apply to all rule methods:
* <ul>
* <li>A method may only be annotated by at most one of the above annotations.</li>
* <li>A rule method may be {@code static} or not; it makes no difference.</li>
* <li>A rule method cannot be generic (i.e. cannot have type parameters).</li>
* <li>With the exception of {@link Model} methods, all methods must have at least one parameter.</li>
* <li>With the exception of {@link Model} methods, all methods must have a {@code void} return type.</li>
* </ul>
* <p>
* See {@link Model} for information on the significance of the return type of a {@link Model} method.
*
* <h4>Subjects and inputs</h4>
* <p>
* Method rules declare the subject and any inputs as parameters to the method.
* With the exception of {@link Model} methods, the subject of the rule is the, required, first parameter and all subsequent parameters are inputs.
* For a non-void {@link Model} method, the subject (i.e. model element being created) is the return object.
* For a void {@link Model} method, the subject is the first method parameter.
* <p>
* The {@link Path} annotation can be placed on any parameter (except the subject of {@link Model} rules) to indicate the model element to bind to.
* If there is no {@link Path} annotation, a “by-type” binding will be attempted.
* The binding scope is determined by how the rule source is applied.
*
* <h3>General class constraints</h3>
* <p>
* Along with the constraints on individual rule methods by their associated annotation, the following are general constraints of rule source implementations:
* <ul>
* <li>Constructors are not allowed.</li>
* <li>Inheritance hierarchies are not allowed (i.e. all rules sources must directly extend {@link RuleSource}).</li>
* <li>Instance variables are not allowed.</li>
* <li>Non-final static variables are not allowed (i.e. constants are allowed).</li>
* <li>Methods cannot be overloaded.</li>
* <li>Implementations cannot be generic (i.e. cannot use type parameters).</li>
* </ul>
*/
@Incubating
public class RuleSource {
}