com.novell.service.nds
Interface NdsIterator

public interface NdsIterator

Creates a large virtual list of objects on the particular server in question containing all the entries that pass the search filter.

An iterator in NDS is a concept for handling large virtual lists. It provides list and search functionality, and it can deal with very large result sets, on the order of hundreds of thousands. An iterator for contexts allows the programmer to traverse the NdsIterator results in either direction. The variables defined here are used to set the iterator position in the list to top, bottom or end of list.

See Also:

NdsIteratorControls, NdsIteratorFactory, NdsIteratorInfo, NdsIteratorResult

Field Summary

static int	DS_ITR_EOF The position at the end of the list, just after the last entry, or no entries are present.
static int	DS_ITR_FIRST The position at the top of the list.
static int	DS_ITR_LAST The position at the bottom of the list.

Method Summary

java.lang.Object	clone() Creates a new object of the same class as this object.
void	close() Closes the iterator and frees all associated memory.
int	count(int timeout, int maxCount, boolean updatePosition) Counts the number of remaining entries (objects) in this iterator.
java.lang.Object	current() Returns the entry (NdsIteratorResult object) at the current position.
NdsIteratorInfo	getInfo() Returns encapsulated information about the iterator.
int	getPosition(int timeout) Returns the current iterator position in the list as an int in the range 0-1000, or 1001 (DS_ITR_EOF).
boolean	hasNext() Returns a boolean indicating whether this NdsIterator has more elements when traversing the list in the forward direction.
boolean	hasPrevious() Returns a boolean indicating whether this NdsIterator has more elements when traversing the list in the reverse direction.
javax.naming.NamingEnumeration	next(int entries, int timeout) Returns the next set (enumeration) of NdsIteratorResult objects (entries) in the list.
javax.naming.NamingEnumeration	previous(int entries, int timeout) Returns the previous set (enumeration) of NdsIteratorResult objects (entries) in the list.
void	setPosition(int position, int timeout) Sets the current iterator position in the list as an integer in the range of 0 to 1001.
void	setPosition(NdsIterator iterator, int timeout) Sets the current iterator position to that of another iterator.
void	setPosition(java.lang.String attribute, java.lang.String value, int timeout) Sets the iterator position according to the passed-in attribute and value parameters.
int	skip(int count, int timeout) Skips the number of entries in the list specified by count, either forward (positive number) or backward (negative number).

Field Detail

DS_ITR_FIRST

public static final int DS_ITR_FIRST

The position at the top of the list.

(DS_ITR_FIRST = 0)

DS_ITR_LAST

public static final int DS_ITR_LAST

The position at the bottom of the list.

(DS_ITR_LAST = 1000)

DS_ITR_EOF

public static final int DS_ITR_EOF

The position at the end of the list, just after the last entry, or no entries are present.

(DS_ITR_EOF = 1001)

Method Detail

getPosition

public int getPosition(int timeout)
                throws com.novell.service.jncp.NSIException

Returns the current iterator position in the list as an int in the range 0-1000, or 1001 (DS_ITR_EOF).

Parameters:

timeout - The time in seconds allowed before returning.

Returns:

The current position in the list.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

See Also:

setPosition(int, int)

setPosition

public void setPosition(int position,
                        int timeout)
                 throws com.novell.service.jncp.NSIException

Sets the current iterator position in the list as an integer in the range of 0 to 1001. The symbols DS_ITR_FIRST(0) and DS_ITR_LAST(1000) set the position to the first or last entry, respectively. The DS_ITR_EOF symbol sets the position to EOF (End-Of-List), just after the last entry.

Parameters:

position - The position to set as an integer from 0 to 1001.

timeout - The time in seconds allowed before returning.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

setPosition

public void setPosition(NdsIterator iterator,
                        int timeout)
                 throws com.novell.service.jncp.NSIException

Sets the current iterator position to that of another iterator. It is not necessary that the two iterators be identical. The system tries to find the closest match in the source iterator and positions the destination iterator accordingly.

Parameters:

iterator - The source iterator.

timeout - The time in seconds allowed before returning.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

setPosition

public void setPosition(java.lang.String attribute,
                        java.lang.String value,
                        int timeout)
                 throws com.novell.service.jncp.NSIException

Sets the iterator position according to the passed-in attribute and value parameters. It implements the 'typedown' functionality.

For example, if you have a list sorted by surname, you can specify D and it will position to the first name starting with D. If you specify DA, it positions to the first name starting with DA, and so forth. If there are no entries matching the value string, it positions to the first one that is greater than the specified value, or it positions to DS_ITR_EOF.

