Package org.simpleframework.transport

## Interface Cursor

- All Known Implementing Classes:
    `TransportCursor`

      public interface Cursor

  The `Cursor` object is used to acquire bytes from a given source. This provides a cursor style reading of bytes from a stream in that it will allow the reader to move the cursor back if the amount of bytes read is too much. Allowing the cursor to move ensures that excess bytes back be placed back in the stream.

  This is used when parsing input from a stream as it ensures that on arrival at a terminal token any excess bytes can be placed back in to the stream. This allows data to be read efficiently in large chunks from blocking streams such as sockets.

  Author:
    Niall Gallagher
  See Also:
    `TransportCursor`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `isOpen()` | Determines whether the cursor is still open.
    `boolean` | `isReady()` | Determines whether the cursor is ready for reading.
    `void` | `push​(byte[] data)` | Pushes the provided data on to the cursor.
    `void` | `push​(byte[] data, int off, int len)` | Pushes the provided data on to the cursor.
    `int` | `read​(byte[] data)` | Reads a block of bytes from the underlying stream.
    `int` | `read​(byte[] data, int off, int len)` | Reads a block of bytes from the underlying stream.
    `int` | `ready()` | Provides the number of bytes that can be read from the stream without blocking.
    `int` | `reset​(int len)` | Moves the cursor backward within the stream.

- - ### Method Detail

    - #### isOpen

          boolean isOpen()
                  throws java.io.IOException

      Determines whether the cursor is still open. The cursor is considered open if there are still bytes to read. If there is still bytes buffered and the underlying transport is closed then the cursor is still considered open.
      Returns:
        true if the read method does not return a -1 value
      Throws:
        `java.io.IOException`

    - #### isReady

          boolean isReady()
                   throws java.io.IOException

      Determines whether the cursor is ready for reading. When the cursor is ready then it guarantees that some amount of bytes can be read from the underlying stream without blocking.
      Returns:
        true if some data can be read without blocking
      Throws:
        `java.io.IOException`

    - #### ready

          int ready()
             throws java.io.IOException

      Provides the number of bytes that can be read from the stream without blocking. This is typically the number of buffered or available bytes within the stream. When this reaches zero then the cursor may perform a blocking read.
      Returns:
        the number of bytes that can be read without blocking
      Throws:
        `java.io.IOException`

    - #### read

          int read​(byte[] data)
            throws java.io.IOException

      Reads a block of bytes from the underlying stream. This will read up to the requested number of bytes from the underlying stream. If there are no ready bytes on the stream this can return zero, representing the fact that nothing was read.
      Parameters:
        `data` - this is the array to read the bytes in to
      Returns:
        this returns the number of bytes read from the stream
      Throws:
        `java.io.IOException`

    - #### read

          int read​(byte[] data,
                   int off,
                   int len)
            throws java.io.IOException

      Reads a block of bytes from the underlying stream. This will read up to the requested number of bytes from the underlying stream. If there are no ready bytes on the stream this can return zero, representing the fact that nothing was read.
      Parameters:
        `data` - this is the array to read the bytes in to
        `off` - this is the offset to begin writing the bytes to
        `len` - this is the number of bytes that are requested
      Returns:
        this returns the number of bytes read from the stream
      Throws:
        `java.io.IOException`

    - #### push

          void push​(byte[] data)
             throws java.io.IOException

      Pushes the provided data on to the cursor. Data pushed on to the cursor will be the next data read from the cursor. This complements the `reset` method which will reset the cursors position on a stream. Allowing data to be pushed on to the cursor allows more flexibility.
      Parameters:
        `data` - this is the data to be pushed on to the cursor
      Throws:
        `java.io.IOException`

    - #### push

          void push​(byte[] data,
                    int off,
                    int len)
             throws java.io.IOException

      Pushes the provided data on to the cursor. Data pushed on to the cursor will be the next data read from the cursor. This complements the `reset` method which will reset the cursors position on a stream. Allowing data to be pushed on to the cursor allows more flexibility.
      Parameters:
        `data` - this is the data to be pushed on to the cursor
        `off` - this is the offset to begin reading the bytes
        `len` - this is the number of bytes that are to be used
      Throws:
        `java.io.IOException`

    - #### reset

          int reset​(int len)
             throws java.io.IOException

      Moves the cursor backward within the stream. This ensures that any bytes read from the last read can be pushed back in to the stream so that they can be read again. This will throw an exception if the reset can not be performed.
      Parameters:
        `len` - this is the number of bytes to reset back
      Returns:
        this is the number of bytes that have been reset
      Throws:
        `java.io.IOException`