MultiItemCollection (Cumulus Java Classes Documentation)

java.lang.Object
- com.canto.cumulus.MultiItemCollection

All Implemented Interfaces:

java.lang.AutoCloseable, java.lang.Iterable<Item>

Direct Known Subclasses:

MultiCategoryItemCollection, MultiRecordItemCollection
```
public class MultiItemCollection
extends java.lang.Object
implements java.lang.Iterable<Item>, java.lang.AutoCloseable
```
A collection of ItemCollection objects of different catalogs. You can create a new instance using Server.newMultiItemCollection(String).

Since:

8.0

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addCollectionListener(CollectionListener<MultiItemCollection> listener)` Add a listener that is called whenever a single item is added / updated / deleted, or the whole content has changed, or the sorting has changed for this ItemCollection.
`void`	`addFilter(java.lang.String filterID, java.util.List<? extends FieldData> dataList)` Add a user live filter to this collection.
`void`	`addFilter(java.lang.String filterID, java.util.List<? extends FieldData> dataList, boolean doesNotMatch)` Add a user live filter to this collection.
`void`	`addFilter(java.lang.String filterID, QueryConditionBase queryConditionBase, java.util.Locale locale, FieldDefinition fieldDefinition)` Add a user live filter to this collection.
`void`	`addFilter(java.lang.String filterID, java.lang.String query, java.util.EnumSet<FindFlag> flags, java.util.Locale locale)` Add a user live filter to this collection.
`void`	`addFilter(java.lang.String filterID, java.lang.String query, java.util.Locale locale)` Add a user live filter to this collection.
`static void`	`addGlobalCollectionListener(CollectionListener<MultiItemCollection> listener)` Add a listener that is called whenever a single item is added / updated / deleted, or the whole content of has changed, or the sorting has changed for any ItemCollection.
`int`	`addItem(int catalogID, int itemID)` Add an existing item to this collection
`int`	`addItem(ItemIdentifier itemIdentifier)` Add an existing item to this collection
`void`	`addItemCollection(ItemCollection itemCollection)` Add an ItemCollection to this MultiItemCollection.
`void`	`addItems(java.util.List<ItemIdentifier> itemIDs)` Add a whole list of items to this collection.
`MultiItemCollection`	`clone(boolean createEmptyClone)` Create a clone of this collection.
`MultiItemCollection`	`clone(boolean createEmptyClone, boolean createNewCollection)` Create a clone of this collection.
`void`	`close()` Close this collection and release all native resources that it occupies.
`AssetCollection`	`doAssetAction(java.lang.String assetAction, Asset destinationAssetContainer)` Perform an asset action on the assets of the items of this collection.
`AssetCollection`	`doAssetAction(java.lang.String assetAction, Asset destinationAssetContainer, boolean returnCreatedAssets)` Perform an asset action on the assets of the items of this collection.
`AssetCollection`	`doAssetAction(java.lang.String assetAction, Asset destinationAssetContainer, boolean returnCreatedAssets, java.util.Map<ItemIdentifier,java.util.Map<GUID,JPack>> customParameters)` Perform an asset action on the assets of the items of this collection.
`boolean`	`equals(java.lang.Object o)`
`void`	`find(java.util.List<FieldData> dataList, CombineMode combine)` Perform a search based on the return value of `getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData)` to search for items that have field values in a given range.
`void`	`find(java.util.List<FieldData> dataList, CombineMode combine, boolean logSearchStatistic)` Perform a search based on the return value of `getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData)` to search for items that have field values in a given range.
`void`	`find(java.lang.String query, java.util.EnumSet<FindFlag> flags, CombineMode combine, java.util.Locale locale)` Performs a search for items.
`void`	`find(java.lang.String query, java.util.EnumSet<FindFlag> flags, CombineMode combine, java.util.Locale locale, boolean logSearchStatistic)` Performs a search for items.
`void`	`find(java.lang.String sourceTableName, java.util.List<ItemIdentifier> sourceItemIDs, GUID relationID, int direction, int scope, int restrictionMode, java.util.Set<GUID> restrictionTypes, java.lang.String additionalQuery)` Find items in the collection that are the result of applying a record filter to the given items of the given table.
`void`	`find(java.lang.String sourceTableName, java.util.List<ItemIdentifier> sourceItemIDs, GUID relationID, int direction, int scope, int restrictionMode, java.util.Set<GUID> restrictionTypes, java.lang.String additionalQuery, boolean logSearchStatistic)` Find items in the collection that are the result of applying a record filter to the given items of the given table.
`void`	`find(java.lang.String sourceTableName, java.util.List<ItemIdentifier> sourceItemIDs, java.lang.String filterName)` Find items in the collection that are the result of applying a record filter to the given items of the given table.
`void`	`find(java.lang.String sourceTableName, java.util.List<ItemIdentifier> sourceItemIDs, java.lang.String filterName, boolean logSearchStatistic)` Find items in the collection that are the result of applying a record filter to the given items of the given table.
`void`	`findAll()` Find all available items in this collection.
`void`	`findAll(boolean logSearchStatistic)` Find all available items in this collection.
`java.util.List<java.lang.Integer>`	`getCatalogIDs()` Return the catalog ID of all ItemCollections that are contained in this MultiItemCollection.
`CumulusSession`	`getCumulusSession()` Returns the current `CumulusSession` object.
`int[]`	`getDailyStatistics(GUID fieldUID, java.util.Date startDate, int numberOfDays)` Get statistics on how many items have date field values that fall into days of the range specified.
`int[]`	`getDailyStatistics(GUID fieldUID, DateOnlyFieldValue startDate, int numberOfDays)` Get statistics on how many items have DateOnly field values that fall into days of the range specified.
`Item`	`getItemByID(int catalogID, int itemID)` Return an item specified by catalog ID and item ID.
`Item`	`getItemByID(ItemIdentifier itemIdentifier)` Return an item specified by identifier.
`ItemCollection`	`getItemCollection(int catalogID)` Return the contained ItemCollection for the given catalog ID.
`int`	`getItemCount()` Return the number of items in this collection.
`<T extends FieldData> java.util.List<FieldData>`	`getItemFieldStatistics(T fieldRangeData)` Get statistics on the number of items that have field values in the given value range.
`java.util.List<FieldDefinitionData>`	`getItemFieldsWithStatistics(boolean currentCollection, java.util.Set<GUID> requestedFields, java.util.Locale locale)` Return a list of fields that support getting field value statistics.
`java.util.List<FieldDefinitionData>`	`getItemFieldsWithStatistics(java.util.Locale locale)` Return a list of fields that support getting field value statistics.
`java.util.List<FieldDefinitionData>`	`getItemFieldsWithStatistics(java.util.Set<GUID> requestedFields, java.util.Locale locale)` Return a list of fields that support getting field value statistics.
`java.util.List<RecordData>`	`getItemFieldValues(java.util.Collection<ItemIdentifier> identifiers, java.util.Set<GUID> fieldGUIDs)` Get field values for the given set of items.
`java.util.List<ItemIdentifier>`	`getItemIDs(int startIndex, int numIDs)` Get the Identifier of some or all items of the collection.
`int`	`getItemPosition(int catalogID, int itemID)` Return the zero-based index of the given item inside this collection.
`int`	`getItemPosition(ItemIdentifier itemIdentifier)` Return the zero-based index of the given item inside this collection.
`int`	`getItemTotalCount()` Return the total number of items that are available in the catalogs of the collections contained in this MultiItemCollection.
`MultiLayout`	`getMultiLayout()` Returns the `MultiLayout` for this collection which makes it easier to work with `FieldDefinition` instances from multiple catalogs.
`java.util.List<SortFieldDescriptor>`	`getMultiSorting()` Return the list of fields that this collection is sorted by.
`Server`	`getServer()` Return the server object that this collection was created from.
`SortDirection`	`getSortDirection()` Return the current sort direction of this collection.
`GUID`	`getSorting()` Get the unique ID of the field that this collection is currently sorted by.
`java.lang.String`	`getTableName()` Get the name of the table for this MultiItemCollection.
`int`	`hashCode()`
`boolean`	`hasItem(int catalogID, int itemID)` Return whether the collection contains a given item specified by ID.
`java.util.Iterator<Item>`	`iterator()` Return an iterator that iterates over all items in this collection.
`java.util.Set<ItemIdentifier>`	`matchIDs(java.lang.String query, java.util.EnumSet<FindFlag> flags, java.util.Locale locale, java.util.Set<ItemIdentifier> itemIDs)` Filter the given item IDs and return only those matching a given query.
`void`	`moveItem(int fromPosition, int toPosition)` Move an existing item to a different position inside the collection.
`void`	`quickSearch(java.lang.String searchString, CombineMode combine)` Performs a search for items on the configured QuickSearch fields.
`void`	`removeAllItems()` Remove all items from this collection making it empty.
`void`	`removeCollectionListener(CollectionListener<MultiItemCollection> listener)` Remove a listener previously added with the call to `addCollectionListener(com.canto.cumulus.events.CollectionListener)`
`void`	`removeFilter(java.lang.String filterID)` Remove a user live filter that was added using `addFilter(String, String, java.util.Locale)` or `addFilter(String, java.util.List)`.
`static void`	`removeGlobalCollectionListener(CollectionListener<MultiItemCollection> listener)` Remove a listener previously added using `addGlobalCollectionListener(com.canto.cumulus.events.CollectionListener)`.
`int`	`removeItem(int catalogID, int itemID)` Remove an item from this collection.
`int`	`removeItem(ItemIdentifier itemIdentifier)` Remove an item from this collection.
`void`	`removeItemCollection(int catalogID)` Remove the ItemCollection of the given catalog from this collection.
`void`	`removeItems(java.util.Collection<ItemIdentifier> itemIDs)` Remove a whole list of items from this collection.
`void`	`setFreesorted()` Set this collection to be custom sorted.
`void`	`setMultiSorting(java.util.List<SortFieldDescriptor> sortFields)` Sort this collection by the given list of fields and sorting directions.
`void`	`setSortDirection(SortDirection direction)` Change the sorting direction from ascending to descending or vice-versa.
`void`	`setSorting(GUID fieldUID)` Sort this collection by a given field.
`void`	`updateWantedFields(GUID... wantedFields)` Add the given fields to the list of preferred fields that this collection should retrieve from the server when getting items.
`void`	`updateWantedFields(java.util.Set<GUID> wantedFields)` Add the given fields to the list of preferred fields that this collection should retrieve from the server when getting items.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getCumulusSession
```
public CumulusSession getCumulusSession()
```
    Returns the current CumulusSession object.
    
    Returns:
    the current CumulusSession object.
  - getTableName
```
public java.lang.String getTableName()
```
    Get the name of the table for this MultiItemCollection.
    
    Returns:
    The table name of this collection.
  - close
```
public void close()
```
    Close this collection and release all native resources that it occupies. You should call this method to be sure that the network connection to the Cumulus server is closed. After this call you can no longer work with this object.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
  - clone
```
public MultiItemCollection clone(boolean createEmptyClone)
```
    Create a clone of this collection. The cloned collection will either be empty or contain the same ItemCollections and items as this collection.
    
    Parameters:
    createEmptyClone - Pass true if you want the new collection to be empty. Pass false if it should contain the same items as this collection.
    
    Returns:
    The newly created clone of this collection.
  - clone
```
public MultiItemCollection clone(boolean createEmptyClone,
                        boolean createNewCollection)
