com.softwareag.tamino.db.api.objectModel
Interface TXMLObjectIterator

All Known Implementing Classes:
TXMLObjectFetchingIterator, TXMLObjectFetchingIteratorTimeLoggingImpl, TXMLObjectIteratorImpl, TXMLObjectIteratorTimeLoggingImpl

public interface TXMLObjectIterator

TXMLObjectIterator is a bidirectional iterator to iterate over a list of TXMLObject instances. It�s behaviour is similar to the java.util.ListIterator. The methods of the iterator may throw two different kind of exceptions. If there are problems accessing Tamino the TIteratorException is thrown. If the iterator moves beyond the boundaries of the result set the TNoSuchXMLObjectException is thrown. Note that two TXMLObject instances representing the same Tamino document retrieved via an iterator may not necessarily be identical Java objects. You should therefore not use the Java comparator "==" to decide whether two TXMLObject instances represent the same Tamino document.

Alternating calls to next and previous will return the same TXMLObject instance repeatedly. If you call moveBy with a positive argument n, it has the same effect on the position of the iterator as calling next n times. If you call moveBy with a negative argument n, it has the same effect on the iterator as calling previous n times. Calling moveBy with a zero argument has no effect.

Version:
$Revision: 1.20 $
Author:
Marcus Schreyer

Method Summary
 boolean canMoveBy(int offset)
          Indicates if this iterator can be moved by the given offset.
 void close()
          Closes this iterator.
 int getCount()
          Gets the query count as an int.
 boolean hasCount()
          Indicates if the response of Tamino contained the query count.
 boolean hasNext()
          Returns true if this iterator has more TXMLObject instances when traversing the list in the forward direction.
 boolean hasPrevious()
          Returns true if this list iterator has more TXMLObject instances when traversing the list in the reverse direction.
 void moveBy(int offset)
          Moves the iterator by the given offset.
 TXMLObject next()
          Returns the next element in the list of TXMLObject instances.
 TXMLObject previous()
          Returns the previous TXMLObject instance in the list.
 void reset()
          Resets the iterator to its initial state.
 

Method Detail

hasNext

boolean hasNext()
Returns true if this iterator has more TXMLObject instances when traversing the list in the forward direction. (In other words, returns true if next would return a TXMLObject instance rather than throwing an exception.)

Returns:
true if the list iterator has more TXMLObject instances when traversing the list in the forward direction.

next

TXMLObject next()
                throws TNoSuchXMLObjectException,
                       TIteratorException
Returns the next element in the list of TXMLObject instances. This method may be called repeatedly to iterate through the list, or intermixed with calls to previous to go back and forth. (Note that alternating calls to next and previous will return the same TXMLObject instance repeatedly.)

Returns:
the next TXMLObject instance in the list.
Throws:
TNoSuchXMLObjectException - the if iteration has no next TXMLObject instance.
TIteratorException - signals an error while attempting to access Tamino.

hasPrevious

boolean hasPrevious()
Returns true if this list iterator has more TXMLObject instances when traversing the list in the reverse direction. (In other words, returns true if previous would return a TXMLObject instance rather than throwing an exception.)

Returns:
true if the list iterator has more TXMLObject instances when traversing the list in the reverse direction.

previous

TXMLObject previous()
                    throws TNoSuchXMLObjectException,
                           TIteratorException
Returns the previous TXMLObject instance in the list. This method may be called repeatedly to iterate through the list backwards, or intermixed with calls to next to go back and forth. (Note that alternating calls to previous and next will return the same TXMLObject instance repeatedly.)

Returns:
The previous TXMLObject instance in the list.
Throws:
TNoSuchXMLObjectException - if the iteration has no previous TXMLObject instance.
TIteratorException - signals an error while attempting to access Tamino.

hasCount

boolean hasCount()
Indicates if the response of Tamino contained the query count.

Returns:
true if the response of Tamino contained the query count, false otherwise.

getCount

int getCount()
Gets the query count as an int. The query count is the total number of resulting objects for a query issued against Tamino. This value is independent from the quantity specified in the query method. The query count is only available for queries that have been issued using the query method specifying a quantity (i.e. when the Tamino cursoring mechanism is being used). Furthermore it is not available for xqueries. Tamino only returns a query count in case its calculation does not require the creation of the result set as a whole. In other words, Tamino only returns a query count if it is not expensive to calculate.

Returns:
the query count as an int, if available. Otherwise, -1 is returned.

canMoveBy

boolean canMoveBy(int offset)
                  throws TIteratorException
Indicates if this iterator can be moved by the given offset.

Parameters:
offset - the positive or negative amount to move the iterator
Returns:
true if move is possible, false otherwise.
Throws:
TIteratorException - signals an error while attempting to access Tamino.

moveBy

void moveBy(int offset)
            throws TNoSuchXMLObjectException,
                   TIteratorException
Moves the iterator by the given offset. If you call moveBy with a positive argument n, it has the same effect on the position of the iterator as calling next n times. If you call moveBy with a negative argument n, it has the same effect on the iterator as calling previous n times. Calling moveBy with a zero argument has no effect.

Parameters:
offset - the positive or negative amount to move the iterator
Throws:
TNoSuchXMLObjectException - if the new position is out of bounds.
TIteratorException - signals an error while attempting to access Tamino.

reset

void reset()
           throws TIteratorException
Resets the iterator to its initial state. The iterator is moved back to point before the first TXMLObject instance in the list.

Throws:
TIteratorException - signals an error while attempting to access Tamino.

close

void close()
           throws TIteratorException
Closes this iterator. Closing the iterator releases all resources held by the iterator. After closing an iterator it is no longer usable.

Throws:
TIteratorExceptionsignals - an error while attempting to access Tamino.
TIteratorException


Copyright (c) 2013 Software AG. All Rights Reserved.