messif.objects.util
Class AbstractObjectIterator<E extends AbstractObject>

java.lang.Object
  extended by messif.objects.util.AbstractObjectIterator<E>
Type Parameters:
E - the class of the iterated objects
All Implemented Interfaces:
java.util.Iterator<E>, ObjectProvider<E>
Direct Known Subclasses:
AbstractStreamObjectIterator, ExtractorIterator, ObjectIteratorsIterator, ObjectProvidersIterator, SearchAbstractObjectIterator

public abstract class AbstractObjectIterator<E extends AbstractObject>
extends java.lang.Object
implements java.util.Iterator<E>, ObjectProvider<E>

Implementation of an iterator over a collection of abstract objects. It provides methods for getting objects by their position, ID, data-equality, locator or ObjectMatcher.

All methods are implemented in a "stream" fashion, i.e. only the Iterator.next() method is used to accomplish all the getting methods. Note that iterator cannot go back, so for example the get-by-id method will only find the object if it has not been skipped in the iterator before.


Constructor Summary
AbstractObjectIterator()
           
 
Method Summary
abstract  E getCurrentObject()
          Returns an object returned by the last call to Iterator.next().
 UniqueID getCurrentObjectID()
          Returns an ID of the object returned by the last call to Iterator.next().
 GenericMatchingObjectList<E> getMatchingObjects(ObjectMatcher<? super E> matcher)
          Returns matching objects.
 GenericMatchingObjectList<E> getMatchingObjects(ObjectMatcher<? super E> matcher, boolean removeMatching)
          Returns matching objects.
 GenericMatchingObjectList<E> getMatchingObjects(ObjectMatcher<? super E> matcher, boolean removeMatching, int whoStays)
          Returns matching objects.
 GenericMatchingObjectList<E> getMatchingObjects(ObjectMatcher<? super E> matcher, boolean removeMatching, int[] whoStays)
          Get matching objects Method returns all objects that satisfy the matching contraints specified by matcher and deletes matching objects from the bucket when required.
 E getObjectByAnyLocator(java.util.Set<java.lang.String> locatorURIs, boolean removeFound)
          Returns the first instance of object, that has one of the specified locators.
 E getObjectByData(LocalAbstractObject object)
          Returns the first instance of object, that has data equal to the provided object.
 E getObjectByID(UniqueID objectID)
          Returns the first instance of object, that has the specified ID.
 E getObjectByLocator(java.lang.String locatorURI)
          Returns the first instance of object, that has the specified locator.
 E getObjectByPosition(int position)
          Returns an instance of object on the position of position from the current object.
 E getRandomObject()
          Returns a randomly choosen object from the objects remaining in this iterator.
 AbstractObjectList<E> getRandomObjects(int count, boolean unique)
          Returns a list containing randomly choosen objects from the objects remaining in this iterator.
 UniqueID nextObjectID()
          Returns an ID of the object returned by a call to Iterator.next().
 AbstractObjectIterator<E> provideObjects()
          Returns an iterator over the provided objects.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Iterator
hasNext, next, remove
 

Constructor Detail

AbstractObjectIterator

public AbstractObjectIterator()
Method Detail

getCurrentObject

public abstract E getCurrentObject()
                                                   throws java.util.NoSuchElementException
Returns an object returned by the last call to Iterator.next().

Returns:
an object returned by the last call to Iterator.next()
Throws:
java.util.NoSuchElementException - if Iterator.next() has not been called yet

getCurrentObjectID

public UniqueID getCurrentObjectID()
                            throws java.util.NoSuchElementException
Returns an ID of the object returned by the last call to Iterator.next().

Returns:
an ID of the object returned by the last call to Iterator.next().
Throws:
java.util.NoSuchElementException - if next() has not been called yet.

nextObjectID

public UniqueID nextObjectID()
Returns an ID of the object returned by a call to Iterator.next(). That is, the next object is obtained from the iterator via Iterator.next() and its ID is returned.

Returns:
an ID of the object returned by a call to Iterator.next()

getObjectByPosition

public E getObjectByPosition(int position)
                                             throws java.util.NoSuchElementException
Returns an instance of object on the position of position from the current object. Specifically, next() is called position times and then the current object is returned. That is, position 0 means current object, 1 means the next object, etc.

Parameters:
position - the position from the current object
Returns:
an instance of object on the position of position from the current object
Throws:
java.util.NoSuchElementException - if such an object cannot be found.

getObjectByID

public E getObjectByID(UniqueID objectID)
                                       throws java.util.NoSuchElementException
Returns the first instance of object, that has the specified ID.

Parameters:
objectID - ID of the object that we are searching for
Returns:
the first instance of object, that has the specified objectID
Throws:
java.util.NoSuchElementException - if such an object cannot be found.

getObjectByData

public E getObjectByData(LocalAbstractObject object)
                                         throws java.util.NoSuchElementException
Returns the first instance of object, that has data equal to the provided object.

Parameters:
object - the object to match the data against
Returns:
the first instance of object, that has the data equal to the specified object
Throws:
java.util.NoSuchElementException - if such an object cannot be found.

getObjectByLocator

public final E getObjectByLocator(java.lang.String locatorURI)
                                                  throws java.util.NoSuchElementException
Returns the first instance of object, that has the specified locator.

Parameters:
locatorURI - the locator of the object that we are searching for
Returns:
the first instance of object, that has specified locatorURI
Throws:
java.util.NoSuchElementException - if there is no object with the specified locator

getObjectByAnyLocator

public E getObjectByAnyLocator(java.util.Set<java.lang.String> locatorURIs,
                               boolean removeFound)
                                               throws java.util.NoSuchElementException
