org.gradle.api.provider.MapProperty Maven / Gradle / Ivy
Show all versions of gradle-api Show documentation
/*
* 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.
*
*
* You can create a {@link MapProperty} instance using factory method {@link org.gradle.api.model.ObjectFactory#mapProperty(Class, Class)}.
*
*
* Note: This interface is not intended for implementation by build script or plugin authors.
*
* @param the type of keys.
* @param the type of values.
* @since 5.1
*/
@SupportsKotlinAssignmentOverloading
public interface MapProperty extends Provider>, HasConfigurableValue, SupportsConvention {
/**
* Sets the value of this property to an empty map, and replaces any existing value.
*
* @return this property.
*/
MapProperty 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.
*
* The returned provider will track the value of this property and query its value when it is queried.
*
* This method is equivalent to
*
*
* map(m -> m.get(key))
*
*
* but possibly more efficient.
*
* @param key the key
* @return a {@link Provider} for the value
*/
Provider 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.
*
* 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 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> 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.
*
*
This is the same as {@link #set(Map)} but returns this property to allow method chaining.
*
* @param entries the entries, can be {@code null}
* @return this
* @since 5.6
*/
MapProperty value(@Nullable Map 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.
*
* This is the same as {@link #set(Provider)} but returns this property to allow method chaining.
*
* @param provider Provider of the entries.
* @since 5.6
*/
MapProperty value(Provider> provider);
/**
* Adds a map entry to the property value.
*
* @param key the key
* @param value the value
*/
void put(K key, V value);
/**
* Adds a map entry to the property value.
*
* The given provider will be queried when the value of this property is queried.
* This property will have no value when the given provider has no value.
*
* @param key the key
* @param providerOfValue the provider of the value
*/
void put(K key, Provider providerOfValue);
/**
* Adds all entries from another {@link Map} to the property value.
*
* @param entries a {@link Map} containing the entries to add
*/
void putAll(Map entries);
/**
* Adds all entries from another {@link Map} to the property value.
*
*
The given provider will be queried when the value of this property is queried.
* This property will have no value when the given provider has no value.
*
* @param provider the provider of the entries
*/
void putAll(Provider> provider);
/**
* Returns a {@link Provider} that returns the set of keys for the map that is the property value.
*
*
The returned provider will track the value of this property and query its value when it is queried.
*
* This method is equivalent to
*
*
* map(m -> m.keySet())
*
*
* but possibly more efficient.
*
* @return a {@link Provider} that provides the set of keys for the map
*/
Provider> 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 convention(@Nullable Map 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 convention(Provider> valueProvider);
/**
* {@inheritDoc}
*
*
* This is similar to calling {@link #value(Map)} with a null argument.
*
*/
@Incubating
@Override
MapProperty unset();
/**
* {@inheritDoc}
*
*
* This is similar to calling {@link #convention(Map)} with a null argument.
*
*/
@Incubating
@Override
MapProperty 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.
*
* 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.
*
* 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.
*/
@Override
void finalizeValue();
}