```
    Create a clone of this collection. The cloned collection will either be empty or contain the same ItemCollections and items as this collection.
    
    Parameters:
    createEmptyClone - Pass true if you want the new collection to be empty. Pass false if it should contain the same items as this collection.
    createNewCollection - Pass true if you want the new collection has no specific filters and sorting settings. Pass false if you want the new collection to have the same filters and sorting settings as this collection.
    
    Returns:
    The newly created clone of this collection.
    Since:
    
    9.2.4
  - getCatalogIDs
```
public java.util.List<java.lang.Integer> getCatalogIDs()
```
    Return the catalog ID of all ItemCollections that are contained in this MultiItemCollection.
    
    Returns:
    The catalog IDs of all contained ItemCollections.
    See Also:
    addItemCollection(ItemCollection)
  - getItemCollection
```
public ItemCollection getItemCollection(int catalogID)
```
    Return the contained ItemCollection for the given catalog ID.
    
    Parameters:
    catalogID - The catalog ID of the collection to be returned.
    
    Returns:
    The ItemCollection contained in this collection that comes from the given catalog.
    See Also:
    addItemCollection(ItemCollection)
  - addItemCollection
```
public void addItemCollection(ItemCollection itemCollection)
```
    Add an ItemCollection to this MultiItemCollection. The table name of the ItemCollection must match the table name of this MultiItemCollection.
    
    Parameters:
    itemCollection - The ItemCollection to add to this collection.
    See Also:
    removeItemCollection(int)
  - removeItemCollection
```
public void removeItemCollection(int catalogID)
                          throws InvalidArgumentException
