COLLECTION is a container element to be used each time we have to gather
items of the same kind. It is used in different contexts, each allowing a
limited subset of elements for its content. COLLECTION items must all be of
the same type. COLLECTION can be populated either by a static list of items
(INSTANCE, ATTRIBUTE, ..) or by joining to another COLLECTION by using the
JOIN statement.

In INSTANCE:

1. As child of INSTANCE
    The COLLECTION serves as a container for elements with multiplicity > 1

    Examples of usage in this context would be:
        * an array attribute
        * a reference relation with multiplicity > 1
        * a composition relation with multiplicity > 1

Example of a COLLECTION child of INSTANCE. It must have a role
as an enclosing INSTANCE component. In this example, the collection plays
the role model:Thing.elems within the enclosing instance. The role is the
actual VODMID of the corresponding VO-DML composition:

<INSTANCE dmtype="model:Thing">
    <COLLECTION dmrole="model:Thing.elems">
        <ATTRIBUTE dmtype="model:Foo" value="100" />
        <ATTRIBUTE dmtype="model:Foo" value="110" />
    </COLLECTION>
</INSTANCE>

In GLOBALS:

2. As child of GLOBALS
    The COLLECTION serves as a proxy for TABLE, grouping common INSTANCE for selection by PRIMARY_KEY, FOREIGN_KEY pairs.
    Examples of usage in this context would be:
        * a set of photometry filters, which apply to various rows of a photometric data table, based on the value of the 'band' column.
        * a set of Dataset metadata instances, which apply to various rows of a photometric data table, based on the value of the 'id' column.

Example of COLLECTION child of GLOBALS
t plays no specific role as being part of the GLOBALS elements:

<GLOBALS>
    <!--
    Container for the datasets (one per timeseries)
    -->
    <COLLECTION dmid="IDDatasets" dmrole="">
        <INSTANCE dmid="IDds1" dmtype="ds:experiment.ObsDataset">
            <PRIMARY_KEY dmtype="ivoa:string" value="5813181197970338560"/>
            <ATTRIBUTE dmrole="ds:dataset.Dataset.dataProductType"
                       dmtype="ds:dataset.DataProductType" value="TIMESERIES"/>
            <ATTRIBUTE dmrole="ds:dataset.Dataset.dataProductSubtype"
                       dmtype="ivoa:string" value="GAIA Time Series"/>
            <ATTRIBUTE dmrole="ds:experiment.ObsDataset.calibLevel"
                       dmtype="ivoa:integer" value="1"/>
            <REFERENCE dmrole="ds:experiment.ObsDataset.target" dmref="IDtg1"/>
        </INSTANCE>
        <INSTANCE dmid="IDds1" dmtype="ds:experiment.ObsDataset">
            <PRIMARY_KEY dmtype="ivoa:string" value="5813181197970338561"/>
            ...
        </INSTANCE>
    </COLLECTION>
</GLOBALS>

In COLLECTION:

3. As child of COLLECTION
    The collection contains a matrix of atomic values.

Example of COLLECTION mapping a 2x2 matrix:

<TEMPLATES>
    <INSTANCE dmtype="model:matrix_22">
        <COLLECTION dmrole="model:matrix">
            <COLLECTION>
                <ATTRIBUTE dmtype="ivoa:real" ref="field_11"/>
                <ATTRIBUTE dmtype="ivoa:real" ref="field_12"/>
            </COLLECTION>
            <COLLECTION>
                <ATTRIBUTE dmtype="ivoa:real" ref="field_21"/>
                <ATTRIBUTE dmtype="ivoa:real" ref="field_22"/>
            </COLLECTION>
        </COLLECTION>
    </INSTANCE>
</TEMPLATES>

Populated with JOIN:

Example of COLLECTION populated with a JOIN. The collection will be populated with the rows of another
collection of the MIVOT block identified by @dmid=IDtsIDdata and that
match both WHERE conditions:

<TEMPLATES tableref="IDPKTable">
    <INSTANCE dmid="IDTimeSeries" dmrole="" dmtype="cube:SparseCube">
        ....
        <COLLECTION dmrole="cube:SparseCube.data">
            <JOIN dmref="IDtsIDdata">
                <WHERE foreignkey="IDsrcid" primarykey="IDpksrcid" />
                <WHERE foreignkey="IDband" primarykey="IDpkband" />
            </JOIN>
        </COLLECTION>
    </INSTANCE>
</TEMPLATES>