Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD