org.apache.hadoop.fs

## Class FSDataInputStream

- java.lang.Object
- - java.io.InputStream
  - - java.io.FilterInputStream
    - - java.io.DataInputStream
      - - org.apache.hadoop.fs.FSDataInputStream

- All Implemented Interfaces:
    Closeable, DataInput, AutoCloseable, ByteBufferReadable, CanSetDropBehind, CanSetReadahead, CanUnbuffer, org.apache.hadoop.fs.HasEnhancedByteBufferAccess, org.apache.hadoop.fs.HasFileDescriptor, PositionedReadable, Seekable, StreamCapabilities
  Direct Known Subclasses:
    HdfsDataInputStream

      @InterfaceAudience.Public
       @InterfaceStability.Stable
      public class FSDataInputStream
      extends DataInputStream
      implements Seekable, PositionedReadable, ByteBufferReadable, org.apache.hadoop.fs.HasFileDescriptor, CanSetDropBehind, CanSetReadahead, org.apache.hadoop.fs.HasEnhancedByteBufferAccess, CanUnbuffer, StreamCapabilities

  Utility that wraps a `FSInputStream` in a `DataInputStream` and buffers input through a `BufferedInputStream`.

- - ### Field Summary

    - ### Fields inherited from class java.io.FilterInputStream

      `in`

    - ### Fields inherited from interface org.apache.hadoop.fs.StreamCapabilities

      `DROPBEHIND, HFLUSH, HSYNC, READAHEAD, UNBUFFER`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FSDataInputStream(InputStream in)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `FileDescriptor` | `getFileDescriptor()`
    `long` | `getPos()` Get the current position in the input stream.
    `boolean` | `hasCapability(String capability)` Query the stream for a specific capability.
    `int` | `read(ByteBuffer buf)` Reads up to buf.remaining() bytes into buf.
    `ByteBuffer` | `read(ByteBufferPool bufferPool, int maxLength)`
    `ByteBuffer` | `read(ByteBufferPool bufferPool, int maxLength, EnumSet<ReadOption> opts)` Get a ByteBuffer containing file data.
    `int` | `read(long position, byte[] buffer, int offset, int length)` Read bytes from the given position in the stream to the given buffer.
    `void` | `readFully(long position, byte[] buffer)` See `readFully(long, byte[], int, int)`.
    `void` | `readFully(long position, byte[] buffer, int offset, int length)` Read bytes from the given position in the stream to the given buffer.
    `void` | `releaseBuffer(ByteBuffer buffer)` Release a ByteBuffer which was created by the enhanced ByteBuffer read function.
    `void` | `seek(long desired)` Seek to the given offset.
    `boolean` | `seekToNewSource(long targetPos)` Seek to the given position on an alternate copy of the data.
    `void` | `setDropBehind(Boolean dropBehind)` Configure whether the stream should drop the cache.
    `void` | `setReadahead(Long readahead)` Set the readahead on this stream.
    `String` | `toString()` String value.
    `void` | `unbuffer()` Reduce the buffering.

    - ### Methods inherited from class java.io.DataInputStream

      `read, read, readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, readUTF, skipBytes`

    - ### Methods inherited from class java.io.FilterInputStream

      `available, close, mark, markSupported, read, reset, skip`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### FSDataInputStream

          public FSDataInputStream(InputStream in)

  - ### Method Detail

    - #### seek

          public void seek(long desired)
                    throws IOException

      Seek to the given offset.
      Specified by:
        `seek` in interface `Seekable`
      Parameters:
        `desired` - offset to seek to
      Throws:
        `IOException`

    - #### getPos

          public long getPos()
                      throws IOException

      Get the current position in the input stream.
      Specified by:
        `getPos` in interface `Seekable`
      Returns:
        current position in the input stream
      Throws:
        `IOException`

    - #### read

          public int read(long position,
                          byte[] buffer,
                          int offset,
                          int length)
                   throws IOException

      Read bytes from the given position in the stream to the given buffer.
      Specified by:
        `read` in interface `PositionedReadable`
      Parameters:
        `position` - position in the input stream to seek
        `buffer` - buffer into which data is read
        `offset` - offset into the buffer in which data is written
        `length` - maximum number of bytes to read
      Returns:
        total number of bytes read into the buffer, or `-1` if there is no more data because the end of the stream has been reached
      Throws:
        `IOException` - IO problems.

    - #### readFully

          public void readFully(long position,
                                byte[] buffer,
                                int offset,
                                int length)
                         throws IOException

      Read bytes from the given position in the stream to the given buffer. Continues to read until `length` bytes have been read.
      Specified by:
        `readFully` in interface `PositionedReadable`
      Parameters:
        `position` - position in the input stream to seek
        `buffer` - buffer into which data is read
        `offset` - offset into the buffer in which data is written
        `length` - the number of bytes to read
      Throws:
        `IOException` - IO problems
        `EOFException` - If the end of stream is reached while reading. If an exception is thrown an undetermined number of bytes in the buffer may have been written.

    - #### readFully

          public void readFully(long position,
                                byte[] buffer)
                         throws IOException

      See `readFully(long, byte[], int, int)`.
      Specified by:
        `readFully` in interface `PositionedReadable`
      Parameters:
        `position` - position within file
        `buffer` - destination buffer
      Throws:
        `IOException` - IO problems.
        `EOFException` - the end of the data was reached before the read operation completed

    - #### seekToNewSource

          public boolean seekToNewSource(long targetPos)
                                  throws IOException

      Seek to the given position on an alternate copy of the data.
      Parameters:
        `targetPos` - position to seek to
      Returns:
        true if a new source is found, false otherwise
      Throws:
        `IOException`

    - #### read

          public int read(ByteBuffer buf)
                   throws IOException

      Description copied from interface: `ByteBufferReadable`
      Reads up to buf.remaining() bytes into buf. Callers should use buf.limit(..) to control the size of the desired read.

      After a successful call, buf.position() will be advanced by the number of bytes read and buf.limit() should be unchanged.

      In the case of an exception, the values of buf.position() and buf.limit() are undefined, and callers should be prepared to recover from this eventuality.

      Many implementations will throw `UnsupportedOperationException`, so callers that are not confident in support for this method from the underlying filesystem should be prepared to handle that exception.

      Implementations should treat 0-length requests as legitimate, and must not signal an error upon their receipt.
      Specified by:
        `read` in interface `ByteBufferReadable`
      Parameters:
        `buf` - the ByteBuffer to receive the results of the read operation.
      Returns:
        the number of bytes read, possibly zero, or -1 if reach end-of-stream
      Throws:
        `IOException` - if there is some error performing the read

    - #### getFileDescriptor

          public FileDescriptor getFileDescriptor()
                                           throws IOException

      Specified by:
        `getFileDescriptor` in interface `org.apache.hadoop.fs.HasFileDescriptor`
      Returns:
        the FileDescriptor
      Throws:
        `IOException`

    - #### setReadahead

          public void setReadahead(Long readahead)
                            throws IOException,
                                   UnsupportedOperationException

      Description copied from interface: `CanSetReadahead`
      Set the readahead on this stream.
      Specified by:
        `setReadahead` in interface `CanSetReadahead`
      Parameters:
        `readahead` - The readahead to use. null means to use the default.
      Throws:
        `IOException` - If there was an error changing the dropBehind setting. UnsupportedOperationException If this stream doesn't support setting readahead.
        `UnsupportedOperationException`

    - #### setDropBehind

          public void setDropBehind(Boolean dropBehind)
                             throws IOException,
                                    UnsupportedOperationException

      Description copied from interface: `CanSetDropBehind`
      Configure whether the stream should drop the cache.
      Specified by:
        `setDropBehind` in interface `CanSetDropBehind`
      Parameters:
        `dropBehind` - Whether to drop the cache. null means to use the default value.
      Throws:
        `IOException` - If there was an error changing the dropBehind setting. UnsupportedOperationException If this stream doesn't support setting the drop-behind.
        `UnsupportedOperationException`

    - #### read

          public ByteBuffer read(ByteBufferPool bufferPool,
                                 int maxLength,
                                 EnumSet<ReadOption> opts)
                          throws IOException,
                                 UnsupportedOperationException

      Description copied from interface: `org.apache.hadoop.fs.HasEnhancedByteBufferAccess`
      Get a ByteBuffer containing file data. This ByteBuffer may come from the stream itself, via a call like mmap, or it may come from the ByteBufferFactory which is passed in as an argument.
      Specified by:
        `read` in interface `org.apache.hadoop.fs.HasEnhancedByteBufferAccess`
      Parameters:
        `bufferPool` - If this is non-null, it will be used to create a fallback ByteBuffer when the stream itself cannot create one.
        `maxLength` - The maximum length of buffer to return. We may return a buffer which is shorter than this.
        `opts` - Options to use when reading.
      Returns:
        We will always return an empty buffer if maxLength was 0, whether or not we are at EOF. If maxLength > 0, we will return null if the stream has reached EOF. Otherwise, we will return a ByteBuffer containing at least one byte. You must free this ByteBuffer when you are done with it by calling releaseBuffer on it. The buffer will continue to be readable until it is released in this manner. However, the input stream's close method may warn about unclosed buffers.
      Throws:
        `IOException`
        `UnsupportedOperationException`

    - #### read

          public final ByteBuffer read(ByteBufferPool bufferPool,
                                       int maxLength)
                                throws IOException,
                                       UnsupportedOperationException

      Throws:
        `IOException`
        `UnsupportedOperationException`

    - #### releaseBuffer

          public void releaseBuffer(ByteBuffer buffer)

      Description copied from interface: `org.apache.hadoop.fs.HasEnhancedByteBufferAccess`
      Release a ByteBuffer which was created by the enhanced ByteBuffer read function. You must not continue using the ByteBuffer after calling this function.
      Specified by:
        `releaseBuffer` in interface `org.apache.hadoop.fs.HasEnhancedByteBufferAccess`
      Parameters:
        `buffer` - The ByteBuffer to release.

    - #### unbuffer

          public void unbuffer()

      Description copied from interface: `CanUnbuffer`
      Reduce the buffering. This will also free sockets and file descriptors held by the stream, if possible.
      Specified by:
        `unbuffer` in interface `CanUnbuffer`

    - #### hasCapability

          public boolean hasCapability(String capability)

      Description copied from interface: `StreamCapabilities`
      Query the stream for a specific capability.
      Specified by:
        `hasCapability` in interface `StreamCapabilities`
      Parameters:
        `capability` - string to query the stream support for.
      Returns:
        True if the stream supports capability.

    - #### toString

          public String toString()

      String value. Includes the string value of the inner stream
      Overrides:
        `toString` in class `Object`
      Returns:
        the stream

Copyright © 2022 Apache Software Foundation. All rights reserved.