org.xshare.base.iterator
Class RangeIterator

java.lang.Object
  |
  +--org.xshare.base.iterator.RangeIterator

All Implemented Interfaces:

java.util.Iterator

public class RangeIterator

extends java.lang.Object

implements java.util.Iterator

Specialized Iterator implementation - based on UnaryPredicates - to limit the returned elements of another Iterator pointing to a sorted list of elements.

When is it usefull?

In some cases you would like to process only some elements of an iterator. Mostly the FilterIterator is the best choice for that task. If the iterator is not sorted and doesn't point to a huge amount of objects, you should use the FilterIterator. In some seldom cases, you will get a iterator pointing to a huge sorted set of elements, e.g. a iterator with all customers of your company stored in a collection - maintained by a OO database - and sorted by name. Now imagine you want to process all members starting with C. If you choose the FilterIterator, this iterator will process all elements of your source iterator to find out, which elements to return. Choosing this iterator implementation you can avoid this and configure this iterator in such a way, that it stops to return elements if the name of a customer starts with D and not with C.

How to setup this iterator

This iterator is based on predicates. This allows you to express the condition with which element to start and after which one to stop with the help of UnaryPredicates. A very clean solution to express the conditions. Starting from now I will call this predicates borders. A RangeIterator can have two borders: One for specifing the left border of the element range and another one for the right border. The predicate for the left border specifies the first object returned by this iterator and the one for the right border specifies the object where this iterator stops to return objects. This object is not returned.

Example

This example will show how to filter all customers starting with "C" and "D" stored in a huge collection which is sorted by name.

 // The customer class
 class Customer {
  String getName() { ... }
 }
 ...
 public Iterator getAllCustomersWithCAndD() {
  return new RangeIterator(
      // predicate for the left border. we start to return objects
      // if we find a 'C'
      new UnaryPredicate() {
          boolean exec(Object pObject) {
              return ((Customer)pObject).getName().startsWith("C");
          }
      }
      
      // source iterator
      customerSortedList.iterator(),
      
      // predicate for the right border. we stop, if we find a 'E'
      new UnaryPredicate() {
          boolean exec(Object pObject) {
              return ((Customer)pObject).getName().startsWith("E");
          }
      });
 }

 ...

 

Notes On The Implementation

• The search for the first object starts if you call next() or hasNext() and not after creating an instance of this iterator.
• Since null is a valid return value for a iteration, the used predicate functions must be able to handle null as argument.

Version:

$Revision: 1.5 $

Author:

Oliver Fischer

See Also:

FilterIterator

Field Summary

protected UnaryPredicate	leftBorder Specifies the left border of the element range.
protected UnaryPredicate	rightBorder Specifies the right border of the element range.

Constructor Summary

RangeIterator(java.util.Iterator pSourceIterator, UnaryPredicate pRightBorder)
Creates a new RangeIterator instance with given predicate for the right border.

RangeIterator(UnaryPredicate pLeftBorder, java.util.Iterator pSourceIterator)
Creates a new RangeIterator instance with a given predicate for the left border.

RangeIterator(UnaryPredicate pLeftBorder, java.util.Iterator pSourceIterator, UnaryPredicate pRightBorder)
Creates a new RangeIterator instance with a given predicate for the right border and the left border.

Method Summary

boolean	hasNext() Checks if there is a element left to be returned by next().
java.lang.Object	next() Returns the next object of the specified range.
void	remove() Removes the last element returned by next() from the underlaying iteration by forwarding the remove call to it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

leftBorder

protected UnaryPredicate leftBorder

Specifies the left border of the element range.

rightBorder

protected UnaryPredicate rightBorder

Specifies the right border of the element range.

Constructor Detail

RangeIterator

public RangeIterator(UnaryPredicate pLeftBorder,
                     java.util.Iterator pSourceIterator,
                     UnaryPredicate pRightBorder)

Creates a new RangeIterator instance with a given predicate for the right border and the left border. An instance created with this constructor will return only elements between both borders.

Parameters:

pLeftBorder - an UnaryPredicate object specifing the left border of the elements.

pSourceIterator - an Iterator object representing the source iteration for this instance.

pRightBorder - an UnaryPredicate value

RangeIterator

public RangeIterator(UnaryPredicate pLeftBorder,
                     java.util.Iterator pSourceIterator)

Creates a new RangeIterator instance with a given predicate for the left border. An instance created with this constructor returns all elements starting from the left border.

Parameters:

pLeftBorder - an UnaryPredicate object specifing the left border of the elements.

pSourceIterator - an Iterator object representing the source iteration for this instance.

RangeIterator

public RangeIterator(java.util.Iterator pSourceIterator,
                     UnaryPredicate pRightBorder)

Creates a new RangeIterator instance with given predicate for the right border. An instance created with this constructor returns all elements til the right border has been reached.

Parameters:

pSourceIterator - an Iterator object representing the source iteration for this instance.

pRightBorder - an UnaryPredicate object specifing the right border of the elements.

Method Detail

remove

public void remove()

Removes the last element returned by next() from the underlaying iteration by forwarding the remove call to it.

Specified by:

remove in interface java.util.Iterator

Throws:

java.lang.UnsupportedOperationException - if the source iteration doesn't support this method.

next

public java.lang.Object next()

Returns the next object of the specified range.

Specified by:

next in interface java.util.Iterator

Throws:

java.util.NoSuchElementException - if hasNext() returns false.

See Also:

hasNext()

hasNext

public boolean hasNext()

Checks if there is a element left to be returned by next().

Specified by:

hasNext in interface java.util.Iterator

Returns:

a boolean value which is true if there are elements of the specified range left, which can be returned via next(). Otherwise this method returns false.

See Also:

next()