Working with Collections

This topic shows you how to create a new list-type collection. It also provides an example that illustrates how to iterate a returned set-type collection using paging.

Creating a Collection

Many Content Engine API methods take a collection, either empty or populated with elements, as an argument. The Factory class provides methods that create empty list-type collections to which you can add elements of the appropriate type, if necessary. You can also use inherited methods to manipulate elements in Content Engine API collection objects.

The following code fragment creates a new empty AccessPermissionList collection and adds an element to the collection:

Java Example

// Create a new collection
AccessPermissionList apl = Factory.AccessPermission.createList();
  
// Create a new AccessPermission object and add it to the collection
AccessPermission ap = Factory.AccessPermission.createInstance();
  
// set some access permissions (not shown)  
// ...
  
// add the item to the list
apl.add(ap);

C# Example

// Create a new collection
IAccessPermissionList apl = Factory.AccessPermission.CreateList();

// Create a new AccessPermission object and add it to the collection
IAccessPermission ap = Factory.AccessPermission.CreateInstance();
  
// set some access permissions (not shown)  
// ...

// add the item to the list
apl.Add(ap);

Note  A DependentObjectList is not reusable. That is, a DependentObjectList taken from a fetched independent object should not be reassigned to another independent object. For more information, see the related information in the DependentObjects topic.

Iterating a Collection

The two code examples below show how to iterate a set-type collection using paging and illustrate the use of page sizing and page marking.

Page Sizing

The following code example shows how to iterate a collection of subfolders. Note that the page size for the prefetch—the initial fetch that occurs when creating the object set containing the objects to be iterated—is set independently from the page size for all subsequent fetches, and these two page sizes can be different. The example output (shown after the code example) shows the impact of these different page sizes.

Java Example

// Get folders for iteration
private static void iterateFolders(
    Folder mainFolder,       // Folder to iterate
    int pageSizePrefetch,    // Prefetch page size. Example: 1
    int pageSizeFetch)       // Fetch page size. Example: 1
{        
    // Show attributes
    System.out.println("Parameter pageSizePrefetch: " + pageSizePrefetch);
    System.out.println("Parameter pageSizeFetch: " + pageSizeFetch);
    System.out.println("");
        
    // Get sub folders collection (and set prefetch page size)
    Property prop = mainFolder.fetchProperty(
        "SubFolders", null, new Integer(pageSizePrefetch));   
    IndependentObjectSet objectSet = prop.getIndependentObjectSetValue();
            
    // Initialize page iterator (and set fetch page size)
    PageIterator pageIter = objectSet.pageIterator();
    pageIter.setPageSize(pageSizeFetch);
        
    // Iterate through sub folders
    iteratePageElements(pageIter);        
}       
    
// Iterate through page elements
public static void iteratePageElements(
    PageIterator pageIter)
{    	
    // Cycle through pages
    int pageCount = 0;
    while (pageIter.nextPage() == true)
    {
        // Get counts
        pageCount++;
        int elementCount = pageIter.getElementCount();

        // Display number of objects on this page
        System.out.println("Page: " 
            + pageCount + "  Element count: " + elementCount);

        // Get elements on page
        Object[] pageObjects = pageIter.getCurrentPage();                
        for (int index = 0; index < pageObjects.length; index++)
        {
            // Get sub object
            Object elementObject = pageObjects[index];

            // Check if document
            if (elementObject instanceof Document)
            {
                Document elementDoc = (Document) elementObject;
            	elementDoc.refresh();
            	com.filenet.api.property.Properties props = elementDoc.getProperties();
            	System.out.println(" -" + props.getStringValue("DocumentTitle"));                    
            }
            // Check if any other type
            else
            {
                Containable conObject = (Containable) elementObject;
                System.out.println(" -" + conObject.get_Name());                                		
            }
        }
    } 	
}

C# Example