```
    Remove the ItemCollection of the given catalog from this collection.
    
    Parameters:
    catalogID - The ID of the collection to remove.
    
    Throws:
    
    InvalidArgumentException - if the catalog ID does not specify an ItemCollection inside this MultiItemCollection.
  - getItemCount
```
public int getItemCount()
```
    Return the number of items in this collection.
    
    Returns:
    The number of items in this collection.
    See Also:
    getItemIDs(int, int)
  - hasItem
```
public boolean hasItem(int catalogID,
              int itemID)
```
    Return whether the collection contains a given item specified by ID.
    
    Parameters:
    catalogID - catalog ID of the item to check
    itemID - The ID of the item to check
    
    Returns:
    true if the given item is contained in the collection. Return false otherwise.
    Since:
    
    8.1.1
  - getItemTotalCount
```
public int getItemTotalCount()
```
    Return the total number of items that are available in the catalogs of the collections contained in this MultiItemCollection.
    
    Returns:
    The total number of items in all catalogs of this collection.
  - getItemIDs
```
public java.util.List<ItemIdentifier> getItemIDs(int startIndex,
                                        int numIDs)
```
    Get the Identifier of some or all items of the collection.
    
    Parameters:
    startIndex - The zero-based index of the first item to return
    numIDs - The number of item Identifiers to return. You can specify a number that exceeds the total number of available items here. The returned list will be limited to the available items only.
    
    Returns:
    A list containing the Identifiers of the items at the given position in the collection.
  - getItemPosition
```
public int getItemPosition(ItemIdentifier itemIdentifier)
```
    Return the zero-based index of the given item inside this collection.
    
    Parameters:
    itemIdentifier - The Identifier of the item
    
    Returns:
    The zero-based index of the item in this collection.
    
    Throws:
    
    CumulusException - on error
  - getItemPosition
```
public int getItemPosition(int catalogID,
                  int itemID)
```
    Return the zero-based index of the given item inside this collection.
    
    Parameters:
    catalogID - The catalog ID of the item
    itemID - The item ID of the item inside it's catalog
    
    Returns:
    The zero-based index of the item in this collection.
    
    Throws:
    
    CumulusException - on error
  - getItemByID
```
public Item getItemByID(int catalogID,
               int itemID)
                 throws ItemNotFoundException,
                        CumulusException
```
    Return an item specified by catalog ID and item ID.
    
    Parameters:
    catalogID - The ID of the item's catalog to be returned.
    itemID - The ID of the item to be returned.
    
    Returns:
    The Item object for the given catalog ID and item ID.
    
    Throws:
    
    ItemNotFoundException - if the collection does not contain the given item.
    
    CumulusException - on other errors.
  - getItemByID
```
public Item getItemByID(ItemIdentifier itemIdentifier)
                 throws ItemNotFoundException,
                        CumulusException
```
    Return an item specified by identifier.
    
    Parameters:
    itemIdentifier - The identifier of the item to be returned.
    
    Returns:
    The Item object for the given identifier.
    
    Throws:
    
    ItemNotFoundException - if the collection does not contain the given item.
    
    CumulusException - on other errors.
  - moveItem
```
public void moveItem(int fromPosition,
            int toPosition)
```
    Move an existing item to a different position inside the collection.
    
    Parameters:
    fromPosition - The zero-based index that the item is currently located.
    toPosition - The desired zero-based index that the item should be moved to.
  - addItem
```
public int addItem(ItemIdentifier itemIdentifier)
```
    Add an existing item to this collection
    
    Parameters:
    itemIdentifier - The identifier of the item to add.
    
    Returns:
    The new zero-based index of the added item in this collection.
  - addItem
```
public int addItem(int catalogID,
          int itemID)
```
    Add an existing item to this collection
    
    Parameters:
    catalogID - The ID of the item's catalog to be added.
    itemID - The ID of the item to be added.
    
    Returns:
    The new zero-based index of the added item in this collection.
  - addItems
```
public void addItems(java.util.List<ItemIdentifier> itemIDs)
```
    Add a whole list of items to this collection. The items are specified by their identifiers. Items that already contained in this collection are not added a second time.
    
    Parameters:
    itemIDs - The list identifiers of the items to add.
  - removeItem
```
public int removeItem(int catalogID,
             int itemID)
```
    Remove an item from this collection.
    
    Parameters:
    catalogID - The ID of the item's catalog to be removed.
    itemID - The ID of the item to be removed.
    
    Returns:
    The old zero-based index of the item in this collection.
    See Also:
    removeItem(ItemIdentifier)
  - removeItem
```
public int removeItem(ItemIdentifier itemIdentifier)
```
    Remove an item from this collection.
    
    Parameters:
    itemIdentifier - The identifier of the item to be removed.
    
    Returns:
    The old zero-based index of the item in this collection.
    See Also:
    removeItem(int, int)
  - removeItems
```
public void removeItems(java.util.Collection<ItemIdentifier> itemIDs)
```
    Remove a whole list of items from this collection. The items are specified by their identifiers.
    
    Parameters:
    itemIDs - The list of identifiers for the items to be removed.
  - removeAllItems
```
public void removeAllItems()
```
    Remove all items from this collection making it empty.
  - find
```
public void find(java.lang.String sourceTableName,
        java.util.List<ItemIdentifier> sourceItemIDs,
        java.lang.String filterName)
          throws java.lang.IllegalArgumentException,
                 CumulusException
