Package edu.caltech.nanodb.storage.heapfile

Class DataPage

  • public class DataPage
extends java.lang.Object
    This class provides the constants and operations necessary for manipulating a data page within a heap file. Heap files use a slotted-page structure where tuple-data is filled from the end of the page forward, so for two slots at indexes i and j, where i < j, the start of i's tuple data will be after j's tuple data.
    Design Note:
    (Donnie) Why is this class a static class, instead of a wrapper class around the DBPage? No particular reason, really. The class is used relatively briefly when a table is being accessed, and there is no real need for it to manage its own object-state, so it was just as convenient to provide all functionality as static methods. This avoids the (small) overhead of instantiating an object as well. But really, these are not particularly strong reasons.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int EMPTY_SLOT
      This offset-value is stored into a slot when it is empty.
      private static org.apache.logging.log4j.Logger logger
      A logging object for reporting anything interesting that happens.
      static int OFFSET_NUM_SLOTS
      The offset in the data page where the number of slots in the slot table is stored.

    • Constructor Summary

      Constructors 
      Constructor Description
      DataPage()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static int allocNewTuple​(DBPage dbPage, int len)
      Update the data page so that it has space for a new tuple of the specified size.
      static void deleteTuple​(DBPage dbPage, int slot)
      Deletes the tuple at the specified slot from the data page.
      static void deleteTupleDataRange​(DBPage dbPage, int off, int len)
      This static helper function removes a sequence of bytes from the current tuple data in the page, sliding tuple data below the offset forward to fill in the gap.
      static int getFreeSpaceInPage​(DBPage dbPage)
      This static helper function returns the amount of free space in a tuple data page.
      static int getNumSlots​(DBPage dbPage)
      Returns the number of slots in this data page.
      static int getSlotIndexFromOffset​(DBPage dbPage, int offset)  
      static int getSlotOffset​(int slot)  
      static int getSlotsEndIndex​(DBPage dbPage)
      This static helper function returns the index where the slot list ends in the data page.
      static int getSlotValue​(DBPage dbPage, int slot)
      This static helper function returns the value stored in the specified slot.
      static int getTupleDataEnd​(DBPage dbPage)
      This static helper function returns the index of where tuple data currently ends in the specified data page.
      static int getTupleDataStart​(DBPage dbPage)
      This static helper function returns the index of where tuple data currently starts in the specified data page.
      static int getTupleLength​(DBPage dbPage, int slot)
      Returns the length of the tuple stored at the specified slot.
      static void initNewPage​(DBPage dbPage)
      Initialize a newly allocated data page.
      static void insertTupleDataRange​(DBPage dbPage, int off, int len)
      This static helper function creates a space in the data page of the specified size, sliding tuple data below the offset down to create a gap.
      static void sanityCheck​(DBPage dbPage)
      This static helper method verifies that the specified data page has proper structure and organization by performing various sanity checks.
      static void setNumSlots​(DBPage dbPage, int numSlots)
      Sets the number of slots in this data page.
      static void setSlotValue​(DBPage dbPage, int slot, int value)
      This static helper function sets the value for the specified slot.

      • 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.

      • OFFSET_NUM_SLOTS

        public static final int OFFSET_NUM_SLOTS
        The offset in the data page where the number of slots in the slot table is stored.
        See Also:
        Constant Field Values

      • EMPTY_SLOT

        public static final int EMPTY_SLOT
        This offset-value is stored into a slot when it is empty. It is set to zero because this is where the page's slot-count is stored and therefore this is obviously an invalid offset for a tuple to be located at.
        See Also:
        Constant Field Values

    • Constructor Detail

      • DataPage

        public DataPage()

    • Method Detail

      • initNewPage

        public static void initNewPage​(DBPage dbPage)
        Initialize a newly allocated data page. Currently this involves setting the number of slots to 0. There is no other internal structure in data pages at this point.
        Parameters:
        dbPage - the data page to initialize

      • getSlotOffset

        public static int getSlotOffset​(int slot)

      • getNumSlots

        public static int getNumSlots​(DBPage dbPage)
        Returns the number of slots in this data page. This can be considered to be the current "capacity" of the page, since any number of the slots could be set to EMPTY_SLOT to indicate that they are empty.
        Parameters:
        dbPage - the data page to retrieve the number of slots for
        Returns:
        the current number of slots in the page

      • setNumSlots

        public static void setNumSlots​(DBPage dbPage,
                               int numSlots)
        Sets the number of slots in this data page. Note that if the number of slots is increased, the new slots must be initialized to EMPTY_SLOT, or else functions like getFreeSpaceInPage(edu.caltech.nanodb.storage.DBPage) (which relies on the offset stored in the last slot) will produce wrong results.
        Parameters:
        dbPage - the data page to set the number of slots for
        numSlots - the value to store

      • getSlotsEndIndex

        public static int getSlotsEndIndex​(DBPage dbPage)
        This static helper function returns the index where the slot list ends in the data page.
        Parameters:
        dbPage - the data page to examine
        Returns:
        the index in the page data where the slot-table ends. This also happens to be the size of the slot-table in bytes.

      • getSlotValue

        public static int getSlotValue​(DBPage dbPage,
                               int slot)
        This static helper function returns the value stored in the specified slot. This will either be the offset of the start of a tuple in the data page, or it will be EMPTY_SLOT if the slot is empty.
        Parameters:
        dbPage - the data page to retrieve the slot-value from
        slot - the slot to retrieve the value for; valid values are from 0 to getNumSlots(edu.caltech.nanodb.storage.DBPage) - 1.
        Returns:
        the current value stored for the slot in the data page
        Throws:
        java.lang.IllegalArgumentException - if the specified slot number is outside the range [0, getNumSlots(edu.caltech.nanodb.storage.DBPage)).

      • setSlotValue

        public static void setSlotValue​(DBPage dbPage,
                                int slot,
                                int value)
        This static helper function sets the value for the specified slot. This should either be the offset of the start of a tuple in the data page, or it should be EMPTY_SLOT if the slot is empty.
        Parameters:
        dbPage - the data page to set the slot-value for
        slot - the slot to set the value of; valid values are from 0 to getNumSlots(edu.caltech.nanodb.storage.DBPage) - 1.
        value - the value to store for the slot
        Throws:
        java.lang.IllegalArgumentException - if the specified slot number is outside the range [0, getNumSlots(edu.caltech.nanodb.storage.DBPage)).

      • getSlotIndexFromOffset

        public static int getSlotIndexFromOffset​(DBPage dbPage,
                                         int offset)
                                  throws java.lang.IllegalArgumentException
        Throws:
        java.lang.IllegalArgumentException

      • getTupleDataStart

        public static int getTupleDataStart​(DBPage dbPage)
        This static helper function returns the index of where tuple data currently starts in the specified data page. This method uses the last slot in the slot-table to determine where the tuple data begins, since the slots must be organized in decreasing order of offset-value. (In other words, we add tuple data from the back of the block towards the front.)
        Parameters:
        dbPage - the data page to examine
        Returns:
        the index where the tuple data starts in this data page
        See Also:
        setNumSlots(edu.caltech.nanodb.storage.DBPage, int)

      • getTupleDataEnd

        public static int getTupleDataEnd​(DBPage dbPage)
        This static helper function returns the index of where tuple data currently ends in the specified data page. This value depends more on the overall structure of the data page, and at present is simply the page-size.
        Parameters:
        dbPage - the data page to examine
        Returns:
        the index where the tuple data ends in this data page

      • getTupleLength

        public static int getTupleLength​(DBPage dbPage,
                                 int slot)
        Returns the length of the tuple stored at the specified slot. It is invalid to use this method on an empty slot.
        Parameters:
        dbPage - the data page being examined
        slot - the slot of the tuple to retrieve the length of
        Returns:
        the length of the tuple's data stored in this slot
        Throws:
        java.lang.IllegalArgumentException - if the specified slot is invalid, or if the specified slot has EMPTY_SLOT for its value

      • getFreeSpaceInPage

        public static int getFreeSpaceInPage​(DBPage dbPage)
        This static helper function returns the amount of free space in a tuple data page. It simply uses other methods in this class to perform the simple computation.
        Parameters:
        dbPage - the data page to examine
        Returns:
        the amount of free space in the data page, in bytes

      • sanityCheck

        public static void sanityCheck​(DBPage dbPage)
        This static helper method verifies that the specified data page has proper structure and organization by performing various sanity checks. Currently, the only sanity check it performs is to verify that slot-offsets do indeed decrease monotonically as the slot-index increases.

        Any issues will cause warnings to be logged.

        Parameters:
        dbPage - the data page to check

      • insertTupleDataRange

        public static void insertTupleDataRange​(DBPage dbPage,
                                        int off,
                                        int len)

        This static helper function creates a space in the data page of the specified size, sliding tuple data below the offset down to create a gap. Because tuples below the specified offset will actually move, some of the slots in the page may also need to be modified.

        The new space is initialized to all zero values.

        Parameters:
        dbPage - The table data-page to insert space into.
        off - The offset in the page where the space will be added.
        len - The number of bytes to insert.

      • deleteTupleDataRange

        public static void deleteTupleDataRange​(DBPage dbPage,
                                        int off,
                                        int len)
        This static helper function removes a sequence of bytes from the current tuple data in the page, sliding tuple data below the offset forward to fill in the gap. Because tuples below the specified offset will actually move, some of the slots in the page may also need to be modified.
        Parameters:
        dbPage - The table data-page to insert space into.
        off - The offset in the page where the space will be removed.
        len - The number of bytes to remove.

      • allocNewTuple

        public static int allocNewTuple​(DBPage dbPage,
                                int len)
        Update the data page so that it has space for a new tuple of the specified size. The new tuple is assigned a slot (whose index is returned by this method), and the space for the tuple is initialized to all zero values.
        Parameters:
        dbPage - The data page to store the new tuple in.
        len - The length of the new tuple's data.
        Returns:
        The slot-index for the new tuple. The offset to the start of the requested space is available via that slot. (Use getSlotValue(edu.caltech.nanodb.storage.DBPage, int) to retrieve that offset.)

      • deleteTuple

        public static void deleteTuple​(DBPage dbPage,
                               int slot)
        Deletes the tuple at the specified slot from the data page. The space occupied by the tuple's data is reclaimed by sliding tuple-data lower in the page upward. Also, any trailing slots that are now marked as "deleted" are reclaimed.
        Parameters:
        dbPage - the data page to remove the tuple from
        slot - the slot of the tuple to delete