Package edu.caltech.nanodb.storage

Class DBFile

  • public class DBFile
extends java.lang.Object

    This class provides page-level access to a database file, which contains some kind of data utilized in a database system. This class may be utilized for many different kinds of database files. Here is an example of the kinds of data that might be stored in files:

    • Tuples in a database table.
    • Table indexes in a hashtable, tree, or some other format.
    • Recovery logs.
    • Checkpoint files.

    DBFiles are created by using the StorageManager.openDBFile(java.lang.String) method. This allows the StorageManager to provide caching of opened DBFiles so that unnecessary IOs can be avoided. (Internally, the StorageManager uses FileManagerImpl.openDBFile(java.lang.String) to open files, and the BufferManager to cache opened files and loaded pages.)

    For a file to be opened as a DBFile, it must have specific details stored in the first page of the file:

    • Byte 0: file type (unsigned byte) - value taken from DBFileType
    • Byte 1: page size p (unsigned byte) - file's page size is P = 2p
    See Also:
    RandomAccessFile

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.io.File dataFile
      The actual data file on disk.
      static int DEFAULT_PAGESIZE
      The default page size is 8K bytes.
      private java.io.RandomAccessFile fileContents
      The file data is accessed via this variable.
      static int MAX_PAGESIZE
      The maximum page size is 64K bytes.
      static int MIN_PAGESIZE
      The minimum page size is 512 bytes.
      private int pageSize
      This is the size of pages that are read and written to the data file.
      private DBFileType type
      The type of the data file.

    • Constructor Summary

      Constructors 
      Constructor Description
      DBFile​(java.io.File dataFile, DBFileType type, int pageSize)
      Constructs a new object from the specified information, and opens the backing data-file as well.
      DBFile​(java.io.File dataFile, DBFileType type, int pageSize, java.io.RandomAccessFile fileContents)
      Constructs a new object from the specified information and the previously opened data-file.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void checkValidPageSize​(int pageSize)
      This static helper method checks the specified page-size with isValidPageSize(int), and if the size is not valid then an IllegalArgumentException runtime exception is thrown.
      static int decodePageSize​(int encoded)
      Given the base-2 logarithm of a page size, this method returns the actual page size.
      static int encodePageSize​(int pageSize)
      Given a valid page size, this method returns the base-2 logarithm of the page size for storing in a data file.
      boolean equals​(java.lang.Object obj)
      Returns true if obj is an instance of DBFile with the same backing file.
      java.io.File getDataFile()
      Returns the actual file that holds the data on the disk.
      java.io.RandomAccessFile getFileContents()
      Returns the RandomAccessFile for accessing the data file's contents.
      long getFileSize()  
      int getNumPages()
      Reads the current file-length of this database file and computes the total number of pages based on this value.
      int getPageSize()
      Returns the page size for this database file, in bytes.
      DBFileType getType()
      Returns the type of this data file.
      int hashCode()
      Returns a hash-code based on the filename of the backing file.
      static boolean isValidPageSize​(int pageSize)
      This static helper method returns true if the specified page size is valid; i.e.
      void setDataFile​(java.io.File file)
      Sets the actual file that holds the data on the disk.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • MIN_PAGESIZE

        public static final int MIN_PAGESIZE
        The minimum page size is 512 bytes.
        See Also:
        Constant Field Values

      • MAX_PAGESIZE

        public static final int MAX_PAGESIZE
        The maximum page size is 64K bytes.
        See Also:
        Constant Field Values

      • DEFAULT_PAGESIZE

        public static final int DEFAULT_PAGESIZE
        The default page size is 8K bytes.
        See Also:
        Constant Field Values

      • dataFile

        private java.io.File dataFile
        The actual data file on disk.

      • type

        private DBFileType type
        The type of the data file.

      • pageSize

        private int pageSize
        This is the size of pages that are read and written to the data file. This value will be a power of two, between the minimum and maximum page sizes.

      • fileContents

        private java.io.RandomAccessFile fileContents
        The file data is accessed via this variable.

    • Constructor Detail

      • DBFile

        public DBFile​(java.io.File dataFile,
              DBFileType type,
              int pageSize)
       throws java.io.IOException
        Constructs a new object from the specified information, and opens the backing data-file as well.
        Parameters:
        dataFile - the actual file containing the data
        type - the type of the data file
        pageSize - the page-size of the data file
        Throws:
        java.lang.IllegalArgumentException - if the page size is not valid.
        java.io.IOException - if some other IO error occurs

      • DBFile

        public DBFile​(java.io.File dataFile,
              DBFileType type,
              int pageSize,
              java.io.RandomAccessFile fileContents)
        Constructs a new object from the specified information and the previously opened data-file.
        Parameters:
        dataFile - the actual file containing the data
        type - the type of the data file
        pageSize - the page-size of the data file
        fileContents - an already opened RandomAccessFile to use for accessing the data file's contents
        Throws:
        java.lang.IllegalArgumentException - if the page size is not valid.

    • Method Detail

      • isValidPageSize

        public static boolean isValidPageSize​(int pageSize)
        This static helper method returns true if the specified page size is valid; i.e. it must be within the minimum and maximum page sizes, and it must be a power of two.
        Parameters:
        pageSize - the page-size to test for validity
        Returns:
        true if the specified page-size is valid, or false otherwise.

      • checkValidPageSize

        public static void checkValidPageSize​(int pageSize)
        This static helper method checks the specified page-size with isValidPageSize(int), and if the size is not valid then an IllegalArgumentException runtime exception is thrown. The method is intended for checking arguments.
        Parameters:
        pageSize - the page-size to test for validity
        Throws:
        java.lang.IllegalArgumentException - if the specified page-size is invalid.

      • encodePageSize

        public static int encodePageSize​(int pageSize)
        Given a valid page size, this method returns the base-2 logarithm of the page size for storing in a data file. For example, encodePageSize(512) will return 9.
        Parameters:
        pageSize - the page-size to encode
        Returns:
        the base-2 logarithm of the page size
        Throws:
        java.lang.IllegalArgumentException - if the specified page-size is invalid.

      • decodePageSize

        public static int decodePageSize​(int encoded)
        Given the base-2 logarithm of a page size, this method returns the actual page size. For example, decodePageSize(9) will return 512.
        Parameters:
        encoded - the encoded page-size
        Returns:
        the actual page size, computed as 2encoded.
        Throws:
        java.lang.IllegalArgumentException - if the resulting page-size is invalid.

      • equals

        public boolean equals​(java.lang.Object obj)
        Returns true if obj is an instance of DBFile with the same backing file.
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Returns a hash-code based on the filename of the backing file.
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getDataFile

        public java.io.File getDataFile()
        Returns the actual file that holds the data on the disk.
        Returns:
        the File object that actually holds the data on disk.

      • setDataFile

        public void setDataFile​(java.io.File file)
        Sets the actual file that holds the data on the disk. This should only be called in special circumstances, like when a data file is renamed.

      • getType

        public DBFileType getType()
        Returns the type of this data file.
        Returns:
        the enumerated value indicating the file's type.

      • getPageSize

        public int getPageSize()
        Returns the page size for this database file, in bytes.
        Returns:
        the page size for this database file, in bytes.

      • getFileSize

        public long getFileSize()

      • getNumPages

        public int getNumPages()
        Reads the current file-length of this database file and computes the total number of pages based on this value. Note that since this method involves an IO operation, it should be called infrequently since it will be slow.
        Returns:
        the number of pages currently in this database file.

      • getFileContents

        public java.io.RandomAccessFile getFileContents()
        Returns the RandomAccessFile for accessing the data file's contents.
        Returns:
        the RandomAccessFile for accessing the data file's contents.