```
    Find items in the collection that are the result of applying a record filter to the given items of the given table. This method implements the core functionality that is available in the Cumulus client in split-view to show items that are determined by applying a record filter to selected items of another view. You can use this method to find all user comments for a given asset record.
    
    Parameters:
    sourceTableName - The name of the table that the given "sourceItemIDs" items are coming from.
    sourceItemIDs - The input items for the filter to apply. The items are taken from the given table.
    filterName - The name of a record filter to be used for filtering the resulting item.
    
    Throws:
    
    java.lang.IllegalArgumentException - if a parameter is wrong (e.g. the filter name is invalid)
    
    CumulusException - on other error.
  - find
```
public void find(java.lang.String sourceTableName,
        java.util.List<ItemIdentifier> sourceItemIDs,
        java.lang.String filterName,
        boolean logSearchStatistic)
          throws java.lang.IllegalArgumentException,
                 CumulusException
```
    Find items in the collection that are the result of applying a record filter to the given items of the given table. This method implements the core functionality that is available in the Cumulus client in split-view to show items that are determined by applying a record filter to selected items of another view. You can use this method to find all user comments for a given asset record.
    
    Parameters:
    sourceTableName - The name of the table that the given "sourceItemIDs" items are coming from.
    sourceItemIDs - The input items for the filter to apply. The items are taken from the given table.
    filterName - The name of a record filter to be used for filtering the resulting item.
    logSearchStatistic - specifies whether the query result has to be logged in the search statistic
    
    Throws:
    
    java.lang.IllegalArgumentException - if a parameter is wrong (e.g. the filter name is invalid)
    
    CumulusException - on other error.
    Since:
    
    10.2
  - find
```
public void find(java.lang.String sourceTableName,
        java.util.List<ItemIdentifier> sourceItemIDs,
        GUID relationID,
        int direction,
        int scope,
        int restrictionMode,
        java.util.Set<GUID> restrictionTypes,
        java.lang.String additionalQuery)
```
    Find items in the collection that are the result of applying a record filter to the given items of the given table. This method implements the core functionality that is available in the Cumulus client in split-view to show items that are determined by applying a record filter to selected items of another view. You can use this method to find all user comments for a given asset record.
    
    Parameters:
    sourceTableName - The name of the table that the given "sourceItemIDs" items are coming from.
    sourceItemIDs - The input items for the filter to apply. The items are taken from the given table.
    relationID - The ID of the relation to the items found. This is one of the following values: GUID.UID_ASSET_RELATION_CONTAINS, GUID.UID_ASSET_RELATION_REFERENCES, GUID.UID_ASSET_RELATION_IS_ALTERNATE, GUID.UID_ASSET_RELATION_IS_VARIATION, GUID.UID_ASSET_RELATION_IS_SELECTED, GUID.UID_ASSET_RELATION_RELATED_IN_TABLE, GUID.UID_ASSET_RELATION_MATCHES_ALL_ASSIGNED_CATEGORIES, GUID.UID_ASSET_RELATION_MATCHES_ONE_ASSIGNED_CATEGORY
    direction - The direction of the relation to follow. Possible values are RecordFilter.DIRECTION_FORWARD, RecordFilter.DIRECTION_BACKWARD.
    scope - The scope of the found related items. This is one of the following: RecordFilter.SCOPE_OPTION_FIRST_LEVEL, RecordFilter.SCOPE_OPTION_LAST_LEVEL, RecordFilter.SCOPE_OPTION_ALL_LEVELS
    restrictionMode - The way the restriction types are evaluated. Possible values are RecordFilter.RESTRICTION_MODE_OPTION_ALL_TYPES, RecordFilter.RESTRICTION_MODE_OPTION_INCLUDE, RecordFilter.RESTRICTION_MODE_OPTION_EXCLUDE
    restrictionTypes - The asset types to restrict the result to. This is a set of one or more of the following GUIDs: GUID.UID_ASSET_TYPE_PAGE, GUID.UID_ASSET_TYPE_IMAGE, GUID.UID_ASSET_TYPE_VIDEO_SHOT If this set is empty or the parameter is null then no restriction by type is applied.
    additionalQuery - The additional query to be applied to the items found by the options above. If this query is null then no additional query is applied.
    Since:
    
    9.1
  - find
```
public void find(java.lang.String sourceTableName,
        java.util.List<ItemIdentifier> sourceItemIDs,
        GUID relationID,
        int direction,
        int scope,
        int restrictionMode,
        java.util.Set<GUID> restrictionTypes,
        java.lang.String additionalQuery,
        boolean logSearchStatistic)
```
    Find items in the collection that are the result of applying a record filter to the given items of the given table. This method implements the core functionality that is available in the Cumulus client in split-view to show items that are determined by applying a record filter to selected items of another view. You can use this method to find all user comments for a given asset record.
    
    Parameters:
    sourceTableName - The name of the table that the given "sourceItemIDs" items are coming from.
    sourceItemIDs - The input items for the filter to apply. The items are taken from the given table.
    relationID - The ID of the relation to the items found. This is one of the following values: GUID.UID_ASSET_RELATION_CONTAINS, GUID.UID_ASSET_RELATION_REFERENCES, GUID.UID_ASSET_RELATION_IS_ALTERNATE, GUID.UID_ASSET_RELATION_IS_VARIATION, GUID.UID_ASSET_RELATION_IS_SELECTED, GUID.UID_ASSET_RELATION_RELATED_IN_TABLE, GUID.UID_ASSET_RELATION_MATCHES_ALL_ASSIGNED_CATEGORIES, GUID.UID_ASSET_RELATION_MATCHES_ONE_ASSIGNED_CATEGORY
    direction - The direction of the relation to follow. Possible values are RecordFilter.DIRECTION_FORWARD, RecordFilter.DIRECTION_BACKWARD.
    scope - The scope of the found related items. This is one of the following: RecordFilter.SCOPE_OPTION_FIRST_LEVEL, RecordFilter.SCOPE_OPTION_LAST_LEVEL, RecordFilter.SCOPE_OPTION_ALL_LEVELS
    restrictionMode - The way the restriction types are evaluated. Possible values are RecordFilter.RESTRICTION_MODE_OPTION_ALL_TYPES, RecordFilter.RESTRICTION_MODE_OPTION_INCLUDE, RecordFilter.RESTRICTION_MODE_OPTION_EXCLUDE
    restrictionTypes - The asset types to restrict the result to. This is a set of one or more of the following GUIDs: GUID.UID_ASSET_TYPE_PAGE, GUID.UID_ASSET_TYPE_IMAGE, GUID.UID_ASSET_TYPE_VIDEO_SHOT If this set is empty or the parameter is null then no restriction by type is applied.
    additionalQuery - The additional query to be applied to the items found by the options above. If this query is null then no additional query is applied.
    logSearchStatistic - specifies whether the query result has to be logged in the search statistic
    Since:
    
    10.2
  - matchIDs
```
public java.util.Set<ItemIdentifier> matchIDs(java.lang.String query,
                                     java.util.EnumSet<FindFlag> flags,
                                     java.util.Locale locale,
                                     java.util.Set<ItemIdentifier> itemIDs)
                                       throws QueryParserException,
                                              CumulusException
```
    Filter the given item IDs and return only those matching a given query.
    
    Parameters:
    query - the query string in this format. If the given query string is empty, nothing will be returned.
    flags - Flags that control how the query string is parsed and how the search is performed.
    locale - Locale to use when parsing locale dependent string values or null for the default locale
    itemIDs - The item IDs to use as input.
    
    Returns:
    a new set of item IDs that are the input IDs filtered by the given query.
    
    Throws:
    
    QueryParserException - on error parsing the query (e.g. field does not exist in the catalog)
    
    CumulusException - on other errors
    Since:
    
    10.1
  - setSorting
```
public void setSorting(GUID fieldUID)
                throws CumulusException
```
    Sort this collection by a given field. The field is specified by it's unique ID. The field needs to be sortable in all catalogs that this collection contains collections for. You may check this by inspecting FieldDefinition.getIndexing().
    
    Parameters:
    fieldUID - The unique ID of the field to use for sorting.
    
    Throws:
    
    CumulusException - on errors.
  - setMultiSorting
```
public void setMultiSorting(java.util.List<SortFieldDescriptor> sortFields)
                     throws CumulusException
```
    Sort this collection by the given list of fields and sorting directions. The fields are specified by their unique IDs. The fields need to be sortable. You may check this by inspecting FieldDefinition.getIndexing().
    
    Parameters:
    sortFields - The fields to sort by including whether to sort ascending or descending.
    
    Throws:
    
    CumulusException - on errors.
    Since:
    
    8.1
  - getMultiSorting
```
public java.util.List<SortFieldDescriptor> getMultiSorting()
```
    Return the list of fields that this collection is sorted by. If the collection is not sorted by any field the returned list is empty.
    
    Returns:
    The list of fields that this collection is sorted by (empty for free sorted collection).
    Since:
    
    8.1
  - setSortDirection
```
public void setSortDirection(SortDirection direction)
```
    Change the sorting direction from ascending to descending or vice-versa.
    
    Parameters:
    direction - The new sorting direction.
  - getSorting
```
public GUID getSorting()
```
    Get the unique ID of the field that this collection is currently sorted by. It returns null if the collection is not sorted by any field.
    
    Returns:
    The unique field ID of the current sorting field.
  - getSortDirection
```
public SortDirection getSortDirection()
```
    Return the current sort direction of this collection. If the collection is sorted by multiple fields this returns the direction of the first level field.
    
    Returns:
    The current sort direction.
  - setFreesorted
```
public void setFreesorted()
```
    Set this collection to be custom sorted. This means that newly added items are added to the end of the collection and does not respect any sorting field.
  - findAll
```
public void findAll()
```
    Find all available items in this collection. The collection is filled with all items that the current user is allowed to access.
  - findAll
```
public void findAll(boolean logSearchStatistic)
```
    Find all available items in this collection. The collection is filled with all items that the current user is allowed to access.
    
    Parameters:
    logSearchStatistic - specifies whether the query result has to be logged in the search statistic
    Since:
    
    11.1.6
  - find
```
public void find(java.lang.String query,
        java.util.EnumSet<FindFlag> flags,
        CombineMode combine,
        java.util.Locale locale)
```
    Performs a search for items.
    Parameters:
    query - the query string in this format. If the given query string is empty, nothing will be found.
    flags - The set of find flags to use for searching, see FindFlag
    combine - specifies how to combine the result of this search with the existing contents of the collection.:
    
    CombineMode.FIND_NEW: the search replaces the current contents of the collection.
    
    CombineMode.FIND_NARROW: the search result will only leave the items in the collection that match the query.
    
    CombineMode.FIND_BROADEN: the search result will be added to the current collection contents.
    locale - Locale to use when parsing locale dependent string values or null for the default locale
    
    Throws:
    
    CumulusException - in case of an error // * @throws com.canto.cumulus.exceptions.QueryParserException in case of an invalid query string
  - find
```
public void find(java.lang.String query,
        java.util.EnumSet<FindFlag> flags,
        CombineMode combine,
        java.util.Locale locale,
        boolean logSearchStatistic)
```
    Performs a search for items.
    Parameters:
    query - the query string in this format. If the given query string is empty, nothing will be found.
    flags - The set of find flags to use for searching, see FindFlag
    combine - specifies how to combine the result of this search with the existing contents of the collection.:
    
    CombineMode.FIND_NEW: the search replaces the current contents of the collection.
    
    CombineMode.FIND_NARROW: the search result will only leave the items in the collection that match the query.
    
    CombineMode.FIND_BROADEN: the search result will be added to the current collection contents.
    locale - Locale to use when parsing locale dependent string values or null for the default locale
    logSearchStatistic - specifies whether the query result has to be logged in the search statistic
    
    Throws:
    
    CumulusException - in case of an error // * @throws com.canto.cumulus.exceptions.QueryParserException in case of an invalid query string
    Since:
    
    10.2
  - quickSearch
```
public void quickSearch(java.lang.String searchString,
               CombineMode combine)
