# Understanding Collections

version 8.12

Gradle provides types for maintaining collections of objects, intended to work well to extends Gradle’s DSLs and provide useful features such as lazy configuration.

## Available collections

These collection types are used for managing collections of objects, particularly in the context of build scripts and plugins:

1. `DomainObjectSet<T>`: Represents a set of objects of type T. This set does not allow duplicate elements, and you can add, remove, and query objects in the set.

2. `NamedDomainObjectSet<T>`: A specialization of `DomainObjectSet` where each object has a unique name associated with it. This is often used for collections where each element needs to be uniquely identified by a name.

3. `NamedDomainObjectList<T>`: Similar to `NamedDomainObjectSet`, but represents a list of objects where order matters. Each element has a unique name associated with it, and you can access elements by index as well as by name.

4. `NamedDomainObjectContainer<T>`: A container for managing objects of type T, where each object has a unique name. This container provides methods for adding, removing, and querying objects by name.

5. `ExtensiblePolymorphicDomainObjectContainer<T>`: An extension of `NamedDomainObjectContainer` that allows you to define instantiation strategies for different types of objects. This is useful when you have a container that can hold multiple types of objects, and you want to control how each type of object is instantiated.

These types are commonly used in Gradle plugins and build scripts to manage collections of objects, such as tasks, configurations, or custom domain objects.

## 1. `DomainObjectSet`

A `DomainObjectSet` simply holds a set of configurable objects.

Compared to `NamedDomainObjectContainer`, a `DomainObjectSet` doesn’t manage the objects in the collection. They need to be created and added manually.

You can create an instance using the ObjectFactory.domainObjectSet() method:

build.gradle.kts

    abstract class MyPluginExtensionDomainObjectSet {
        // Define a domain object set to hold strings
        val myStrings: DomainObjectSet<String> = project.objects.domainObjectSet(String::class)

        // Add some strings to the domain object set
        fun addString(value: String) {
            myStrings.add(value)
        }
    }

build.gradle

    abstract class MyPluginExtensionDomainObjectSet {
        // Define a domain object set to hold strings
        DomainObjectSet<String> myStrings = project.objects.domainObjectSet(String)

        // Add some strings to the domain object set
        void addString(String value) {
            myStrings.add(value)
        }
    }

## 2. `NamedDomainObjectSet`

A `NamedDomainObjectSet` holds a set of configurable objects, where each element has a name associated with it.

This is similar to `NamedDomainObjectContainer`, however a `NamedDomainObjectSet` doesn’t manage the objects in the collection. They need to be created and added manually.

You can create an instance using the ObjectFactory.namedDomainObjectSet() method.

build.gradle.kts

    abstract class Person(val name: String)

    abstract class MyPluginExtensionNamedDomainObjectSet {
        // Define a named domain object set to hold Person objects
        private val people: NamedDomainObjectSet<Person> = project.objects.namedDomainObjectSet(Person::class)

        // Add a person to the set
        fun addPerson(name: String) {
            people.plus(name)
        }
    }

build.gradle

    abstract class Person {
        String name
    }

    abstract class MyPluginExtensionNamedDomainObjectSet {
        // Define a named domain object set to hold Person objects
        NamedDomainObjectSet<Person> people = project.objects.namedDomainObjectSet(Person)

        // Add a person to the set
        void addPerson(String name) {
            people.create(name)
        }
    }

## 3. `NamedDomainObjectList`

A `NamedDomainObjectList` holds a list of configurable objects, where each element has a name associated with it.

This is similar to `NamedDomainObjectContainer`, however a `NamedDomainObjectList` doesn’t manage the objects in the collection. They need to be created and added manually.

You can create an instance using the ObjectFactory.namedDomainObjectList() method.

build.gradle.kts

    abstract class Person(val name: String)

    abstract class MyPluginExtensionNamedDomainObjectList {
        // Define a named domain object list to hold Person objects
        private val people: NamedDomainObjectList<Person> = project.objects.namedDomainObjectList(Person::class)

        // Add a person to the container
        fun addPerson(name: String) {
            people.plus(name)
        }
    }

build.gradle

    abstract class Person {
        String name
    }

    abstract class MyPluginExtensionNamedDomainObjectList {
        // Define a named domain object container to hold Person objects
        NamedDomainObjectList<Person> people = project.container(Person)

        // Add a person to the container
        void addPerson(String name) {
            people.create(name: name)
        }
    }