Returns the first instance of object, that has one of the specified locators.

Parameters:
locatorURIs - the set of locators that we are searching for
removeFound - if true the locators which were found are removed from the locatorURIs set, otherwise, locatorURIs is not touched
Returns:
the first instance of object, that has one of the specified locators
Throws:
java.util.NoSuchElementException - if there is no object with any of the specified locators

getRandomObject

public E getRandomObject()
                                         throws java.util.NoSuchElementException
Returns a randomly choosen object from the objects remaining in this iterator. Note that all the remaining objects in this iterator are read.

Returns:
a randomly choosen object
Throws:
java.util.NoSuchElementException - if this iterator has no objects left

getRandomObjects

public AbstractObjectList<E> getRandomObjects(int count,
                                              boolean unique)
Returns a list containing randomly choosen objects from the objects remaining in this iterator. Note that all the remaining objects in this iterator are read.

Parameters:
count - the number of objects to return
unique - flag if the returned list contains each object only once
Returns:
a new list instance which contains randomly selected objects
See Also:
AbstractObjectList.randomList(int, boolean, java.util.List, java.util.Iterator)

provideObjects

public AbstractObjectIterator<E> provideObjects()
Returns an iterator over the provided objects. This implementation of the ObjectProvider interface returns itself as an iterator.

Specified by:
provideObjects in interface ObjectProvider<E extends AbstractObject>
Returns:
an iterator over the provided objects

getMatchingObjects

public GenericMatchingObjectList<E> getMatchingObjects(ObjectMatcher<? super E> matcher)
                                                                       throws java.util.NoSuchElementException,
                                                                              OccupationLowException,
                                                                              FilterRejectException
Returns matching objects. Method returns all objects that satisfy the matching contraints specified by matcher, i.e. ObjectMatcher.match(T) method in the matcher returns non-zero when applied on them.

Parameters:
matcher - The matching condition implemented in the ObjectMatcher interface.
Returns:
a list of objects which satisfy the matching condition
Throws:
java.util.NoSuchElementException - if deletion reported it or if this method is called after next was called.
FilterRejectException - if delettion of a matching object was rejected by a filter (in case this is an iterator of LocalFilteredBucket).
OccupationLowException - if deletion of matching objects caused too low an occupation of bucket than allowed.

getMatchingObjects

public GenericMatchingObjectList<E> getMatchingObjects(ObjectMatcher<? super E> matcher,
                                                       boolean removeMatching)
                                                                       throws java.util.NoSuchElementException,
                                                                              OccupationLowException,
                                                                              FilterRejectException
Returns matching objects. Method returns all objects that satisfy the matching contraints specified by matcher (i.e. ObjectMatcher.match(T) method in the matcher returns non-zero when applied on them) and deletes matching objects from the bucket when required.

Parameters:
matcher - The matching condition implemented in the ObjectMatcher interface.
removeMatching - Matching objects are also deleted from the bucket.
Returns:
a list of objects which satisfy the matching condition
Throws:
java.util.NoSuchElementException - if deletion reported it or if this method is called after next was called.
FilterRejectException - if delettion of a matching object was rejected by a filter (in case this is an iterator of LocalFilteredBucket).
OccupationLowException - if deletion of matching objects caused too low an occupation of bucket than allowed.

getMatchingObjects

public GenericMatchingObjectList<E> getMatchingObjects(ObjectMatcher<? super E> matcher,
                                                       boolean removeMatching,
                                                       int whoStays)
                                                                       throws java.util.NoSuchElementException,
                                                                              OccupationLowException,
                                                                              FilterRejectException
Returns matching objects. Method returns all objects that satisfy the matching contraints specified by matcher and deletes matching objects from the bucket when required. An object is considered as matching if and only if ObjectMatcher.match(T) returns value different from whoStays.

Parameters:
matcher - The matching condition implemented in the ObjectMatcher interface.
removeMatching - Matching objects are also deleted from the bucket.
whoStays - Identification of a partition whose objects stay in this bucket.
Returns:
a list of objects which satisfy the matching condition (i.e. ObjectMatcher.match(T) is not equal to whoStays when applied on them)
Throws:
java.util.NoSuchElementException - if deletion reported it or if this method is called after next was called.
FilterRejectException - if delettion of a matching object was rejected by a filter (in case this is an iterator of LocalFilteredBucket).
OccupationLowException - if deletion of matching objects caused too low an occupation of bucket than allowed.

getMatchingObjects

public GenericMatchingObjectList<E> getMatchingObjects(ObjectMatcher<? super E> matcher,
                                                       boolean removeMatching,
                                                       int[] whoStays)
                                                                       throws java.util.NoSuchElementException,
                                                                              OccupationLowException,
                                                                              FilterRejectException
Get matching objects Method returns all objects that satisfy the matching contraints specified by matcher and deletes matching objects from the bucket when required. An object is considered as matching if and only if ObjectMatcher.match() returns value different from all elements of whoStays.

Parameters:
matcher - The matching condition implemented in the ObjectMatcher interface.
removeMatching - Matching objects are also deleted from the bucket.
whoStays - An array of identifications of partitions whose objects stay in this bucket.
Returns:
Returns list of objects which satisfy the matching condition (i.e. ObjectMatcher.match() is not equal to whoStays when applied on them).
Throws:
java.util.NoSuchElementException - if deletion reported it or if this method is called after next was called.
FilterRejectException - if delettion of a matching object was rejected by a filter (in case this is an iterator of LocalFilteredBucket).
OccupationLowException - if deletion of matching objects caused too low an occupation of bucket than allowed.