```
    Performs a search for items on the configured QuickSearch fields.
    
    Parameters:
    searchString - the string to search for
    
    Throws:
    
    CumulusException - in case of an error // * @throws com.canto.cumulus.exceptions.QueryParserException in case of an invalid query string
    Since:
    
    10.1.2
  - getItemFieldValues
```
public java.util.List<RecordData> getItemFieldValues(java.util.Collection<ItemIdentifier> identifiers,
                                            java.util.Set<GUID> fieldGUIDs)
```
    Get field values for the given set of items. This is a method that is optimized for performance in getting several field values for a whole list of items.
    
    Parameters:
    identifiers - The identifiers of the items whose field values to get.
    fieldGUIDs - The unique IDs of the fields to get the values for.
    
    Returns:
    A list of data wrapper objects that contain the field values for each item. This list may contain fewer items than requested in case items were deleted during the call.
  - getDailyStatistics
```
public int[] getDailyStatistics(GUID fieldUID,
                       java.util.Date startDate,
                       int numberOfDays)
                         throws CumulusException
```
    Get statistics on how many items have date field values that fall into days of the range specified. You can use this method to find out how many items were used in the specified time range.
    
    Parameters:
    fieldUID - The unique ID of the field to examine.
    startDate - The start date and time in UTC. The statistics will start at the given second and add 24 hours for each day to build the ranges for each day.
    numberOfDays - The number of 24-hor days to examine starting at the given second.
    
    Returns:
    The number of items for each of the days requested. The returned array will contain one number for each day requested.
    
    Throws:
    
    CumulusException - on error (e.g. the field does not exist)
  - getDailyStatistics
```
public int[] getDailyStatistics(GUID fieldUID,
                       DateOnlyFieldValue startDate,
                       int numberOfDays)
                         throws CumulusException
```
    Get statistics on how many items have DateOnly field values that fall into days of the range specified. You can use this method to find out how many items were used in the specified time range.
    
    Parameters:
    fieldUID - The unique ID of the field to examine.
    startDate - The start date. The statistics will start at the given second and add 24 hours for each day to build the ranges for each day.
    numberOfDays - The number of 24-hor days to examine starting at the given second.
    
    Returns:
    The number of items for each of the days requested. The returned array will contain one number for each day requested.
    
    Throws:
    
    CumulusException - on error (e.g. the field does not exist)
    Since:
    
    8.6
  - getItemFieldsWithStatistics
```
public java.util.List<FieldDefinitionData> getItemFieldsWithStatistics(java.util.Locale locale)
```
    Return a list of fields that support getting field value statistics. The resulting list contains objects that contain information about each field as well as the number of items that have values in the field. Typically you start calling this method and then recursively call getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData) to get field value statistics for value ranges of a given field. You can pass each returned FieldDefinitionData object to a call to getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData).
    
    Parameters:
    locale - The locale to use for field value display string later in the process.
    
    Returns:
    The list of fields that support field value statistics.
    See Also:
    getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData), find(java.util.List, com.canto.cumulus.constants.CombineMode)
  - getItemFieldsWithStatistics
```
public java.util.List<FieldDefinitionData> getItemFieldsWithStatistics(java.util.Set<GUID> requestedFields,
                                                              java.util.Locale locale)
```
    Return a list of fields that support getting field value statistics. The resulting list contains objects that contain information about each field as well as the number of items that have values in the field. Typically you start calling this method and then recursively call getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData) to get field value statistics for value ranges of a given field. You can pass each returned FieldDefinitionData object to a call to getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData).
    
    Parameters:
    requestedFields - set of field UIDs to evaluate for the result of this call. It's recommended to only request statistics for the fields you are really interested in
    locale - The locale to use for field value display string later in the process.
    
    Returns:
    The list of fields that support field value statistics.
    Since:
    
    8.1.1
    
    See Also:
    getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData), find(java.util.List, com.canto.cumulus.constants.CombineMode)
  - getItemFieldsWithStatistics
```
public java.util.List<FieldDefinitionData> getItemFieldsWithStatistics(boolean currentCollection,
                                                              java.util.Set<GUID> requestedFields,
                                                              java.util.Locale locale)
```
    Return a list of fields that support getting field value statistics. The resulting list contains objects that contain information about each field as well as the number of items that have values in the field. Typically you start calling this method and then recursively call getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData) to get field value statistics for value ranges of a given field. You can pass each returned FieldDefinitionData object to a call to getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData).
    
    Parameters:
    currentCollection - specifies whether the result should only contain values that are valid for the current collection content.
    requestedFields - set of field UIDs to evaluate for the result of this call. It's recommended to only request statistics for the fields you are really interested in
    locale - The locale to use for field value display string later in the process.
    
    Returns:
    The list of fields that support field value statistics.
    Since:
    
    8.6
    
    See Also:
    getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData), find(java.util.List, com.canto.cumulus.constants.CombineMode)
  - getItemFieldStatistics
```
public <T extends FieldData> java.util.List<FieldData> getItemFieldStatistics(T fieldRangeData)
```
    Get statistics on the number of items that have field values in the given value range. The given value range is split into a number of sub-ranges. The resulting list contains objects that contain information about each field value sub-range as well as the number of items that have values in the field.
    
    Parameters:
    fieldRangeData - The value range to get the statistics for. typically this parameter is the result of a call to getItemFieldsWithStatistics(java.util.Locale) or getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData).
    
    Returns:
    A list of sub-ranges for the given value range along with statistics on how many items have values that fall into each of the sub-ranges.
    See Also:
    getItemFieldsWithStatistics(java.util.Locale), find(java.util.List, com.canto.cumulus.constants.CombineMode)
  - find
```
public void find(java.util.List<FieldData> dataList,
        CombineMode combine)
```
    Perform a search based on the return value of getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData) to search for items that have field values in a given range.
    Parameters:
    dataList - The list of field value ranges to search for.
    combine - specifies how to combine the result of this search with the existing contents of the collection.:
    
    CombineMode.FIND_NEW: the search replaces the current contents of the collection.
    
    CombineMode.FIND_NARROW: the search result will only leave the items in the collection that match the query.
    
    CombineMode.FIND_BROADEN: the search result will be added to the current collection contents.
  - find
```
public void find(java.util.List<FieldData> dataList,
        CombineMode combine,
        boolean logSearchStatistic)
