-
Notifications
You must be signed in to change notification settings - Fork 4.6k
/
HasMultipleValues.java
258 lines (237 loc) · 9.78 KB
/
HasMultipleValues.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
/*
* Copyright 2017 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.api.provider;
import org.gradle.api.Incubating;
import org.gradle.api.SupportsKotlinAssignmentOverloading;
import javax.annotation.Nullable;
/**
* Represents a property whose value can be set using multiple elements of type {@link T}, such as a collection property.
*
* <p><b>Note:</b> This interface is not intended for implementation by build script or plugin authors. You can use the factory methods on {@link org.gradle.api.model.ObjectFactory} to create various subtypes of this interface.
*
* @param <T> the type of elements.
* @since 4.5
*/
@SupportsKotlinAssignmentOverloading
public interface HasMultipleValues<T> extends HasConfigurableValue, SupportsConvention {
/**
* Sets the value of the property to the elements of the given iterable, and replaces any existing value. This property will query the elements of the iterable each time the value of this property is queried.
*
* <p>This method can also be used to discard the value of the property, by passing {@code null} as the value.
* The convention for this property, if any, will be used to provide the value instead.
*
* @param elements The elements, can be null.
*/
void set(@Nullable Iterable<? extends T> elements);
/**
* Sets the property to have the same value of the given provider, and replaces any existing value. This property will track the value of the provider and query its value each time the value of this property is queried. When the provider has no value, this property will also have no value.
*
* @param provider Provider of the elements.
*/
void set(Provider<? extends Iterable<? extends T>> provider);
/**
* Sets the value of the property to the elements of the given iterable, and replaces any existing value. This property will query the elements of the iterable each time the value of this property is queried.
*
* <p>This is the same as {@link #set(Iterable)} but returns this property to allow method chaining.</p>
*
* @param elements The elements, can be null.
* @return this
* @since 5.6
*/
HasMultipleValues<T> value(@Nullable Iterable<? extends T> elements);
/**
* Sets the property to have the same value of the given provider, and replaces any existing value. This property will track the value of the provider and query its value each time the value of this property is queried. When the provider has no value, this property will also have no value.
*
* <p>This is the same as {@link #set(Provider)} but returns this property to allow method chaining.</p>
*
* @param provider Provider of the elements.
* @return this
* @since 5.6
*/
HasMultipleValues<T> value(Provider<? extends Iterable<? extends T>> provider);
/**
* Sets the value of this property to an empty collection, and replaces any existing value.
*
* @return this property.
* @since 5.0
*/
HasMultipleValues<T> empty();
/**
* Adds an element to the property value.
* <p>
* Contrary to {@link #append(Object)}, if this property has no value, this operation has no effect on the value of this property.
* </p>
*
* @param element The element
* @see #append(Object) for a more convenient
*/
void add(T element);
/**
* Adds an element to the property value.
*
* <p>The given provider will be queried when the value of this property is queried.
* <p>
* Contrary to {@link #append(Provider)}, if this property has no value, this operation has no effect on the value of this property.
* </p>
* <p>
* Also contrary to {@link #append(Provider)}, this property will have no value when the given provider has no value.
* </p>
*
* @param provider The provider of an element
*/
void add(Provider<? extends T> provider);
/**
* Adds zero or more elements to the property value.
*
* <p>
* Contrary to {@link #appendAll(Object[])}, if this property has no value, this operation has no effect on the value of this property.
* </p>
*
* @param elements The elements to add
* @since 4.10
*/
@SuppressWarnings("unchecked")
void addAll(T... elements);
/**
* Adds zero or more elements to the property value.
*
* <p>The given iterable will be queried when the value of this property is queried.
*
* <p>
* Contrary to {@link #appendAll(Iterable)}, if this property has no value, this operation has no effect on the value of this property.
* </p>
*
* @param elements The elements to add.
* @since 4.10
*/
void addAll(Iterable<? extends T> elements);
/**
* Adds zero or more elements to the property value.
*
* <p>The given provider will be queried when the value of this property is queried.
* <p>
* Contrary to {@link #appendAll(Provider)}, if this property has no value, this operation has no effect on the value of this property.
* </p>
* <p>
* Also contrary to {@link #appendAll(Provider)}, this property will have no value when the given provider has no value.
* </p>
*
* @param provider Provider of elements
*/
void addAll(Provider<? extends Iterable<? extends T>> provider);
/**
* Adds an element to the property value.
*
* <p>
* When invoked on a property with no value, this method first sets the value
* of the property to its current convention value, if set, or an empty collection.
* </p>
*
* @param element The element
* @since 8.7
*/
@Incubating
void append(T element);
/**
* Adds an element to the property value.
*
* <p>The given provider will be queried when the value of this property is queried.
*
* <p>
* When invoked on a property with no value, this method first sets the value
* of the property to its current convention value, if set, or an empty collection.
* </p>
* <p>Even if the given provider has no value, after this method is invoked,
* the actual value of this property is guaranteed to be present.</p>
*
* @param provider The provider of an element
* @since 8.7
*/
@Incubating
void append(Provider<? extends T> provider);
/**
* Adds zero or more elements to the property value.
*
* <p>
* When invoked on a property with no value, this method first sets the value
* of the property to its current convention value, if set, or an empty collection.
* </p>
*
* @param elements The elements to add
* @since 8.7
*/
@Incubating
void appendAll(T... elements);
/**
* Adds zero or more elements to the property value.
*
* <p>The given iterable will be queried when the value of this property is queried.
*
* <p>
* When invoked on a property with no value, this method first sets the value
* of the property to its current convention value, if set, or an empty collection.
* </p>
*
* @param elements The elements to add.
* @since 8.7
*/
@Incubating
void appendAll(Iterable<? extends T> elements);
/**
* Adds zero or more elements to the property value.
*
* <p>The given provider will be queried when the value of this property is queried.
*
* <p>
* When invoked on a property with no value, this method first sets the value
* of the property to its current convention value, if set, or an empty collection.
* </p>
* <p>Even if the given provider has no value, after this method is invoked,
* the actual value of this property is guaranteed to be present.</p>
*
* @param provider Provider of elements
* @since 8.7
*/
@Incubating
void appendAll(Provider<? extends Iterable<? extends T>> provider);
/**
* Specifies the value to use as the convention for this property. The convention is used when no value has been set for this property.
*
* @param elements The elements, or {@code null} when the convention is that the property has no value.
* @return this
* @since 5.1
*/
HasMultipleValues<T> convention(@Nullable Iterable<? extends T> elements);
/**
* Specifies the provider of the value to use as the convention for this property. The convention is used when no value has been set for this property.
*
* @param provider The provider of the elements
* @return this
* @since 5.1
*/
HasMultipleValues<T> convention(Provider<? extends Iterable<? extends T>> provider);
/**
* Disallows further changes to the value of this property. Calls to methods that change the value of this property, such as {@link #set(Iterable)} or {@link #add(Object)} will fail.
*
* <p>When this property has elements provided by a {@link Provider}, the value of the provider is queried when this method is called and the value of the provider will no longer be tracked.</p>
*
* <p>Note that although the value of the property will not change, the resulting collection may contain mutable objects. Calling this method does not guarantee that the value will become immutable.</p>
*
* @since 5.0
*/
@Override
void finalizeValue();
}