## 4. `NamedDomainObjectContainer`

A `NamedDomainObjectContainer` manages a set of objects, where each element has a name associated with it.

The container takes care of creating and configuring the elements, and provides a DSL that build scripts can use to define and configure elements. It is intended to hold objects which are themselves configurable, for example a set of custom Gradle objects.

Gradle uses `NamedDomainObjectContainer` type extensively throughout the API. For example, the `project.tasks` object used to manage the tasks of a project is a `NamedDomainObjectContainer<Task>`.

You can create a container instance using the ObjectFactory service, which provides the ObjectFactory.domainObjectContainer() method. This is also available using the Project.container() method, however in a custom Gradle type it’s generally better to use the injected `ObjectFactory` service instead of passing around a `Project` instance.

You can also create a container instance using a read-only managed property.

build.gradle.kts

    abstract class Person(val name: String)

    abstract class MyPluginExtensionNamedDomainObjectContainer {
        // Define a named domain object container to hold Person objects
        private val people: NamedDomainObjectContainer<Person> = project.container(Person::class)

        // Add a person to the container
        fun addPerson(name: String) {
            people.create(name)
        }
    }

build.gradle

    abstract class Person {
        String name
    }

    abstract class MyPluginExtensionNamedDomainObjectContainer {
        // Define a named domain object container to hold Person objects
        NamedDomainObjectContainer<Person> people = project.container(Person)

        // Add a person to the container
        void addPerson(String name) {
            people.create(name: name)
        }
    }

In order to use a type with any of the `domainObjectContainer()` methods, it must either

- be a named managed type; or

- expose a property named “name” as the unique, and constant, name for the object. The `domainObjectContainer(Class)` variant of the method creates new instances by calling the constructor of the class that takes a string argument, which is the desired name of the object.

Objects created this way are treated as custom Gradle types, and so can make use of the features discussed in this chapter, for example service injection or managed properties.

See the above link for `domainObjectContainer()` method variants that allow custom instantiation strategies:

    public interface DownloadExtension {
        NamedDomainObjectContainer<Resource> getResources();
    }

    public interface Resource {
        // Type must have a read-only 'name' property
        String getName();

        Property<URI> getUri();

        Property<String> getUserName();
    }

For each container property, Gradle automatically adds a block to the Groovy and Kotlin DSL that you can use to configure the contents of the container:

build.gradle.kts

    plugins {
        id("org.gradle.sample.download")
    }

    download {
        // Can use a block to configure the container contents
        resources {
            register("gradle") {
                uri = uri("https://gradle.org")
            }
        }
    }

build.gradle

    plugins {
        id("org.gradle.sample.download")
    }

    download {
        // Can use a block to configure the container contents
        resources {
            register('gradle') {
                uri = uri('https://gradle.org')
            }
        }
    }

## 5. `ExtensiblePolymorphicDomainObjectContainer`

An ExtensiblePolymorphicDomainObjectContainer is a `NamedDomainObjectContainer` that allows you to define instantiation strategies for different types of objects.

You can create an instance using the ObjectFactory.polymorphicDomainObjectContainer() method:

build.gradle.kts

    abstract class Animal(val name: String)

    class Dog(name: String, val breed: String) : Animal(name)

    abstract class MyPluginExtensionExtensiblePolymorphicDomainObjectContainer(objectFactory: ObjectFactory) {
        // Define a container for animals
        private val animals: ExtensiblePolymorphicDomainObjectContainer<Animal> = objectFactory.polymorphicDomainObjectContainer(Animal::class)

        // Add a dog to the container
        fun addDog(name: String, breed: String) {
            var dog : Dog = Dog(name, breed)
            animals.add(dog)
        }
    }

build.gradle

    abstract class Animal {
        String name
    }

    abstract class Dog extends Animal {
        String breed
    }

    abstract class MyPluginExtensionExtensiblePolymorphicDomainObjectContainer {
        // Define a container for animals
        ExtensiblePolymorphicDomainObjectContainer<Animal> animals

        MyPluginExtensionExtensiblePolymorphicDomainObjectContainer(ObjectFactory objectFactory) {
            // Create the container
            animals = objectFactory.polymorphicDomainObjectContainer(Animal)
        }

        // Add a dog to the container
        void addDog(String name, String breed) {
            animals.create(Dog, name: name, breed: breed)
        }
    }