-
Notifications
You must be signed in to change notification settings - Fork 4.6k
/
MapProperty.java
301 lines (277 loc) · 10.7 KB
/
MapProperty.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
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
/*
* Copyright 2018 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;
import java.util.Map;
import java.util.Set;
/**
* Represents a property whose type is a {@link Map} of keys of type {@link K} and values of type {@link V}. Retains iteration order.
*
* <p>
* You can create a {@link MapProperty} instance using factory method {@link org.gradle.api.model.ObjectFactory#mapProperty(Class, Class)}.
* </p>
*
* <p><b>Note:</b> This interface is not intended for implementation by build script or plugin authors.
*
* @param <K> the type of keys.
* @param <V> the type of values.
* @since 5.1
*/
@SupportsKotlinAssignmentOverloading
public interface MapProperty<K, V> extends Provider<Map<K, V>>, HasConfigurableValue, SupportsConvention {
/**
* Sets the value of this property to an empty map, and replaces any existing value.
*
* @return this property.
*/
MapProperty<K, V> empty();
/**
* Returns a provider that resolves to the value of the mapping of the given key. It will have no value
* if the property has no value, or if it does not contain a mapping for the key.
*
* <p>The returned provider will track the value of this property and query its value when it is queried.</p>
*
* <p>This method is equivalent to
*
* <pre><code>
* map(m -> m.get(key))
* </code></pre>
*
* but possibly more efficient.
*
* @param key the key
* @return a {@link Provider} for the value
*/
Provider<V> getting(K key);
/**
* Sets the value of this property to the entries of the given Map, and replaces any existing value.
* This property will query the entries of the map 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 entries the entries, can be {@code null}
*/
void set(@Nullable Map<? extends K, ? extends V> entries);
/**
* 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 entries.
*/
void set(Provider<? extends Map<? extends K, ? extends V>> provider);
/**
* Sets the value of this property to the entries of the given Map, and replaces any existing value.
* This property will query the entries of the map each time the value of this property is queried.
*
* <p>This is the same as {@link #set(Map)} but returns this property to allow method chaining.</p>
*
* @param entries the entries, can be {@code null}
* @return this
* @since 5.6
*/
MapProperty<K, V> value(@Nullable Map<? extends K, ? extends V> entries);
/**
* 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 entries.
* @since 5.6
*/
MapProperty<K, V> value(Provider<? extends Map<? extends K, ? extends V>> provider);
/**
* Adds a map entry to the property value.
*
* <p>
* Contrary to {@link #insert(Object, Object)}, if this property has no value, this operation has no effect on the value of this property.
* </p>
*
* @param key the key
* @param value the value
*/
void put(K key, V value);
/**
* Adds a map entry to the property value.
*
* <p>The given provider will be queried when the value of this property is queried.
* <p>
* Contrary to {@link #insert(Object, Provider)}, if this property has no value, this operation has no effect on the value of this property.
* </p>
* <p>
* Also contrary to {@link #insert(Object, Provider)}, this property will have no value when the given provider has no value.
* </p>
*
* @param key the key
* @param providerOfValue the provider of the value
*/
void put(K key, Provider<? extends V> providerOfValue);
/**
* Adds all entries from another {@link Map} to the property value.
*
* <p>
* Contrary to {@link #insertAll(Map)}, if this property has no value, this operation has no effect on the value of this property.
* </p>
*
* @param entries a {@link Map} containing the entries to add
*/
void putAll(Map<? extends K, ? extends V> entries);
/**
* Adds all entries from another {@link Map} to the property value.
*
* <p>The given provider will be queried when the value of this property is queried.
* <p>
* Contrary to {@link #insertAll(Provider)}, if this property has no value, this operation has no effect on the value of this property.
* </p>
* <p>
* Also contrary to {@link #insertAll(Provider)}, this property will have no value when the given provider has no value.
* </p>
*
* @param provider the provider of the entries
*/
void putAll(Provider<? extends Map<? extends K, ? extends V>> provider);
/**
* Adds a map entry 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 map.
* </p>
*
* @param key the key
* @param value the value
*
* @since 8.7
*/
@Incubating
void insert(K key, V value);
/**
* Adds a map entry 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 map.
* </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 key the key
* @param providerOfValue the provider of the value
*
* @since 8.7
*/
@Incubating
void insert(K key, Provider<? extends V> providerOfValue);
/**
* Adds all entries from another {@link Map} 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 map.
* </p>
*
* @param entries a {@link Map} containing the entries to add
*
* @since 8.7
*/
@Incubating
void insertAll(Map<? extends K, ? extends V> entries);
/**
* Adds all entries from another {@link Map} 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 map.
* </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 the entries
*
* @since 8.7
*/
@Incubating
void insertAll(Provider<? extends Map<? extends K, ? extends V>> provider);
/**
* Returns a {@link Provider} that returns the set of keys for the map that is the property value.
*
* <p>The returned provider will track the value of this property and query its value when it is queried.</p>
*
* <p>This method is equivalent to
*
* <pre><code>
* map(m -> m.keySet())
* </code></pre>
*
* but possibly more efficient.
*
* @return a {@link Provider} that provides the set of keys for the map
*/
Provider<Set<K>> keySet();
/**
* 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 value The value, or {@code null} when the convention is that the property has no value.
* @return this
*/
MapProperty<K, V> convention(@Nullable Map<? extends K, ? extends V> value);
/**
* 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 valueProvider The provider of the value.
* @return this
*/
MapProperty<K, V> convention(Provider<? extends Map<? extends K, ? extends V>> valueProvider);
/**
* {@inheritDoc}
*
* <p>
* This is similar to calling {@link #value(Map)} with a <code>null</code> argument.
* </p>
*/
@Incubating
@Override
MapProperty<K, V> unset();
/**
* {@inheritDoc}
*
* <p>
* This is similar to calling {@link #convention(Map)} with a <code>null</code> argument.
* </p>
*/
@Incubating
@Override
MapProperty<K, V> unsetConvention();
/**
* Disallows further changes to the value of this property. Calls to methods that change the value of this property, such as {@link #set(Map)} or {@link #put(Object, 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 map may contain mutable objects. Calling this method does not guarantee that the value will become immutable.</p>
*/
@Override
void finalizeValue();
}