```
    Perform a search based on the return value of getItemFieldStatistics(com.canto.cumulus.db.statistics.FieldData) to search for items that have field values in a given range.
    Parameters:
    dataList - The list of field value ranges to search for.
    combine - specifies how to combine the result of this search with the existing contents of the collection.:
    
    CombineMode.FIND_NEW: the search replaces the current contents of the collection.
    
    CombineMode.FIND_NARROW: the search result will only leave the items in the collection that match the query.
    
    CombineMode.FIND_BROADEN: the search result will be added to the current collection contents.
    logSearchStatistic - specifies whether the query result has to be logged in the search statistic
    Since:
    
    10.2
  - addFilter
```
public void addFilter(java.lang.String filterID,
             java.lang.String query,
             java.util.Locale locale)
               throws CumulusException
```
    Add a user live filter to this collection. This filter limits the items returned by any search operation.
    
    Parameters:
    filterID - The ID for this filter. You can use any string. If you want to be sure that the ID is not used by anyone else you can call new GUID ()).toString () to generate a unique ID.
    query - The query for this filter in this format. Only items that can be found by the query will be left in the collection.
    locale - The locale object to use for parsing the query
    
    Throws:
    
    CumulusException - on other error.
    See Also:
    addFilter(String, java.util.List), removeFilter(String)
  - addFilter
```
public void addFilter(java.lang.String filterID,
             java.lang.String query,
             java.util.EnumSet<FindFlag> flags,
             java.util.Locale locale)
               throws CumulusException
```
    Add a user live filter to this collection. This filter limits the items returned by any search operation.
    
    Parameters:
    filterID - The ID for this filter. You can use any string. If you want to be sure that the ID is not used by anyone else you can call new GUID ().toString () to generate a unique ID.
    query - The query for this filter in this format. Only items that can be found by the query will be left in the collection.
    flags - The set of find flags to use for filtering, see FindFlag
    locale - The locale object to use for parsing the query
    
    Throws:
    
    CumulusException - on other error.
    Since:
    
    9.0
    
    See Also:
    addFilter(String, java.util.List), removeFilter(String)
  - addFilter
```
public void addFilter(java.lang.String filterID,
             java.util.List<? extends FieldData> dataList)
               throws CumulusException
```
    Add a user live filter to this collection. This filter limits the items returned by any search operation.
    
    Parameters:
    filterID - The ID for this filter. You can use any string. If you want to be sure that the ID is not used by anyone else you can call new GUID ().toString () to generate a unique ID.
    dataList - The list of field value ranges to search for.
    
    Throws:
    
    CumulusException - on other error.
    See Also:
    addFilter(String, String, java.util.Locale), removeFilter(String)
  - addFilter
```
public void addFilter(java.lang.String filterID,
             java.util.List<? extends FieldData> dataList,
             boolean doesNotMatch)
               throws CumulusException
```
    Add a user live filter to this collection. This filter limits the items returned by any search operation.
    
    Parameters:
    filterID - The ID for this filter. You can use any string. If you want to be sure that the ID is not used by anyone else you can call new GUID ().toString () to generate a unique ID.
    dataList - The list of field value ranges to search for.
    doesNotMatch - add the filter to find all items that do not match the given field data.
    
    Throws:
    
    CumulusException - on other error.
    See Also:
    addFilter(String, String, java.util.Locale), removeFilter(String)
  - addFilter
```
public void addFilter(java.lang.String filterID,
             QueryConditionBase queryConditionBase,
             java.util.Locale locale,
             FieldDefinition fieldDefinition)
               throws CumulusException
```
    Add a user live filter to this collection. This filter limits the items returned by any search operation.
    
    Parameters:
    filterID - The ID for this filter. You can use any string. If you want to be sure that the ID is not used by anyone else you can call new GUID ().toString () to generate a unique ID.
    queryConditionBase - The condition to filter for
    locale - Locale to be used for parsing the condition
    fieldDefinition - the field definition of the field to use as a filter
    
    Throws:
    
    CumulusException - on other error.
    Since:
    
    8.1
    
    See Also:
    addFilter(String, String, java.util.Locale), removeFilter(String)
  - removeFilter
```
public void removeFilter(java.lang.String filterID)
```
    Remove a user live filter that was added using addFilter(String, String, java.util.Locale) or addFilter(String, java.util.List).
    
    Parameters:
    filterID - The ID string of the filter.
    See Also:
    addFilter(String, String, java.util.Locale), addFilter(String, java.util.List)
  - doAssetAction
```
public AssetCollection doAssetAction(java.lang.String assetAction,
                            Asset destinationAssetContainer)
                              throws CumulusException
```
    Perform an asset action on the assets of the items of this collection.
    
    Parameters:
    destinationAssetContainer - The destination container asset to store the resulting assets.
    assetAction - The name of the asset action to perform.
    
    Returns:
    The collection of resulting assets.
    
    Throws:
    
    CumulusException - on errors.
  - doAssetAction
```
public AssetCollection doAssetAction(java.lang.String assetAction,
                            Asset destinationAssetContainer,
                            boolean returnCreatedAssets)
                              throws CumulusException
```
    Perform an asset action on the assets of the items of this collection.
    
    Parameters:
    destinationAssetContainer - The destination container asset to store the resulting assets.
    assetAction - The name of the asset action to perform.
    returnCreatedAssets - Specify true to return the created assets, otherwise false.
    
    Returns:
    The collection of resulting assets when returnCreatedAssets is true, otherwise null
    
    Throws:
    
    CumulusException - on errors.
    Since:
    
    8.6.1
  - doAssetAction
```
public AssetCollection doAssetAction(java.lang.String assetAction,
                            Asset destinationAssetContainer,
                            boolean returnCreatedAssets,
                            java.util.Map<ItemIdentifier,java.util.Map<GUID,JPack>> customParameters)
                              throws CumulusException