Parameters:

attribute - The attribute to use for typedown.

value - The string value to use for typedown.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

skip

public int skip(int count,
                int timeout)
         throws com.novell.service.jncp.NSIException

Skips the number of entries in the list specified by count, either forward (positive number) or backward (negative number).

The number of entries to skip is calculated from the current position. If the skip count extends beyond the boundary of the list, the actual entries skipped is smaller than count. When skip() returns because of timeout, the return value will not equal the count requested.

Parameters:

count - The number of entries to skip.

timeout - The time in seconds allowed before returning.

Returns:

The number of entries actually skipped.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

hasNext

public boolean hasNext()
                throws com.novell.service.jncp.NSIException

Returns a boolean indicating whether this NdsIterator has more elements when traversing the list in the forward direction. In other words, if next() would return entries rather than returning an empty enumeration, TRUE is returned; otherwise, FALSE is returned.

Returns:

A boolean set to TRUE if the NdsIterator has more elements when traversing forward in the list; otherwise, set to FALSE.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

next

public javax.naming.NamingEnumeration next(int entries,
                                           int timeout)
                                    throws com.novell.service.jncp.NSIException

Returns the next set (enumeration) of NdsIteratorResult objects (entries) in the list. 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 elements repeatedly.

Parameters:

entries - The number of next entries to return.

timeout - The time in seconds allowed before returning.

Returns:

The NamingEnumeration of the next elements in the list.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

NoSuchElementException - If the iteration has no next elements.

hasPrevious

public boolean hasPrevious()
                    throws com.novell.service.jncp.NSIException

Returns a boolean indicating whether this NdsIterator has more elements when traversing the list in the reverse direction. In other words, if previous() would return an element rather than returning an empty enumeration, TRUE is returned; otherwise, FALSE is returned.

Returns:

A boolean set to TRUE if the NdsIterator has more elements when traversing backward in the list; otherwise, set to FALSE.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

NoSuchElementException - The iteration has no next elements.

previous

public javax.naming.NamingEnumeration previous(int entries,
                                               int timeout)
                                        throws com.novell.service.jncp.NSIException

Returns the previous set (enumeration) of NdsIteratorResult objects (entries) in the list. The previous() method may be called repeatedly to iterate through the list backwards, or it may be intermixed with calls to next() to go back and forth. Note that alternating calls to next() and previous() will return the same element(s) repeatedly.

Parameters:

entries - The number of previous entries to return.

timeout - The time in seconds allowed before returning.

Returns:

A NamingEnumeration of the previous elements in the list.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

NoSuchElementException - If the iteration has no previous elements.

current

public java.lang.Object current()
                         throws com.novell.service.jncp.NSIException

Returns the entry (NdsIteratorResult object) at the current position.

Returns:

The entry (NdsIteratorResult object) at the current position.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

count

public int count(int timeout,
                 int maxCount,
                 boolean updatePosition)
          throws com.novell.service.jncp.NSIException

Counts the number of remaining entries (objects) in this iterator. Entries are scanned starting from the current position. The list is scanned until the timeout expires or the maxCount entries have been counted or the end of the list is reached.

If both timeout and maxCount are zero, the entire list is scanned and an exact count is returned. This may be very slow on large lists. If scanning stops due to timeout or maxCount, the getPosition() method may be called to establish the real count. If more accuracy is needed, count() may be called again with a longer timeout or maxCount.

Parameters:

timeout - The time in seconds allowed before returning. Zero signifies no time limit.

maxCount - The number of entries to scan before returning. Zero signifies no maximum limit.

updatePosition - A boolean set to TRUE if the current position will be left pointing to the last entry scanned. If set to FALSE the current position is left unchanged.

Returns:

The actual number of objects counted.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.

getInfo

public NdsIteratorInfo getInfo()
                        throws com.novell.service.jncp.NSIException

Returns encapsulated information about the iterator.

Returns:

The information about the iterator.

clone

public java.lang.Object clone()

Creates a new object of the same class as this object. It then initializes each of the new object's fields by assigning the same value as the corresponding field in this object. No constructor is called.

Returns:

A clone of this instance.

close

public void close()
           throws com.novell.service.jncp.NSIException

Closes the iterator and frees all associated memory.

Throws:

com.novell.service.jncp.NSIException - Standard NJCL exception for working on top of XPlat libraries.