// Get folders for iteration
private static void IterateFolders(
    IFolder mainFolder,       // Folder to iterate
    int pageSizePrefetch,     // Prefetch page size. Example: 1
    int pageSizeFetch)        // Fetch page size. Example: 1
{        
    // Show attributes
    Debug.WriteLine("Parameter pageSizePrefetch: " + pageSizePrefetch);
    Debug.WriteLine("Parameter pageSizeFetch: " + pageSizeFetch);
    Debug.WriteLine("");
        
    // Get sub folders collection (and set prefetch page size)
    IProperty prop = mainFolder.FetchProperty(
        "SubFolders", null, pageSizePrefetch);   
    IIndependentObjectSet objectSet = prop.GetIndependentObjectSetValue();
            
    // Initialize page iterator (and set fetch page size)
    IPageEnumerator pageIter = objectSet.GetPageEnumerator();
    pageIter.PageSize = pageSizeFetch;
        
    // Iterate through sub folders
    IteratePageElements(pageIter);        
}

// Iterate through page elements
public static void IteratePageElements(
    IPageEnumerator pageIter)
{    	
    // Cycle through pages
    int pageCount = 0;
    while (pageIter.NextPage() == true)
    {
        // Get counts
        pageCount++;
        int elementCount = pageIter.ElementCount;

        // Display number of objects on this page
        Debug.WriteLine("Page: " 
            + pageCount + "  Element count: " + elementCount);

        // Get elements on page
        Object[] pageObjects = pageIter.CurrentPage;                
        for (int index = 0; index < pageObjects.Length; index++)
        {
            // Get sub object
            Object elementObject = pageObjects[index];

            // Check if document
            if (elementObject is IDocument)
            {
                IDocument elementDoc = (IDocument) elementObject;
            	elementDoc.Refresh();
                IProperties props = elementDoc.Properties;
            	Debug.WriteLine(" -" + props.GetStringValue("DocumentTitle"));                    
            }
            // Check if any other type
            else
            {
                IContainable conObject = (IContainable) elementObject;
                Debug.WriteLine(" -" + conObject.Name);                                		
            }         	
        }
    }   	
}

Example Output: pageSizePrefetch = 1, pageSizeFetch = 3

Parameter pageSizePrefetch: 1
Parameter pageSizeFetch: 3

Page: 1  Element count: 1
 -Subfolder5
Page: 2  Element count: 3
 -Subfolder7
 -Subfolder2
 -Subfolder6
Page: 3  Element count: 3
 -Subfolder3
 -Subfolder4
 -Subfolder1

Example Output: pageSizePrefetch = 3, pageSizeFetch = 1

Parameter pageSizePrefetch: 3
Parameter pageSizeFetch: 1

Page: 1  Element count: 3
 -Subfolder5
 -Subfolder7
 -Subfolder2
Page: 2  Element count: 1
 -Subfolder6
Page: 3  Element count: 1
 -Subfolder3
Page: 4  Element count: 1
 -Subfolder4
Page: 5  Element count: 1
 -Subfolder1

Example Output: pageSizePrefetch = 3, pageSizeFetch = 3

Parameter pageSizePrefetch: 3
Parameter pageSizeFetch: 3

Page: 1  Element count: 3
 -Subfolder5
 -Subfolder7
 -Subfolder2
Page: 2  Element count: 3
 -Subfolder6
 -Subfolder3
 -Subfolder4
Page: 3  Element count: 1
 -Subfolder1

Page Marking

The following code example shows how to iterate a collection of documents. As illustrated in the example output (shown after the code example), you can use page marking to save the iterator position in order to subsequently jump back to that position. This example calls the iteratePageElements() method shown in the previous Page Sizing example.

Java Example

