com.ibm.pim.collection
Interface PIMCollection<E>

All Superinterfaces:
java.util.Collection<E>, java.lang.Iterable<E>

public interface PIMCollection<E>
extends java.util.Collection<E>

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. Thus, a PIMCollection is a collection of IDs, not objects, and we refer to these IDs as the elements in the collection.

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

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

Delete versus remove: an object is said to be deleted if the actual object corresponding to its ID in a PIMCollection is deleted, by a process outside the control of the PIMCollection; an object is said to be removed if it is the argument to an invocation of the remove() method and the method succeeds. If an object is deleted, the size of the PIMCollection is not changed, whereas if an object is removed the size of the PIMCollection is reduced by 1. Note that the fact that an object is removed from a PIMCollection does not imply that the actual object referenced by the ID in the PIMCollection is deleted.

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 for performance reasons, as 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(E o)
          Add the ID of the specified PIM object to this PIM collection.
 boolean addAll(java.util.Collection<? extends E> c)
          Add all the elements in the specified collection to this collection.
 void clear()
          Remove all the elements from this collection, making it empty.
 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 elements of Collection c are within this PIMCollection.
 boolean equals(java.lang.Object o)
          Checks that the PIMCollection appears to contains the same elements as the specified PIMCollection.
 int hashCode()
          A shallow hashcode method which only looks at the elements in this collection.
 boolean isEmpty()
          Test whether this collection is empty.
 java.util.Iterator<E> iterator()
          Get an iterator over the elements in this Collection.
 boolean remove(java.lang.Object o)
          Remove a single instance of the ID of the specified object from this PIM collection.
 boolean removeAll(java.util.Collection<?> c)
          Removes all the elements in the specified collection from this collection.
 boolean retainAll(java.util.Collection<?> c)
          Retains only those elements in this collection that are elements of the specified collection (i.e.
 int size()
          Return the current number of elements in the collection, regardless of whether all the IDs can be resolved.
 java.lang.Object[] toArray()
          Retrieve the whole collection as an array.
<T> T[]
toArray(T[] a)
          Unsupported method.
 

Field Detail

copyright

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

size

int size()
Return the current number of elements in the collection, regardless of whether all the IDs can be resolved. The size will not change if objects are deleted, but it will increase by 1 for each successful add() operation and decrease by 1 for each successful remove() operation.

Specified by:
size in interface java.util.Collection<E>
Returns:
an integer containing the number of elements in this PIMCollection.
See Also:
Collection.size()

isEmpty

boolean isEmpty()
Test whether this collection is empty.

Specified by:
isEmpty in interface java.util.Collection<E>
Returns:
true if and only of there are no elements in this collection.
See Also:
Collection.isEmpty()

contains

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

Specified by:
contains in interface java.util.Collection<E>
Parameters:
o - the object to check for presence in the collection
Returns:
true if the ID of object 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

java.util.Iterator<E> iterator()
Get an iterator over the elements in this Collection. Objects will need to be 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<E>
Specified by:
iterator in interface java.lang.Iterable<E>
Returns:
a java.util.Iterator for retrieving Objects in this collection.
See Also:
Collection.iterator()

toArray

java.lang.Object[] toArray()
Retrieve the whole collection as an array. Warning: This will be very expensive as every element must be resolved. It is recommended this method not be used anywhere where performance is an issue. Use iterator() instead. toArray() behaves slightly differently from 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<E>
Returns:
an array of objects representing the actual data in this PIMCollection.
See Also:
Collection.toArray()

toArray

<T> T[] toArray(T[] 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<E>
Throws:
java.lang.ArrayStoreException - This exception will be thrown in all conditions.
See Also:
Collection.toArray(java.lang.Object[])

add

boolean add(E o)
Add the ID of the specified PIM object to this PIM collection. Note that since this is a Collection (not a Set) it is allowed to add an element that is already in the collection.

Specified by:
add in interface java.util.Collection<E>
Parameters:
o - the PIM object to be added
Returns:
true if this collection changed as a result of the call.
Throws:
java.lang.ClassCastException - if the type of the object to add is not PIMObject
java.lang.NullPointerException - if the object to add is null
See Also:
Collection.add(java.lang.Object)

remove

boolean remove(java.lang.Object o)
Remove a single instance of the ID of the specified object from this PIM collection.

Specified by:
remove in interface java.util.Collection<E>
Parameters:
o - the object to be removed.
Returns:
true if this collection changed as a result of the call.
Throws:
java.lang.ClassCastException - if the type of the object to add is not PIMObject
java.lang.NullPointerException - if the object to add is null
See Also:
Collection.remove(java.lang.Object)

containsAll

boolean containsAll(java.util.Collection<?> c)
Check if all the elements of Collection c are within this PIMCollection.

Specified by:
containsAll in interface java.util.Collection<E>
Parameters:
c - the collection to check against this collection
Returns:
true if the elements 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 is not a PIMCollection or if it contains an object that is not a valid PIM Object
See Also:
Collection.containsAll(java.util.Collection)

addAll

boolean addAll(java.util.Collection<? extends E> c)
Add all the elements in the specified collection to this collection.

Specified by:
addAll in interface java.util.Collection<E>
Parameters:
c - the collection to add to this collection
Returns:
true if any of the elements of c was added to this collection, false if none were.
Throws:
java.lang.ClassCastException - if the type of any element to add is not PIMObject
java.lang.NullPointerException - if c is null or c contains a null entry
PIMInternalException - if c is not a PIMCollection or if it contains an object that is not a valid PIM Object
See Also:
Collection.addAll(java.util.Collection)

removeAll

boolean removeAll(java.util.Collection<?> c)
Removes all the elements in the specified collection from this collection.

Specified by:
removeAll in interface java.util.Collection<E>
Parameters:
c - the collection to remove from this collection
Returns:
true if any of the elements of c was removed from this collection, false if none were.
Throws:
java.lang.ClassCastException - if the type of any element to remove is not PIMObject
java.lang.NullPointerException - if c is null or c contains a null entry
PIMInternalException - if c is not a PIMCollection or if it contains an object that is not a valid PIM Object
See Also:
Collection.removeAll(java.util.Collection)

retainAll

boolean retainAll(java.util.Collection<?> c)
Retains only those elements in this collection that are elements of the specified collection (i.e. remove those elements in this collection that are not elements of the specified collection).

Specified by:
retainAll in interface java.util.Collection<E>
Parameters:
c - the collection to retain in this collection
Returns:
true if any of the elements of this collection not contained in c were removed, false if none were.
Throws:
java.lang.ClassCastException - if the type of any element to retain is not PIMObject
java.lang.NullPointerException - if c is null or c contains a null entry
PIMInternalException - if c is not a PIMCollection or if it contains an object that is not a valid PIM Object
See Also:
Collection.retainAll(java.util.Collection)

clear

void clear()
Remove all the elements from this collection, making it empty.

Specified by:
clear in interface java.util.Collection<E>
See Also:
Collection.clear()

equals

boolean equals(java.lang.Object o)
Checks that the PIMCollection appears to contains the same elements as the specified 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 other. 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 them.

Specified by:
equals in interface java.util.Collection<E>
Overrides:
equals in class java.lang.Object
See Also:
Object.equals(java.lang.Object)

hashCode

int hashCode()
A shallow hashcode method which only looks at the elements in this collection. It does not look into each object's contents and does not take deletions into account.

Specified by:
hashCode in interface java.util.Collection<E>
Overrides:
hashCode in class java.lang.Object
See Also:
Collection.hashCode()