```
    Perform an asset action on the assets of the items of this collection.
    
    Parameters:
    destinationAssetContainer - The destination container asset to store the resulting assets.
    assetAction - The name of the asset action to perform.
    returnCreatedAssets - Specify true to return the created assets, otherwise false.
    customParameters - Custom parameters for each item and each module configured in the asset action. The actual parameter data is provided as a package.
    
    Returns:
    The collection of resulting assets when returnCreatedAssets is true, otherwise null
    
    Throws:
    
    CumulusException - on errors.
    Since:
    
    9.2.1
  - getServer
```
public Server getServer()
```
    Return the server object that this collection was created from. If the collection was created for local catalogs only the returned value is null.
    
    Returns:
    The server object that created this collection or null if it was created by a CumulusSession.
  - updateWantedFields
```
public void updateWantedFields(GUID... wantedFields)
```
    Add the given fields to the list of preferred fields that this collection should retrieve from the server when getting items. This method is available to optimize field access performance. When getting an item from the server the MultiItemCollection immediately gets values of preferred fields. When accessing other field values later it has to get these additional field values from the server individually decreasing the performance. All fields that are accessed are automatically added to the list of preferred fields. You can call this method to add some fields before you start getting items from tis collection to make sure the collection gets all these field values when getting the first item.
    
    Parameters:
    wantedFields - the unique ID of fields you want to add to the list of preferred fields to get.
  - updateWantedFields
```
public void updateWantedFields(java.util.Set<GUID> wantedFields)
```
    Add the given fields to the list of preferred fields that this collection should retrieve from the server when getting items. This method is available to optimize field access performance. When getting an item from the server the MultiItemCollection immediately gets values of preferred fields. When accessing other field values later it has to get these additional field values from the server individually decreasing the performance. All fields that are accessed are automatically added to the list of preferred fields. You can call this method to add some fields before you start getting items from tis collection to make sure the collection gets all these field values when getting the first item.
    
    Parameters:
    wantedFields - the unique ID of fields you want to add to the list of preferred fields to get.
  - getMultiLayout
```
public MultiLayout getMultiLayout()
```
    Returns the MultiLayout for this collection which makes it easier to work with FieldDefinition instances from multiple catalogs.
    
    Returns:
    MultiLayout for this collection
    Since:
    
    9.0
  - iterator
```
public java.util.Iterator<Item> iterator()
```
    Return an iterator that iterates over all items in this collection. This allows you to use Java 5 for-each loops that simplify your source code:
```
 for (Item item : itemCollection)
 {
    // use the item
 }
 
```
    The iterator returned allows you to remove an item consistently:
```
 Iterator  it = iterator ();
 while (it.hasNext ())
 {
     Item item = it.next ();
     if (!item.hasValue (GUID.UID_REC_LABEL))
     {
         it.remove ();
     }
 }
 
```
    Specified by:
    
    iterator in interface java.lang.Iterable<Item>
    
    Returns:
    An iterator for all items in this collection.
  - addCollectionListener
```
public void addCollectionListener(CollectionListener<MultiItemCollection> listener)
```
    Add a listener that is called whenever a single item is added / updated / deleted, or the whole content has changed, or the sorting has changed for this ItemCollection. This method adds a listener to a specific MultiItemCollection. If you are interested in changes in any of the MultiItemCollection objects use addGlobalCollectionListener(com.canto.cumulus.events.CollectionListener) instead. Call removeCollectionListener(com.canto.cumulus.events.CollectionListener) to remove this listener from the collection.
    
    Parameters:
    listener - The listener to add.
    See Also:
    removeCollectionListener(com.canto.cumulus.events.CollectionListener), addGlobalCollectionListener(com.canto.cumulus.events.CollectionListener)
  - removeCollectionListener
```
public void removeCollectionListener(CollectionListener<MultiItemCollection> listener)
```
    Remove a listener previously added with the call to addCollectionListener(com.canto.cumulus.events.CollectionListener)
    
    Parameters:
    listener - The listener to remove.
    See Also:
    addCollectionListener(com.canto.cumulus.events.CollectionListener)
  - addGlobalCollectionListener
```
public static void addGlobalCollectionListener(CollectionListener<MultiItemCollection> listener)
```
    Add a listener that is called whenever a single item is added / updated / deleted, or the whole content of has changed, or the sorting has changed for any ItemCollection. Use this to get notified on any MultiItemCollection changes. If you are interested in a specific MultiItemCollection you should use addCollectionListener(com.canto.cumulus.events.CollectionListener) instead. Call removeGlobalCollectionListener(com.canto.cumulus.events.CollectionListener) to remove this global listener from the MultiItemCollection class.
    
    Parameters:
    listener - The listener to add globally.
  - removeGlobalCollectionListener
```
public static void removeGlobalCollectionListener(CollectionListener<MultiItemCollection> listener)
```
    Remove a listener previously added using addGlobalCollectionListener(com.canto.cumulus.events.CollectionListener).
    
    Parameters:
    listener - The listener to remove.
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object

www.canto.com
Canto, the Canto logo, the Cumulus logo, and Cumulus are registered trademarks of Canto GmbH, registered in the U.S. and other countries.

Class MultiItemCollection

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getCumulusSession

getTableName

close

clone

clone

getCatalogIDs

getItemCollection

addItemCollection

removeItemCollection

getItemCount

hasItem

getItemTotalCount

getItemIDs

getItemPosition

getItemPosition

getItemByID

getItemByID

moveItem

addItem

addItem

addItems

removeItem

removeItem

removeItems

removeAllItems

find

find

find

find

matchIDs

setSorting

setMultiSorting

getMultiSorting

setSortDirection

getSorting

getSortDirection

setFreesorted

findAll

findAll

find

find

quickSearch

getItemFieldValues

getDailyStatistics

getDailyStatistics

getItemFieldsWithStatistics

getItemFieldsWithStatistics

getItemFieldsWithStatistics

getItemFieldStatistics

find

find

addFilter

addFilter

addFilter

addFilter

addFilter

removeFilter

doAssetAction

doAssetAction

doAssetAction

getServer

updateWantedFields

updateWantedFields

getMultiLayout

iterator

addCollectionListener

removeCollectionListener

addGlobalCollectionListener

removeGlobalCollectionListener

equals

hashCode