Enterprise Information Portal APIs

com.ibm.mm.sdk.common
Class DKFederatedCollection

java.lang.Object
  |
  +--com.ibm.mm.sdk.common.DKSequentialCollection
        |
        +--com.ibm.mm.sdk.common.DKFederatedCollection
All Implemented Interfaces:
dkCollection, DKMessageId, java.io.Serializable

public class DKFederatedCollection
extends DKSequentialCollection

A federated collection allows an application program to process data objects resulting from a query as a group or collection and at the same time preserves the sub-grouping relationships that exists between them. It provides the user with a mechanism:

A federated collection is a collection containing DKResults objects, it is created to hold the results of DKFederatedQuery, which may come from several heterogenous datastores. Each DKResults contains the results of subquery of the federated query submitted to a specific native datastore associated with the federated datastore. To iterate over federated collection members (which are DKResults objects), a user should create and use dkIterator or DKSequentialIterator to pull each DKResults object. Then he could create another dkIterator on this DKResults to iterate over it and to process the result according to its datastore origin. Alternatively, the user can create a federated iterator, dkFederatedIterator, and use it to iterate over all element members across collection boundaries, regardless of which datastore the result came from. In theory, a federated collection can contains other nested collections up to any arbitrary depth. In the current implementation, a federated collection is not queryable.

See Also:
dkFederatedIterator, dkIterator, DKSequentialIterator, Serialized Form

Fields inherited from interface com.ibm.mm.sdk.common.DKMessageId
    For details, see the class or interface
 
Constructor Summary
DKFederatedCollection()
          Default constructor
 
Method Summary
 void addAllElements(dkCollection elements)
          Adds all elements in the collection, and invalidates all of the current iterators.
 void addElement(java.lang.Object element)
          Adds an element to the end of the collection, and invalidates all of the current iterators.
 int cardinality()
          Returns the number of all individual (leaf) elements (non-collection) across the collection boundaries.
 dkIterator createIterator()
          Creates a new dkFederatedIterator for this federated collection.
 dkIterator createMemberIterator()
          Creates a new iterator for this federated collection.
 void insertElementAt(java.lang.Object element, dkIterator where)
          Adds a new element, after the element the iterator is currently pointing at.
 int memberCardinality()
          Returns the number of elements in the collection.
 void removeAllElements()
          Removes all elements in the collection Invalidates all other iterators.
 void removeElementAt(dkIterator where)
          Removes the element the iterator is currently pointing at.
 void replaceElementAt(java.lang.Object element, dkIterator where)
          Replaces the element the iterator is currently pointing at.
 java.lang.Object retrieveElementAt(dkIterator where)
          Gets the element that the iterator is pointing at
 void sort()
          Sort is not supported in the FederatedCollection.
 void sort(boolean order)
          Sort is not supported in the FederatedCollection.
 void sort(dkSort sortFunction, boolean sortOrder)
          Sort is not supported in the FederatedCollection.
 
Methods inherited from class com.ibm.mm.sdk.common.DKSequentialCollection
getAssociatedAttrName, getName, getOwner, getSortFunction, setName, setSortFunction
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DKFederatedCollection

public DKFederatedCollection()
Default constructor
Method Detail

cardinality

public int cardinality()
Returns the number of all individual (leaf) elements (non-collection) across the collection boundaries. This is the total of all elements in each sub-collections.
Overrides:
cardinality in class DKSequentialCollection
Following copied from class: com.ibm.mm.sdk.common.DKSequentialCollection
Returns:
the number of elements.

memberCardinality

public int memberCardinality()
Returns the number of elements in the collection. The element could be a collection object, i.e. DKResults object, not necesarily a leaf element (non-collection).

createIterator

public dkIterator createIterator()
Creates a new dkFederatedIterator for this federated collection. This iterator can be used to iterate over the federated collection, across collection boundaries, returning a (non-collection) member one at a time.
Overrides:
createIterator in class DKSequentialCollection
Returns:
an iterator

createMemberIterator

public dkIterator createMemberIterator()
Creates a new iterator for this federated collection. The new iterator would be supporting DKSequentialIterator interface. That is, the method "next" of this iterator would return a collection, such as DKResults object. You can then, create an iterator on this DKResults to iterate over its member.
Returns:
an iterator

retrieveElementAt

public java.lang.Object retrieveElementAt(dkIterator where)
                                   throws DKUsageError
Gets the element that the iterator is pointing at
Overrides:
retrieveElementAt in class DKSequentialCollection
Parameters:
where - location in collection to retrieve an object
Returns:
an element

addElement

public void addElement(java.lang.Object element)
                throws DKUsageError
Adds an element to the end of the collection, and invalidates all of the current iterators.
Overrides:
addElement in class DKSequentialCollection
Parameters:
element - element to be added

addAllElements

public void addAllElements(dkCollection elements)
                    throws DKUsageError
Adds all elements in the collection, and invalidates all of the current iterators.
Parameters:
elements - collection of elements to be added

insertElementAt

public void insertElementAt(java.lang.Object element,
                            dkIterator where)
                     throws DKUsageError
Adds a new element, after the element the iterator is currently pointing at. The iterator is advanced to the new element, invalidating all other iterators.
Overrides:
insertElementAt in class DKSequentialCollection
Parameters:
element - element to be added
where - location in collection

replaceElementAt

public void replaceElementAt(java.lang.Object element,
                             dkIterator where)
                      throws DKUsageError
Replaces the element the iterator is currently pointing at.
Overrides:
replaceElementAt in class DKSequentialCollection
Parameters:
element - element to be added
iter - location in collection

removeElementAt

public void removeElementAt(dkIterator where)
                     throws DKUsageError
Removes the element the iterator is currently pointing at. The iterator is advanced to the next element after this operation, invalidating all other iterators.
Overrides:
removeElementAt in class DKSequentialCollection
Parameters:
iter - location in collection

removeAllElements

public void removeAllElements()
Removes all elements in the collection Invalidates all other iterators.
Overrides:
removeAllElements in class DKSequentialCollection

sort

public void sort()
          throws DKUsageError
Sort is not supported in the FederatedCollection. Exception will be thrown if this function is called.
Overrides:
sort in class DKSequentialCollection
Following copied from class: com.ibm.mm.sdk.common.DKSequentialCollection
See Also:
DKSequentialCollection.sort(dkSort sortFunction, boolean sortOrder)

sort

public void sort(boolean order)
          throws DKUsageError
Sort is not supported in the FederatedCollection. Exception will be thrown if this function is called.
Overrides:
sort in class DKSequentialCollection
Following copied from class: com.ibm.mm.sdk.common.DKSequentialCollection
Parameters:
order - a boolean value indicating the sort order. If true sort in ascending order, otherwise sort in descending order.
See Also:
DKSequentialCollection.sort(dkSort sortFunction, boolean sortOrder)

sort

public void sort(dkSort sortFunction,
                 boolean sortOrder)
          throws DKUsageError
Sort is not supported in the FederatedCollection. Exception will be thrown if this function is called.
Overrides:
sort in class DKSequentialCollection
Following copied from class: com.ibm.mm.sdk.common.DKSequentialCollection
Parameters:
sortFunction - the sort function.
sortOrder - a boolean value indicating the sort order. If true sort in ascending order, otherwise sort in descending order.

EIP Java APIs

(c) Copyright International Business Machines Corporation 1996, 2002. IBM Corp. All rights reserved.