Package org.apache.directory.api.ldap.model.cursor

Interface Cursor<E>

  • Type Parameters:
    E - The type of element on which this cursor will iterate
    All Superinterfaces:
    AutoCloseable, Closeable, Iterable<E>
    All Known Subinterfaces:
    EntryCursor, SearchCursor
    All Known Implementing Classes:
    AbstractCursor, EmptyCursor, EntryCursorImpl, ListCursor, SearchCursorImpl, SetCursor, SingletonCursor
    public interface Cursor<E>
extends Iterable<E>, Closeable
    A Cursor for bidirectional traversal over elements in a dataSet. Cursors unlike Iterators or Enumerations may advance to an element by calling next() or previous() which returns true or false if the request succeeds with a viable element at the new position. Operations for relative positioning in larger increments are provided. If the cursor can not advance, then the Cursor is either positioned before the first element or after the last element in which case the user of the Cursor must stop advancing in the respective direction. If an advance succeeds a get() operation retrieves the current object at the Cursors position. Although this interface presumes Cursors can advance bidirectionally, implementations may restrict this by throwing UnsupportedOperationExceptions.
    Author:
    Apache Directory Project

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void after​(E element)
      Prepares this Cursor, so a subsequent call to Cursor#previous() with a true return value, will have positioned the Cursor on a dataSet element equal to or less than the element argument but not greater.
      void afterLast()
      Positions this Cursor after the last element.
      boolean available()
      Determines whether or not a call to get() will succeed.
      void before​(E element)
      Prepares this Cursor, so a subsequent call to Cursor#next() with a true return value, will have positioned the Cursor on a dataSet element equal to or less than the element argument but not greater.
      void beforeFirst()
      Positions this Cursor before the first element.
      void close​(Exception reason)
      Closes this Cursor and frees any resources it my have allocated.
      boolean first()
      Positions this Cursor at the first element.
      E get()
      Gets the object at the current position.
      boolean isAfterLast()
      Is this Cursor positioned after the last element.
      boolean isBeforeFirst()
      Is this Cursor positioned before the first element.
      boolean isClosed()
      Checks if this Cursor is closed.
      boolean isFirst()
      Is this Cursor positioned at the first element.
      boolean isLast()
      Is this Cursor positioned at the last element.
      boolean last()
      Positions this Cursor at the last element.
      boolean next()
      Advances this Cursor to the next position.
      boolean previous()
      Advances this Cursor to the previous position.
      void setClosureMonitor​(ClosureMonitor monitor)
      Sets a non-null closure monitor to associate with this Cursor.
      String toString​(String tabs)
      Pretty-print a cursor and its wrapped cursor.

    • Method Detail

      • available

        boolean available()
        Determines whether or not a call to get() will succeed.
        Returns:
        true if a call to the get() method will succeed, false otherwise

      • before

        void before​(E element)
     throws LdapException,
            CursorException
        Prepares this Cursor, so a subsequent call to Cursor#next() with a true return value, will have positioned the Cursor on a dataSet element equal to or less than the element argument but not greater. A call to Cursor#previous() with a true return value will position the Cursor on a dataSet element less than the argument. If Cursor#next() returns false then the Cursor is past the last element and so all values in the dataSet are less than the argument. If Cursor#previous() returns false then the Cursor is positioned before the first element and all elements in the dataSet are greater than the argument.
        Parameters:
        element - the element to be positioned before
        Throws:
        LdapException - if we have get any LDAP exception while operating the cursor
        CursorException - if there are problems advancing to this Cursor before the given element, or if this Cursor is closed

      • after

        void after​(E element)
    throws LdapException,
           CursorException
        Prepares this Cursor, so a subsequent call to Cursor#previous() with a true return value, will have positioned the Cursor on a dataSet element equal to or less than the element argument but not greater. A call to Cursor#next() with a true return value will position the Cursor on a dataSet element greater than the argument. If Cursor#next() returns false then the Cursor is past the last element and so all values in the dataSet are less than or equal to the argument. If Cursor#previous() returns false then the Cursor is positioned before the first element and all elements in the dataSet are greater than the argument.
        Parameters:
        element - the element to be positioned after
        Throws:
        LdapException - if we have get any LDAP exception while operating the cursor
        CursorException - if there are problems advancing to this Cursor after the given element, or if this Cursor is closed

      • beforeFirst

        void beforeFirst()
          throws LdapException,
                 CursorException
        Positions this Cursor before the first element.
        Throws:
        LdapException - if we have get any LDAP exception while operating the cursor
        CursorException - if there are problems advancing to this Cursor before the first position, or if this Cursor is closed

      • afterLast

        void afterLast()
        throws LdapException,
               CursorException
        Positions this Cursor after the last element.
        Throws:
        LdapException - if we have get any LDAP exception while operating the cursor
        CursorException - if there are problems advancing to this Cursor after the last position, or if this Cursor is closed

      • first

        boolean first()
       throws LdapException,
              CursorException
        Positions this Cursor at the first element.
        Returns:
        true if the position has been successfully changed to the first element, false otherwise
        Throws:
        LdapException - if we have get any LDAP exception while operating the cursor
        CursorException - if there are problems advancing to this Cursor to the first position, or if this Cursor is closed

      • isFirst

        boolean isFirst()
        Is this Cursor positioned at the first element.
        Returns:
        true if this cursor is positioned at the first element, false otherwise

      • isBeforeFirst

        boolean isBeforeFirst()
        Is this Cursor positioned before the first element.
        Returns:
        true if this cursor is positioned before the first element, false otherwise

      • last

        boolean last()
      throws LdapException,
             CursorException
        Positions this Cursor at the last element.
        Returns:
        true if the position has been successfully changed to the last element, false otherwise
        Throws:
        LdapException - if we have get any LDAP exception while operating the cursor
        CursorException - if there are problems advancing to this Cursor to the last position, or if this Cursor is closed

      • isLast

        boolean isLast()
        Is this Cursor positioned at the last element.
        Returns:
        true if this cursor is positioned at the last element, false otherwise

      • isAfterLast

        boolean isAfterLast()
        Is this Cursor positioned after the last element.
        Returns:
        true if this cursor is positioned after the last element, false otherwise

      • isClosed

        boolean isClosed()
        Checks if this Cursor is closed. Calls to this operation should not fail with exceptions if and only if the cursor is in the closed state.
        Returns:
        true if this Cursor is closed, false otherwise

      • previous

        boolean previous()
          throws LdapException,
                 CursorException
        Advances this Cursor to the previous position. If called before explicitly positioning this Cursor, the position is presumed to be after the last element and this method moves the cursor back to the last element.
        Returns:
        true if the advance succeeded, false otherwise
        Throws:
        LdapException - if we have get any LDAP exception while operating the cursor
        CursorException - if there are problems advancing to this Cursor to the previous position, or if this Cursor is closed

      • next

        boolean next()
      throws LdapException,
             CursorException
        Advances this Cursor to the next position. If called before explicitly positioning this Cursor, the position is presumed to be before the first element and this method moves the cursor forward to the first element.
        Returns:
        true if the advance succeeded, false otherwise
        Throws:
        LdapException - if we have get any LDAP exception while operating the cursor
        CursorException - if there are problems advancing to this Cursor to the next position, or if this Cursor is closed

      • get

        E get()
throws CursorException
        Gets the object at the current position. Cursor implementations may choose to reuse element objects by re-populating them on advances instead of creating new objects on each advance.
        Returns:
        the object at the current position
        Throws:
        CursorException - if the object at this Cursor's current position cannot be retrieved, or if this Cursor is closed

      • close

        void close​(Exception reason)
    throws IOException
        Closes this Cursor and frees any resources it my have allocated. Repeated calls to this method after this Cursor has already been called should not fail with exceptions. The reason argument is the Exception instance thrown instead of the standard CursorClosedException.
        Parameters:
        reason - exception thrown when this Cursor is accessed after close
        Throws:
        IOException - If we can't close the Cursor

      • setClosureMonitor

        void setClosureMonitor​(ClosureMonitor monitor)
        Sets a non-null closure monitor to associate with this Cursor.
        Parameters:
        monitor - the monitor to use for detecting Cursor close events

      • toString

        String toString​(String tabs)
        Pretty-print a cursor and its wrapped cursor.
        Parameters:
        tabs - The spaces to add at each level
        Returns:
        The cursor and all it's wrapped elements, recursively printed