ItemCollection (Cumulus Java Classes Documentation)

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

All Implemented Interfaces:

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

Direct Known Subclasses:

CategoryItemCollection, RecordItemCollection
```
public class ItemCollection
extends java.lang.Object
implements java.lang.Iterable<Item>, java.lang.AutoCloseable
```
This class represents a collection of items of any table of a Cumulus catalog. It is the base class for RecordItemCollection and CategoryItemCollection which hold items of the Cumulus.TABLE_NAME_ASSET_RECORDS table and Cumulus.TABLE_NAME_CATEGORIES table respectively. When creating an ItemCollection of the Cumulus.TABLE_NAME_ASSET_RECORDS table you always get a RecordItemCollection object. When getting an ItemCollection of the Cumulus.TABLE_NAME_CATEGORIES table you always get a CategoryItemCollection object. For all other tables (sub-tables of the above two tables) you will get a plain ItemCollection instance.

Since:

8.0

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addCatalogingListener(CatalogingListener<ItemCollection> catalogingListener)` Add a listener that is called whenever someone catalogs into this ItemCollection.
`void`	`addCollectionListener(CollectionListener<ItemCollection> 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.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`	`addGlobalCatalogingListener(CatalogingListener<ItemCollection> catalogingListener)` Add a listener that is called whenever someone catalogs into any ItemCollection.
`static void`	`addGlobalCollectionListener(CollectionListener<ItemCollection> 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.
`void`	`addItemByID(int itemID)` Add an existing item by ID to this collection
`int`	`addItemsByID(java.util.List<java.lang.Integer> itemIDs)` Add a whole list of items to this collection.
`void`	`catalogAsset(Asset asset, java.lang.String assetHandlingSet, java.lang.String permissionTemplate, java.util.EnumSet<CatalogingFlag> catalogingFlags, CatalogingListener<ItemCollection> catalogingListener)` Catalog a single asset to this collection.
`void`	`catalogAsset(Asset asset, java.lang.String assetHandlingSet, java.lang.String permissionTemplate, java.util.EnumSet<CatalogingFlag> catalogingFlags, Item additionalFieldValuesItem, java.util.Map<GUID,MetadataTemplateEntry.ValueFillMode> additionalFieldValuesFillMode, CatalogingListener<ItemCollection> catalogingListener)` Catalog a single asset to this collection.
`void`	`catalogAsset(Asset asset, java.lang.String assetHandlingSet, java.lang.String permissionTemplate, java.util.EnumSet<CatalogingFlag> catalogingFlags, java.util.Set<java.lang.Integer> assignCategoryIDs, CatalogingListener<ItemCollection> catalogingListener)` Catalog a single asset to this collection.
`void`	`catalogAssets(AssetCollection assetCollection, java.lang.String assetHandlingSet, java.lang.String permissionTemplate, java.util.EnumSet<CatalogingFlag> catalogingFlags, CatalogingListener<ItemCollection> catalogingListener)` Catalog a collection of assets to this collection.
`void`	`catalogAssets(AssetCollection assetCollection, java.lang.String assetHandlingSet, java.lang.String permissionTemplate, java.util.EnumSet<CatalogingFlag> catalogingFlags, Item additionalFieldValuesItem, java.util.Map<GUID,MetadataTemplateEntry.ValueFillMode> additionalFieldValuesFillMode, CatalogingListener<ItemCollection> catalogingListener)` Catalog a collection of assets to this collection.
`void`	`catalogAssets(AssetCollection assetCollection, java.lang.String assetHandlingSet, java.lang.String permissionTemplate, java.util.EnumSet<CatalogingFlag> catalogingFlags, java.util.Set<java.lang.Integer> assignCategoryIDs, CatalogingListener<ItemCollection> catalogingListener)` Catalog a collection of assets to this collection.
`ItemCollection`	`clone()` Create a clone of this collection.
`void`	`close()` Close this collection and release all native resources that it occupies.
`Item`	`createItem()` Create a new item object.
`Item`	`createItem(java.lang.String permissionTemplate)` Create a new item object.
`boolean`	`equals(java.lang.Object o)`
`void`	`find(Asset asset)` Find all items referencing the given asset.
`void`	`find(Asset asset, boolean logSearchStatistic)` Find all items referencing the given asset.
`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`	`findAll()` Find all items that are accessible to the current user.
`Catalog`	`getCatalog()` Return the Catalog object that this collection was created from.
`CumulusSession`	`getCumulusSession()` Returns the current `CumulusSession` object.
`Item`	`getItemByID(int itemID)` Return an item specified by ID.
`int`	`getItemCount()` Return the number of items in the collection.
`java.util.List<java.lang.Integer>`	`getItemIDs(int startIndex, int numIDs)` Get the IDs of some or all items of the collection.
`int`	`getItemPosition(int itemID)` 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 catalog.
`Layout`	`getLayout()` Get the layout containing all field definitions for this collection.
`java.util.List<SortFieldDescriptor>`	`getMultiSorting()` Return the list of fields that this collection is sorted by.
`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 ItemCollection.
`int`	`hashCode()`
`boolean`	`hasItem(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<java.lang.Integer>`	`matchIDs(java.lang.String query, java.util.EnumSet<FindFlag> flags, java.util.Locale locale, java.util.Set<java.lang.Integer> 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`	`moveItemByID(int itemID, int toPosition)` Move an existing item to s given position inside the collection.
`void`	`removeAllItems()` Make this collection empty.
`void`	`removeCatalogingListener(CatalogingListener<ItemCollection> catalogingListener)` Remove a listener previously added using `addCatalogingListener(com.canto.cumulus.events.CatalogingListener)`
`void`	`removeCollectionListener(CollectionListener<ItemCollection> 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)`.
`static void`	`removeGlobalCatalogingListener(CatalogingListener<ItemCollection> catalogingListener)` Remove a listener previously added using `addGlobalCatalogingListener(com.canto.cumulus.events.CatalogingListener)`.
`static void`	`removeGlobalCollectionListener(CollectionListener<ItemCollection> listener)` Remove a listener previously added using `addGlobalCollectionListener(com.canto.cumulus.events.CollectionListener)`.
`int`	`removeItemsByID(java.util.Collection<java.lang.Integer> 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.
`java.util.Set<java.lang.Integer>`	`updateItems(java.util.Set<java.lang.Integer> itemIDs, java.lang.String assetHandlingSet, java.lang.String permissionTemplate, boolean always, boolean includingSubAssets, boolean removeDeletedSubAssetItems, CatalogingListener<ItemCollection> catalogingListener)` Update a set of items in the collection according to changes made to their referenced asset.
`java.util.Set<java.lang.Integer>`	`updateItems(java.util.Set<java.lang.Integer> itemIDs, java.lang.String assetHandlingSet, java.lang.String permissionTemplate, boolean always, boolean includingSubAssets, boolean removeDeletedSubAssetItems, java.util.Set<GUID> fieldsToUpdate, CatalogingListener<ItemCollection> catalogingListener)` Update a set of items in the collection according to changes made to their referenced asset.
`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.
  - getCatalog
```
public Catalog getCatalog()
```
    Return the Catalog object that this collection was created from.
    
    Returns:
    The Catalog object for this collection.
  - getTableName
```
public java.lang.String getTableName()
```
    Get the name of the table for this ItemCollection.
    
    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
  - findAll
```
public void findAll()
```
    Find all items that are accessible to the current user.
  - find
```
public void find(java.lang.String query,
        java.util.EnumSet<FindFlag> flags,
        CombineMode combine,
        java.util.Locale locale)
          throws QueryParserException,
                 CumulusException
```
    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 - Flags that control how the query string is parsed and how the search is performed.
    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:
    
    QueryParserException - on error parsing the query (e.g. field does not exist in the catalog)
    
    CumulusException - on other errors
  - find
```
public void find(java.lang.String query,
        java.util.EnumSet<FindFlag> flags,
        CombineMode combine,
        java.util.Locale locale,
        boolean logSearchStatistic)
          throws QueryParserException,
                 CumulusException
```
    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 - Flags that control how the query string is parsed and how the search is performed.
    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:
    
    QueryParserException - on error parsing the query (e.g. field does not exist in the catalog)
    
    CumulusException - on other errors
    Since:
    
    10.2
  - matchIDs
```
public java.util.Set<java.lang.Integer> matchIDs(java.lang.String query,
                                        java.util.EnumSet<FindFlag> flags,
                                        java.util.Locale locale,
                                        java.util.Set<java.lang.Integer> 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
  - find
```
public void find(Asset asset)
```
    Find all items referencing the given asset.
    
    Parameters:
    asset - the asset to search for.
  - find
```
public void find(Asset asset,
        boolean logSearchStatistic)
```
    Find all items referencing the given asset.
    
    Parameters:
    asset - the asset to search for.
    logSearchStatistic - specifies whether the query result has to be logged in the search statistic
  - addFilter
```
public void addFilter(java.lang.String filterID,
             java.lang.String query,
             java.util.Locale locale)
               throws QueryParserException,
                      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:
    
    QueryParserException - on error parsing the query string
    
    CumulusException - on other error.
    See Also:
    removeFilter(String)
  - addFilter
```
public void addFilter(java.lang.String filterID,
             java.lang.String query,
             java.util.EnumSet<FindFlag> flags,
             java.util.Locale locale)
               throws QueryParserException,
                      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 - Flags that control how the query string is parsed and how the filtering is performed.
    locale - The locale object to use for parsing the query
    
    Throws:
    
    QueryParserException - on error parsing the query string
    
    CumulusException - on other error.
    Since:
    
    9.0
    
    See Also:
    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).
    
    Parameters:
    filterID - The ID string of the filter.
  - getItemCount
```
public int getItemCount()
```
    Return the number of items in the collection.
    
    Returns:
    The number of items in the collection
  - getItemTotalCount
```
public int getItemTotalCount()
```
    Return the total number of items that are available in the catalog. The collection object only contains a subset of item. See getItemCount() to the current number of items in the collection. Not all of these items are accessible to the current user.
    
    Returns:
    The total number of items in the catalog.
  - hasItem
```
public boolean hasItem(int itemID)
```
    Return whether the collection contains a given item specified by ID.
    
    Parameters:
    itemID - The ID of the item to check
    
    Returns:
    true if the given item is contained in the collection. Return false otherwise.
  - getItemIDs
```
public java.util.List<java.lang.Integer> getItemIDs(int startIndex,
                                           int numIDs)
```
    Get the IDs 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 IDs 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 IDs of the items at the given position in the collection.
  - createItem
```
public Item createItem()
                throws PermissionDeniedException,
                       CumulusException
```
    Create a new item object. The item returned is not yet saved to the catalog. You need to set some field values of the Item object and then call the Item.save() method to save the
    
    Returns:
    The newly created item.
    
    Throws:
    
    PermissionDeniedException - if the current user does not have the necessary permissions for this operation.
    
    CumulusException - on other errors.
    See Also:
    Item.save()
  - createItem
```
public Item createItem(java.lang.String permissionTemplate)
                throws PermissionDeniedException,
                       CumulusException
```
    Create a new item object. The item returned is not yet saved to the catalog. You need to set some field values of the Item object and then call the Item.save() method to save the
    
    Parameters:
    permissionTemplate - the permission template to apply to the new item
    
    Returns:
    The newly created item.
    
    Throws:
    
    PermissionDeniedException - if the current user does not have the necessary permissions for this operation.
    
    CumulusException - on other errors.
    Since:
    
    8.5
    
    See Also:
    Item.save()
  - getItemByID
```
public Item getItemByID(int itemID)
                 throws ItemNotFoundException,
                        CumulusException
```
    Return an item specified by ID.
    
    Parameters:
    itemID - The ID of the item to be returned.
    
    Returns:
    The Item object for the given ID.
    
    Throws:
    
    ItemNotFoundException - if the collection does not contain the given item.
    
    CumulusException - on other errors.
    See Also:
    hasItem(int), addItemByID(int), addItemsByID(java.util.List)
  - addItemByID
```
public void addItemByID(int itemID)
```
    Add an existing item by ID to this collection
    
    Parameters:
    itemID - The ID of the item to add.
  - addItemsByID
```
public int addItemsByID(java.util.List<java.lang.Integer> itemIDs)
```
    Add a whole list of items to this collection. The items are specified by their ID. Items that already contained in this collection are not added a second time.
    
    Parameters:
    itemIDs - The list of IDs of the items to add.
    
    Returns:
    The number of items actually added to this collection.
  - removeItemsByID
```
public int removeItemsByID(java.util.Collection<java.lang.Integer> itemIDs)
```
    Remove a whole list of items from this collection. The items are specified by their ID.
    
    Parameters:
    itemIDs - The list of ID for the items to be removed.
    
    Returns:
    The number of items actually removed by this method.
  - removeAllItems
```
public void removeAllItems()
```
    Make this collection empty.
  - 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.
    See Also:
    moveItemByID(int, int)
  - moveItemByID
```
public void moveItemByID(int itemID,
                int toPosition)
```
    Move an existing item to s given position inside the collection.
    
    Parameters:
    itemID - The ID of the item to move.
    toPosition - The new zero-based index where the item should be moved to.
    See Also:
    moveItem(int, int)
  - getItemPosition
```
public int getItemPosition(int itemID)
                    throws CumulusException
```
    Return the zero-based index of the given item inside this collection.
    
    Parameters:
    itemID - The ID of the item
    
    Returns:
    The zero-based index of the item in this collection.
    
    Throws:
    
    CumulusException - on error
  - 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. 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.
  - 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 ItemCollection 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 ItemCollection already 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.
  - catalogAsset
```
public void catalogAsset(Asset asset,
                java.lang.String assetHandlingSet,
                java.lang.String permissionTemplate,
                java.util.EnumSet<CatalogingFlag> catalogingFlags,
                CatalogingListener<ItemCollection> catalogingListener)
                  throws InvalidArgumentException,
                         CumulusException
```
    Catalog a single asset to this collection. Depending on the settings in the given asset handling set and the current state of the items in Cumulus this may add the asset or update items in the Cumulus catalog that refer to the asset. Cataloging a single asset may result in a whole set of assets being added to the catalog if the given asset contains other assets (e.g. a ZIP archive). This method only throws an exception if an input parameter is wrong or the cataloging process can not be started. To get errors that occur while the asset is processed you should specify a listener to be called.
    
    Parameters:
    asset - The asset to catalog
    assetHandlingSet - The name of the asset handling set to use for cataloging. An empty or null string uses the asset handling set that is configured in the user setting to be used by default.
    permissionTemplate - The name of the permission template to be applied after cataloging. Passing an empty or null string does not apply any permission template.
    catalogingFlags - Flags that allow to skip specific functionality. Typically you pass EnumSet.noneOf (CatalogingFlag.class) here to perform all functions.
    catalogingListener - An optional listener that is called for each asset that is processed.
    
    Throws:
    
    InvalidArgumentException - in case you specify an asset handling set or permission template that does not exist.
    
    CumulusException - on other errors.
    See Also:
    catalogAsset(Asset, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener)
  - catalogAsset
```
public void catalogAsset(Asset asset,
                java.lang.String assetHandlingSet,
                java.lang.String permissionTemplate,
                java.util.EnumSet<CatalogingFlag> catalogingFlags,
                java.util.Set<java.lang.Integer> assignCategoryIDs,
                CatalogingListener<ItemCollection> catalogingListener)
                  throws InvalidArgumentException,
                         CumulusException
```
    Catalog a single asset to this collection. Depending on the settings in the given asset handling set and the current state of the items in Cumulus this may add the asset or update items in the Cumulus catalog that refer to the asset. Cataloging a single asset may result in a whole set of assets being added to the catalog if the given asset contains other assets (e.g. a ZIP archive). This method only throws an exception if an input parameter is wrong or the cataloging process can not be started. To get errors that occur while the asset is processed you should specify a listener to be called.
    
    Parameters:
    asset - The asset to catalog
    assetHandlingSet - The name of the asset handling set to use for cataloging. An empty or null string uses the asset handling set that is configured in the user setting to be used by default.
    permissionTemplate - The name of the permission template to be applied after cataloging. Passing an empty or null string does not apply any permission template.
    catalogingFlags - Flags that allow to skip specific functionality. Typically you pass EnumSet.noneOf (CatalogingFlag.class) here to perform all functions.
    assignCategoryIDs - The categories to be assigned to each item that is the result of adding an asset to the catalog. The categories are specified by their ID.
    catalogingListener - An optional listener that is called for each asset that is processed.
    
    Throws:
    
    InvalidArgumentException - in case you specify an asset handling set or permission template that does not exist.
    
    CumulusException - on other errors.
    See Also:
    catalogAsset(Asset, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener)
  - catalogAsset
```
public void catalogAsset(Asset asset,
                java.lang.String assetHandlingSet,
                java.lang.String permissionTemplate,
                java.util.EnumSet<CatalogingFlag> catalogingFlags,
                Item additionalFieldValuesItem,
                java.util.Map<GUID,MetadataTemplateEntry.ValueFillMode> additionalFieldValuesFillMode,
                CatalogingListener<ItemCollection> catalogingListener)
                  throws InvalidArgumentException,
                         CumulusException
```
    Catalog a single asset to this collection. Depending on the settings in the given asset handling set and the current state of the items in Cumulus this may add the asset or update items in the Cumulus catalog that refer to the asset. Cataloging a single asset may result in a whole set of assets being added to the catalog if the given asset contains other assets (e.g. a ZIP archive). This method only throws an exception if an input parameter is wrong or the cataloging process can not be started. To get errors that occur while the asset is processed you should specify a listener to be called.
    
    Parameters:
    asset - The asset to catalog
    assetHandlingSet - The name of the asset handling set to use for cataloging. An empty or null string uses the asset handling set that is configured in the user setting to be used by default.
    permissionTemplate - The name of the permission template to be applied after cataloging. Passing an empty or null string does not apply any permission template.
    catalogingFlags - Flags that allow to skip specific functionality. Typically you pass EnumSet.noneOf (CatalogingFlag.class) here to perform all functions.
    additionalFieldValuesItem - An item providing additional field values which should be applied on newly created records. Depends on the additional parameter additionalFieldValuesFillMode that specifies which fields should be applied and combined with the existing values. Can be null if no other values should be set.
    additionalFieldValuesFillMode - Null or the specification how fields provided by the additionalFieldValuesItem parameter are combined with the records being created by the cataloging process.
    catalogingListener - An optional listener that is called for each asset that is processed.
    
    Throws:
    
    InvalidArgumentException - in case you specify an asset handling set or permission template that does not exist.
    
    CumulusException - on other errors.
    Since:
    
    9.0
    
    See Also:
    catalogAsset(Asset, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener)
  - catalogAssets
```
public void catalogAssets(AssetCollection assetCollection,
                 java.lang.String assetHandlingSet,
                 java.lang.String permissionTemplate,
                 java.util.EnumSet<CatalogingFlag> catalogingFlags,
                 CatalogingListener<ItemCollection> catalogingListener)
                   throws InvalidArgumentException,
                          CumulusException
```
    Catalog a collection of assets to this collection. Depending on the settings in the given asset handling set and the current state of the items in Cumulus this may add assets or update items in the Cumulus catalog. This method only throws an exception if an input parameter is wrong or the cataloging process can not be started. To get errors that occur while the asset is processed you should specify a listener to be called.
    
    Parameters:
    assetCollection - The collection of assets for cataloging
    assetHandlingSet - The name of the asset handling set to use for cataloging. An empty or null string uses the asset handling set that is configured in the user setting to be used by default.
    permissionTemplate - The name of the permission template to be applied after cataloging. Passing an empty or null string does not apply any permission template.
    catalogingFlags - Flags that allow to skip specific functionality. Typically you pass EnumSet.noneOf (CatalogingFlag.class) here to perform all functions.
    catalogingListener - An optional listener that is called for each asset that is processed.
    
    Throws:
    
    InvalidArgumentException - in case you specify an asset handling set or permission template that does not exist.
    
    CumulusException - on other errors.
    See Also:
    catalogAsset(Asset, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAsset(Asset, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener)
  - catalogAssets
```
public void catalogAssets(AssetCollection assetCollection,
                 java.lang.String assetHandlingSet,
                 java.lang.String permissionTemplate,
                 java.util.EnumSet<CatalogingFlag> catalogingFlags,
                 java.util.Set<java.lang.Integer> assignCategoryIDs,
                 CatalogingListener<ItemCollection> catalogingListener)
                   throws InvalidArgumentException,
                          CumulusException
```
    Catalog a collection of assets to this collection. Depending on the settings in the given asset handling set and the current state of the items in Cumulus this may add assets or update items in the Cumulus catalog. This method only throws an exception if an input parameter is wrong or the cataloging process can not be started. To get errors that occur while the asset is processed you should specify a listener to be called.
    
    Parameters:
    assetCollection - The collection of assets for cataloging
    assetHandlingSet - The name of the asset handling set to use for cataloging. An empty or null string uses the asset handling set that is configured in the user setting to be used by default.
    permissionTemplate - The name of the permission template to be applied after cataloging. Passing an empty or null string does not apply any permission template.
    catalogingFlags - Flags that allow to skip specific functionality. Typically you pass EnumSet.noneOf (CatalogingFlag.class) here to perform all functions.
    assignCategoryIDs - The categories to be assigned to each item that is the result of adding an asset to the catalog. The categories are specified by their ID.
    catalogingListener - An optional listener that is called for each asset that is processed.
    
    Throws:
    
    InvalidArgumentException - in case you specify an asset handling set or permission template that does not exist.
    
    CumulusException - on other errors.
    See Also:
    catalogAsset(Asset, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAsset(Asset, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener)
  - catalogAssets
```
public void catalogAssets(AssetCollection assetCollection,
                 java.lang.String assetHandlingSet,
                 java.lang.String permissionTemplate,
                 java.util.EnumSet<CatalogingFlag> catalogingFlags,
                 Item additionalFieldValuesItem,
                 java.util.Map<GUID,MetadataTemplateEntry.ValueFillMode> additionalFieldValuesFillMode,
                 CatalogingListener<ItemCollection> catalogingListener)
                   throws InvalidArgumentException,
                          CumulusException
```
    Catalog a collection of assets to this collection. Depending on the settings in the given asset handling set and the current state of the items in Cumulus this may add assets or update items in the Cumulus catalog. This method only throws an exception if an input parameter is wrong or the cataloging process can not be started. To get errors that occur while the asset is processed you should specify a listener to be called.
    
    Parameters:
    assetCollection - The collection of assets for cataloging
    assetHandlingSet - The name of the asset handling set to use for cataloging. An empty or null string uses the asset handling set that is configured in the user setting to be used by default.
    permissionTemplate - The name of the permission template to be applied after cataloging. Passing an empty or null string does not apply any permission template.
    catalogingFlags - Flags that allow to skip specific functionality. Typically you pass EnumSet.noneOf (CatalogingFlag.class) here to perform all functions.
    additionalFieldValuesItem - item providing initial field values which will be set by the cataloger for all items to be created
    additionalFieldValuesFillMode - fill modes to use when applying the values from the additionalFieldValuesItem parameter
    catalogingListener - An optional listener that is called for each asset that is processed.
    
    Throws:
    
    InvalidArgumentException - in case you specify an asset handling set or permission template that does not exist.
    
    CumulusException - on other errors.
    See Also:
    catalogAsset(Asset, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAsset(Asset, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener)
  - updateItems
```
public java.util.Set<java.lang.Integer> updateItems(java.util.Set<java.lang.Integer> itemIDs,
                                           java.lang.String assetHandlingSet,
                                           java.lang.String permissionTemplate,
                                           boolean always,
                                           boolean includingSubAssets,
                                           boolean removeDeletedSubAssetItems,
                                           CatalogingListener<ItemCollection> catalogingListener)
                                             throws InvalidArgumentException,
                                                    CumulusException
```
    Update a set of items in the collection according to changes made to their referenced asset.
    
    Parameters:
    itemIDs - The IDs of the items to be updated
    assetHandlingSet - The name of the asset handling set to use for updating An empty or null string uses the asset handling set that is configured in the user setting to be used by default.
    permissionTemplate - The name of the permission template to apply after updating an item.
    always - Specify true to force updating the items. Specify false to let Cumulus only update items for assets that have been changed.
    includingSubAssets - Include sub-assets with the updating. This allows you to also update items for contained assets.
    removeDeletedSubAssetItems - Specify true to allow Cumulus to delete items of contained assets if the asset no longer contains them. If you specify false here Cumulus will keep items even though the asset may no longer exist.
    catalogingListener - A listener t be called for each item being processed.
    
    Returns:
    The IDs of all items that were updated during this method call.
    
    Throws:
    
    InvalidArgumentException - in case one of the parameters is wrong (e.g. asset handling set does not exist).
    
    CumulusException - on other errors
  - updateItems
```
public java.util.Set<java.lang.Integer> updateItems(java.util.Set<java.lang.Integer> itemIDs,
                                           java.lang.String assetHandlingSet,
                                           java.lang.String permissionTemplate,
                                           boolean always,
                                           boolean includingSubAssets,
                                           boolean removeDeletedSubAssetItems,
                                           java.util.Set<GUID> fieldsToUpdate,
                                           CatalogingListener<ItemCollection> catalogingListener)
                                             throws InvalidArgumentException,
                                                    CumulusException
```
    Update a set of items in the collection according to changes made to their referenced asset.
    
    Parameters:
    itemIDs - The IDs of the items to be updated
    assetHandlingSet - The name of the asset handling set to use for updating An empty or null string uses the asset handling set that is configured in the user setting to be used by default.
    permissionTemplate - The name of the permission template to apply after updating an item.
    always - Specify true to force updating the items. Specify false to let Cumulus only update items for assets that have been changed.
    includingSubAssets - Include sub-assets with the updating. This allows you to also update items for contained assets.
    removeDeletedSubAssetItems - Specify true to allow Cumulus to delete items of contained assets if the asset no longer contains them. If you specify false here Cumulus will keep items even though the asset may no longer exist.
    fieldsToUpdate - set of fields to update or null to update all fields of the catalog
    catalogingListener - A listener t be called for each item being processed.
    
    Returns:
    The IDs of all items that were updated during this method call.
    
    Throws:
    
    InvalidArgumentException - in case one of the parameters is wrong (e.g. asset handling set does not exist).
    
    CumulusException - on other errors
    Since:
    
    8.5
  - getLayout
```
public Layout getLayout()
```
    Get the layout containing all field definitions for this collection. This is equivalent to calling getCatalog().getLayout(getTableName()).
    
    Returns:
    The layout for this collection.
  - clone
```
public ItemCollection clone()
```
    Create a clone of this collection. The cloned collection will contain the same items as this collection.
    
    Overrides:
    
    clone in class java.lang.Object
    
    Returns:
    The newly created clone of this collection.
  - addCollectionListener
```
public void addCollectionListener(CollectionListener<ItemCollection> 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 ItemCollection. If you are interested in changes in any of the ItemCollection 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<ItemCollection> 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<ItemCollection> 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 ItemCollection changes. If you are interested in a specific ItemCollection you should use addCollectionListener(com.canto.cumulus.events.CollectionListener) instead. Call removeGlobalCollectionListener(com.canto.cumulus.events.CollectionListener) to remove this global listener from the ItemCollection class.
    
    Parameters:
    listener - The listener to add globally.
  - removeGlobalCollectionListener
```
public static void removeGlobalCollectionListener(CollectionListener<ItemCollection> listener)
```
    Remove a listener previously added using addGlobalCollectionListener(com.canto.cumulus.events.CollectionListener).
    
    Parameters:
    listener - The listener to remove.
  - addGlobalCatalogingListener
```
public static void addGlobalCatalogingListener(CatalogingListener<ItemCollection> catalogingListener)
```
    Add a listener that is called whenever someone catalogs into any ItemCollection. Use this to get notified on any ItemCollection cataloging. If you are interested in events that occur while you are cataloging assets you should pass the listener as a parameter to the catalogAsset() method call instead. Call removeGlobalCatalogingListener(com.canto.cumulus.events.CatalogingListener) to remove this global listener from the ItemCollection class.
    
    Parameters:
    catalogingListener - The listener to add globally.
    See Also:
    catalogAsset(Asset, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAsset(Asset, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener), addCatalogingListener(com.canto.cumulus.events.CatalogingListener)
  - removeGlobalCatalogingListener
```
public static void removeGlobalCatalogingListener(CatalogingListener<ItemCollection> catalogingListener)
```
    Remove a listener previously added using addGlobalCatalogingListener(com.canto.cumulus.events.CatalogingListener).
    
    Parameters:
    catalogingListener - The listener to remove.
  - addCatalogingListener
```
public void addCatalogingListener(CatalogingListener<ItemCollection> catalogingListener)
```
    Add a listener that is called whenever someone catalogs into this ItemCollection. Use this to get notified if someone catalogs into this ItemCollection. If you are interested in events that occur while you are cataloging assets you should pass the listener as a parameter to the catalogAsset() method call instead. If you are interested in any cataloging use addGlobalCatalogingListener(com.canto.cumulus.events.CatalogingListener) instead. Call removeCatalogingListener(com.canto.cumulus.events.CatalogingListener) to remove this listener from the ItemCollection.
    
    Parameters:
    catalogingListener - The listener to add.
    See Also:
    catalogAsset(Asset, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAsset(Asset, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, com.canto.cumulus.events.CatalogingListener), catalogAssets(AssetCollection, String, String, java.util.EnumSet, java.util.Set, com.canto.cumulus.events.CatalogingListener), addGlobalCatalogingListener(com.canto.cumulus.events.CatalogingListener), removeCatalogingListener(com.canto.cumulus.events.CatalogingListener)
  - removeCatalogingListener
```
public void removeCatalogingListener(CatalogingListener<ItemCollection> catalogingListener)
```
    Remove a listener previously added using addCatalogingListener(com.canto.cumulus.events.CatalogingListener)
    
    Parameters:
    catalogingListener - The listener to remove.
  - 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.
  - 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 ItemCollection

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getCumulusSession

getCatalog

getTableName

close

findAll

find

find

matchIDs

find

find

addFilter

addFilter

removeFilter

getItemCount

getItemTotalCount

hasItem

getItemIDs

createItem

createItem

getItemByID

addItemByID

addItemsByID

removeItemsByID

removeAllItems

moveItem

moveItemByID

getItemPosition

setSorting

setMultiSorting

getMultiSorting

setSortDirection

getSorting

getSortDirection

setFreesorted

updateWantedFields

updateWantedFields

catalogAsset

catalogAsset

catalogAsset

catalogAssets

catalogAssets

catalogAssets

updateItems

updateItems

getLayout

clone

addCollectionListener

removeCollectionListener

addGlobalCollectionListener

removeGlobalCollectionListener

addGlobalCatalogingListener

removeGlobalCatalogingListener

addCatalogingListener

removeCatalogingListener

iterator

equals

hashCode