public static void iterateDocuments(
    ObjectStore os,
    int pageStart,	// Page to reset iterator to 
    int maxDocCount,	// Maximum number of documents to retrieve
    String folderPath)	// Folder where documents reside. Example: /Sub1/Sub1a
{
    // Show parameters
    System.out.println("Parameter pageStart: " + pageStart);
    System.out.println("Parameter maxDocCount: " + maxDocCount);
    System.out.println("");
    	
    // Set desired page size
    int pageSize = 5;
  
    // Create SQL to retrieve documents
    SearchSQL searchSQL = new SearchSQL();
    searchSQL.setMaxRecords(maxDocCount);
    searchSQL.setSelectList("d.this");
    searchSQL.setFromClauseInitialValue("Document", "d", false);
    searchSQL.setWhereClause("d.this INFOLDER " + "'" + folderPath + "'");
        
    // Create search scope for object store
    SearchScope searchScope = new SearchScope(os);
  
    // Get documents (and set prefetch page size)
    IndependentObjectSet objectSet =
        searchScope.fetchObjects(searchSQL, new Integer(pageSize), null, new Boolean(true));
  
    // Initialize page iterate (and set fetch page size)
    PageIterator pageIter = objectSet.pageIterator();
    pageIter.setPageSize(pageSize);
  
    // Calculate maximum number of pages needed to retrieve documents
    int maxPageCount = (maxDocCount / pageSize) + 1;

    // Get page marks for each page
    PageMark pageMarks[] = new PageMark[maxPageCount];
    int pageCount = 0;
    while (pageIter.nextPage() == true)
    {
        pageMarks[pageCount++] = pageIter.getPageMark();	
    }

    // Reset iterator to desired page
    pageIter.reset(pageMarks[pageStart - 1]);
	    
    // Show page elements
    ChapterCollections.iteratePageElements(pageIter);
}

C# Example

public static void IterateDocuments(
    IObjectStore os,
    int pageStart,	// Page to reset iterator to 
    int maxDocCount,	// Maximum number of documents to retrieve
    String folderPath)	// Folder where documents reside. Example: /Sub1/Sub1a
{
    // Show parameters
    Debug.WriteLine("Parameter pageStart: " + pageStart);
    Debug.WriteLine("Parameter maxDocCount: " + maxDocCount);
    Debug.WriteLine("");
    	
    // Set desired page size
    int pageSize = 5;
  
    // Create SQL to retrieve documents
    SearchSQL searchSQL = new SearchSQL();
    searchSQL.SetMaxRecords(maxDocCount);
    searchSQL.SetSelectList("d.this");
    searchSQL.SetFromClauseInitialValue("Document", "d", false);
    searchSQL.SetWhereClause("d.this INFOLDER " + "'" + folderPath + "'");
        
    // Create search scope for object store
    SearchScope searchScope = new SearchScope(os);
  
    // Get documents (and set prefetch page size)
    IIndependentObjectSet objectSet =
        searchScope.FetchObjects(searchSQL, pageSize, null, true);
  
    // Initialize page iterate (and set fetch page size)
    IPageEnumerator pageIter = objectSet.GetPageEnumerator();
    pageIter.PageSize = pageSize;

    // Calculate maximum number of pages needed to retrieve documents
    int maxPageCount = (maxDocCount / pageSize) + 1;

    // Get page marks for each page
    IPageMark[] pageMarks = new IPageMark[maxPageCount];
    int pageCount = 0;
    while (pageIter.NextPage() == true)
    {
        pageMarks[pageCount++] = pageIter.PageMark;	
    }

    // Reset iterator to desired page
    pageIter.Reset(pageMarks[pageStart - 1]);
	    
    // Show page elements
    ChapterCollections.IteratePageElements(pageIter);
}

Example Output: pageStart = 1, maxDocCount = 12

Parameter pageStart: 1
Parameter maxDocCount: 12

Page: 1  Element count: 5
 -Document9
 -Document7
 -Document4
 -Document3
 -Document1
Page: 2  Element count: 5
 -Document2
 -Document8
 -Document10
 -Document12
 -Document11
Page: 3  Element count: 2
 -Document5
 -Document6

Example Output: pageStart = 2, maxDocCount = 12

Parameter pageStart: 2
Parameter maxDocCount: 12

Page: 1  Element count: 5
 -Document2
 -Document8
 -Document10
 -Document12
 -Document11
Page: 2  Element count: 2
 -Document5
 -Document6

Example Output: pageStart = 3, maxDocCount = 12

Parameter pageStart: 3
Parameter maxDocCount: 12

Page: 1  Element count: 2
 -Document5
 -Document6