xxl.cursors
Class AbstractCursor

java.lang.Object
  |
  +--xxl.cursors.AbstractCursor

Direct Known Subclasses:

InputIterator, RandomIntegers, SingletonCursor

public abstract class AbstractCursor

extends java.lang.Object

implements Cursor

The AbstractCursor implements most of the methods of the Cursor-interface and is useful in that cases when you produce elements and want to ´return´ them by a Cursor. e.g. consider a query-operation on an index structure that returns an Iterator of results. It is sufficient then to create an AbstractCursor and implement the abstract method computeNext(). computeNext() is a protected method that is only called internally by the AbstractCursor whenever a new result is requested on that Cursor. The contract of computeNext() is that it computes the next element (hence its name).

Example usage: the RandomIntegers-Cursor produces a certain number (noOfObjects) of random Integer-Objects by calling java.util.Random.nextInt(..). RandomIntegers extends AbstractCursor and the implementation of computeNext() is as follows:

	protected void computeNext(){
		if(noOfObjects-- > 0)		
			setNext(new Integer(random.nextInt(maxValue)));
	}
	

This means, as long as noOfObjects > 0 holds the next result of the AbstractCursor will be set to:

		new Integer(random.nextInt(maxValue));

	

The protected method setNext() sets the next Object to be returned by this AbstractCursor. If noOfObjects <= 0 holds no result will be set, i.e. all consequent calls to hasNext() will return false.

If you want to pass an entire Iterator in computeNext() to the AbstractCursor you should call

		boolean setNextIterator(myIterator);
	

where ´myIterator´ is an Iterator that must not be empty. In that case, the elements contained in myIterator will be returned by this Cursor and computeNext() will only be called again when myIterator is empty. (The method returns false, if myIterator was empty.)

See Also:

RandomIntegers

Field Summary

protected boolean	hasNext
protected java.util.Iterator	iterator
protected java.lang.Object	next

Constructor Summary

AbstractCursor()

Method Summary

void	close() Closes the Cursor.
protected abstract void	computeNext() Computes the next element (Contract: this method computes the next element to be returned by a call to next(), it sets the next-field by calling setNext(Object), or setNextIterator(Iterator), this method is only called by getNext()).
boolean	hasNext() Returns true if the iteration has more elements.
java.lang.Object	next() Returns the next element in the iteration.
java.lang.Object	peek() Shows the next element in the iteration without removing it.
void	remove() Removes from the underlying collection the last element returned by the iterator (optional operation).
void	reset() Resets the Cursor to its initial state.
protected void	setNext(java.lang.Object next) Sets the attribute "next" and sets hasNext=true.
protected boolean	setNextIterator(java.util.Iterator iterator) Sets the attribute "next" with the given non-empty Iterator and sets hasNext=true (IMPORTANT: This method is called setNextIterator and not setNext because this is a potential source of bugs if this AbstractCursor is a Cursors of Iterators, in that case it would not be clear which method has to be called).
boolean	supportsPeek() Returns true if the peek operation is supported by this PeekIterator.
void	update(java.lang.Object object) Replaces the object that was returned by the last call to next() or peek().

Methods inherited from class java.lang.Object

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

Field Detail

hasNext

protected boolean hasNext

next

protected java.lang.Object next

iterator

protected java.util.Iterator iterator

Constructor Detail

AbstractCursor

public AbstractCursor()

Method Detail

close

public void close()

Closes the Cursor. Signals the cursor to cleanup resources, close files, etc. After a call to close() calls to methods like next() or peek() are not guarantied to yield proper results.

Specified by:

close in interface Cursor

hasNext

public boolean hasNext()

Returns true if the iteration has more elements.

Specified by:

hasNext in interface Cursor

Returns:

true if the iterator has more elements

computeNext

protected abstract void computeNext()

Computes the next element (Contract: this method computes the next element to be returned by a call to next(), it sets the next-field by calling setNext(Object), or setNextIterator(Iterator), this method is only called by getNext()).

setNext

protected void setNext(java.lang.Object next)

Sets the attribute "next" and sets hasNext=true.

setNextIterator

protected boolean setNextIterator(java.util.Iterator iterator)

Sets the attribute "next" with the given non-empty Iterator and sets hasNext=true (IMPORTANT: This method is called setNextIterator and not setNext because this is a potential source of bugs if this AbstractCursor is a Cursors of Iterators, in that case it would not be clear which method has to be called).

Returns:

false if the iterator is empty, true otherwise

next

public java.lang.Object next()
                      throws java.util.NoSuchElementException

Returns the next element in the iteration.

Specified by:

next in interface Cursor

Returns:

the next element in the iteration

Throws:

java.util.NoSuchElementException - iteration has no more elements

peek

public java.lang.Object peek()
                      throws java.util.NoSuchElementException,
                             java.lang.UnsupportedOperationException

Shows the next element in the iteration without removing it.

Specified by:

peek in interface Cursor

Returns:

the next element in the iteration

Throws:

java.util.NoSuchElementException - iteration has no more elements

java.lang.UnsupportedOperationException - if the peek operation is not supported by this PeekIterator

remove

public void remove()
            throws java.lang.IllegalStateException,
                   java.lang.UnsupportedOperationException

Removes from the underlying collection the last element returned by the iterator (optional operation).

Specified by:

remove in interface Cursor

Throws:

java.lang.IllegalStateException - if the next method has not yet been called, or the remove method has already been called after the last call to the next method.

java.lang.UnsupportedOperationException - if the remove operation is not supported by this PeekIterator.

reset

public void reset()
           throws java.lang.UnsupportedOperationException

Resets the Cursor to its initial state.

Specified by:

reset in interface Cursor

supportsPeek

public boolean supportsPeek()

Returns true if the peek operation is supported by this PeekIterator.

Specified by:

supportsPeek in interface Cursor

Returns:

true if the peek operation is supported by this PeekIterator.

update

public void update(java.lang.Object object)
            throws java.lang.IllegalStateException,
                   java.lang.UnsupportedOperationException

Replaces the object that was returned by the last call to next() or peek(). This operation must not be called after a call to hasNext(). It should follow a call to next() or peek().

Specified by:

update in interface Cursor

Parameters:

object - the object that replaces the object returned by the last call to next() or peek()