Package edu.caltech.nanodb.storage

Class DBFileReader

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    Direct Known Subclasses:
    DBFileWriter
    public class DBFileReader
extends java.lang.Object
implements java.lang.AutoCloseable

    This class provides the basic abilty to read a DBFile as a single sequential file, obscuring the fact that it is actually broken into pages. As the file-pointer moves through the file, the Storage Manager is used to load individual pages into the buffer manager.

    It is certainly possible that a value being read might span two adjacent data pages. In these cases, the access will be a little slower, as the operation must access partial data from the first page, and then access the remainder of the data from the next page.

    There is a subclass of this reader, the DBFileWriter, which allows data to be read and written sequentially to a DBFile.

    Design Note:
    This class always has the current DBPage pinned, and it will unpin the current page when it moves into the next page. This means that when the reader is closed, it may still have a page that is pinned. Therefore, the class implements AutoCloseable so that users can call close() on a reader to unpin the last page, or they can use this type with the "try-with-resources" Java syntax.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected DBFile dbFile
      The database file being read by this reader.
      protected DBPage dbPage
      The last page used for reading the database file.
      protected boolean extendFile
      A flag controlling whether the file being read should be extended as it is read.
      private static org.apache.logging.log4j.Logger logger
      A logging object for reporting anything interesting that happens.
      protected int pageSize
      The page-size of the database file being read from.
      protected int position
      The current position in the file where reads will occur from.
      protected StorageManager storageManager
      A reference to the storage manager, which we will use to read pages needed for the various operations.
      protected byte[] tmpBuf
      This temporary buffer is used to read primitive values that overlap the boundaries between two pages.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void checkDBPage()
      This helper function checks to see whether the currently cached DBPage object matches the page-number of the current position value.
      void close()
      If the file-reader currently holds a DBPage, this method will unpin the page.
      DBFile getDBFile()  
      int getPosition()
      Returns the current location in the page where the next operation will start from.
      protected int getPositionPageNo()
      Computes and returns the page-number of the page that the position value currently falls within.
      protected int getPositionPageOffset()
      Computes and returns the offset within the current page that the position value currently falls at.
      void movePosition​(int n)
      Move the current position by n bytes.
      void read​(byte[] b)
      Read a sequence of bytes into the provided byte-array.
      void read​(byte[] b, int off, int len)
      Read a sequence of bytes into the provided byte-array, starting with the specified offset, and reading the specified number of bytes.
      boolean readBoolean()
      Reads and returns a Boolean value from the current position.
      byte readByte()
      Reads and returns a signed byte from the current position.
      char readChar()
      Reads and returns a two-byte char value from the current position.
      double readDouble()  
      float readFloat()  
      int readInt()
      Reads and returns a four-byte integer value from the current position.
      long readLong()
      Reads and returns an eight-byte long integer value from the current position.
      short readShort()
      Reads and returns a signed short from the current position.
      int readUnsignedByte()
      Reads and returns an unsigned byte from the current position.
      long readUnsignedInt()
      Reads and returns a four-byte unsigned integer value from the current position.
      int readUnsignedShort()
      Reads and returns an unsigned short from the current position.
      java.lang.String readVarString255()
      This method reads and returns a variable-length string whose maximum length is 255 bytes.
      java.lang.String readVarString65535()
      This method reads and returns a variable-length string whose maximum length is 65535 bytes.
      void setPosition​(int position)
      Sets the location in the page where the next operation will start from.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • logger

        private static org.apache.logging.log4j.Logger logger
        A logging object for reporting anything interesting that happens.

      • storageManager

        protected StorageManager storageManager
        A reference to the storage manager, which we will use to read pages needed for the various operations.

      • dbFile

        protected DBFile dbFile
        The database file being read by this reader.

      • extendFile

        protected boolean extendFile
        A flag controlling whether the file being read should be extended as it is read. The reader is expected to not extend the file, but the DBFileWriter, a subclass of this class, sets this flag to true.

      • pageSize

        protected int pageSize
        The page-size of the database file being read from.

      • dbPage

        protected DBPage dbPage
        The last page used for reading the database file.

      • position

        protected int position
        The current position in the file where reads will occur from.

      • tmpBuf

        protected byte[] tmpBuf
        This temporary buffer is used to read primitive values that overlap the boundaries between two pages.

    • Method Detail

      • close

        public void close()
        If the file-reader currently holds a DBPage, this method will unpin the page. The dbPage value is also set to null so that if someone tries to use the reader later, the page will be re-loaded (and therefore also re-pinned).
        Specified by:
        close in interface java.lang.AutoCloseable

      • getDBFile

        public DBFile getDBFile()

      • getPosition

        public int getPosition()
        Returns the current location in the page where the next operation will start from.
        Returns:
        the current location in the page

      • setPosition

        public void setPosition​(int position)
        Sets the location in the page where the next operation will start from.
        Parameters:
        position - the new location in the page

      • movePosition

        public void movePosition​(int n)
        Move the current position by n bytes. A negative value of n will move the position backward.
        Parameters:
        n - the delta to apply to the current position

      • getPositionPageNo

        protected int getPositionPageNo()
        Computes and returns the page-number of the page that the position value currently falls within.
        Returns:
        the page-number of the page that the position value currently falls within

      • getPositionPageOffset

        protected int getPositionPageOffset()
        Computes and returns the offset within the current page that the position value currently falls at.
        Returns:
        the offset within the current page that the position value currently falls at

      • checkDBPage

        protected void checkDBPage()
        This helper function checks to see whether the currently cached DBPage object matches the page-number of the current position value. If they don't match, or if there currently isn't any DBPage cached, then this method will load the required DBPage from the Storage Manager.

      • read

        public void read​(byte[] b,
                 int off,
                 int len)
        Read a sequence of bytes into the provided byte-array, starting with the specified offset, and reading the specified number of bytes.
        Parameters:
        b - the byte-array to read bytes into
        off - the offset to read the bytes into the array
        len - the number of bytes to read into the array

      • read

        public void read​(byte[] b)
        Read a sequence of bytes into the provided byte-array. The entire array is filled from start to end.
        Parameters:
        b - the byte-array to read bytes into

      • readBoolean

        public boolean readBoolean()
        Reads and returns a Boolean value from the current position. A zero value is interpreted as false, and a nonzero value is interpreted as true.

      • readByte

        public byte readByte()
        Reads and returns a signed byte from the current position.

      • readUnsignedByte

        public int readUnsignedByte()
        Reads and returns an unsigned byte from the current position. The value is returned as an int whose value will be between 0 and 255, inclusive.

      • readUnsignedShort

        public int readUnsignedShort()
        Reads and returns an unsigned short from the current position. The value is returned as an int whose value will be between 0 and 65535, inclusive.

      • readShort

        public short readShort()
        Reads and returns a signed short from the current position.

      • readChar

        public char readChar()
        Reads and returns a two-byte char value from the current position.

      • readUnsignedInt

        public long readUnsignedInt()
        Reads and returns a four-byte unsigned integer value from the current position.

      • readInt

        public int readInt()
        Reads and returns a four-byte integer value from the current position.

      • readLong

        public long readLong()
        Reads and returns an eight-byte long integer value from the current position.

      • readFloat

        public float readFloat()

      • readDouble

        public double readDouble()

      • readVarString255

        public java.lang.String readVarString255()
        This method reads and returns a variable-length string whose maximum length is 255 bytes. The string is expected to be in US-ASCII encoding, so multibyte characters are not supported.

        The string's data format is expected to be a single unsigned byte b specifying the string's length, followed by b more bytes consisting of the string value itself.

      • readVarString65535

        public java.lang.String readVarString65535()
        This method reads and returns a variable-length string whose maximum length is 65535 bytes. The string is expected to be in US-ASCII encoding, so multibyte characters are not supported.

        The string's data format is expected to be a single unsigned short (two bytes) s specifying the string's length, followed by s more bytes consisting of the string value itself.