PIMCollection class: Collections of product entities

In the Java™ API, you use the class PIMCollection to deal with a set or array of IBM® Product Master entities, such as a set of items or a list of user-defined log entries.

The PIMCollection class is a read-only, immutable specialization of java.util.Collection that is optimized for handling Product Master Server objects such as catalogs, categories, items, hierarchies, and specs.

This class implements a "lazy lookup", which keeps hold of objects by their internal ID only, and does not try to resolve the ID to a real object until the last possible moment (such as when you try to retrieve the object from the collection).

The PIMCollection class applies to many entities where only a subset of these entities is required to be shown to users. A PIMCollection class provides a way of working with a subset of a large set of entities.

The disadvantage of using the PIMCollection class is that in a large, rapidly changing Product Master system, the contents of the collection must be different from what is shown by the PIMCollection class. For example, an object might get deleted after the collection was created.

The behavior of this class is different from the java.util.Collection class in the following ways:
pimCollection.iterator()
Returns a java.util.Iterator of entities in the collection that exist at the time the iterator is constructed. An entity that was deleted since the collection was constructed is ignored by .next() and .hasNext(). In this way, you can get a reasonably up-to-date view on the PIMCollection when you construct a new iterator(). You might experience fewer iterations than expected.
pimCollection.toArray() and pimCollection.size()
These methods always reflect the size of the collection at the time the PIMCollection was constructed. Any entities that were deleted appears as null at the appropriate array index. Your code must be prepared to retrieve unexpected null values.
pimCollection.toArray()
This method always returns the same size of array (equal to pimCollection.size()); however it reretrieves all entities in the array each time it is called. This behavior has two consequences:
  • Subsequent calls to give toArray() a more up-to-date view of the data, but might differ from earlier calls if data changed.
  • Because toArray() resolves every object in the PIMCollection, it is not recommended for general use on large collections. Performance is poor due to the expense of resolving every object. Use pimCollection.iterator() instead.

Methods that return PIMCollections

PIMCollection items = catalog.getAllItems();
PIMCollection categories = hierarchy.getAllCategories();