com.ibm.pim.interfaces.collection
Interface PIMCollection

All Superinterfaces:
java.util.Collection

public interface PIMCollection
extends java.util.Collection

Read only, immutable PIM version of java.util.Collection, which can only handle PIM objects (Catalog, Category, Item, Hierarchy, Spec, LookupTable etc)

Implements a "lazy lookup", for performance reasons. This means that the collection 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.

The advantage here is greater performance, the cost is that in a large dynamic system, the contents of the collection may actuallly be different, for example if an object has been deleted since the collection was created.

This means that the behaviour of this class is different than java.util.Collection.

IMPORTANT WARNING: This collection provides a moment in time view of the collection, which will allow you to access those objects in the collection for as long as they still exist in the underlying database. If underlying objects change, you may experience unexpected results, such as fewer iterations than expected, or nulls where you did not expect them.

Also, toArray() is not recommended for general use due to performance reasons, it will resolve every object in the Collection. It will be VERY slow on large collections We recommend using PIMCollection.iterator() instead


Field Summary
static java.lang.String copyright
           
 
Method Summary
 boolean add(java.lang.Object o)
          Unsupported method.
 boolean addAll(java.util.Collection c)
          Unsupported method.
 void clear()
          Unsupported method
 boolean contains(java.lang.Object o)
          Check if the object o is in the collection.
 boolean containsAll(java.util.Collection c)
          Check if all the contents of Collection c are within this PIMCollection.
 boolean equals(java.lang.Object o)
           
 int hashCode()
           
 java.util.Iterator iterator()
          Iterates over the objects in this Collection.
 boolean remove(java.lang.Object o)
          Unsupported method.
 boolean removeAll(java.util.Collection c)
          Unsupported method
 boolean retainAll(java.util.Collection c)
          Unsupported method
 int size()
          This will return the size of the collection at the time it is created, regardless of whether all the objects can be resolved.
 java.lang.Object[] toArray()
          Retrieves the whole collection as an array.
 java.lang.Object[] toArray(java.lang.Object[] a)
          Unsupported method.
 
Methods inherited from interface java.util.Collection
isEmpty
 

Field Detail

copyright

public static final java.lang.String copyright
See Also:
Constant Field Values
Method Detail

size

public int size()
This will return the size of the collection at the time it is created, regardless of whether all the objects can be resolved. It will not change over time if items are deleted.

Specified by:
size in interface java.util.Collection
Returns:
an integer containing the number of items in this PIMCollection at creation time
See Also:
Collection.size()

contains

public boolean contains(java.lang.Object o)
Check if the object o is in the collection.

Specified by:
contains in interface java.util.Collection
Parameters:
o - the object to check for presence in the collection
Returns:
true if o is present in the collection, false if not
Throws:
java.lang.NullPointerException - if o is null
PIMInternalException - if the object is not a valid PIM object type
See Also:
*

iterator

public java.util.Iterator iterator()
Iterates over the objects in this Collection. Objects will be need to cast to the appropriate PIM Object type once retrieved. Beware: since we are in a lazily instantiated collection, iterator().next() will skip over any deleted entries. You may get fewer iterations than you expected.

Specified by:
iterator in interface java.util.Collection
Returns:
a java.util.Iterator for retrieving Objects in this collection.
See Also:
Collection.iterator()

toArray

public java.lang.Object[] toArray()
Retrieves the whole collection as an array. Warning: This will be very expensive as every element must be resolved It is recommended this method is not used anywhere where performance is an issue. Use iterator() instead. toArray() behaves slightly differently to iterator() in that null (removed/inaccessible) entries will not be skipped, but will remain as null entries in the array. This means you can count on the array size always matching the PIMCollection's size() method. The array will be recalculated each time you call toArray().

Specified by:
toArray in interface java.util.Collection
Returns:
an array of objects representing the actual data in this PIMCollection.
See Also:
Collection.toArray()

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)
Unsupported method.

This method will not work, because you cannot change the type of a PIM Object

Specified by:
toArray in interface java.util.Collection
Throws:
java.lang.ArrayStoreException - This exception will be thrown in all conditions.
See Also:
Collection.toArray(java.lang.Object[])

add

public boolean add(java.lang.Object o)
Unsupported method.

Specified by:
add in interface java.util.Collection
Throws:
java.lang.UnsupportedOperationException - This exception will be thrown in all conditions.
See Also:
Collection.add(java.lang.Object)

remove

public boolean remove(java.lang.Object o)
Unsupported method.

Specified by:
remove in interface java.util.Collection
Throws:
java.lang.UnsupportedOperationException - This exception will be thrown in all conditions.
See Also:
Collection.remove(java.lang.Object)

containsAll

public boolean containsAll(java.util.Collection c)
Check if all the contents of Collection c are within this PIMCollection.

Specified by:
containsAll in interface java.util.Collection
Parameters:
c - the collection to check against this collection
Returns:
true if the contents of c are all present in this PIMCollection, false if not.
Throws:
java.lang.NullPointerException - if c is null or c contains a null entry
PIMInternalException - if c contains an object which is not a valid PIM Object
See Also:
Collection.containsAll(java.util.Collection)

addAll

public boolean addAll(java.util.Collection c)
Unsupported method.

Specified by:
addAll in interface java.util.Collection
Throws:
java.lang.UnsupportedOperationException - This exception will be thrown in all conditions.
See Also:
Collection.addAll(java.util.Collection)

removeAll

public boolean removeAll(java.util.Collection c)
Unsupported method

Specified by:
removeAll in interface java.util.Collection
Throws:
java.lang.UnsupportedOperationException - This exception will be thrown in all conditions.
See Also:
Collection.removeAll(java.util.Collection)

retainAll

public boolean retainAll(java.util.Collection c)
Unsupported method

Specified by:
retainAll in interface java.util.Collection
Throws:
java.lang.UnsupportedOperationException - This exception will be thrown in all conditions.
See Also:
Collection.retainAll(java.util.Collection)

clear

public void clear()
Unsupported method

Specified by:
clear in interface java.util.Collection
Throws:
java.lang.UnsupportedOperationException - This exception will be thrown in all conditions.
See Also:
Collection.clear()

equals

public boolean equals(java.lang.Object o)
Specified by:
equals in interface java.util.Collection
See Also:
Checks that the PIMCollection *appears* to contains the ojbects as another PIMCollection It uses its hashcode method to check for equality - which checks only the underlying ID and does not take into account the contents of the underlying objects. This means that an object could be changed or deleted in one of the collections and equals() would still return true. It also means that there is no guarantee that all the objects in one collection exist in the second. If you need to be certain about the contents of every element, you will need to use .iterator() or .toArray() See the javadoc on those methods for caveats on each of those methods.

hashCode

public int hashCode()
Specified by:
hashCode in interface java.util.Collection
See Also:
A shallow hashcode method which only looks at which objects were in this collection at the time of its creation. It does not look into each object's contents and does not take into account edits or deletions. It will always return the same value for the life of this PIMCollection